<!-- Source: https://hermesbible.com/docs/user-guide/messaging/dingtalk -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/dingtalk

DingTalk 設定

Hermes Agent 整合了 DingTalk（钉钉）聊天機器人功能，讓你可以透過私訊或群組聊天與 AI 助理互動。機器人透過 DingTalk 的 Stream Mode 連線——一種長效 WebSocket 連線，無需公開 URL 或 webhook 伺服器——並透過 DingTalk 的 session webhook API 以 markdown 格式回覆訊息。

在開始設定之前，先說明 most 人最想知道的部分：Hermes 在你的 DingTalk 工作空間中的行為模式。

Hermes 的行為模式

DingTalk 中的 Session 模型

預設情況下：

• 每段私訊有各自的 session
• 群組聊天中的每位使用者在該群組內有各自的 session

這由 config.yaml 控制：

group_sessions_per_user: true

只有在你明確想要整個群組共用一段對話時，才設為 false：

group_sessions_per_user: false

本指南將帶你完成完整的設定流程——從建立你的 DingTalk 機器人到發送第一則訊息。

前置需求

安裝所需的 Python 套件：

pip install "hermes-agent[dingtalk]"

或分別安裝：

pip install dingtalk-stream httpx alibabacloud-dingtalk

• dingtalk-stream — DingTalk 官方的 Stream Mode SDK（基於 WebSocket 的即時通訊）
• httpx — 非同步 HTTP 客戶端，用於透過 session webhook 發送回覆
• alibabacloud-dingtalk — DingTalk OpenAPI SDK，用於 AI 卡片、表情回應和媒體下載

步驟一：建立 DingTalk 應用

1. 前往 DingTalk Developer Console。
2. 使用你的 DingTalk 管理員帳號登入。
3. 點選 應用開發 → 自訂應用 → 透過 H5 微應用建立應用（或根據你的控制台版本選擇 機器人）。
4. 填寫：
   • 應用名稱：例如 Hermes Agent
   • 描述：選填
5. 建立後，前往 憑證與基本資訊 找到你的 Client ID（AppKey）和 Client Secret（AppSecret）。複製兩者。

:::warning[憑證僅顯示一次] Client Secret 在建立應用時只會顯示一次。如果遺失，你需要重新產生。切勿公開分享這些憑證或將它們提交至 Git。 :::

步驟二：啟用機器人功能

1. 在你的應用設定頁面中，前往 新增功能 → 機器人。
2. 啟用機器人功能。
3. 在 訊息接收模式 中，選擇 Stream Mode（建議——無需公開 URL）。

提示

Stream Mode 是建議的設定方式。它使用從你的機器器啟動的長效 WebSocket 連線，因此你不需要公開 IP、域名或 webhook 端點。這在 NAT、防火牆後方和本地機器上都能運作。

步驟三：取得你的 DingTalk User ID

Hermes Agent 使用你的 DingTalk User ID 來控制誰可以與機器人互動。DingTalk User ID 是由你的組織管理員設定的字母數字字串。

取得方式：

1. 請你的 DingTalk 組織管理員——User ID 在 DingTalk 管理控制台的 通訊錄 → 成員 中設定。
2. 另一種方式：機器人會記錄每則收到訊息的 sender_id。啟動 gateway，發送一則訊息給機器人，然後在日誌中查看你的 ID。

步驟四：設定 Hermes Agent

選項 A：互動式設定（建議）

執行引導式設定指令：

hermes gateway setup

在提示時選擇 DingTalk。設定精靈可以透過以下兩種方式授權：

• QR Code 裝置流程（建議）。 使用 DingTalk 手機應用掃描終端機中顯示的 QR Code——你的 Client ID 和 Client Secret 會自動回傳並寫入 ~/.hermes/.env。無需前往開發者控制台。
• 手動貼上。 如果你已有憑證（或 QR Code 掃描不方便），在提示時貼上你的 Client ID、Client Secret 和允許的 User ID。

注意——openClaw 品牌揭露

由於 DingTalk 的 verification_uri_complete 在 API 層級硬編碼為 openClaw 身份，目前 QR Code 授權畫面顯示的是 openClaw 來源字串，直到阿里巴巴/ DingTalk-Real-AI 在伺服器端註冊 Hermes 專屬的模板為止。這只是 DingTalk 顯示授權畫面的方式——你建立的機器人完全屬於你的租戶且為私有。

選項 B：手動設定

將以下內容加入你的 ~/.hermes/.env 檔案：

# 必填
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret

# 安全性：限制誰可以與機器人互動
DINGTALK_ALLOWED_USERS=user-id-1

# 多位允許的使用者（以逗號分隔）
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# 選填：群組聊天存取控制（對應 Slack/Telegram/Discord/WhatsApp）
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小馬
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true

~/.hermes/config.yaml 中的選填行為設定：

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # 群組中需要 @mention 機器人才會回覆（與 Slack/Telegram/Discord 一致）。
        # 私訊不受影響——機器人始終在 1:1 聊天中回覆。
        require_mention: true

        # 平台級別的允許清單。設定後，只有這些 DingTalk User ID 可以與機器人互動
        # （與 DINGTALK_ALLOWED_USERS 相同語意，但範圍限定在此處而非 .env）。
        allowed_users:
          - user-id-1
          - user-id-2

• group_sessions_per_user: true 讓每位參與者在共用群組聊天中保持獨立的對話上下文
• require_mention: true 防止機器人回覆每則群組訊息——只在有人 @提及 時才回應
• dingtalk.extra 下的 allowed_users 是 DINGTALK_ALLOWED_USERS 的替代方案；若兩者都設定，會合併使用

啟動 Gateway

設定完成後，啟動 DingTalk gateway：

hermes gateway

機器人應在幾秒內連線至 DingTalk 的 Stream Mode。發送一則訊息——無論是私訊或已加入的群組——來測試。

提示

你可以將 hermes gateway 作為背景程式或 systemd 服務持續運行。詳見部署文件。

功能

AI 卡片

Hermes 可以使用 DingTalk AI 卡片回覆，而非純 markdown 訊息。卡片提供更豐富、更有結構的顯示效果，並支援在代理程式產生回應時的串流更新。

要啟用 AI 卡片，請在 config.yaml 中設定卡片模板 ID：

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "your-card-template-id"

你可以在 DingTalk Developer Console 中你的應用 AI 卡片設定下找到卡片模板 ID。啟用 AI 卡片後，所有回覆都以卡片形式發送，並支援串流文字更新。

表情回應

Hermes 會自動為你的訊息添加表情回應以顯示處理狀態：

• 🤔Thinking — 在機器人開始處理你的訊息時添加
• 🥳Done — 在回應完成時添加（取代 Thinking 回應）

這些回應在私訊和群組聊天中都有效。

顯示設定

你可以獨立於其他平台自訂 DingTalk 的顯示行為：

display:
  platforms:
    dingtalk:
      show_reasoning: false   # 在回覆中顯示模型推理/思考過程
      streaming: true         # 啟用串流回應（搭配 AI 卡片運作）
      tool_progress: all      # 顯示工具執行進度（all/new/off）
      interim_assistant_messages: true  # 顯示中間評論訊息

要關閉工具進度和中間訊息以獲得更簡潔的體驗：

display:
  platforms:
    dingtalk:
      tool_progress: off
      interim_assistant_messages: false

疑難排解

機器人沒有回應訊息

原因：機器人功能未啟用，或 DINGTALK_ALLOWED_USERS 未包含你的 User ID。

修正方法：確認你的應用設定中已啟用機器人功能且已選擇 Stream Mode。檢查你的 User ID 是否在 DINGTALK_ALLOWED_USERS 中。重新啟動 gateway。

「dingtalk-stream not installed」錯誤

原因：未安裝 dingtalk-stream Python 套件。

修正方法：安裝它：

pip install dingtalk-stream httpx

「DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required」

原因：環境變數或 .env 檔案中未設定憑證。

修正方法：確認 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET 已正確設定在 ~/.hermes/.env 中。Client ID 是你的 AppKey，Client Secret 是你在 DingTalk Developer Console 中的 AppSecret。

Stream 斷線 / 重連迴圈

原因：網路不穩定、DingTalk 平台維護或憑證問題。

修正方法：轉接器會自動以指數退避重連（2s → 5s → 10s → 30s → 60s）。檢查你的憑證是否有效且應用未被停用。確認你的網路允許出站 WebSocket 連線。

機器人離線

原因：Hermes gateway 未運行或連線失敗。

修正方法：確認 hermes gateway 正在運行。查看終端機輸出的錯誤訊息。常見問題：憑證錯誤、應用已停用、未安裝 dingtalk-stream 或 httpx。

「No session_webhook available」

原因：機器人嘗試回覆但沒有 session webhook URL。這通常發生在 webhook 過期或機器人在收到訊息和發送回覆之間重啟。

修正方法：向機器人發送一則新訊息——每則收到的訊息都會提供一個新的 session webhook 用於回覆。這是 DingTalk 的正常限制；機器人只能回覆最近收到的訊息。

安全性

警告

務必設定 DINGTALK_ALLOWED_USERS 以限制誰可以與機器人互動。若未設定，gateway 會作為安全措施預設拒絕所有使用者。只新增你信任的使用者的 User ID——授權使用者擁有對代理程式功能的完整存取權限，包括工具使用和系統存取。

如需更多關於保護 Hermes Agent 部署安全的資訊，請參閱 安全指南。

附註

• Stream Mode：無需公開 URL、域名或 webhook 伺服器。連線從你的機器器透過 WebSocket 啟動，因此在 NAT 和防火牆後方也能運作。
• AI 卡片：可選擇使用豐富的 AI 卡片回覆，而非純 markdown。透過 card_template_id 設定。
• 表情回應：自動添加 🤔Thinking/🥳Done 表情回應以顯示處理狀態。
• Markdown 回覆：回覆使用 DingTalk 的 markdown 格式以實現富文字顯示。
• 媒體支援：收到訊息中的圖片和檔案會自動解析，可由視覺工具處理。
• 訊息去重：轉接器在 5 分鐘時間窗口內對訊息進行去重，防止重複處理相同訊息。
• 自動重連：若 stream 連線中斷，轉接器會自動以指數退避重連。
• 訊息長度限制：每則訊息的回覆上限為 20,000 個字元。較長的回覆會被截斷。

---

---

Feishu / Lark