Docker 部署 OpenClaw：从零到“懂你”的 AI 助理OpenClaw：从零到“懂你”的 AI 助理引言

通过 Docker 部署 OpenClaw：从零到“懂你”的 AI 助理

引言

OpenClaw 是一个开源、本地优先、可深度定制的 AI 代理。与普通的云端 AI（如 ChatGPT）不同，OpenClaw 拥有持久的本地记忆、对系统的实际执行权限，并且可以通过“技能”无限扩展能力。它真正有可能成为你的“数字分身”——一个既懂你、又能帮你操作电脑的智能助理。

我使用的是 MacBook Air M4 芯片，希望通过 Docker 方式部署 OpenClaw，既保证环境隔离，又便于管理。本文将详细记录我在 M4 Mac 上部署 OpenClaw 的全过程，包括环境准备、安装步骤、配置技巧、常见的“令牌不匹配”问题，以及如何优化 CLI 命令避免每次输入 token。

一、环境准备

硬件：MacBook Air (M4 芯片，16GB 内存，512GB 存储)
操作系统：macOS Sequoia 15.3.1
软件：
- Docker Desktop for Mac（最新版，支持 Apple Silicon）
- Git（通常 macOS 自带，可执行 git --version 确认）
- （可选）Homebrew，用于安装一些辅助工具
网络：由于 Docker 镜像拉取可能较慢，建议提前配置国内镜像加速器（见下文）。
API 密钥：如果你计划使用通义千问（Qwen）等模型，需要提前在阿里云百炼平台申请 API Key，并领取免费额度。后续在配置向导中会用到。

二、Docker 环境配置

2.1 安装 Docker Desktop

访问 Docker 官网，下载 Mac with Apple Chip 版本。
双击安装，将 Docker 拖入 Applications 文件夹。
从 Launchpad 启动 Docker，等待顶部菜单栏的鲸鱼图标变绿，表示 Docker 引擎已运行。

2.2 配置镜像加速器（推荐）

国内访问 Docker Hub 速度较慢，配置镜像加速可以大幅提升拉取速度。

编辑（或新建）~/.docker/daemon.json，添加以下内容：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

保存后，重启 Docker：点击菜单栏 Docker 图标 → Restart。

2.3 验证 Docker 与 Docker Compose

打开终端，执行：

docker --version
docker compose version

确保两条命令都能正常输出版本信息（注意新版 Docker 使用 docker compose 空格，而非旧版的 docker-compose）。

2.4 处理 Rosetta 问题（M1/M2/M4 用户）

安装过程中可能会遇到 Failed to install Rosetta 的报错，这通常不影响使用。如果担心，可以手动安装 Rosetta：

softwareupdate --install-rosetta --agree-to-license

或者在 Docker Desktop 的设置中勾选 “Use Rosetta for x86/amd64 emulation on Apple Silicon”。

三、克隆 OpenClaw 仓库

为了保持目录清晰，我在 ~/Developer 下存放所有开发项目：

mkdir -p ~/Developer
cd ~/Developer
git clone https://github.com/openclaw/openclaw.git

如果遇到网络问题（如 RPC failed），可以尝试：

设置 Git 代理（如果你有代理客户端）
强制 Git 使用 HTTP/1.1：git config --global http.version HTTP/1.1
使用镜像加速克隆：git clone https://githubproxy.cc/openclaw/openclaw.git

克隆完成后，进入项目目录：

cd openclaw

四、运行安装脚本

执行以下命令启动安装流程：

sh docker-setup.sh

脚本会做两件事：

构建 OpenClaw 的 Docker 镜像（可能需要几分钟，取决于网络）。
进入交互式配置向导（Wizard）。

可能遇到的问题：镜像拉取超时

如果看到类似 i/o timeout 的错误，说明镜像拉取失败。请检查：

Docker 镜像加速器是否配置正确。
网络是否稳定。可以尝试手动拉取基础镜像：docker pull node:22-bookworm。

五、配置向导详解

向导会依次询问多个配置项，以下是关键选择：

5.1 模型选择

选择你希望使用的 AI 模型。我选择的是 “千问”（通义千问），因为它在中文任务上表现优秀，并且阿里云百炼提供免费额度。

接下来会要求填写 API 密钥。将你在阿里云百炼创建的 API Key 粘贴进去。

⚠️ 重要坑点：之后需要手动修改配置文件，将模型的 reasoning 参数设为 false，否则网关启动会失败。我们会在第七章详细说明。

5.2 聊天通道

向导会列出 Telegram、WhatsApp、iMessage 等多种接入方式。由于我们打算通过 Web 界面直接使用，这里选择 Skip for now。

5.3 技能依赖

同样选择 Skip for now。核心聊天功能已经可用，技能可以后续按需安装。

5.4 Hooks（钩子）

这里务必选择 session-memory！这是开启长期记忆的关键，让 AI 能跨会话记住你的信息。其他钩子可根据需要勾选，我暂时只选了 session-memory。

5.5 其他可选配置

如 Google Places API 等，可根据需求填写或跳过。

配置完成后，脚本会启动 OpenClaw 网关服务，并显示一些信息，包括访问令牌（Token）、配置目录等。请务必保存好这个令牌，例如：

Token: your_gateway_token

六、网关启动与配置文件调整

首次启动后，网关可能无法正常运行，需要根据日志调整配置文件。

6.1 查看网关状态

cd ~/Developer/openclaw
docker compose ps

如果 openclaw-gateway-1 的状态是 Restarting，说明启动失败，需要查看日志：

docker compose logs openclaw-gateway

6.2 常见错误及解决

错误 1：Control UI 安全限制

日志中出现：

Error: non-loopback Control UI requires gateway.controlUi.allowedOrigins...

原因：网关检测到可能暴露给外部网络，要求明确指定允许的来源。

解决：编辑配置文件 ~/.openclaw/openclaw.json，在 gateway 段添加：

"controlUi": {
  "allowedOrigins": ["http://localhost:18789", "http://127.0.0.1:18789"]
}

错误 2：绑定地址导致其他容器无法连接

日志可能没有直接报错，但 CLI 工具（如 devices list）无法连接网关，出现 gateway closed (1006)。原因是配置中的 "bind": "loopback" 让网关只监听容器内的 127.0.0.1，导致其他容器无法通过服务名访问。

解决：将 bind 改为 local（或直接删除该行，默认即为 local）：

"bind": "local"

错误 3：令牌不匹配（token mismatch）

这是最常见的认证问题，表现为：

Web 界面连接时提示 unauthorized: gateway token mismatch
CLI 命令报 gateway token mismatch (set gateway.remote.token to match gateway.auth.token)

根本原因：OpenClaw 需要同时设置服务端令牌（auth.token）和客户端令牌（remote.token），且两者必须一致。默认配置中可能缺少 remote.token。

解决步骤：

打开 ~/.openclaw/openclaw.json。

找到 gateway 部分，确保存在以下两个字段，值相同：

"auth": {
  "mode": "token",
  "token": "your_gateway_token"
},
"remote": {
  "token": "your_gateway_token"
}

保存文件，重启网关：

docker compose restart openclaw-gateway

为什么需要 remote.token？
OpenClaw 的设计将服务端和客户端令牌分离，为将来实现多客户端、不同权限的管理做准备。当前版本只需将两者设为相同即可。

6.3 验证千问模型的 `reasoning` 参数

在 ~/.openclaw/openclaw.json 中找到 models 部分，确保你添加的千问模型配置中 reasoning 为 false：

{
  "id": "qwen3-max-2026-01-23",
  "name": "qwen3-max-2026-01-23",
  "reasoning": false,
  ...
}

如果不设置，网关可能无法正常响应。

6.4 重启网关并验证

完成上述修改后，重启网关：

docker compose down
docker compose up -d

再次查看状态，应为 Up。

七、CLI 命令的优化之路：从 `oclaw` 到 `oclaw-gw`

安装完成后，我们不可避免地需要通过命令行管理 OpenClaw，例如查看设备配对、安装技能等。OpenClaw 提供了 CLI 工具，但使用起来有一些“坑”。

7.1 初次尝试：创建 `oclaw` 别名

官方推荐通过 docker compose run --rm openclaw-cli 来执行 CLI 命令。为了方便，我首先在 ~/.zshrc 中创建了别名：

alias oclaw='cd ~/Developer/openclaw && docker compose run --rm openclaw-cli'

然后执行 oclaw devices list。但结果令人沮丧：

[openclaw] CLI failed: Error: gateway closed (1006 abnormal closure (no close frame)): no close reason
Gateway target: ws://127.0.0.1:18789
...

7.2 问题分析：网络隔离

错误信息显示 CLI 容器尝试连接 ws://127.0.0.1:18789。但在容器内部，127.0.0.1 指向的是 CLI 容器自身，而不是运行着网关的另一个容器。因此网络不通，导致连接失败。

7.3 发现可靠的替代方案：直接在网关容器内执行命令

通过查看 Docker 容器状态，我发现网关容器 openclaw-gateway-1 一直正常运行。既然 CLI 工具本身也是 Node.js 脚本，为何不直接在网关容器内调用呢？

测试命令（成功！）：

docker compose -f ~/Developer/openclaw/docker-compose.yml exec openclaw-gateway node dist/index.js devices list --token "your_gateway_token"

终于看到了正确的输出（设备列表为空）。于是我又创建了第二个别名：

alias oclaw-gw='docker compose -f ~/Developer/openclaw/docker-compose.yml exec openclaw-gateway node dist/index.js'

现在可以用 oclaw-gw devices list --token <token> 来管理了。

7.4 进一步优化：告别每次输入 token

每次都要手动输入 --token 依然繁琐。我决定将 token 存入文件，并让 oclaw-gw 自动读取。

步骤：

创建 token 文件并设置权限：

echo "your_gateway_token" > ~/.openclaw/token
chmod 600 ~/.openclaw/token

将别名改为函数，从文件读取 token：

oclaw-gw() {
  local token_file="$HOME/.openclaw/token"
  if [[ ! -f "$token_file" ]]; then
    echo "Error: Token file not found at $token_file" >&2
    return 1
  fi
  local token=$(cat "$token_file" | tr -d '\n')
  docker compose -f "$HOME/Developer/openclaw/docker-compose.yml" exec openclaw-gateway node dist/index.js "$@" --token "$token"
}

由于之前已经定义了别名 oclaw-gw，需要先删除别名才能定义同名函数：
```
unalias oclaw-gw   # 移除别名
```
然后将上述函数添加到 ~/.zshrc，替换原来的别名行。
重新加载配置：
```
source ~/.zshrc
```

现在，一切变得无比丝滑：

oclaw-gw devices list
oclaw-gw skills list
oclaw-gw health

不再需要手动输入 token，而且命令简洁优雅。

7.5 为什么不用环境变量？

我最初尝试通过环境变量 OPENCLAW_GATEWAY 指定网关地址，但发现 CLI 工具并不读取该变量（或配置文件优先级更高）。exec 方式直接绕过了网络隔离，是最可靠的。

7.6 给其他用户的建议

如果你的 oclaw 别名（基于 run）能够正常工作，恭喜你！但多数用户会遇到网络问题，此时 oclaw-gw 是最佳选择。
将 token 存入文件并创建自动附加参数的函数，能极大提升使用体验。
记得在修改 .zshrc 后执行 source ~/.zshrc，并确保没有别名与函数冲突（可用 unalias 解决）。

八、Web 界面连接与最终成功

8.1 访问 Web 界面

浏览器打开 http://127.0.0.1:18789，你会看到 OpenClaw 的仪表板概览页。

8.2 首次连接：配对流程

点击页面上的 “连接” 按钮，可能会提示 pairing required，而不是直接要求输入令牌。这是 OpenClaw 的安全配对机制。

此时需要批准配对请求：

在终端查看待处理请求（使用我们刚刚优化好的命令）：
```
oclaw-gw devices list
```
输出中会有一个请求 ID，例如 0f7ee8dd-a397-4b0c-b4c4-1a88b0e211a0。

批准该请求：

oclaw-gw devices approve 0f7ee8dd-a397-4b0c-b4c4-1a88b0e211a0

返回浏览器，页面应自动连接成功，右上角显示“已连接”。如果没有自动刷新，可以手动刷新页面。

8.3 初次对话

连接成功后，点击左侧的 “聊天”，你会看到一个对话界面。AI 会主动打招呼，并询问你的称呼、希望它扮演的角色等。这正是它开始建立长期记忆的第一步。

你可以这样回复：

“我叫小明，希望你叫我小助手。”
“你的风格可以幽默一些，表情符号就用 🦞 吧。”

AI 会将这些信息存入记忆，后续对话中会记得。

九、体验与进阶配置

9.1 技能安装

技能是 OpenClaw 扩展功能的“插件”。你可以通过 Web 界面的 “技能” 页面浏览和安装，也可以使用 CLI：

oclaw-gw skills install github

9.2 记忆管理

所有记忆都存储在 ~/.openclaw/memory/ 目录下，以纯文本 Markdown 文件形式存在。你可以直接查看、编辑甚至删除，完全透明可控。

9.3 多通道接入

如果你希望在其他平台（如 Telegram）使用 OpenClaw，可以在 Web 界面的 “频道” 中配置。需要创建 Bot 并获取 Token。

十、常见问题排错指南

问题	可能原因	解决方案
镜像拉取超时	网络慢，无镜像加速	配置国内镜像加速器，或手动拉取基础镜像
Rosetta 安装失败	系统虚拟化组件问题	忽略或手动安装 Rosetta，Docker 中开启 Rosetta 支持
网关容器反复重启	配置文件错误	查看日志，检查 JSON 格式、`reasoning` 参数、`allowedOrigins` 等
`oclaw` 命令报 `gateway closed (1006)`	网络隔离，CLI 容器找不到网关	改用 `oclaw-gw`（基于 `exec`）直接在网关容器内执行命令
Web 界面无法连接，提示 `pairing required`	首次连接需配对	通过 `oclaw-gw devices list` 查看并批准待处理请求
令牌不匹配（mismatch）	缺少 `remote.token` 或两者不一致	在配置文件中添加 `remote.token`，值与 `auth.token` 相同，重启网关
AI 无回复或报错	API Key 无效、模型 ID 错误、`reasoning` 未设为 false	检查 API Key 和模型配置，确认 `reasoning: false`

十一、总结与展望

在 MacBook Air M4 上通过 Docker 部署 OpenClaw 虽然有些曲折，但最终成功后的体验是值得的。OpenClaw 不仅仅是一个聊天机器人，它拥有长期记忆、可执行系统操作、可无限扩展技能，真正有望成为你的“数字助理”。

部署心得

耐心是关键：配置文件需要手动调整几个关键点，尤其是 remote.token 和 reasoning。
善用日志：遇到问题先看 docker compose logs，大部分错误都能在日志中找到线索。
安全第一：OpenClaw 拥有较高权限，建议在备用机或隔离环境中使用，避免安装来路不明的技能。
CLI 优化：通过 oclaw-gw 函数和 token 文件，日常管理变得轻松愉快。

未来可玩性

你可以教会 OpenClaw 处理日常事务，如整理文件、管理项目、发送邮件。
社区不断涌现新技能，从控制智能家居到自动生成周报，想象力无限。
结合 Hooks，你可以定制自己的自动化工作流。

致谢

感谢 OpenClaw 开发团队的辛勤工作，以及社区的分享。本文所有步骤均基于 OpenClaw 2026.2.23 版本，未来版本可能会有变化，请以官方文档为准。

附录

常用命令速查（基于 `oclaw-gw`）

# 查看设备配对请求
oclaw-gw devices list

# 批准配对请求
oclaw-gw devices approve <requestId>

# 列出所有技能
oclaw-gw skills list

# 安装技能
oclaw-gw skills install <skill-name>

# 查看网关健康状态
oclaw-gw health

# 列出所有会话
oclaw-gw sessions list

配置文件示例（脱敏）

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "local",
    "auth": {
      "mode": "token",
      "token": "your_gateway_token"
    },
    "remote": {
      "token": "your_gateway_token"
    },
    "controlUi": {
      "allowedOrigins": ["http://localhost:18789", "http://127.0.0.1:18789"]
    },
    "tailscale": {
      "mode": "off"
    }
  },
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "your_api_key",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-max-2026-01-23",
            "name": "qwen3-max-2026-01-23",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 262144,
            "maxTokens": 65536
          }
        ]
      }
    }
  }
}

参考链接

OpenClaw 官网：openclaw.ai
GitHub 仓库：github.com/openclaw/op…
阿里云百炼：bailian.console.aliyun.com
Docker 镜像加速器配置：docs.docker.com/registry/re…

希望这篇博客能帮助你在 MacBook Air M4 上顺利部署 OpenClaw，并避开我在 CLI 优化上踩过的坑。如果在安装过程中还有任何疑问，欢迎在评论区留言讨论。

Docker 部署 OpenClaw：从零到“懂你”的 AI 助理