OpenClaw Docker 部署指南：集成飞书钉钉 QQ 机器人

5.1.1 docker-compose.yml 完整内容

version: '3.8'
services:
  openclaw-gateway:
    container_name: openclaw-gateway
    image: ${OPENCLAW_IMAGE}
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
      - DAC_OVERRIDE
    user: ${OPENCLAW_RUN_USER:-0:0}
    environment:
      TZ: Asia/Shanghai
      HOME: /home/node
      TERM: xterm-256color
      SYNC_MODEL_CONFIG: ${SYNC_MODEL_CONFIG}
      MODEL_ID: ${MODEL_ID}
      IMAGE_MODEL_ID: ${IMAGE_MODEL_ID}
      BASE_URL: ${BASE_URL}
      API_KEY: ${API_KEY}
      API_PROTOCOL: ${API_PROTOCOL}
      CONTEXT_WINDOW: ${CONTEXT_WINDOW}
      MAX_TOKENS: ${MAX_TOKENS}
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      FEISHU_APP_ID: ${FEISHU_APP_ID}
      FEISHU_APP_SECRET: ${FEISHU_APP_SECRET}
      DINGTALK_CLIENT_ID: ${DINGTALK_CLIENT_ID}
      DINGTALK_CLIENT_SECRET: ${DINGTALK_CLIENT_SECRET}
      DINGTALK_ROBOT_CODE: ${DINGTALK_ROBOT_CODE}
      DINGTALK_CORP_ID: ${DINGTALK_CORP_ID}
      DINGTALK_AGENT_ID: ${DINGTALK_AGENT_ID}
      QQBOT_APP_ID: ${QQBOT_APP_ID}
      QQBOT_CLIENT_SECRET: ${QQBOT_CLIENT_SECRET}
      NAPCAT_REVERSE_WS_PORT: ${NAPCAT_REVERSE_WS_PORT}
      NAPCAT_HTTP_URL: ${NAPCAT_HTTP_URL}
      NAPCAT_ACCESS_TOKEN: ${NAPCAT_ACCESS_TOKEN}
      NAPCAT_ADMINS: ${NAPCAT_ADMINS}
      WECOM_TOKEN: ${WECOM_TOKEN}
      WECOM_ENCODING_AES_KEY: ${WECOM_ENCODING_AES_KEY}
      WECOM_BOTS_JSON: ${WECOM_BOTS_JSON}
      WORKSPACE: ${WORKSPACE}
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
      OPENCLAW_GATEWAY_BIND: ${OPENCLAW_GATEWAY_BIND}
      OPENCLAW_GATEWAY_PORT: ${OPENCLAW_GATEWAY_PORT}
      OPENCLAW_BRIDGE_PORT: ${OPENCLAW_BRIDGE_PORT}
      OPENCLAW_GATEWAY_MODE: ${OPENCLAW_GATEWAY_MODE}
      OPENCLAW_GATEWAY_ALLOWED_ORIGINS: ${OPENCLAW_GATEWAY_ALLOWED_ORIGINS}
      OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH: ${OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH}
      OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH: ${OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH}
      OPENCLAW_GATEWAY_AUTH_MODE: ${OPENCLAW_GATEWAY_AUTH_MODE}
      OPENCLAW_PLUGINS_ENABLED: ${OPENCLAW_PLUGINS_ENABLED}
    volumes:
      - ${OPENCLAW_DATA_DIR}:/home/node/.openclaw
    ports:
      - "${OPENCLAW_GATEWAY_PORT}:18789"
      - "${OPENCLAW_BRIDGE_PORT}:18790"
    init: true
    restart: unless-stopped

5.1.2 .env.example 完整内容

# OpenClaw Docker 环境变量配置示例
# 复制此文件为 .env 并修改相应的值

# Docker 镜像配置
OPENCLAW_IMAGE=justlikemaki/openclaw-docker-cn-im:latest 

# 模型配置
SYNC_MODEL_CONFIG=true
MODEL_ID=model id
IMAGE_MODEL_ID=
BASE_URL=http://xxxxx/v1
API_KEY=123456
API_PROTOCOL=openai-completions
CONTEXT_WINDOW=200000
MAX_TOKENS=8192

# Telegram 配置（可选，留空则不启用）
TELEGRAM_BOT_TOKEN=

# 飞书配置（可选，留空则不启用）
FEISHU_APP_ID=
FEISHU_APP_SECRET=

# 钉钉配置（可选，留空则不启用）
DINGTALK_CLIENT_ID=
DINGTALK_CLIENT_SECRET=
DINGTALK_ROBOT_CODE=
DINGTALK_CORP_ID=
DINGTALK_AGENT_ID=

# QQ 机器人配置（可选，留空则不启用）
QQBOT_APP_ID=
QQBOT_CLIENT_SECRET=

# NapCat (OneBot v11) 配置（可选，留空则不启用）
NAPCAT_REVERSE_WS_PORT=
NAPCAT_HTTP_URL=
NAPCAT_ACCESS_TOKEN=
NAPCAT_ADMINS=

# 企业微信配置（可选，留空则不启用）
WECOM_TOKEN=
WECOM_ENCODING_AES_KEY=
WECOM_BOTS_JSON=

# 工作空间配置（不要更改）
WORKSPACE=/home/node/.openclaw/workspace 

# 挂载目录配置（按实际更改）
OPENCLAW_DATA_DIR=~/.openclaw 

# 可选：容器启动用户 UID:GID
OPENCLAW_RUN_USER=0:0 

# Gateway 配置
OPENCLAW_GATEWAY_TOKEN=123456
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_MODE=local 
OPENCLAW_GATEWAY_ALLOWED_ORIGINS=http://localhost 
OPENCLAW_GATEWAY_ALLOW_INSECURE_AUTH=true 
OPENCLAW_GATEWAY_DANGEROUSLY_DISABLE_DEVICE_AUTH=false 
OPENCLAW_PLUGINS_ENABLED=true 

5.2 配置环境变量

复制环境变量模板并编辑，至少配置 AI 模型相关参数：

cp .env.example .env 
nano .env 

5.2.1 最小配置示例

提示：IM 平台配置为可选项，可以先启动服务，后续再配置需要的平台。

5.3 启动服务

docker-compose up -d

5.4 查看日志

docker-compose logs -f

5.5 停止服务

docker-compose down 

六、详细配置指南

6.1 AI 模型配置

本项目支持 OpenAI 协议和 Claude 协议两种 API 格式。

推荐模型：推荐使用 gemini-3-flash-preview 模型，该模型具有超大上下文窗口（1M tokens）、快速响应速度和优秀的性价比，非常适合作为 OpenClaw 的后端模型。

6.1.1 基础配置参数

6.1.2 协议类型说明

6.1.3 配置示例

1. OpenAI 协议（Gemini 模型）

MODEL_ID=gemini-3-flash-preview 
BASE_URL=http://localhost:3000/v1 
API_KEY=your-api-key 
API_PROTOCOL=openai-completions 
CONTEXT_WINDOW=1000000 
MAX_TOKENS=8192 

2. Claude 协议（Claude 模型）

MODEL_ID=claude-sonnet-4-5 
BASE_URL=http://localhost:3000 
API_KEY=your-api-key 
API_PROTOCOL=anthropic-messages 
CONTEXT_WINDOW=200000 
MAX_TOKENS=8192 

6.2 Gateway 配置

6.3 工作空间配置

6.4 IM 平台配置

6.4.1 飞书配置

1. 获取飞书机器人凭证

   • 在飞书开放平台创建自建应用
   • 添加应用能力 - 机器人
   • 在凭证页面获取 App ID 和 App Secret
   • 开启所需权限
   • 配置事件订阅

2. 必需权限（租户级别）

3. 事件订阅 ⚠️（最容易遗漏） 如果机器人能发消息但收不到消息，请检查此项。在飞书开放平台的应用后台，进入 事件与回调 页面：

• 事件配置方式：选择 使用长连接接收事件（推荐）
• 添加事件订阅，勾选以下事件：

4. 环境变量配置（在 .env 文件中添加）

FEISHU_APP_ID=your-app-id 
FEISHU_APP_SECRET=your-app-secret 

6.4.2 钉钉配置

1. 创建钉钉应用

   • 访问钉钉开发者后台
   • 创建企业内部应用
   • 添加「机器人」能力
   • 配置消息接收模式为 Stream 模式
   • 发布应用

2. 获取凭证 从开发者后台获取：Client ID（AppKey）、Client Secret（AppSecret）、Robot Code（与 Client ID 相同）、Corp ID（与 Client ID 相同）、Agent ID（应用 ID）

3. 环境变量配置（在 .env 文件中添加）

DINGTALK_CLIENT_ID=your-dingtalk-client-id 
DINGTALK_CLIENT_SECRET=your-dingtalk-client-secret 
DINGTALK_ROBOT_CODE=your-dingtalk-robot-code 
DINGTALK_CORP_ID=your-dingtalk-corp-id 
DINGTALK_AGENT_ID=your-dingtalk-agent-id 

6.4.3 QQ 机器人配置

1. 获取 QQ 机器人凭证

   • 访问 QQ 开放平台
   • 创建机器人应用
   • 获取 AppID 和 AppSecret（ClientSecret）
   • 获取主机在公网的 IP，配置到 IP 白名单

2. 环境变量配置（在 .env 文件中添加）

QQBOT_APP_ID=你的 AppID 
QQBOT_CLIENT_SECRET=你的 AppSecret 

6.4.4 企业微信配置

1. 获取企业微信凭证

   • 访问企业微信管理后台
   • 进入'应用管理' - 用 API 模式创建'智能机器人'应用
   • 在应用的'接收消息'配置中设置 Token 和 EncodingAESKey
   • 设置'接收消息'URL 为你的服务地址（例如：https://your-domain.com/webhooks/wxwork），需要当前服务可公网访问

2. 环境变量配置（在 .env 文件中添加）

WECOM_TOKEN=your-token 
WECOM_ENCODING_AES_KEY=your-aes-key 

七、高级使用

7.1 使用 Docker 命令运行

如果不使用 Docker Compose，可以直接使用 Docker 命令启动容器：

docker run -d\
--name openclaw-gateway \
--cap-add=CHOWN \
--cap-add=SETUID \
--cap-add=SETGID \
--cap-add=DAC_OVERRIDE \
-e MODEL_ID=model id\
-e BASE_URL=http://xxxxx/v1 \
-e API_KEY=123456\
-e API_PROTOCOL=openai-completions \
-e CONTEXT_WINDOW=200000\
-e MAX_TOKENS=8192\
-e FEISHU_APP_ID=your-app-id \
-e FEISHU_APP_SECRET=your-app-secret \
-e DINGTALK_CLIENT_ID=your-dingtalk-client-id \
-e DINGTALK_CLIENT_SECRET=your-dingtalk-client-secret \
-e DINGTALK_ROBOT_CODE=your-dingtalk-robot-code \
-e DINGTALK_CORP_ID=your-dingtalk-corp-id \
-e DINGTALK_AGENT_ID=your-dingtalk-agent-id \
-e QQBOT_APP_ID=your-qqbot-app-id \
-e QQBOT_CLIENT_SECRET=your-qqbot-client-secret \
-e WECOM_TOKEN=your-token \
-e WECOM_ENCODING_AES_KEY=your-aes-key \
-e OPENCLAW_GATEWAY_TOKEN=123456\
-e OPENCLAW_GATEWAY_BIND=lan \
-e OPENCLAW_GATEWAY_PORT=18789\
-v ~/.openclaw:/home/node/.openclaw \
-v ~/.openclaw/workspace:/home/node/.openclaw/workspace \
-p18789:18789 \
-p18790:18790 \
--restart unless-stopped \
justlikemaki/openclaw-docker-cn-im:latest

7.2 数据持久化

容器使用以下卷进行数据持久化，确保配置和工作数据不丢失：

• /home/node/.openclaw - OpenClaw 配置和数据目录
• /home/node/.openclaw/workspace - 工作空间目录

7.3 端口说明

• 18789 - OpenClaw Gateway 端口
• 18790 - OpenClaw Bridge 端口

7.4 自定义配置文件

如果需要完全自定义配置文件，可按以下步骤操作：

• 在宿主机创建配置文件 ~/.openclaw/openclaw.json
• 挂载该目录到容器：-v ~/.openclaw:/home/node/.openclaw
• 容器启动时会检测到已存在的配置文件，跳过自动生成

八、常见问题

Q: 修改了环境变量但配置没有生效？

容器启动时只有在配置文件不存在时才会生成新配置。如需重新生成配置，请删除现有配置文件：

rm ~/.openclaw/openclaw.json 
docker-compose restart 

或者直接删除整个数据目录重新开始：

rm -rf ~/.openclaw 
docker-compose up -d

Q: 连接 AIClient-2-API 失败？

• 确认 AIClient-2-API 服务运行中
• 检查 Base URL 是否正确（OpenAI 协议需要 /v1 后缀）
• 尝试使用 127.0.0.1 替代 localhost

Q: 401 错误？

• 检查 API Key 是否正确配置
• 确认环境变量 API_KEY 已设置

Q: 模型不可用？

• 在 AIClient-2-API Web UI 确认已配置对应提供商
• 重启容器：docker-compose restart

Q: 飞书机器人能发消息但收不到消息？

• 检查是否配置了事件订阅（最容易遗漏的配置）
• 确认事件配置方式选择了'使用长连接接收事件'
• 确认已添加 im.message.receive_v1 事件

Q: Telegram 机器人如何配对？

如果需要启用 Telegram，必须提供有效的 TELEGRAM_BOT_TOKEN，启用后需要执行以下命令进行配对审批：

openclaw pairing approve telegram {token}

并且需要重启 Docker 服务使配置生效。

Q: 同样的启动命令，为什么有人报错 Permission denied？

这通常不是命令本身不稳定，而是运行上下文变化导致：宿主机挂载目录所有者（UID/GID）与容器内进程用户不一致。

为什么会'偶发' 同样是 docker compose up -d，但目录来源不同：

• 你手动创建目录：可能是当前用户（如 1000:1000）
• Docker 自动创建或使用 sudo 创建：可能是 root:root（0:0）

本镜像最终以 node 用户运行网关；若挂载目录归属不匹配，就可能无法写入。

快速排查

ls -ln ~/.openclaw 
docker run --rm justlikemaki/openclaw-docker-cn-im:latest id

若容器用户是 uid=1000，而宿主机目录是 uid=0 且权限不足，就会报错。

解决方案（推荐顺序）

1. 宿主机修正目录所有权（最直接）

sudo chown -R 1000:1000 ~/.openclaw 

2. 显式指定容器运行用户（可选）

在 .env 中设置：

OPENCLAW_RUN_USER=1000:1000 

然后重启：

docker compose up -d

3. SELinux 场景（CentOS/RHEL/Fedora）

若权限看起来没问题但仍拒绝访问，请给挂载卷加 :Z 标签。

本项目已做的稳态处理：

• docker-compose.yml 新增可选 user 配置：OPENCLAW_RUN_USER（默认 0:0）
• init.sh 启动时会：打印挂载目录当前 UID/GID 与目标 UID/GID；尝试自动修复 /home/node/.openclaw 权限；若仍不可写，输出明确的修复命令并失败退出，避免'有时成功有时报错'的隐性状态

九、注意事项

• 确保宿主机的 18789 和 18790 端口未被占用
• 配置文件中的敏感信息（如 API 密钥、令牌）应妥善保管
• 首次运行时会自动创建必要的目录和配置文件，包括 openclaw.json 配置文件，已存在时不会覆盖
• 容器以 node 用户身份运行，确保挂载的卷有正确的权限
• IM 平台配置均为可选项，可根据实际需求选择性配置
• 使用 OpenAI 协议时，Base URL 需要包含 /v1 后缀
• 使用 Claude 协议时，Base URL 不需要 /v1 后缀