macOS 本地部署 OpenClaw 的 Docker 完整指南

验证容器运行状态：

docker ps

输出应显示 openclaw 容器状态为 Up，且端口映射正确。

首次访问控制台并获取 Token

1. 打开控制台

在浏览器中访问 http://localhost:18789，你会看到 OpenClaw 的仪表板页面，但状态显示为'Disconnected'，并提示需要 Token。

2. 获取初始 Token

OpenClaw 在首次启动时会自动生成一个 Token。执行以下命令查看日志获取 Token：

docker logs openclaw | grep -i token 

日志中可能会提示生成了新 Token，但不会直接打印值。需要用命令从配置中读取：

docker exec openclaw openclaw config get gateway.auth.token 

输出一串长字符串（例如 ed0904424aca...），复制保存，后续需要用到。

3. 填入 Token 并尝试连接

在浏览器页面中，找到'Gateway Token'输入框，粘贴复制的 Token，然后点击右下角的 Connect 按钮。此时可能会遇到两种错误：

• pairing required：表示设备需要配对，见下一节。
• control ui requires device identity：确保你使用的是 http://localhost:18789 而非 IP 地址，否则浏览器会因安全策略阻止连接。

设备配对

首次连接时，OpenClaw 要求手动批准设备。即使 Token 正确，也需要执行配对操作。

1. 查看待配对设备

进入容器：

docker exec -it openclaw sh

运行：

openclaw devices list 

输出会列出待处理的配对请求（Pending），其中应包含一个来自你本地 IP（如 192.168.65.1）的请求。

2. 批准设备

使用请求 ID（第一列）批准：

openclaw devices approve a66fb94c-060****8-2c4c21241c72 

或使用设备 ID（第二列）：

openclaw devices approve d53730f4722d2f******43d4d86f85e143f0498b66a98 

批准后，退出容器（exit），刷新浏览器页面，此时应该显示'Connected'，网关状态变为绿色。

配置 AI 模型提供商

OpenClaw 默认使用 Anthropic 的 Claude 模型，但我们需要配置国内可用的硅基流动（SiliconFlow）API。

1. 获取硅基流动 API 密钥

1. 注册/登录硅基流动控制台。
2. 在'账户管理' -> 'API 密钥'中，点击'新建 API 密钥'，生成一个以 sk- 开头的密钥，复制并妥善保存。

2. 添加自定义模型提供商

进入容器：

docker exec -it openclaw sh

运行交互式命令添加 OpenAI 兼容的提供商：

openclaw models auth add

按提示操作：

• 当出现'Token provider'时，选择 custom（或 OpenAI-compatible）。
• 输入 Provider id：例如 siliconflow。
• 输入 Base URL：https://api.siliconflow.cn/v1
• 输入 API Key：粘贴你刚获取的密钥。
• 输入 Default model：选择一个模型 ID，例如 deepseek-ai/DeepSeek-V3（可从硅基流动的'模型广场'查找）。
• 其他选项按回车接受默认。

完成添加后，会自动将模型写入配置。可以验证：

openclaw config get models.providers.siliconflow 

输出应包含 baseUrl、apiKey、models 数组等信息。

3. 设置默认模型

虽然上一步设置了默认模型，但为了确保，可以手动指定：

openclaw models set siliconflow/deepseek-ai/DeepSeek-V3 

如果模型 ID 格式正确，会提示配置文件已更新。

退出容器：exit

4. 重启容器使配置生效

docker restart openclaw 

重启后，查看日志确认模型已切换：

docker logs openclaw --tail 20 | grep "agent model"

应输出类似：

[gateway] agent model: siliconflow/deepseek-ai/DeepSeek-V3 

测试 AI 对话

回到浏览器 http://localhost:18789，进入 Chat 页面。在输入框中发送任意消息，Agent 应该会调用硅基流动的模型进行回复。如果出现错误，请检查：

• 硅基流动账户是否有余额（新注册用户通常有免费额度）。
• API 密钥是否有效，是否被泄露（如有泄露请立即吊销并重新生成）。
• 控制台日志：docker logs openclaw --tail 50 查看详细错误。

常见问题与解决方案

容器启动后立即退出

• 原因：启动命令中未保持前台进程，或配置缺失导致网关退出。
• 解决：使用本教程提供的命令（直接运行 openclaw gateway run，不加 sh -c 和后台符）。

连接时提示 pairing required 但 devices list 为空

• 原因：没有触发配对请求，或 token 不正确。
• 解决：在浏览器中清除站点数据（LocalStorage），重新填入 token 并点击 Connect，同时实时监控日志 docker logs -f openclaw，观察是否有配对码出现。也可尝试重启容器。

配置模型时出现 Config validation failed 错误

• 原因：手动设置提供商配置时缺少 models 字段。
• 解决：使用 openclaw models auth add 交互式添加，会自动生成正确结构。

发送消息后返回 HTTP 403

• 原因：默认模型仍为 Anthropic，或硅基流动 API 密钥无效/余额不足。
• 解决：确保 gateway.agent.model 已改为硅基流动的模型 ID，并检查密钥有效性。

如何更新 OpenClaw 版本？

• 进入容器：docker exec -it openclaw sh
• 运行：openclaw update
• 退出并重启：docker restart openclaw

安全提醒

• API 密钥保护：切勿将密钥明文分享或提交到公开代码库。
• 定期轮换：建议每隔一段时间更换 API 密钥，降低风险。
• 数据持久化：使用 Docker 卷（-v openclaw-data:/data）确保配置和状态不会因容器删除而丢失。

通过以上步骤，你应该能在 macOS 上成功运行 OpenClaw，并连接到硅基流动的 AI 模型。现在你可以开始探索 OpenClaw 的更多功能，如连接聊天频道、管理 Agent 等。如果遇到其他问题，欢迎查阅官方文档或社区支持。