macOS 本地部署 OpenClaw 智能体框架指南

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 地址，否则浏览器安全策略会阻止连接。

设备配对

即使 Token 正确，首次连接也需手动批准设备。

1. 查看待配对设备

进入容器内部：

docker exec -it openclaw sh

运行列表命令：

openclaw devices list

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

2. 批准设备

使用请求 ID 或设备 ID 进行批准：

openclaw devices approve <请求 ID>

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

[图示：Web 控制台连接成功状态]

配置 AI 模型提供商

默认使用 Anthropic 的 Claude 模型，国内用户建议配置硅基流动（SiliconFlow）API。

1. 获取 API 密钥

注册/登录硅基流动控制台，在账户管理中生成以 sk- 开头的密钥，妥善保存。

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

进入容器：

docker exec -it openclaw sh

运行交互式命令：

openclaw models auth add

按提示操作：

• Token provider：选择 custom。
• 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

3. 设置默认模型

为确保生效，可手动指定：

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

退出容器并重启使配置生效：

exit
docker restart openclaw

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

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

应输出类似：[gateway] agent model: siliconflow/deepseek-ai/DeepSeek-V3

测试对话

回到浏览器 http://localhost:18789，进入 Chat 页面。在输入框发送任意消息，Agent 应该会调用硅基流动的模型进行回复。

如果报错，请检查：

• 硅基流动账户是否有余额。
• API 密钥是否有效。
• 控制台日志：docker logs openclaw --tail 50 查看详细错误。

[图示：AI 对话界面示例]

常见问题排查

1. 容器启动后立即退出

• 原因：启动命令未保持前台进程。
• 解决：使用教程提供的命令，直接运行 openclaw gateway run。

2. 连接时提示 pairing required 但设备列表为空

• 原因：未触发配对请求或 Token 不正确。
• 解决：清除浏览器站点数据，重新填入 Token 并点击 Connect，同时实时监控日志 docker logs -f openclaw。

3. 配置模型时报错 Config validation failed

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

4. 发送消息返回 HTTP 403

• 原因：默认模型仍为 Anthropic 或 API 密钥无效。
• 解决：确保 gateway.agent.model 已改为硅基流动的模型 ID。

5. 如何更新版本？

进入容器运行 openclaw update，然后重启容器即可。

安全提醒

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

通过以上步骤，你应该能在 macOS 上成功运行 OpenClaw，并连接到 AI 模型。现在你可以开始探索更多功能，如连接聊天频道、管理 Agent 等。