配置参考与故障排除（钉钉）

本文档提供 Docker Compose + 钉钉部署的完整配置参考和故障排除指南。这是 Docker Compose + 钉钉部署指南的配套文档。

openclaw.json 完整示例

json5

{
  // Agent 配置
  "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}" }
  }
}

配置参考

Agents 配置

配置项	说明	默认值
`agents.defaults.workspace`	Agent 工作区路径	`~/.openclaw/workspace`
`agents.defaults.model.primary`	主模型，格式 `provider/model-id`	—

模型提供商配置

配置项	说明	默认值
`models.providers.<name>.baseUrl`	API 基地址	—
`models.providers.<name>.apiKey`	API 密钥	—
`models.providers.<name>.api`	API 协议（`anthropic-messages`、`openai` 等）	—
`models.providers.<name>.models`	可用模型列表。模型 `id` 应使用完整的带日期后缀的 ID（如 `claude-sonnet-4-5-20250929`），短别名可能导致 422 错误	—

钉钉通道配置

配置项	类型	说明	默认值
`channels.dingtalk.enabled`	boolean	启用/禁用钉钉通道	`true`
`channels.dingtalk.clientId`	string	应用的 AppKey（必填）	—
`channels.dingtalk.clientSecret`	string	应用的 AppSecret（必填）	—
`channels.dingtalk.robotCode`	string	机器人代码（用于下载媒体和发送卡片）	—
`channels.dingtalk.corpId`	string	企业 ID	—
`channels.dingtalk.agentId`	string	应用 ID	—
`channels.dingtalk.dmPolicy`	string	私聊策略：`open` / `pairing` / `allowlist`	`"open"`
`channels.dingtalk.groupPolicy`	string	群聊策略：`open` / `allowlist`	`"open"`
`channels.dingtalk.allowFrom`	string[]	允许的发送者 ID 列表	`[]`
`channels.dingtalk.messageType`	string	消息类型：`markdown` / `card`	`"markdown"`
`channels.dingtalk.cardTemplateId`	string	AI 互动卡片模板 ID（仅 `messageType=card` 时使用）	—
`channels.dingtalk.cardTemplateKey`	string	卡片模板内容字段键（仅 `messageType=card` 时使用）	`"content"`
`channels.dingtalk.debug`	boolean	是否开启调试日志	`false`
`channels.dingtalk.maxConnectionAttempts`	number	最大连接尝试次数	`10`
`channels.dingtalk.initialReconnectDelay`	number	初始重连延迟（毫秒）	`1000`
`channels.dingtalk.maxReconnectDelay`	number	最大重连延迟（毫秒）	`60000`
`channels.dingtalk.reconnectJitter`	number	重连延迟抖动因子（0-1）	`0.3`

AI 互动卡片配置

如果使用 messageType: "card"，需要先在钉钉卡片平台创建卡片模板：

进入「我的模板」→「创建模板」
卡片模板场景选择 「AI 卡片」
按需设计卡片排版，保存并发布
复制模板 ID（格式如 xxxxx-xxxxx-xxxxx.schema）
将模板 ID 配置到 cardTemplateId 字段

json5

{
  "channels": {
    "dingtalk": {
      "messageType": "card",
      "cardTemplateId": "你的模板ID"
    }
  }
}

提示：使用钉钉官方 AI 卡片模板时，cardTemplateKey 默认为 "msgContent"，无需修改。如果使用自定义模板，需将 cardTemplateKey 配置为模板中定义的内容字段名称。

网关配置

配置项	说明	默认值
`gateway.mode`	网关运行模式（`"local"` 或 `"remote"`）。需设为 `"local"` 才能启动网关（Docker 镜像通过 `--allow-unconfigured` 可绕过此限制，但建议显式设置）	未设置
`gateway.port`	网关监听端口	`18789`
`gateway.auth.token`	网关认证令牌	—

更多配置项请参阅网关配置和网关配置示例。

Docker Compose 详解

完整的 docker-compose.yml

yaml

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？ 网关绑定到容器内的 127.0.0.1，标准 Docker 端口映射（ports:）通过桥接网络转发流量，网关会拒绝非 localhost 来源的连接。使用 network_mode: host 让容器直接共享宿主机网络栈。macOS 用户需要在 Docker Desktop 设置中启用 "Enable host networking"。
macOS 替代方案：macOS Docker Desktop 的 network_mode: host 通过 VM 实现，行为与 Linux 不同，可能导致端口冲突或异常。钉钉插件使用 Stream 模式（客户端主动外连），不依赖宿主机接收入站连接，因此也可以使用桥接模式加端口映射：
yaml
# 替换 network_mode: host 为：
ports:
  - "18789:18789"
1
2
3
为什么挂载整个目录而非单独文件？ 网关运行时需要在 .openclaw 目录下创建多个子目录（identity/、credentials/、canvas/ 等）并写入临时文件。单独挂载 openclaw.json 文件会导致该文件成为独立挂载点，无法被原子重命名覆盖（报 EBUSY 错误），同时容器也无法在父目录创建新文件（报 EACCES 错误）。

卷挂载说明

挂载	容器路径	说明
`./openclaw-data/`	`/home/node/.openclaw`	整个 OpenClaw 数据目录，包含配置文件（`openclaw.json`）、Agent 工作区（`workspace/`）、网关状态（`state/`）、Agent 会话数据（`agents/`）、身份信息（`identity/`）、凭据（`credentials/`）等

权限说明

Docker 镜像默认以 node 用户（uid 1000）运行。挂载目录必须对该用户可读写。

在 Linux 上创建并设置目录权限：

bash

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

环境变量

通过 .env 文件传递的环境变量：

变量	说明
`OPENCLAW_GATEWAY_TOKEN`	网关认证令牌
`DINGTALK_CLIENT_ID`	钉钉应用 Client ID（AppKey）
`DINGTALK_CLIENT_SECRET`	钉钉应用 Client Secret（AppSecret）
`DINGTALK_ROBOT_CODE`	机器人代码（与 Client ID 相同）
`DINGTALK_CORP_ID`	企业 ID
`DINGTALK_AGENT_ID`	应用 ID
`ANTHROPIC_AUTH_TOKEN`	模型 API Token
`ANTHROPIC_BASE_URL`	模型 API 基地址

在 openclaw.json 中通过 ${VAR_NAME} 语法引用环境变量。这些变量由 OpenClaw 在运行时从容器的进程环境中读取（由 Docker Compose 的 env_file 注入），而非 Docker Compose 自身的变量替换。

端口配置

默认端口为 18789。由于使用 network_mode: host，容器直接监听宿主机端口，无需 ports: 映射。如需修改端口：

更新 openclaw-data/openclaw.json 中的 gateway.port
如果使用桥接模式（ports:），同步更新 docker-compose.yml 中的端口映射
重启容器：docker compose up -d

多实例部署：如果同一台机器上已运行其他 OpenClaw 实例（如飞书、企微），必须为每个实例分配不同的端口（如 18789、18790、18791），否则会因端口冲突导致容器启动失败。

故障排除

容器启动失败

症状：docker compose up -d 后容器立即退出或反复重启。

排查步骤：

检查容器日志：docker compose logs
检查 .env 文件中的变量是否正确填写
检查 openclaw.json 语法是否正确（JSON5 格式允许注释和尾逗号）
检查端口是否被占用：lsof -i :18789
如果日志显示 unknown channel id: dingtalk，说明钉钉插件未安装。需先安装插件再启动容器（参阅第 1 步）
如果日志显示 Gateway failed to start: another gateway instance is already listening，说明端口已被其他 OpenClaw 实例占用。修改 openclaw.json 中的 gateway.port 为其他值（如 18791），并同步更新 docker-compose.yml

openclaw.json 中的 ${VAR_NAME} 被替换为实际值

症状：openclaw.json 中的 ${ANTHROPIC_BASE_URL} 等环境变量引用被替换为实际值（如 https://api.anthropic.com）。

原因：openclaw plugins install 或 openclaw doctor 在运行时可能自动修改配置文件，将 ${VAR_NAME} 展开为当前环境变量的实际值。

解决方案：安装插件后检查 openclaw.json，将被展开的值恢复为 ${VAR_NAME} 格式。建议在安装插件前备份配置文件：

bash

cp openclaw-data/openclaw.json openclaw-data/openclaw.json.bak

钉钉机器人无响应

症状：在钉钉中向机器人发消息，无任何回复。

排查步骤：

确认应用已发布并获管理员批准
确认机器人能力已启用（应用功能 → 机器人）
确认消息接收模式已正确配置（Stream 模式或 HTTP 回调模式）
确认应用权限完整（参阅权限配置）
确认网关正在运行：docker compose logs -f，检查相关连接日志
确认应用的可见范围包含当前用户（参阅可见范围）
检查钉钉插件是否已安装：openclaw plugins list，确认 dingtalk 在列表中

权限错误（EACCES / EBUSY）

症状：日志中出现 EACCES: permission denied 或 EBUSY: resource busy or locked 错误。

EACCES：Docker 镜像以 node（uid 1000）运行。确保挂载目录权限正确：

bash

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

EBUSY：如果您将 openclaw.json 作为单独文件挂载（而非挂载整个目录），容器无法原子替换该文件。解决方案：改为挂载整个 openclaw-data 目录（参见上方 Docker Compose 详解）。

群聊中机器人无响应

症状：机器人在私聊中正常，但在群组中无响应。

排查步骤：

确认机器人已添加到群组
默认需要 @提及机器人才会响应（钉钉群聊中需要先输入 @ 然后选择机器人名称）
确认 groupPolicy 未设置为 "disabled"
检查日志中是否有群组消息的记录
确认群组中的 群机器人 设置允许该机器人发言

注意：钉钉群聊中 @提及机器人的行为与飞书略有不同。在钉钉中，用户必须在消息开头或中间使用 @提及，且消息文本中会包含 @机器人名称的文字。

插件未找到

症状：日志中出现钉钉通道加载失败的错误。

钉钉是 OpenClaw 的社区插件，需要单独安装：

bash

openclaw plugins install https://github.com/soimy/openclaw-channel-dingtalk.git

确认插件已安装：openclaw plugins list，检查 dingtalk 是否在列表中。

如果使用 Docker，确保镜像中已包含该插件。

控制面板无法访问（ERR_EMPTY_RESPONSE）

症状：浏览器打开 http://127.0.0.1:18789/ 时显示 ERR_EMPTY_RESPONSE 或 "didn't send any data"，但容器日志显示 [gateway] listening。

原因：网关绑定到容器内的 127.0.0.1，标准 Docker 端口映射通过桥接网络转发流量（来源 IP 不是 localhost），网关拒绝连接。

解决方案：

在 docker-compose.yml 中使用 network_mode: host（并移除 ports: 配置）
macOS 用户需在 Docker Desktop 设置中启用 "Enable host networking"（设置 → 资源 → 网络）
重新创建容器：docker compose down && docker compose up -d

控制面板显示 "unauthorized: gateway token missing"

症状：控制面板页面加载成功，但显示 WebSocket 断开连接，提示 "unauthorized: gateway token missing"。

解决方案：通过 URL 传递令牌访问控制面板：

http://127.0.0.1:18789/?token=<your-gateway-token>

将 <your-gateway-token> 替换为 .env 中的 OPENCLAW_GATEWAY_TOKEN 值。

模型 422 错误（model not found）

症状：发送消息时返回 HTTP 422: model not found。

原因：自定义端点不识别短模型别名。大多数自定义/代理端点需要完整的带日期后缀的模型 ID。

解决方案：在 openclaw-data/openclaw.json 中将模型 ID 更新为完整格式（如 claude-sonnet-4-5-20250929 而非 claude-3-5-sonnet），同时更新 agents.defaults.model.primary 和 models.providers.<name>.models[].id。

API 频率限制（Rate Limit）

症状：日志中出现 429 Too Many Requests 或 exceeded the frequency limit 错误。

原因：钉钉开放平台对 API 调用有频率限制，且限制比飞书更为严格。不同 API 的限制不同。

排查步骤：

检查日志中的具体错误信息，确认是哪个 API 被限流
常见限制：
- 机器人发送消息：单聊 20 条/秒，群聊 20 条/秒
- 通讯录查询：150 次/秒
- 文件上传：50 次/秒
如果频繁触发限流，考虑在消息发送间添加延迟
检查是否有重复消息或循环调用导致请求量异常

提示：钉钉的频率限制因 API 不同而异，具体限制请参阅钉钉开放平台文档 — 频率限制。

Stream 连接断开

症状：使用 Stream 模式时，连接频繁断开或无法建立连接。

排查步骤：

检查网络连接是否稳定
确认 clientId 和 clientSecret 正确无误
检查服务器出口 IP 是否在白名单中（如果配置了 IP 白名单）
查看容器日志中是否有连接错误的详细信息：docker compose logs -f
确认应用已发布且处于启用状态
检查是否有防火墙或代理拦截 WebSocket 连接（Stream 模式使用长连接）

提示：Stream 模式的连接由客户端主动发起，因此不受 NAT 限制。如果连接持续断开，通常是凭据错误或网络不稳定导致。可以尝试重启容器：docker compose restart。

Docker Compose + 钉钉部署指南 — 快速开始和部署概览
钉钉应用配置详解 — 钉钉开放平台配置步骤

配置参考与故障排除（钉钉） ​

openclaw.json 完整示例 ​

配置参考 ​

Agents 配置 ​

模型提供商配置 ​

钉钉通道配置 ​

AI 互动卡片配置 ​

网关配置 ​

Docker Compose 详解 ​

完整的 docker-compose.yml ​

卷挂载说明 ​

权限说明 ​

环境变量 ​

端口配置 ​

故障排除 ​

容器启动失败 ​

openclaw.json 中的 ${VAR_NAME} 被替换为实际值 ​

钉钉机器人无响应 ​

权限错误（EACCES / EBUSY） ​

群聊中机器人无响应 ​

插件未找到 ​

控制面板无法访问（ERR_EMPTY_RESPONSE） ​

控制面板显示 "unauthorized: gateway token missing" ​

模型 422 错误（model not found） ​

API 频率限制（Rate Limit） ​

Stream 连接断开 ​

返回 ​

相关文档 ​

配置参考与故障排除（钉钉）

openclaw.json 完整示例

配置参考

Agents 配置

模型提供商配置

钉钉通道配置

AI 互动卡片配置

网关配置

Docker Compose 详解

完整的 docker-compose.yml

卷挂载说明

权限说明

环境变量

端口配置

故障排除

容器启动失败

openclaw.json 中的 ${VAR_NAME} 被替换为实际值

钉钉机器人无响应

权限错误（EACCES / EBUSY）

群聊中机器人无响应

插件未找到

控制面板无法访问（ERR_EMPTY_RESPONSE）

控制面板显示 "unauthorized: gateway token missing"

模型 422 错误（model not found）

API 频率限制（Rate Limit）

Stream 连接断开

返回

相关文档