DingTalk Channel for OpenClaw

钉钉企业内部机器人 Channel 插件，使用 Stream 模式（无需公网 IP）。

功能特性

• ✅ Stream 模式 — WebSocket 长连接，无需公网 IP 或 Webhook
• ✅ 私聊支持 — 直接与机器人对话
• ✅ 群聊支持 — 在群里 @机器人
• ✅ 多种消息类型 — 文本、图片、语音（自带识别）、视频、文件
• ✅ Markdown 回复 — 支持富文本格式回复
• ✅ 互动卡片 — 支持流式更新，适用于 AI 实时输出
• ✅ 完整 AI 对话 — 接入 Clawdbot 消息处理管道

安装

方法 A：通过 npm 包安装 (推荐)

手动通过 npm 包名安装：

openclaw plugins install @soimy/dingtalk

方法 B：通过本地源码安装

如果你想对插件进行二次开发，可以先克隆仓库：

# 1. 克隆仓库
git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk

# 2. 安装依赖 (必需)
npm install

# 3. 以链接模式安装 (方便修改代码后实时生效)
openclaw plugins install -l .

方法 C：手动安装

1. 将本目录下载或复制到 ~/.openclaw/extensions/dingtalk。
2. 确保包含 index.ts, openclaw.plugin.json 和 package.json。
3. 运行 openclaw plugins list 确认 dingtalk 已显示在列表中。

安装后必做：配置插件信任白名单（plugins.allow）

从 OpenClaw 新版本开始，如果发现了非内置插件且 plugins.allow 为空，会提示：

[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load ...

这是一条安全告警（不是安装失败），建议显式写入你信任的插件 id。

步骤 1：确认插件 id

本插件 id 固定为：dingtalk（定义于 openclaw.plugin.json）。

也可用下面命令查看已发现插件：

openclaw plugins list

步骤 2：在 ~/.openclaw/openclaw.json 添加 plugins.allow

{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  }
}

如果你还有其他已安装且需要启用的插件，请一并加入，例如：

{
  "plugins": {
    "allow": ["dingtalk", "telegram", "voice-call"]
  }
}

步骤 3：重启 Gateway

openclaw gateway restart

注意：如果你之前已经配置过 plugins.allow，但没有 dingtalk，那么插件不会被加载。请把 dingtalk 加入该列表。

更新

openclaw plugins update 使用插件 id（不是 npm 包名），并且仅适用于 npm 安装来源。

如果你是通过 npm 安装本插件：

openclaw plugins update dingtalk

如果你是本地源码/链接安装（openclaw plugins install -l .），请在插件目录更新代码后重启 Gateway：

git pull
openclaw gateway restart

配置

OpenClaw 支持交互式配置和手动配置文件两种方式。

方法 1：交互式配置（推荐）

使用 OpenClaw 命令行向导式配置插件参数：

# 方式 A：使用 onboard 命令
openclaw onboard

# 方式 B：直接配置 channels 部分
openclaw configure --section channels

交互式配置流程：

1. 选择插件 — 在插件列表中选择 dingtalk 或 DingTalk (钉钉)
2. Client ID — 输入钉钉应用的 AppKey
3. Client Secret — 输入钉钉应用的 AppSecret
4. 完整配置 — 可选配置 Robot Code、Corp ID、Agent ID（推荐）
5. 卡片模式 — 可选启用 AI 互动卡片模式
   • 如启用，需输入 Card Template ID 和 Card Template Key
6. 私聊策略 — 选择 open（开放）或 allowlist（白名单）
7. 群聊策略 — 选择 open（开放）或 allowlist（白名单）

所有的参数参考下文中的钉钉开发者平台配置指南

配置完成后会自动保存并重启 Gateway。

钉钉开发者平台配置指南

1. 创建钉钉应用

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

2. 配置权限管理

在应用的权限管理页面，需要开启以下权限：

• ✅ Card.Instance.Write — 创建和投放卡片实例
• ✅ Card.Streaming.Write — 对卡片进行流式更新

步骤：

1. 进入应用 → 权限管理
2. 搜索「Card」相关权限
3. 勾选上述两个权限
4. 保存权限配置

3. 建立卡片模板(可选)

步骤：

1. 访问 钉钉卡片平台
2. 进入「我的模板」
3. 点击「创建模板」
4. 卡片模板场景选择 「AI 卡片」
5. 按需设计卡片排版,点击保存并发布
6. 记下模板中定义的内容字段名称
7. 复制模板 ID（格式如：xxxxx-xxxxx-xxxxx.schema）
8. 将 templateId 配置到 openclaw.json 的 cardTemplateId 字段
9. 或在OpenClaw控制台的Channel标签->Dingtalk配置面板-> Card Template Id填入
10. 将记下的内容字段变量名配置到 openclaw.json 的 cardTemplateKey 字段
11. 或在OpenClaw控制台的Channel标签->Dingtalk配置面板-> Card Template Key填入

说明：

• 使用 DingTalk 官方 AI 卡片模板时，cardTemplateKey 默认为 'msgContent'，无需修改
• 如果您创建自定义卡片模板，需要确保模板中包含相应的内容字段，并将 cardTemplateKey 配置为该字段名称

4. 获取凭证

从开发者后台获取：

• Client ID (AppKey)
• Client Secret (AppSecret)
• Robot Code (与 Client ID 相同)
• Corp ID (企业 ID)
• Agent ID (应用 ID)

方法 2：手动配置文件

在 ~/.openclaw/openclaw.json 中添加（仅作参考，交互式配置会自动生成）：

至少包含 plugins.allow 和 channels.dingtalk 两部分，内容参考上文钉钉开发者配置指南

{
  "plugins": {
    "enabled": true,
    "allow": ["dingtalk"]
  },

  ...
  "channels": {
    "telegram": { ... },

    "dingtalk": {
      "enabled": true,
      "clientId": "dingxxxxxx",
      "clientSecret": "your-app-secret",
      "robotCode": "dingxxxxxx",
      "corpId": "dingxxxxxx",
      "agentId": "123456789",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "debug": false,
      "messageType": "markdown", // 或 "card"
      // 仅card需要配置
      "cardTemplateId": "你复制的模板ID",
      "cardTemplateKey": "你模板的内容变量"
    }
  },
  ...
}

最后重启 Gateway

使用交互式配置时，Gateway 会自动重启。使用手动配置时需要手动执行：

openclaw gateway restart

配置选项

连接鲁棒性配置

为提高连接稳定性，插件支持以下高级配置：

• maxConnectionAttempts: 连接失败后的最大重试次数，超过后将停止尝试并报警。
• initialReconnectDelay: 第一次重连的初始延迟（毫秒），后续重连会按指数增长。
• maxReconnectDelay: 重连延迟的上限（毫秒），防止等待时间过长。
• reconnectJitter: 延迟抖动因子，在延迟基础上增加随机变化（±30%），避免多个客户端同时重连。

重连延迟计算公式：delay = min(initialDelay × 2^attempt, maxDelay) × (1 ± jitter)

示例延迟序列（默认配置）：~1s, ~2s, ~4s, ~8s, ~16s, ~32s, ~60s（达到上限）

更多详情请参阅 CONNECTION_ROBUSTNESS.md。

安全策略

私聊策略 (dmPolicy)

• open — 任何人都可以私聊机器人
• pairing — 新用户需要通过配对码验证
• allowlist — 只有 allowFrom 列表中的用户可以使用

群聊策略 (groupPolicy)

• open — 任何群都可以 @机器人
• allowlist — 只有配置的群可以使用

消息类型支持

接收

发送

API 消耗说明

Text/Markdown 模式

Card（AI 互动卡片）模式

| 阶段 | API 调用 | 说明
…(truncated)…