在 macOS 上通过 Docker 本地安装 OpenClaw 完整教程
在 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 官方镜像托管在腾讯云容器镜像服务上，执行以下命令拉取最新版：
docker pull sgccr.ccs.tencentyun.com/openclaw/openclaw:latest 2. 启动 OpenClaw 容器
使用以下命令运行容器（注意替换容器名，这里我们用 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）。
验证容器运行：
dockerps输出应显示 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 值，需要用命令从配置中读取：
dockerexec 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 查看待配对设备
进入容器：
dockerexec -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 密钥
- 注册/登录 硅基流动控制台。
- 在“账户管理” -> “API 密钥”中，点击“新建 API 密钥”，生成一个以
sk-开头的密钥，复制并妥善保存（注意保密，不要泄露）。
5.2 在 OpenClaw 中添加自定义模型提供商
进入容器：
dockerexec -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 等。如果遇到其他问题，欢迎查阅官方文档或社区支持。
