OpenClaw Docker 部署实战：从零到 QQ 机器人完整指南

一、环境准备

服务器要求

项目	要求
操作系统	Ubuntu 20.04 / 22.04 / 24.04
CPU	1 核以上
内存	建议 2GB+
磁盘	至少 10GB 可用空间
网络	公网 IP，开放 80/443 端口

实际资源占用参考（2核4G 服务器）：

• OpenClaw 容器：约 200-400MB 内存，CPU 占用 <1%
• Nginx：约 10MB 内存
• 系统总计：约 800MB / 3.8GB（21%），剩余充足

连接服务器

ssh ubuntu@<服务器IP> -p <SSH端口>

---

二、安装 Docker

# 1. 更新系统包
sudo apt update && sudo apt upgrade -y

# 2. 安装依赖
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# 3. 添加 Docker GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 4. 添加 Docker APT 源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 6. 将当前用户加入 docker 组
sudo usermod -aG docker $USER

# 7. 重新登录使组权限生效
exit

验证安装：

docker --version
docker run hello-world

---

三、部署 OpenClaw

1. 创建项目目录

mkdir -p ~/openclaw/config ~/openclaw/workspace

2. 生成认证 Token

openssl rand -hex 32

输出示例（保存好，后续访问需要用到）：

a1b2c3d4e5f6...（64位十六进制字符串）

3. 创建配置文件

nano ~/openclaw/config/openclaw.json

写入以下内容：

{
  "agents": {
    "defaults": {
      "workspace": "/home/node/.openclaw/workspace"
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "<你的Token>"
    },
    "controlUi": {
      "allowedOrigins": ["*"],
      "allowInsecureAuth": true
    }
  }
}

⚠️ 最新版本已不支持 auth.mode: "none"，必须使用 Token 认证。

4. 启动容器

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  --memory 1g \
  --memory-swap 1g \
  -v ~/openclaw/config:/home/node/.openclaw \
  -v ~/openclaw/workspace:/home/node/.openclaw/workspace \
  --restart unless-stopped \
  openclaw/openclaw:latest \
  openclaw gateway

参数说明：

• --memory 1g：内存上限 1GB，防止内存泄漏拖垮服务器
• -v ~/openclaw/config:/home/node/.openclaw：挂载配置目录
• -v ~/openclaw/workspace:/home/node/.openclaw/workspace：挂载工作空间（记忆、身份信息持久化）

5. 验证启动

docker ps | grep openclaw
docker logs openclaw --tail 10

预期看到 [gateway] ready 和 [heartbeat] started。

---

四、配置 Nginx 反代 + SSL 证书

背景

浏览器从 2024 年起强制要求 WebSocket 必须在 HTTPS 下建立。直接用 HTTP 访问会被阻止 WebSocket 连接。

1. DNS 解析

在域名管理面板添加 A 记录：

记录类型	主机记录	记录值
A	claw	<服务器IP>

验证：

nslookup claw.<你的域名>

2. 申请 Let's Encrypt 免费证书

sudo certbot certonly --nginx -d claw.<你的域名> \
  --non-interactive --agree-tos --email <你的邮箱>

3. 创建 Nginx 配置

sudo tee /etc/nginx/conf.d/claw.conf > /dev/null << 'EOF'
server {
    listen 443 ssl;
    server_name claw.<你的域名>;

    ssl_certificate /etc/letsencrypt/live/claw.<你的域名>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/claw.<你的域名>/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

server {
    if ($host = claw.<你的域名>) {
        return 301 https://$host$request_uri;
    }
    listen 80;
    server_name claw.<你的域名>;
    return 404;
}
EOF

4. 测试并重载

sudo nginx -t
sudo systemctl reload nginx

5. 开放防火墙

sudo ufw allow 80
sudo ufw allow 443

⚠️ 云服务器还需在安全组中放行 80 和 443 端口。

6. 验证访问

curl -sk -o /dev/null -w "HTTP %{http_code}" https://claw.<你的域名>/

返回 HTTP 200 即成功。

---

五、首次访问：设备配对

首次通过 HTTPS 访问时，浏览器会提示"设备配对"。

在服务器上执行：

# 从页面提示或服务器日志中获取 requestId
docker logs openclaw --tail 20 2>&1 | grep 'requestId'

# 批准请求
docker exec openclaw openclaw devices approve <requestId>

批准后刷新浏览器即可。

每个新浏览器/新设备首次访问都需要批准一次。

---

六、配置 AI 模型

以 xiaomimimo 为例

修改 ~/openclaw/config/openclaw.json，在根级别添加 models 字段：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xiaomimimo": {
        "baseUrl": "https://api.xiaomimimo.com/v1",
        "apiKey": "<你的API Key>",
        "api": "openai-completions",
        "models": [
          {
            "id": "mimo-v2.5",
            "name": "MiMo v2.5",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 1000000,
            "maxTokens": 32000
          }
        ]
      }
    }
  }
}

字段说明：

• api：API 协议类型，可选 openai-completions、anthropic-messages、google-generative-ai、ollama 等
• contextWindow：上下文窗口大小（token 数）
• id 和 name 都是必填字段

重启并设置为默认模型：

docker restart openclaw
sleep 10
docker exec openclaw openclaw models set xiaomimimo/mimo-v2.5

验证：

docker exec openclaw openclaw models list

---

七、配置 QQ Bot（可选）

1. 前置条件

• 在 QQ 开放平台 注册并创建机器人应用
• 获取 AppID 和 AppSecret
• 在沙箱配置中添加测试成员

2. 安装插件

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

3. 添加通道

docker exec openclaw openclaw channels add --channel qqbot --token "<AppID>:<AppSecret>"

4. 重启并验证

docker restart openclaw
sleep 10
docker exec openclaw openclaw channels status --channel qqbot

预期输出：connected

5. 禁用内置冲突插件

docker exec openclaw openclaw plugins disable qqbot
docker restart openclaw

---

八、访问地址

https://claw.<你的域名>#token=<你的Token>

使用 #token= 而非 ?token=，Token 不会被发送到服务器，更安全。

---

九、踩坑清单

1. 容器启动失败：配置格式错误

现象： 日志显示 Invalid config

解决： 恢复备份 cp config.json.bak config.json && docker restart openclaw

2. 502 Bad Gateway

现象： HTTPS 能连但返回 502

解决： 容器可能还在启动中，等 10 秒再试。检查 docker ps 确认容器状态。

3. OpenAI 在香港不可用

现象： 403 Forbidden: Country, region, or territory not supported

解决： 香港服务器无法直接使用 OpenAI，需配置其他模型（xiaomimimo、DeepSeek 等）。

4. WorkspaceVanishedError

现象： QQ Bot 收到消息但不回复

解决： 删除 attestation 文件：

docker exec openclaw rm -rf /home/node/.openclaw/workspace-attestations
docker restart openclaw

5. 多个 QQ Bot 插件冲突

现象： 日志出现 plugin skill name collision

解决： 禁用内置插件：docker exec openclaw openclaw plugins disable qqbot

6. 模型配置导致容器崩溃

现象： models.providers.xxx.models.0.name: Invalid input

解决： 模型配置中 id 和 name 都是必填字段。

7. 手机 QQ 内置浏览器无法登录

现象： 域名能访问但登不了

解决： QQ 内置浏览器被识别为新设备，需要在服务器上批准设备配对。建议用 Chrome/Safari 访问。

---

十、常用命令速查

用途	命令
查看容器状态	docker ps
查看日志	docker logs openclaw --tail 20
重启容器	docker restart openclaw
测试 Nginx	sudo nginx -t
重载 Nginx	sudo systemctl reload nginx
查看证书	sudo certbot certificates
查看模型	docker exec openclaw openclaw models list
查看通道	docker exec openclaw openclaw channels status
批准设备	docker exec openclaw openclaw devices approve <requestId>

---

十一、卸载清理

# 停止并删除容器
docker stop openclaw && docker rm openclaw

# 删除镜像
docker rmi openclaw/openclaw:latest

# 删除项目目录
rm -rf ~/openclaw

# 删除 Nginx 配置
sudo rm /etc/nginx/conf.d/claw.conf
sudo nginx -t && sudo systemctl reload nginx

# 删除 SSL 证书（可选）
sudo certbot delete --cert-name claw.<你的域名>

---

总结

阶段	关键步骤	注意事项
Docker 安装	官方源安装	务必重启加载新内核
OpenClaw 配置	Token 认证 + 模型配置	id 和 name 都必填
容器启动	挂载 config + workspace	加 --memory 1g 限制
Nginx 反代	443 → 18789	WebSocket 必需 Upgrade 头
SSL 证书	Let's Encrypt 免费	DNS 先解析成功
防火墙	ufw + 云安全组	两边都要放行
设备配对	首次访问手动批准	换浏览器需重新批准
QQ Bot	安装官方插件	禁用内置冲突插件