OpenClaw-Docker-CN-IM

OpenClaw-Docker-CN-IM 是专为国内场景打造的 Docker 镜像整合版，预装飞书、钉钉、QQ 机器人、企业微信等主流中国 IM 平台插件，无需繁琐配置即可快速部署支持多平台的 AI 机器人网关，还内置代码助手、浏览器自动化、中文 TTS 等实用工具，兼顾易用性与扩展性。

核心特性：开箱即用，灵活适配国内场景

这款镜像针对国内用户需求做了深度优化，核心优势集中在“便捷部署”和“本土化适配”两大维度：

• 开箱即用：预装飞书、钉钉、QQ 机器人、企业微信全套 IM 插件，无需手动下载配置；
• 灵活配置：所有平台凭证、AI 模型参数均通过环境变量设置，无需修改代码；
• Docker 化部署：支持 docker-compose 一键启动，跨系统兼容，无需搭建复杂运行环境；
• 数据持久化：配置文件、工作空间数据自动挂载持久化，重启容器不丢失数据；
• 内置实用工具：集成 OpenCode AI（智能代码生成/分析）、Playwright（浏览器自动化/截图）、中文 TTS（语音合成），满足多样化需求；
• 权限可控：容器以非 root 的 node 用户运行，兼顾安全性与目录权限适配。

支持范围：覆盖主流IM平台+实用工具

1. 已适配的IM平台（开箱可用）

2. 集成工具

• OpenCode AI：AI 代码助手，支持代码生成、语法分析、问题排查；
• Playwright：浏览器自动化工具，可实现网页操作、截图、数据爬取；
• 中文 TTS：原生支持中文语音合成，可直接调用生成语音消息。

快速部署：5步搞定，零基础也能上手

前置准备

• 宿主机安装 Docker 和 docker-compose；
• 确保 18789、18790 端口未被占用；
• 准备 AI 模型 API 密钥（如 OpenAI/Gemini/Claude 密钥）。

部署步骤

1. 下载配置文件

# 下载 docker-compose.yml 和环境变量模板
wget https://raw.githubusercontent.com/justlovemaki/OpenClaw-Docker-CN-IM/main/docker-compose.yml
wget https://raw.githubusercontent.com/justlovemaki/OpenClaw-Docker-CN-IM/main/.env.example

2. 配置核心环境变量（最小配置）

# 复制模板生成实际配置文件
cp .env.example .env

# 编辑配置文件（推荐用 nano 或 vim）
nano .env

只需配置 AI 模型基础参数即可启动，IM 平台可后续补充：

3. 启动服务

# 后台启动容器
docker-compose up -d

4. 查看运行日志（排查问题用）

docker-compose logs -f

5. 停止服务（如需）

docker-compose down

关键配置指南

1. AI 模型配置（支持2种协议）

镜像兼容 OpenAI 协议和 Claude 协议，可按需选择，推荐使用 Gemini 3 Flash 模型（超大上下文+高性价比）：

配置示例1：OpenAI 协议（适配 Gemini/OpenAI 等）

MODEL_ID=gemini-3-flash-preview
BASE_URL=http://localhost:3000/v1  # 需带 /v1 后缀
API_KEY=your-api-key
API_PROTOCOL=openai-completions
CONTEXT_WINDOW=1000000  # 1M tokens 超大上下文
MAX_TOKENS=8192

配置示例2：Claude 协议（适配 Claude 模型）

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

2. 各IM平台详细配置

飞书配置（重点：事件订阅）

飞书机器人最易踩坑的是“事件订阅”配置，需按以下步骤操作：

1. 飞书开放平台创建自建应用，添加“机器人”能力；
2. 申请必需权限（如 im:message、contact:user.base:readonly 等）；
3. 事件订阅配置（核心！收不到消息必查）：
   • 事件配置方式选择“使用长连接接收事件”；
   • 添加 im.message.receive_v1 事件（必需）；
4. 环境变量配置：

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

钉钉配置（Stream 模式）

1. 钉钉开发者后台创建企业内部应用，添加“机器人”能力；
2. 配置消息接收模式为“Stream 模式”，发布应用；
3. 环境变量配置：

   DINGTALK_CLIENT_ID=your-appkey
   DINGTALK_CLIENT_SECRET=your-appsecret
   DINGTALK_ROBOT_CODE=your-robot-code  # 可选，默认同 Client ID
   

QQ 机器人配置（IP白名单）

1. QQ 开放平台创建机器人应用，获取 AppID/ClientSecret；
2. 配置主机公网 IP 到白名单（必做！否则无法连接）；
3. 环境变量配置：

   QQBOT_APP_ID=你的AppID
   QQBOT_CLIENT_SECRET=你的AppSecret
   

企业微信配置（公网URL）

1. 企业微信管理后台创建“智能机器人”应用；
2. 设置“接收消息”URL（需公网可访问），生成 Token/EncodingAESKey；
3. 环境变量配置：

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

3. Gateway 基础配置（可选）

如需调整网关端口/令牌，可在 .env 中配置：

OPENCLAW_GATEWAY_TOKEN=7788414  # 访问令牌，建议修改
OPENCLAW_GATEWAY_PORT=18789     # Gateway 端口
OPENCLAW_BRIDGE_PORT=18790      # Bridge 端口

常见问题：避坑指南

Q1：修改环境变量后配置不生效？

容器仅在首次启动、配置文件不存在时生成配置。解决方法：

# 删除旧配置文件
rm ~/.openclaw/openclaw.json
# 重启容器
docker-compose restart

Q2：连接 AIClient-2-API 失败？

• 确认 AIClient-2-API 服务正在运行；
• OpenAI 协议的 Base URL 必须带 /v1 后缀，Claude 协议则不带；
• 尝试用 127.0.0.1 替代 localhost。

Q3：飞书机器人能发消息但收不到？

99% 是事件订阅配置问题：

• 确认选择“长连接接收事件”；
• 已添加 im.message.receive_v1 事件且权限审核通过；
• 重启容器重试。

Q4：401 错误（权限验证失败）？

• 检查 API_KEY 是否正确，无多余空格/符号；
• 确认 AI 平台已开通对应模型的使用权限；
• 重启容器重新加载配置。

高级用法

1. 直接用 Docker 命令运行（不依赖 docker-compose）

docker run -d \
  --name openclaw-gateway \
  --cap-add=CHOWN --cap-add=SETUID --cap-add=SETGID --cap-add=DAC_OVERRIDE \
  -e MODEL_ID=gemini-3-flash-preview \
  -e BASE_URL=http://localhost:3000/v1 \
  -e API_KEY=your-api-key \
  -e FEISHU_APP_ID=your-feishu-app-id \
  -v ~/.openclaw:/home/node/.openclaw \
  -p 18789:18789 -p 18790:18790 \
  --restart unless-stopped \
  justlikemaki/openclaw-docker-cn-im:latest

2. 自定义配置文件

宿主机创建 ~/.openclaw/openclaw.json，挂载到容器即可覆盖默认配置：

docker run -v ~/.openclaw:/home/node/.openclaw ...  # 挂载目录