在 macOS 上通过 Docker 本地安装 OpenClaw 完整教程

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw-data:/data \
  sgccr.ccs.tencentyun.com/openclaw/openclaw:latest \
  openclaw gateway run --bind lan --port 18789 --allow-unconfigured 

参数解释：

• -d：后台运行容器。
• --name openclaw：给容器命名，方便后续操作。
• -p 18789:18789：将容器的 18789 端口映射到本机，用于访问 Web 控制台。
• -v openclaw-data:/data：创建一个 Docker 卷 openclaw-data，挂载到容器内的 /data 目录，用于持久化配置和状态。
• openclaw gateway run ...：容器启动后执行的命令，以网关模式运行，监听所有网络接口（--bind lan），端口 18789，允许未完全配置的状态下启动（--allow-unconfigured）。

验证容器运行：

docker ps

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

3. 首次访问控制台并获取 Token

3.1 打开控制台

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

3.2 获取初始 Token

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

docker logs openclaw | grep -i token 

你应该看到类似：

auth token was missing. Generated a new token and saved it to config (gateway.auth.token). 

但日志中并不会直接打印 Token 值，需要用命令从配置中读取：

docker exec openclaw openclaw config get gateway.auth.token 

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

3.3 填入 Token 并尝试连接

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

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

4. 设备配对（解决 pairing required）

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

4.1 查看待配对设备

进入容器：

docker exec -it openclaw sh

运行：

openclaw devices list 

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

Pending (2) ┌──────────────────────────────────────┬───────────────────────────────────┬──────────┬──────────────┐ │ Request │ Device │ Role │ IP │ ├──────────────────────────────────────┼───────────────────────────────────┼──────────┼──────────────┤ │ a66fb94c-***-***2c4c21241c72 │ d53730f4722d2f9867ff6f0bbb70d2f8... │ operator │ 192.168.65.1 │ 

4.2 批准设备

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

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

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

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

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

5. 配置 AI 模型提供商（以硅基流动为例）

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

5.1 获取硅基流动 API 密钥

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

5.2 在 OpenClaw 中添加自定义模型提供商

进入容器：

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 数组等信息。

5.3 设置默认模型

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

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

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

退出容器：exit

5.4 重启容器使配置生效

docker restart openclaw 

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

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

应输出类似：

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

6. 测试 AI 对话

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

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

7. 常见问题与解决方案

7.1 容器启动后立即退出

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

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

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

7.3 配置模型时出现 Config validation failed: models.providers.siliconflow.models: expected array

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

7.4 发送消息后返回 HTTP 403

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

7.5 如何更新 OpenClaw 版本？

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

8. 安全提醒

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

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