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

什么是 OpenClaw？------ 你的本地 AI 智能体执行框架
OpenClaw 不仅仅是一个聊天机器人，而是一个功能强大的 AI 智能体执行框架。你可以把它想象成一个能自主思考、调用工具、并替你完成复杂任务的数字员工。

🧠 核心概念

智能体：OpenClaw 的核心大脑。它能理解你的自然语言指令，拆解任务，并决定调用哪些工具来执行。
网关：所有外部访问的入口。它负责处理 WebSocket 连接、管理设备配对、路由消息，是你与智能体交互的桥梁。
技能：智能体可调用的具体工具，比如访问文件、操作浏览器、发送消息、查询数据库等。你可以根据需要扩展技能库。
记忆：OpenClaw 可以存储对话历史和重要信息，实现长期记忆和上下文理解，让交互更连贯。
通道：连接外部聊天平台的渠道，如 WhatsApp、Telegram、Discord 等。你可以让智能体通过你熟悉的聊天应用与你交互。

🎯 它能做什么？

自动化任务：例如定时备份文件、自动整理下载文件夹、根据邮件内容回复、在日历上创建日程。
信息处理：从网页抓取数据、总结文档、翻译文本、生成报告。
系统交互：在授权下，它可以执行本地命令、管理文件、启动应用程序。
多平台连接：通过通道，你可以让智能体接入 Slack、Discord 等团队协作工具，成为团队中的 AI 成员。

🚀 为什么选择 OpenClaw？

本地运行：所有数据都在你自己的电脑上，无需上传到云端，隐私安全可控。
模型自由：支持多种 AI 模型提供商（如 OpenAI、Anthropic、硅基流动），甚至可以通过 Ollama 使用完全本地化的开源模型，零成本运行。
高度可扩展：通过插件和自定义技能，你可以让 OpenClaw 适应任何你想自动化的场景。
开源透明：代码公开，你可以审计其行为，确保安全。

⚠️ 安全提示

由于 OpenClaw 可以访问你的系统和数据，务必保护好你的 API 密钥和配对 Token。建议在隔离的环境中测试，并仔细审查其技能权限。

接下来，我们将一步步在 macOS 上通过 Docker 安装并配置 OpenClaw，让它真正成为你的个人 AI 助理。

1. 环境准备

1.1 安装 Docker Desktop for Mac

访问 Docker 官网下载 Docker Desktop for Mac（Intel 芯片或 Apple Silicon 根据你的 Mac 选择）。
安装完成后，启动 Docker，确认菜单栏出现 Docker 图标，并且终端运行 docker --version 能正常输出版本号。

1.2 拉取 OpenClaw 镜像

OpenClaw 官方镜像托管在腾讯云容器镜像服务上，执行以下命令拉取最新版：

bash 复制代码

docker pull sgccr.ccs.tencentyun.com/openclaw/openclaw:latest

2. 启动 OpenClaw 容器

使用以下命令运行容器（注意替换容器名，这里我们用 openclaw）：

bash 复制代码

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）。

验证容器运行：

bash 复制代码

docker ps

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

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

3.1 打开控制台

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

3.2 获取初始 Token

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

bash 复制代码

docker logs openclaw | grep -i token

你应该看到类似：

复制代码

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

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

bash 复制代码

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 查看待配对设备

进入容器：

bash 复制代码

docker exec -it openclaw sh

运行：

bash 复制代码

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（第一列）批准：

bash 复制代码

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

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

bash 复制代码

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

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

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

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

5.1 获取硅基流动 API 密钥

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

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

进入容器：

bash 复制代码

docker exec -it openclaw sh

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

bash 复制代码

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（可从硅基流动的"模型广场"查找）。
其他选项（如模型类型、是否设为默认）按回车接受默认。

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

bash 复制代码

openclaw config get models.providers.siliconflow

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

5.3 设置默认模型

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

bash 复制代码

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

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

退出容器：exit

5.4 重启容器使配置生效

bash 复制代码

docker restart openclaw

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

bash 复制代码

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 等。如果遇到其他问题，欢迎查阅官方文档或社区支持。

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