OpenClaw（原名 Clawdbot / Moltbot）是一个受到开发者关注的开源 AI Agent 平台。它可以在本地运行，通过 Telegram、WhatsApp、Discord 等多种渠道与用户交互，并执行复杂的自动化任务。

如果直接在本机安装 OpenClaw，AI Agent 将获得对主机文件系统和网络的访问权限。出于安全考虑，使用 Docker 容器化部署通常是更稳妥的选择。

适用场景判断

开始之前，先根据官方文档判断 Docker 部署是否适合你的场景：

环境准备

先决条件

• Docker Desktop（macOS/Windows）或 Docker Engine（Linux）
• Docker Compose v2
• 足够的磁盘空间存放镜像和日志

克隆仓库

git clone https://github.com/openclaw/openclaw
cd openclaw

快速部署（推荐方式）

OpenClaw 提供了一个一键启动脚本 docker-setup.sh，它能自动完成以下工作：

• 构建 Gateway 镜像
• 运行入门引导（Onboarding Wizard）
• 输出 Provider 配置提示
• 通过 Docker Compose 启动 Gateway
• 生成 Gateway Token 并写入 .env 文件

./docker-setup.sh

脚本执行后，将在宿主机上创建两个关键目录，并以 Volume 的方式挂载到容器内：

Onboarding 向导要点

首次运行时，OpenClaw 会提出一系列配置问题。以下是几个容易踩坑的选项：

Onboarding 模式

选择 manual，这样可以完全控制每一步配置。

Gateway 类型

选择 Local gateway (this machine)，适用于大多数 Docker 部署场景。

模型 Provider

推荐 OpenAI Codex with ChatGPT OAuth。这种方式的优势在于：

• 使用已有的 ChatGPT 订阅（如 $20/月 Plus 套餐）对应的 Token 配额
• 为 Agent 的 Token 消耗设定自然上限，避免 API 账单失控

OAuth 认证流程： OpenClaw 会输出一个 URL，在浏览器中打开后会重定向到一个未运行的 localhost 服务地址并显示错误——这是正常现象。只需将浏览器地址栏中的完整 localhost URL 复制粘贴回 OpenClaw 的终端即可完成认证。

Tailscale

除非有明确的远程访问需求，建议选择 No。启用 Tailscale 可能导致网络配置问题。

Shell Helpers（可选但推荐）

官方提供了 ClawDock Shell 辅助工具，可以大幅简化日常操作：

安装

mkdir -p ~/.clawdock && curl -sL \
  https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh \
  -o ~/.clawdock/clawdock-helpers.sh

加载到 Shell

# zsh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

# bash
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.bashrc && source ~/.bashrc

核心命令

Web Dashboard 访问

OpenClaw 的 Web UI 默认监听 18789 端口。但直接访问 http://localhost:18789 通常会提示需要认证。

获取 Dashboard URL

docker compose run --rm openclaw-cli dashboard --no-open

该命令会输出可访问 Dashboard 的链接（在部分版本中会带 ?token=... 参数），在浏览器打开即可。

处理 “Pairing Required” 错误

这是 Docker 部署中较常见的问题。打开 Dashboard 后可能看到如下错误：

disconnected (1008): pairing required

原因分析： 浏览器作为一个新设备连接到 OpenClaw Gateway，需要先完成设备配对审批。

方法一：使用 CLI 管理配对（官方推荐）

# 列出待配对的设备
docker compose run --rm openclaw-cli devices list

# 审批指定设备
docker compose run --rm openclaw-cli devices approve <requestId>

方法二：直接在 Gateway 容器中操作

如果 openclaw-cli 容器遇到问题，可以直接在 Gateway 容器中执行：

# 列出设备
docker compose exec openclaw-gateway \
  node dist/index.js devices list

# 审批设备（使用输出中的 Request ID）
docker compose exec openclaw-gateway \
  node dist/index.js devices approve <REQUEST_ID>

解决 Token Mismatch 问题（Ubuntu 部分环境）

这是在部分 Ubuntu 环境中可能遇到的更深层问题。按上述方法执行 devices list 时，可能出现以下错误：

gateway connect failed: Error: unauthorized: gateway token mismatch
(set gateway.remote.token to match gateway.auth.token)

根因分析（社区案例）

在部分 Ubuntu + Docker 环境中，容器内 CLI 可能无法正确读取 openclaw.json 中的 Gateway Token，进而触发 token mismatch。该问题更多来自社区实践反馈，官方文档未将其定义为通用必现问题。

五步修复方案

第一步：找到宿主机上的 Gateway Token

cat ~/.openclaw/openclaw.json | grep -A5 '"auth"'

记下 gateway.auth 下的 token 值。

第二步：验证容器内的 Token 是否一致

# 获取容器 ID
docker ps

# 查看容器内的 token
docker exec -it <CONTAINER_ID> \
  cat /home/node/.openclaw/openclaw.json | grep -A5 '"auth"'

两端的 Token 应该一致。如果不一致，那就是问题所在。

第三步：使用环境变量覆盖方式列出设备

关键操作——使用 docker exec -e 注入 Token 环境变量：

docker exec -e OPENCLAW_GATEWAY_TOKEN=<YOUR_TOKEN> -it <CONTAINER_ID> \
  node dist/index.js devices list

这会输出待审批的设备列表，类似这样：

Pending (1)
┌──────────────────────────────────────┬──────────┬────────────┬────────┐
│ Request                              │ Role     │ IP         │ Age    │
├──────────────────────────────────────┼──────────┼────────────┼────────┤
│ 6f9db1bd-a1cc-4d3f-b643-2c195262464e │ operator │ 172.18.0.1 │ 2m ago │
└──────────────────────────────────────┴──────────┴────────────┴────────┘

第四步：审批待配对设备

docker compose exec openclaw-gateway \
  node dist/index.js devices approve <REQUEST_ID>

成功后会输出：Approved <device_id>

第五步：验证

在浏览器中刷新 http://localhost:18789，pairing required 错误应消失，Dashboard 可正常加载。

Token Mismatch 的一行速查命令

docker exec -e OPENCLAW_GATEWAY_TOKEN=<YOUR_TOKEN> -it <CONTAINER_ID> \
  node dist/index.js devices list

注意： 在出现 token mismatch 时，可优先尝试通过环境变量（如 OPENCLAW_GATEWAY_TOKEN）临时覆盖。命令行参数方式（如 --gateway.remote.token=...）通常会报 unknown option。若你的环境未出现该问题，优先使用官方推荐的 openclaw-cli devices list/approve 流程即可。

高级配置

docker-setup.sh 运行时会自动读取项目根目录下的 .env 文件。相比逐行 export 环境变量，把配置集中写入 .env 更清晰、可维护，也便于持久化：

# .env（在 openclaw 仓库根目录下创建或编辑）

# 挂载额外宿主机目录到容器内（格式：source:target[:options]，逗号分隔）
OPENCLAW_EXTRA_MOUNTS=$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw

# 持久化容器 /home/node 目录，避免重建后丢失数据
OPENCLAW_HOME_VOLUME=openclaw_home

# 预装系统包，烘焙到镜像中（空格分隔）
OPENCLAW_DOCKER_APT_PACKAGES=ffmpeg build-essential ripgrep

配置完成后，只需运行一条命令即可生效：

./docker-setup.sh

注意事项：

• OPENCLAW_EXTRA_MOUNTS 每项格式为 source:target[:options]，不能包含空格、Tab 或换行
• macOS/Windows 上挂载的路径需先在 Docker Desktop 中设置为共享目录
• 修改 .env 后需重新运行 docker-setup.sh 使配置生效
• docker-setup.sh 会根据 .env 自动生成 docker-compose.extra.yml，无需手动编辑

如果不想重建镜像，也可以在运行中的容器里以 root 身份临时安装软件包（重启后丢失）：

docker compose exec -u root openclaw-gateway bash
apt-get update && apt-get install -y ripgrep

消息通道配置

OpenClaw 支持多种消息平台，包括 Telegram、Discord、WhatsApp 等。以 Telegram 为例：

1. 在 Telegram 中找到 @BotFather，发送 /newbot 创建机器人
2. 获取 Bot Token
3. 在 OpenClaw 中配置：

docker compose run --rm openclaw-cli channels add --channel telegram --token "<BOT_TOKEN>"

4. 完成配对审批：

docker compose run --rm openclaw-cli pairing approve telegram <CODE>

配置完成后，你就可以直接在手机上的 Telegram 与 OpenClaw Agent 交互。

健康检查

docker compose exec openclaw-gateway \
  node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

常见问题排查

参考资源

• OpenClaw 官方 Docker 文档
• Simon Willison: Running OpenClaw in Docker
• Rik Banerjee: Fixing OpenClaw Docker’s “Pairing Required” Dead End on Ubuntu
• ClawDock Shell Helpers README

关于

📬 关注我获取更多资讯

📢 公众号

💬 个人号