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

验证容器运行：

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

到此这篇关于macOS系统上通过Docker本地安装OpenClaw的文章就介绍到这了,更多相关Docker本地安装OpenClaw内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！