DingTalk (钉钉)

DingTalk 自定义群机器人使用 HMAC-SHA256 签名 URL。下一步计划支持 Stream Mode（WebSocket）。

🟡 支持自定义机器人外发消息，支持 outgoing webhook 接收消息 最低门槛的接入方式是钉钉"自定义群机器人"配合签名 URL。企业自建应用与 Stream Mode（钉钉推荐的 WebSocket 传输方式）将在后续版本支持。

功能说明

外发文本消息：通过 POST https://oapi.dingtalk.com/robot/send，使用 HMAC-SHA256 URL 签名（timestamp + secret）。
接收 outgoing webhook：在 /webhooks/dingtalk 接收自定义机器人 @提及消息。钉钉以 POST 方式将用户消息回传，携带新的 timestamp 和 sign，Minara 以与外发签名相同的方式进行验证。
仅支持文本：Markdown、actionCard、feedCard 消息类型暂不支持。
单条文本限 5000 字符。

配置步骤

1. 创建自定义群机器人

在桌面端或移动端打开目标钉钉群
群设置 → "群助手" → "添加机器人" → "自定义"
填写名称和头像；在"安全设置"中选择**"加签"**（即签名 URL 方式，非"自定义关键词"或"IP 地址"）
保存后复制以下两个字符串：
- Webhook URL（即 https://oapi.dingtalk.com/robot/send?access_token=... 格式的地址）
- 加签密钥（以 SEC 开头）

2. 配置 Minara

minara auth messaging add
# pick `dingtalk`; paste the webhook URL + SECxxxx secret.

或直接设置环境变量：

DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=<token>
DINGTALK_WEBHOOK_SECRET=SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. 测试

minara auth messaging test dingtalk

目标群组将在一两秒内收到"✅ Minara gateway test ping"消息。

外发签名原理

钉钉要求每次 POST 请求在 URL 中携带毫秒级时间戳和密钥的 HMAC 签名：

sign = base64( HmacSHA256( "<timestamp>\n<secret>", secret ) )
url  = <webhook URL>?timestamp=<ts>&sign=<urlencoded sig>

钉钉会拒绝与其服务器时钟偏差超过 1 小时的请求，时钟不同步的主机会收到"签名错误"响应。

接收 webhook（outgoing-message 模式）

在自定义机器人的 outgoing-message 流程中，钉钉会向以下地址发送 POST 请求：

https://<your-host>/webhooks/dingtalk

请求体携带用户消息，请求头包含新的 timestamp 和 sign。Minara 使用相同的 DINGTALK_WEBHOOK_SECRET 重新计算签名，不匹配时返回 401。

接收到的消息体结构：

{
  "msgtype": "text",
  "text": { "content": "@bot hello world" },
  "senderId": "user-staff-id",
  "senderNick": "Alice",
  "conversationId": "cidxxxx",
  "msgId": "<unique>",
  "createAt": 1700000000000
}

仅转发 msgtype === "text" 的事件；其他类型（image、audio、markdown、actionCard）将被丢弃。

限制与注意事项

时钟偏差影响签名。钉钉对外发 timestamp 设有 1 小时窗口限制；主机时钟漂移将导致签名失败。
outgoing webhook 仅在 @提及时触发。群机器人不会接收所有消息，只接收对自身的 @提及；这是钉钉的设计限制，非 Minara 过滤行为。
Stream Mode 是官方推荐的未来方案。钉钉官方建议新应用使用 Stream Mode（WebSocket）。Minara 当前实现了遗留的自定义机器人方式，Stream Mode 将在后续版本跟进。

故障排查

外发时出现"签名错误"

服务器时钟漂移。运行 chronyc tracking 或 timedatectl status，确认偏差远小于 1 秒。
DINGTALK_WEBHOOK_SECRET 填写有误。SECxxxx 字符串是完整密钥，包含 SEC 前缀。

"Inbound webhook returns 401"

接收端签名不匹配。最常见原因：群的"安全设置"选择了"加签"，但密钥已轮换，新值未同步到 ~/.minara/credentials.json。

"机器人对群中 @ 提及无响应"

请确认机器人详情页中"消息接收地址"（outgoing webhook）已启用。该开关与接收 URL 相互独立；未启用时机器人仅支持推送消息。

参考资料

环境变量：DINGTALK_WEBHOOK_URL、DINGTALK_WEBHOOK_SECRET
外发实现：apps/agent/src/messaging/dingtalk.ts
接收规范：apps/agent/src/messaging/inbound/specs/dingtalk.ts
钉钉开放平台：open.dingtalk.com
Stream Mode（规划中）：协议说明

本页目录