Docker 安装 OpenClaw 指南

Docker 安装 OpenClaw 完整指南

本文档将带你从零开始，使用 Docker 安装和配置 OpenClaw AI 助手。

一、OpenClaw 简介

OpenClaw 是一个强大的 AI 助手框架，支持多平台接入（QQ、飞书等），可以通过技能扩展功能，让你创建专属的 AI 工作流。

核心功能：

🤖 多平台接入（QQ、飞书、微信等）
🧩 技能系统（扩展 AI 能力）
🔌 插件机制（集成第三方服务）
📊 Web 控制台（可视化管理）

二、准备工作

1. 安装 Docker 和 Docker Compose

确保你的系统已安装 Docker 和 Docker Compose：

# 检查 Docker 版本
docker --version

# 检查 Docker Compose 版本
docker compose version

如果未安装，请参考：

Docker 官方文档 (https://docs.docker.com/get-docker/)
Docker Compose 文档 (https://docs.docker.com/compose/install/)

2. 创建工作目录

# 创建配置目录（根据你的系统调整路径）
mkdir -p /vol1/1000/docker/openclaw/config

# 查看创建结果
ls -la /vol1/1000/docker/openclaw/

说明：

/vol1/1000/docker/openclaw/config - 配置文件存储位置
你可以根据需要修改路径，但要记住这个位置

3. 拉取 OpenClaw 镜像

docker pull ghcr.io/openclaw/openclaw:latest

三、创建配置目录

确保宿主机目录存在并具有正确的权限：

# 创建目录（如果不存在）
mkdir -p /vol1/1000/docker/openclaw/config

# 检查目录权限
ls -ld /vol1/1000/docker/openclaw/config

# 确保当前用户有权限（显示 drwxrwxrwx）
chmod 777 /vol1/1000/docker/openclaw/config

为什么需要正确的权限？

OpenClaw 容器内的 node 用户（UID 1000）需要能够读写宿主机的配置目录。权限不足会导致配置无法保存或读取失败。

四、编写 Docker Compose 文件

1. 创建工作目录

cd /vol1/1000/docker/openclaw

2. 编写 docker-compose.yml

创建 docker-compose.yml 文件：

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    # 端口映射：宿主机18789 → 容器18789
    ports:
      - "18789:18789"
    # 卷挂载：持久化配置
    volumes:
      - /vol1/1000/docker/openclaw/config:/home/node/.openclaw
      - /var/run/docker.sock:/var/run/docker.sock
    # 环境变量
    environment:
      - NODE_ENV=production
      - TZ=Asia/Shanghai
      - OPENCLAW_CN_MIRROR=true
      - ANTHROPIC_API_KEY=Admin123.
    # 启动命令
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "lan",
        "--port",
        "18789",
      ]
    restart: unless-stopped

3. 配置说明

配置项	说明	备注
`image`	镜像名称	使用官方最新版
`ports`	端口映射	18789 用于 Web 控制台访问
`volumes`	卷挂载	第一个挂载点是配置目录，必须
`environment`	环境变量	TZ 设置时区，OPENCLAW_CN_MIRROR 加速国内访问
`restart`	重启策略	`unless-stopped` 除非手动停止否则自动重启

五、初始化配置

重要： 首次运行必须执行初始化命令，生成配置文件。

1. 运行初始化命令

docker run --rm \
  -u node \
  -v /vol1/1000/docker/openclaw/config:/home/node/.openclaw \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/openclaw/openclaw:latest \
  node dist/index.js setup

2. 参数解释

参数	说明	必需性
`--rm`	容器运行完后自动删除，不留垃圾	✅ 推荐
`-u node`	以 node 用户身份运行，避免权限问题	✅ 必需
`-v ...`	挂载配置目录到容器内	✅ 必需
`node dist/index.js setup`	显式调用初始化命令	✅ 必需

3. 验证初始化结果

# 检查配置文件是否生成
ls -la /vol1/1000/docker/openclaw/config

你应该能看到这些文件：

openclaw.json - 主配置文件
agents/ - Agent 配置目录
credentials/ - 凭证存储目录
workspace/ - 工作空间
其他配置文件...

如果没有看到文件，说明初始化失败，请检查：

目录权限是否正确
卷挂载路径是否正确

六、启动服务

1. 启动 OpenClaw

cd /vol1/1000/docker/openclaw
docker compose up -d

参数说明：

-d - 后台运行（detached mode）

2. 查看容器状态

docker ps | grep openclaw

应该看到容器状态为 Up。

3. 查看启动日志

docker logs -f openclaw

预期输出：

OpenClaw Gateway starting...
Listening on http://0.0.0.0:18789

按 Ctrl+C 退出日志查看（容器继续运行）。

4. 访问 Web 控制台

打开浏览器，访问：

http://你的服务器IP:18789

你应该能看到 OpenClaw 的控制台界面。

七、初次配置

1. 进入容器

docker exec -it openclaw /bin/bash

参数说明：

-it - 交互式终端
/bin/bash - 启动 bash shell

2. 运行向导配置

openclaw onboard

按照提示完成配置：

设置模型（如 Anthropic Claude、智谱 AI 等）
配置消息渠道（QQ、飞书等）
设置 Agent（默认为 main）
完成配置

3. 退出容器

exit

4. 重启服务使配置生效

docker compose restart

八、安装 QQ 机器人插件

QQBot 是 OpenClaw 最常用的插件之一，让你在 QQ 中使用 AI 助手。

1. 申请 QQ 机器人

访问 QQ 开放平台 (https://q.qq.com/)
创建机器人应用
获取 AppID 和 AppSecret
记录这些信息，后面配置需要

2. 安装 QQBot 插件

在容器内执行：

# 进入容器
docker exec -it openclaw /bin/bash

# 安装插件
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# 退出容器
exit

3. 配置 QQBot

在容器内执行：

docker exec -it openclaw /bin/bash

# 绑定 QQ 机器人（格式：AppID:AppSecret）
openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"

示例：

openclaw channels add --channel qqbot --token "1903592456:tkPr56vWv64pNhnf"

4. 重启 OpenClaw 服务

docker compose restart

5. 验证 QQBot 是否工作

在容器内查看日志：

docker logs -f openclaw

向你的 QQ 机器人发送消息
如果收到回复，说明配置成功！

九、常见问题排查

问题 1：权限错误

错误信息： Permission denied 或无法读写配置文件

解决方法：

# 修改目录权限
chmod 777 /vol1/1000/docker/openclaw/config

# 或者修改所有者
sudo chown -R 1000:1000 /vol1/1000/docker/openclaw/config

问题 2：初始化没有生成文件

可能原因：

卷挂载路径错误
目录权限不足

排查步骤：

# 1. 检查目录是否存在
ls -la /vol1/1000/docker/openclaw/config

# 2. 重新初始化
docker run --rm \
  -u node \
  -v /vol1/1000/docker/openclaw/config:/home/node/.openclaw \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/openclaw/openclaw:latest \
  node dist/index.js setup

问题 3：容器启动失败

查看详细日志：

docker logs openclaw

常见错误：

端口被占用 → 修改 docker-compose.yml 的端口映射
镜像拉取失败 → 检查网络或使用国内镜像

问题 4：无法访问 Web 控制台

排查步骤：

检查容器是否运行：

docker ps | grep openclaw

检查端口映射：

docker port openclaw

检查防火墙：

# 检查端口是否开放
netstat -tuln | grep 18789

# 或使用 ufw
sudo ufw allow 18789

问题 5：QQBot 无法连接

排查步骤：

检查配置：

docker exec -it openclaw /bin/bash
openclaw channels list

查看日志：

docker logs -f openclaw | grep qqbot

确认 AppID 和 AppSecret 正确

十、常用命令速查

容器管理

# 启动服务
docker compose up -d

# 停止服务
docker compose stop

# 重启服务
docker compose restart

# 查看日志
docker logs -f openclaw

# 进入容器
docker exec -it openclaw /bin/bash

# 删除容器（保留数据）
docker compose down

# 删除容器和数据
docker compose down -v

OpenClaw 命令（容器内）

# 配置向导
openclaw onboard

# 安装插件
openclaw plugins install <插件名>

# 列出插件
openclaw plugins list

# 添加渠道
openclaw channels add --channel <类型> --token 

# 列出渠道
openclaw channels list

# 查看状态
openclaw status

# 查看配置
openclaw config show

十一、进阶配置

1. 修改 Web 控制台端口

如果 18789 端口被占用，可以修改：

services:
  openclaw:
    ports:
      - "8080:18789"  # 修改宿主机端口为 8080

然后访问 http://你的服务器IP:8080

2. 启用 HTTPS（生产环境推荐）

使用 Nginx 进行请求转发：

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

3. 配置自动备份

# 添加到 crontab
0 2 * * * tar -czf /backup/openclaw-$(date +\%Y\%m\%d).tar.gz /vol1/1000/docker/openclaw/config

每天凌晨 2 点自动备份配置。

十二、总结

通过本文档，你应该已经成功：

✅ 使用 Docker 安装了 OpenClaw ✅ 完成了初始化配置 ✅ 启动了 Web 控制台 ✅ 安装并配置了 QQBot 插件

下一步：

📚 探索 OpenClaw 的技能系统
🤖 尝试接入更多平台（飞书、微信等）
🔌 安装更多插件扩展功能
📊 使用 Web 控制台管理你的 AI 助手

参考资料

OpenClaw 官方文档 (https://docs.openclaw.ai)
OpenClaw GitHub (https://github.com/openclaw/openclaw)
Docker 官方文档 (https://docs.docker.com/)
QQBot 插件文档 (https://github.com/tencent-connect/openclaw-qqbot)

祝你使用愉快！如有问题，欢迎在评论区留言交流。 🚀