Docker Compose + 钉钉部署指南

本指南介绍如何使用 Docker Compose 部署 OpenClaw 网关，并配置钉钉机器人通道。适用于需要容器化部署、对接钉钉的场景。

社区插件：钉钉通道由社区插件 openclaw-channel-dingtalk 提供，使用 Stream 模式（无需公网 IP）。

前置阅读：本指南假设您已了解 OpenClaw 基本概念。如需了解更多，请参阅 Docker 安装。

---

前置条件

• Docker & Docker Compose v2 已安装（Docker Desktop 或 Docker Engine）
• Node.js >= 22（如需本地运行 CLI 工具）
• 钉钉账号，可访问 钉钉开放平台
• 钉钉插件：钉钉通道以社区插件形式提供（openclaw-channel-dingtalk），需要单独安装（见下方第 1 步）
• AI 模型凭据：您的 API Token 和 Base URL（如 Anthropic、或兼容 Anthropic Messages API 的自定义端点）

---

快速开始

按照以下 7 步完成部署。每一步的详细说明请参阅对应的链接文档。

第 1 步：安装钉钉插件

钉钉通道以社区插件形式提供，必须先安装：

# 方法 A：通过远程仓库安装（推荐）
openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

# 方法 B：通过本地源码安装（适合二次开发）
git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk
npm install
openclaw plugins install -l .

Docker 用户：预构建镜像 ghcr.io/openclaw/openclaw:latest 不包含钉钉插件，需通过一次性容器安装。注意必须传入 --env-file，否则 OpenClaw 读取配置时会因找不到环境变量而报错：

docker run --rm --env-file .env \
  -v ./openclaw-data:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest \
  sh -c "node /app/openclaw.mjs plugins install https://github.com/soimy/openclaw-channel-dingtalk.git"

安装顺序：如果 openclaw.json 中已配置了 channels.dingtalk 但插件尚未安装，容器启动时会因 unknown channel id: dingtalk 报错并反复重启。建议的做法是：先创建不含 channels.dingtalk 的配置文件 → 安装插件 → 再添加钉钉通道配置。或者先完成第 4 步（编写完整配置），再用上述命令安装插件（安装命令不会因 channel 未知而失败，只是 doctor 会给出警告）。

重要：安装插件时 openclaw doctor 可能自动运行并将 openclaw.json 中的 ${VAR_NAME} 展开为环境变量的实际值。安装完成后，请检查 openclaw.json，确保 ${VAR_NAME} 引用仍然保留（如被展开，需手动恢复）。

插件更新：openclaw plugins update dingtalk

第 2 步：创建项目目录

mkdir -p openclaw-dingtalk/openclaw-data
cd openclaw-dingtalk

创建 .env 文件存放敏感配置：

# .env

# 网关安全
OPENCLAW_GATEWAY_TOKEN=your-secure-gateway-token

# 钉钉凭据（第 3 步获取后填入）
DINGTALK_CLIENT_ID=
DINGTALK_CLIENT_SECRET=
DINGTALK_ROBOT_CODE=
DINGTALK_CORP_ID=
DINGTALK_AGENT_ID=

# 自定义模型提供商（按需修改）
ANTHROPIC_AUTH_TOKEN=your_api_token_here
ANTHROPIC_BASE_URL=https://api.anthropic.com

安全提示：请将 .env 加入 .gitignore，切勿提交到版本控制。

生成令牌：在 macOS 或 Linux 上，可使用以下命令生成安全的随机令牌：

openssl rand -base64 32

第 3 步：创建钉钉应用

在钉钉开放平台创建企业内部应用，获取 Client ID、Client Secret、Robot Code、Corp ID 和 Agent ID，配置权限并启用机器人能力。

详细步骤请参阅 钉钉应用配置详解。

第 4 步：编写 OpenClaw 配置

在 openclaw-data/ 目录下创建 openclaw.json 配置文件：

mkdir -p openclaw-data

{
  "agents": {
    "defaults": {
      "workspace": "/home/node/.openclaw/workspace",
      "model": { "primary": "custom-claude/claude-sonnet-4-5-20250929" }
    }
  },
  "models": {
    "providers": {
      "custom-claude": {
        "baseUrl": "${ANTHROPIC_BASE_URL}",
        "apiKey": "${ANTHROPIC_AUTH_TOKEN}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "${DINGTALK_CLIENT_ID}",
      "clientSecret": "${DINGTALK_CLIENT_SECRET}",
      "robotCode": "${DINGTALK_ROBOT_CODE}",
      "corpId": "${DINGTALK_CORP_ID}",
      "agentId": "${DINGTALK_AGENT_ID}",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown",
      "debug": false
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": { "token": "${OPENCLAW_GATEWAY_TOKEN}" }
  }
}

模型 ID：自定义端点通常需要完整的带日期后缀的模型 ID（如 claude-sonnet-4-5-20250929），短别名（如 claude-3-5-sonnet）可能会返回 422 错误。请根据您的端点支持的模型 ID 进行修改。

消息类型：messageType 支持 "markdown"（默认）和 "card"（AI 互动卡片，支持流式更新）。使用卡片模式需额外配置 cardTemplateId，详见 配置参考。

多实例部署：如果同一台机器上已运行其他 OpenClaw 实例（如飞书、企微），需将 gateway.port 修改为不同的端口（如 18791），避免端口冲突。同时更新 docker-compose.yml 中的端口映射。

完整配置说明请参阅 配置参考与故障排除（钉钉）。

第 5 步：编写 Docker Compose

创建 docker-compose.yml：

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw_dingtalk
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    volumes:
      # 整个 .openclaw 目录（配置文件 + 持久化数据）
      - ./openclaw-data:/home/node/.openclaw

为什么使用 network_mode: host？ OpenClaw 网关绑定到容器内的 127.0.0.1。标准 Docker 端口映射通过桥接网络转发流量，网关会因来源 IP 不是 localhost 而拒绝连接。network_mode: host 让容器直接共享宿主机网络栈，从而正常访问。

macOS 用户：需要在 Docker Desktop 中启用 "Enable host networking"（设置 → 资源 → 网络）。如果遇到端口冲突或 network_mode: host 行为异常（macOS Docker Desktop 通过 VM 实现 host 网络，行为与 Linux 不同），可以改用桥接模式加端口映射：

# 替换 network_mode: host 为：
ports:
  - "18789:18789"

钉钉 Stream 模式使用客户端主动外连，不依赖宿主机接收入站连接，因此桥接模式同样适用。仅当需要通过浏览器访问控制面板（http://127.0.0.1:18789/）时才需要端口映射。

为什么挂载整个目录？ 网关运行时需要在 .openclaw 目录下创建多个子目录（identity/、credentials/、canvas/ 等）。单独挂载文件会导致权限错误（EACCES、EBUSY），因为容器无法在挂载点旁创建临时文件。

权限注意：Docker 镜像默认以 node 用户（uid 1000）运行。如在 Linux 上遇到权限问题：

sudo chown -R 1000:1000 ./openclaw-data

第 6 步：启动并配置消息接收

docker compose up -d
docker compose logs -f

等待日志中出现 [gateway] listening，表示网关已就绪。

钉钉插件使用 Stream 模式（WebSocket 长连接），无需公网地址，适合内网部署：

1. 进入钉钉开放平台 → 应用管理 → 您的应用
2. 进入 应用功能 → 机器人 → 启用机器人能力
3. 消息接收模式选择 Stream 模式
4. 创建版本并发布应用

提示：Stream 模式类似飞书的长连接模式，由客户端主动连接钉钉服务器，不受 NAT 和防火墙限制。插件仅支持 Stream 模式。

详细步骤请参阅 钉钉应用配置详解 — 消息接收模式。

第 7 步：配对机器人

1. 在钉钉中找到您的机器人，发送一条消息（如 "你好"）
2. 机器人会回复一个配对码（如 123-456）
3. 通过 CLI 批准配对：

docker compose exec openclaw openclaw pairing approve dingtalk <CODE>

如果 openclaw 命令未找到，请使用以下替代命令：

docker compose exec openclaw node dist/index.js pairing approve dingtalk <CODE>

4. 配对完成后，机器人即可正常响应消息

提示：如果 dmPolicy 设为 "open"，则所有用户无需配对即可直接使用。配对流程仅在 dmPolicy 为 "pairing" 时生效。

---

常见操作

重启服务

docker compose restart

更新镜像

docker compose pull && docker compose up -d

查看配对列表

docker compose exec openclaw openclaw pairing list dingtalk
# 或：docker compose exec openclaw node dist/index.js pairing list dingtalk

访问控制 UI

在浏览器中打开 http://127.0.0.1:<port>/?token=<your-token>（将 <port> 替换为 openclaw.json 中配置的 gateway.port，默认 18789；将 <your-token> 替换为 .env 中的 OPENCLAW_GATEWAY_TOKEN 值）。

检查健康状态

docker compose exec openclaw node dist/index.js health --token "<your-gateway-token>"

请将 <your-gateway-token> 替换为您在 .env 中设置的 OPENCLAW_GATEWAY_TOKEN 值。$OPENCLAW_GATEWAY_TOKEN 由主机 shell 解析，如果未在主机环境中导出该变量，需手动填入 token 值。

试玩一下

想快速验证部署是否正常？向机器人发送以下消息：

访问 https://xialiao.ai/skill.md 并按照说明加入「虾聊社区」

机器人会自动回复结果，一步确认你的 OpenClaw 已经跑起来了。

---

详细文档

• 钉钉应用配置详解 — 钉钉开放平台完整配置步骤、访问控制和消息接收模式
• 配置参考与故障排除（钉钉） — openclaw.json 完整参考、Docker Compose 说明和故障排除

相关文档

• Docker 安装 — Docker 部署详细参考
• 网关配置 — 网关配置参考
• 网关配置示例 — 更多配置示例