使用Docker部署OpenClaw完整指南

前置准备#

软件要求#

确保服务器上已安装 Docker 和 Docker Compose：

1
# 检查 Docker 版本
2
docker --version
3

4
# 检查 Docker Compose 版本
5
docker compose version

如果尚未安装，可以看我前面的教程：Linux安装Docker完整教程

部署步骤#

步骤 1：创建目录结构#

1
# 创建主目录
2
mkdir -p /data/openclaw
3

4
# 创建 OpenClaw 配置和工作区目录
5
mkdir -p /data/openclaw/.openclaw/workspace
6

7
# 设置正确的所有权
8
# UID 1000 是容器内 node 用户的 UID，确保容器有读写权限
9
sudo chown -R 1000:1000 /data/openclaw/.openclaw

为什么是 1000:1000？

OpenClaw 官方镜像使用 node 用户运行（UID 1000）。如果宿主机目录权限不匹配，容器内将无法写入配置，导致启动失败。

步骤 2：生成 Token#

1
# 生成 256 位（32 字节）随机 token
2
openssl rand -hex 32
3
# 示例输出: a1b2c3d4e5f6...

步骤 3：创建环境变量文件#

1
cat > /data/openclaw/.env <<'EOF'
2
# ========================================
3
# 镜像配置
4
# ========================================
5
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
6

7
# ========================================
8
# 安全配置
9
# ========================================
10
# Gateway 认证 Token，请替换为步骤 2 生成的值
11
OPENCLAW_GATEWAY_TOKEN=<你的随机token>
12

13
# Gateway 绑定模式
14
# - lan: 监听所有局域网接口（0.0.0.0）
15
# - local: 仅监听本地回环（127.0.0.1）
16
OPENCLAW_GATEWAY_BIND=lan
17

18
# ========================================
19
# 时区配置
20
# ========================================
21
OPENCLAW_TZ=Asia/Shanghai
22

23
# ========================================
24
# 目录配置
25
# ========================================
26
# 配置文件存储目录
27
OPENCLAW_CONFIG_DIR=/data/openclaw/.openclaw
28
# Agent 工作区目录
29
OPENCLAW_WORKSPACE_DIR=/data/openclaw/.openclaw/workspace
30

31
# ========================================
32
# 端口配置
33
# ========================================
34
# Gateway WebSocket 端口
35
OPENCLAW_GATEWAY_PORT=18789
36
# Bridge Server 端口
37
OPENCLAW_BRIDGE_PORT=18790
38
EOF

步骤 4：创建 Docker Compose 配置文件#

1
cat > /data/openclaw/docker-compose.yml <<'EOF'
2
services:
3
  # ========================================
4
  # Gateway 服务
5
  # ========================================
6
  openclaw-gateway:
7
    image: ${OPENCLAW_IMAGE}
8
    container_name: openclaw-gateway
9
    environment:
10
      # 容器内用户主目录
11
      HOME: /home/node
12
      # 终端类型（支持彩色输出）
13
      TERM: xterm-256color
14
      # Gateway 认证 Token
15
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
16
      # 时区
17
      TZ: ${OPENCLAW_TZ:-UTC}
18
    volumes:
19
      # 挂载配置目录
20
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
21
      # 挂载工作区目录
22
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
23
    ports:
24
      # Gateway WebSocket 端口
25
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
26
      # Bridge Server 端口
27
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
28
    # 使用 init 进程处理子进程和信号
29
    init: true
30
    # 重启策略：除非手动停止，否则自动重启
31
    restart: unless-stopped
32
    # 启动命令
33
    command:
34
      [
35
        "node",
36
        "dist/index.js",
37
        "gateway",
38
        "--bind",
39
        "${OPENCLAW_GATEWAY_BIND:-lan}",
40
        "--port",
41
        "18789",
42
      ]
43
    # 健康检查
44
    healthcheck:
45
      test:
46
        [
47
          "CMD",
48
          "node",
49
          "-e",
50
          "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
51
        ]
52
      interval: 30s    # 每 30 秒检查一次
53
      timeout: 5s       # 超时时间
54
      retries: 5        # 失败 5 次后标记为不健康
55
      start_period: 20s # 启动后 20 秒才开始检查
56

57
  # ========================================
58
  # CLI 管理容器
59
  # ========================================
60
  openclaw-cli:
61
    image: ${OPENCLAW_IMAGE}
62
    container_name: openclaw-cli
63
    # 共享 Gateway 的网络命名空间
64
    # 这样 CLI 可以通过 localhost 访问 Gateway
65
    network_mode: "service:openclaw-gateway"
66
    # 安全加固：移除不必要的网络权限
67
    cap_drop:
68
      - NET_RAW
69
      - NET_ADMIN
70
    security_opt:
71
      - no-new-privileges:true
72
    environment:
73
      HOME: /home/node
74
      TERM: xterm-256color
75
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
76
      # 禁用浏览器（CLI 不需要）
77
      BROWSER: echo
78
      TZ: ${OPENCLAW_TZ:-UTC}
79
    volumes:
80
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
81
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
82
    # 保持 STDIN 打开（支持交互式命令）
83
    stdin_open: true
84
    # 分配伪终端
85
    tty: true
86
    init: true
87
    # CLI 容器的入口点
88
    entrypoint: ["node", "dist/index.js"]
89
    # 依赖 Gateway 启动
90
    depends_on:
91
      - openclaw-gateway
92
EOF

步骤 5：初始化配置#

1
cd /data/openclaw
2

3
# 运行初始化向导
4
docker compose run --rm openclaw-cli onboard

步骤 5.1 配置 allowedOrigins#

由于我们使用了 OPENCLAW_GATEWAY_BIND=lan，需要在配置文件中明确允许的访问来源（CORS）：

1
# 使用文本编辑器修改配置文件
2
vim /data/openclaw/.openclaw/openclaw.json

在 gateway 配置中添加 controlUi.allowedOrigins：

1
{
2
 "gateway": {
3
  "controlUi": {
4
   "allowedOrigins": ["http://127.0.0.1:18789"]
5
  }
6
 }
7
}

步骤 6：启动服务#

1
# 启动 Gateway 服务
2
docker compose up -d openclaw-gateway
3

4
# 查看服务状态
5
docker compose ps
6

7
# 查看日志（如果启动失败）
8
docker compose logs -f openclaw-gateway

步骤 7：配置 SSH 隧道与控制面板访问#

步骤 7.1 建立 SSH 隧道#

1
# 基本语法
2
ssh -N -L 本地端口:目标主机:目标端口 用户名@服务器IP
3

4
# 示例：将本地 18789 端口转发到服务器的 127.0.0.1:18789
5
ssh -N -L 18789:127.0.0.1:18789 用户名@服务器IP

参数	说明
`-N`	不执行远程命令，仅做端口转发
`-L`	本地端口转发
`18789:127.0.0.1:18789`	本地端口:远程主机:远程端口

使用密钥认证（推荐）：

1
ssh -N -i ~/.ssh/your_key -L 18789:127.0.0.1:18789 用户名@服务器IP

步骤 7.2 访问控制面板#

SSH 隧道建立后，在本地浏览器打开：http://127.0.0.1:18789

输入之前生成的 OPENCLAW_GATEWAY_TOKEN 登录。

步骤 7.3 设备配对#

首次登录时，会遇到 pairing required 错误：

preview-1

这是 OpenClaw 的安全机制，需要手动批准连接请求。

在服务器上执行以下命令：

1
# 查看待处理的配对请求
2
docker compose exec openclaw-gateway openclaw devices list
3

4
# 批准最新的待处理请求
5
docker compose exec openclaw-gateway openclaw devices approve --latest

preview-2

devices 命令详解：

命令作用
devices list 列出所有待处理和已配对的设备
devices approve <id> 批准特定的配对请求
devices approve --latest 批准最新的待处理请求
devices remove <id> 移除已配对的设备
devices clear --yes 清除所有配对（危险！）

命令	作用
`devices list`	列出所有待处理和已配对的设备
`devices approve <id>`	批准特定的配对请求
`devices approve --latest`	批准最新的待处理请求
`devices remove <id>`	移除已配对的设备
`devices clear --yes`	清除所有配对（危险！）

批准后，刷新浏览器即可正常登录控制面板。

QQ 机器人接入#

步骤 1：创建 QQ 机器人#

访问 QQ 开放平台：

preview-3

点击创建机器人：

preview-4

步骤 2：安装 QQ 机器人插件#

1
docker compose exec openclaw-gateway openclaw plugins install @tencent-connect/openclaw-qqbot@latest

步骤 3：添加 QQ 机器人渠道#

1
# 注意：所有 openclaw 命令都需要在容器内执行
2
# 格式：docker compose exec <service> <command>
3

4
docker compose exec openclaw-gateway openclaw channels add --channel qqbot --token "AppID:AppSecret"

命令结构解析：

部分说明
docker compose exec 在运行的容器中执行命令
openclaw-gateway 目标服务名
openclaw channels add OpenClaw 添加渠道命令
--channel qqbot 指定渠道类型
--token 机器人凭据

部分	说明
`docker compose exec`	在运行的容器中执行命令
`openclaw-gateway`	目标服务名
`openclaw channels add`	OpenClaw 添加渠道命令
`--channel qqbot`	指定渠道类型
`--token`	机器人凭据

步骤 4：重启 Gateway 使配置生效#

1
docker compose exec openclaw-gateway openclaw gateway restart

或者直接重启容器：

1
docker compose restart openclaw-gateway

步骤 5：验证 QQ 机器人状态#

1
# 查看已配置的渠道
2
docker compose exec openclaw-gateway openclaw channels list
3

4
# 查看日志
5
docker compose logs -f openclaw-gateway | grep qqbot