@soimy/dingtalk

v3.1.4

Published

3 days ago

DingTalk (钉钉) channel plugin for OpenClaw

0High
0Medium
0Low

soimy

bot channel clawdbot dingtalk openclaw stream 钉钉

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：手动安装

将本目录下载或复制到 ~/.openclaw/extensions/dingtalk。
确保包含 index.ts, openclaw.plugin.json 和 package.json。
运行 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

交互式配置流程：

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

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

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

钉钉开发者平台配置指南

1. 创建钉钉应用

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

2. 配置权限管理

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

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

步骤：

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

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

步骤：

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

配置选项

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

连接鲁棒性配置

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

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 — 只有配置的群可以使用

消息类型支持

接收

| 类型 | 支持 | 说明 | | ------ | ---- | -------------------- | | 文本 | ✅ | 完整支持 | | 富文本 | ✅ | 提取文本内容 | | 图片 | ✅ | 下载并传递给 AI | | 语音 | ✅ | 使用钉钉语音识别结果 | | 视频 | ✅ | 下载并传递给 AI | | 文件 | ✅ | 下载并传递给 AI |

发送

| 类型 | 支持 | 说明 | | -------- | ---- | -------------------------------- | | 文本 | ✅ | 完整支持 | | Markdown | ✅ | 自动检测或手动指定 | | 互动卡片 | ✅ | 支持流式更新，适用于 AI 实时输出 | | 图片 | ⏳ | 需要通过媒体上传 API |

API 消耗说明

Text/Markdown 模式

| 操作 | API 调用次数 | 说明 | | ---------- | ------------ | ---------------------------------------------------------------------------- | | 获取 Token | 1 | 共享/缓存（60 秒检查过期一次） | | 发送消息 | 1 | 使用 /v1.0/robot/oToMessages/batchSend 或 /v1.0/robot/groupMessages/send | | 总计 | 2 | 每条回复 1 次 |

Card（AI 互动卡片）模式

| 阶段 | API 调用 | 说明 | | ------------ | ---------------------- | --------------------------------------------------- | | 创建卡片 | 1 | POST /v1.0/card/instances/createAndDeliver | | 流式更新 | M | M = 回复块数量，每块一次 PUT /v1.0/card/streaming | | 完成卡片 | 包含在最后一次流更新中 | 使用 isFinalize=true 标记 | | 总计 | 1 + M | M = Agent 产生的回复块数 |

典型场景成本对比

| 场景 | Text/Markdown | Card | 节省 | | ---------------- | ------------- | ---- | ------ | | 简短回复（1 块） | 2 | 2 | ✓ 相同 | | 中等回复（5 块） | 6 | 6 | ✓ 相同 | | 长回复（10 块） | 12 | 11 | ✓ 1 次 |

优化策略

降低 API 调用的方法：

合并回复块 — 通过调整 Agent 输出配置，减少块数量
使用缓存 — Token 自动缓存（60 秒），无需每次都获取
Buffer 模式 — 使用 dispatchReplyWithBufferedBlockDispatcher 合并多个小块

成本建议：

✅ 推荐 — Card 模式：流式体验更好，成本与 Text/Markdown 相当或更低
⚠️ 谨慎 — 频繁调用需要监测配额，建议使用钉钉开发者后台查看 API 调用量

消息类型选择

插件支持两种消息回复类型，可通过 messageType 配置：

1. markdown（Markdown 格式）【默认】

支持富文本格式（标题、粗体、列表等）
自动检测消息是否包含 Markdown 语法
适用于大多数场景

2. card（AI 互动卡片）

支持流式更新（实时显示 AI 生成内容）
更好的视觉呈现和交互体验
支持 Markdown 格式渲染
通过 cardTemplateId 指定模板
通过 cardTemplateKey 指定内容字段
适用于 AI 对话场景
支持在卡片中实时显示 AI 思考过程（推理流）和工具执行结果

AI Card API 特性： 当配置 messageType: 'card' 时：

使用 /v1.0/card/instances/createAndDeliver 创建并投放卡片
使用 /v1.0/card/streaming 实现真正的流式更新
自动状态管理（PROCESSING → INPUTING → FINISHED）
更稳定的流式体验，无需手动节流

AI 思考过程与工具执行显示（AI Card 模式）

当 messageType 为 card 时，插件可以在卡片中实时展示 AI 的推理过程（🤔 思考中）和工具调用结果（🛠️ 工具执行）。这两项功能通过对话级命令控制，无需修改配置文件：

| 功能 | 对话命令 | 说明 | | ----------------- | --------------------- | ---------------------------------- | | 显示 AI 推理流 | /reasoning stream | 开启后，AI 思考内容实时更新到卡片 | | 显示工具执行结果 | /verbose on | 开启后，工具调用结果实时更新到卡片 | | 关闭 AI 推理流 | /reasoning off | 关闭推理流显示 | | 关闭工具执行显示 | /verbose off | 关闭工具执行结果显示 |

显示格式：

思考内容以 🤔 **思考中** 为标题，正文以 > 引用块展示，最多显示前 500 个字符
工具结果以 🛠️ **工具执行** 为标题，正文以 > 引用块展示，最多显示前 500 个字符

注意： 推理流和工具执行均会产生额外的卡片流式更新 API 调用，在 AI 推理步骤较多时可能显著增加 API 消耗，建议按需开启。

配置示例：

{
  messageType: 'card', // 启用 AI 互动卡片模式
  cardTemplateId: '382e4302-551d-4880-bf29-a30acfab2e71.schema', // AI 卡片模板 ID（默认值）
  cardTemplateKey: 'msgContent', // 卡片内容字段键（默认值：msgContent）
}

注意：cardTemplateKey 应与您的卡片模板中定义的字段名称一致。默认值为 'msgContent'，适用于 DingTalk 官方 AI 卡片模板。如果您使用自定义模板，请根据模板定义的字段名称进行配置。

使用示例

配置完成后，直接在钉钉中：

私聊机器人 — 找到机器人，发送消息
群聊 @机器人 — 在群里 @机器人名称 + 消息

故障排除

收不到消息

确认应用已发布
确认消息接收模式是 Stream
检查 Gateway 日志：openclaw logs | grep dingtalk

群消息无响应

确认机器人已添加到群
确认正确 @机器人（使用机器人名称）
确认群是企业内部群

连接失败

检查 clientId 和 clientSecret 是否正确
确认网络可以访问钉钉 API

错误 payload 日志规范（`[ErrorPayload]`）

为便于快速定位 4xx/5xx 参数问题，插件会在 API 错误分支输出统一格式日志：

通用前缀：[DingTalk][ErrorPayload][<scope>]
AI Card 前缀：[DingTalk][AICard][ErrorPayload][<scope>]
内容格式：code=<...> message=<...> payload=<...>（同时保留脱敏后的完整 payload）

常见 scope 示例：

send.proactiveMessage / send.proactiveMedia / send.message
outbound.sendText / outbound.sendMedia
inbound.downloadMedia / inbound.cardFinalize
card.create / card.stream / card.stream.retryAfterRefresh
retry.beforeDecision

排查建议：

openclaw logs | grep "\[ErrorPayload\]"

如果你看到 code=invalidParameter，通常优先检查请求 payload 的必填字段（例如 robotCode、userIds、msgKey、msgParam）是否完整且格式正确。

开发指南

首次设置

克隆仓库并安装依赖

git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk
npm install

验证开发环境

npm run type-check              # TypeScript 类型检查
npm run lint                    # ESLint 代码检查

常用命令

| 命令 | 说明 | | -------------------- | ------------------- | | npm run type-check | TypeScript 类型检查 | | npm run lint | ESLint 代码检查 | | npm run lint:fix | 自动修复格式问题 |

项目结构

src/
  channel.ts           - 插件定义和辅助函数（535 行）
  runtime.ts           - 运行时管理（14 行）
  types.ts             - 类型定义（30+ interfaces）

index.ts              - 插件注册（29 行）
utils.ts              - 工具函数（110 行）

openclaw.plugin.json  - 插件配置
package.json          - 项目配置
README.md             - 本文件

代码质量

TypeScript: 严格模式，0 错误
ESLint: 自动检查和修复
Type Safety: 完整的类型注解（30+ 接口）

类型系统

核心类型定义在 src/types.ts 中，包括：

// 配置
DingTalkConfig; // 插件配置
DingTalkChannelConfig; // 多账户配置

// 消息处理
DingTalkInboundMessage; // 收到的钉钉消息
MessageContent; // 解析后的消息内容
HandleDingTalkMessageParams; // 消息处理参数

// AI 互动卡片
AICardInstance; // AI 卡片实例
AICardCreateAndDeliverRequest; // 创建并投放卡片请求
AICardStreamingRequest; // 流式更新请求
AICardStatus; // 卡片状态常量

// 工具函数类型
Logger; // 日志接口
RetryOptions; // 重试选项
MediaFile; // 下载的媒体文件

公开 API

插件导出以下低级 API 函数，可用于自定义集成：

// 文本/Markdown 消息
sendBySession(config, sessionWebhook, text, options); // 通过会话发送

// AI 互动卡片
createAICard(config, conversationId, data, log); // 创建并投放 AI 卡片
streamAICard(card, content, finished, log); // 流式更新卡片内容
finishAICard(card, content, log); // 完成并关闭卡片

// 自动模式选择
sendMessage(config, conversationId, text, options); // 根据配置自动选择（含卡片/文本回退）

// 认证
getAccessToken(config, log); // 获取访问令牌

使用示例：

import { createAICard, streamAICard, finishAICard } from './src/channel';

// 创建 AI 卡片
const card = await createAICard(config, conversationId, messageData, log);

// 流式更新内容
for (const chunk of aiResponseChunks) {
  await streamAICard(card, currentText + chunk, false, log);
}

// 完成并关闭卡片
await finishAICard(card, finalText, log);

架构

插件遵循 Telegram 参考实现的架构模式：

index.ts: 最小化插件注册入口
src/channel.ts: 所有 DingTalk 特定的逻辑（API、消息处理、配置等）
src/runtime.ts: 运行时管理（getter/setter）
src/types.ts: 类型定义
utils.ts: 通用工具函数

测试

项目已基于 Vitest 初始化自动化测试，目录结构如下：

tests/
  unit/
    sign.test.ts               # HmacSHA256 + Base64 签名测试
    message-transform.test.ts  # 文本/Markdown 消息转换测试
  integration/
    send-lifecycle.test.ts     # 插件 outbound.sendText 生命周期适配测试

运行测试

# 安装依赖（pnpm）
pnpm install

# 运行全部测试
pnpm test

# 生成覆盖率报告（coverage/）
pnpm test:coverage

Mock 约束

所有测试中的网络请求均通过 vi.mock('axios') 拦截，禁止真实调用钉钉 API。
集成测试通过模块 mock 隔离 openclaw/plugin-sdk、dingtalk-stream 等外部依赖。

许可

MIT