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（規劃中）：協議說明

本頁目錄