跳到主要內容

釘釘設置

Hermes Agent 與釘釘（DingTalk）集成作為聊天機器人，讓您可以通過私聊或群聊與您的 AI 助手進行對話。該機器人通過釘釘的流模式（Stream Mode）連接——一種長期保持的 WebSocket 連接，無需公網 URL 或 Webhook 服務器——並通過釘釘的會話 Webhook API 以 Markdown 格式發送回覆。

在設置之前，這裡是最讓人關心的部分：Hermes 在您的釘釘工作區中將如何表現。

Hermes 的行為表現​

上下文行為
私聊（1:1 聊天）Hermes 對每條消息都作出響應。無需 @提及。每個私聊都有獨立的會話。
群聊當您 @提及 它時，Hermes 才會響應。未被提及的消息，Hermes 會忽略。
多人共享的群組默認情況下，Hermes 在群組內為每個用戶隔離會話歷史。兩個人在同一個群組中聊天時，不會共享同一份對話記錄，除非您顯式禁用此功能。

釘釘中的會話模型​

默認情況下：

  • 每個私聊擁有獨立的會話
  • 在共享群聊中，每個用戶擁有獨立的會話

這由 config.yaml 控制：

group_sessions_per_user: true

僅當您明確希望整個群組共享一個對話時，才將其設置為 false：

group_sessions_per_user: false

本指南將引導您完成完整的設置流程——從創建釘釘機器人到發送第一條消息。

先決條件​

安裝所需的 Python 包：

pip install dingtalk-stream httpx
  • dingtalk-stream —— 釘釘官方提供的流模式 SDK（基於 WebSocket 的實時消息）
  • httpx —— 用於通過會話 Webhook 發送回覆的異步 HTTP 客戶端

第一步：創建釘釘應用​

  1. 訪問 釘釘開發者控制檯。
  2. 使用您的釘釘管理員賬號登錄。
  3. 點擊 應用開發 → 自建應用 → 通過 H5 小程序創建應用（或根據控制檯版本選擇 機器人）。
  4. 填寫以下信息：
    • 應用名稱：例如 Hermes Agent
    • 描述：可選
  5. 創建完成後，進入 憑證與基本信息 頁面，找到您的 Client ID（AppKey）和 Client Secret（AppSecret）。請複製這兩項。
憑證僅顯示一次

Client Secret 僅在創建應用時顯示一次。如果丟失，您需要重新生成。請勿將這些憑證公開分享，也請勿提交到 Git。

第二步：啟用機器人功能​

  1. 在應用設置頁面，點擊 添加能力 → 機器人。
  2. 啟用機器人功能。
  3. 在 消息接收模式 中，選擇 流模式（推薦——無需公網 URL）。
提示

流模式是推薦的配置。它使用從您的機器發起的長期 WebSocket 連接，因此無需公網 IP、域名或 Webhook 端點。該模式可在 NAT、防火牆後以及本地機器上正常工作。

第三步：查找您的釘釘用戶 ID​

Hermes Agent 使用您的釘釘用戶 ID 來控制誰可以與機器人互動。釘釘用戶 ID 是由組織管理員設置的字母數字字符串。

要查找您的用戶 ID：

  1. 請向您的釘釘組織管理員諮詢——用戶 ID 在釘釘管理員控制檯的 通訊錄 → 成員 中配置。
  2. 或者，機器人會記錄每條消息的 sender_id。啟動網關後，向機器人發送一條消息，然後檢查日誌以獲取您的 ID。

第四步：配置 Hermes Agent​

運行引導式設置命令：

hermes gateway setup

提示時選擇 DingTalk，然後粘貼您的 Client ID、Client Secret 和允許的用戶 ID。

選項 B：手動配置​

將以下內容添加到您的 ~/.hermes/.env 文件中：

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

# 安全：限制哪些用戶可以與機器人交互
DINGTALK_ALLOWED_USERS=user-id-1

# 多個允許用戶（用逗號分隔）
# DINGTALK_ALLOWED_USERS=用戶-id-1,用戶-id-2

可選的行為設置在 ~/.hermes/config.yaml 中：

group_sessions_per_user: true
  • group_sessions_per_user: true 在共享群聊中為每位參與者保持上下文隔離

啟動網關​

配置完成後，啟動釘釘網關：

hermes gateway

機器人應在幾秒內連接到釘釘的流模式。向它發送一條消息——無論是私聊還是已添加的群聊——以進行測試。

提示

您可以將 hermes gateway 在後臺運行，或作為 systemd 服務運行以實現持久化操作。詳情請參閱部署文檔。

故障排除​

機器人不響應消息​

原因：機器人功能未啟用，或 DINGTALK_ALLOWED_USERS 中未包含您的用戶 ID。

解決方法：確認您的應用設置中已啟用機器人功能，並選擇了流模式。檢查您的用戶 ID 是否在 DINGTALK_ALLOWED_USERS 中。重啟網關。

“dingtalk-stream 未安裝” 錯誤​

原因：dingtalk-stream Python 包未安裝。

解決方法：安裝該包：

pip install dingtalk-stream httpx

“DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET 必需”​

原因：憑證未在您的環境變量或 .env 文件中設置。

修復方法：請確認 ~/.hermes/.env 文件中已正確設置 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET。Client ID 即為您的 AppKey，Client Secret 即為釘釘開發者後臺的 AppSecret。

流連接中斷 / 重連循環​

原因：網絡不穩定、釘釘平臺維護或憑證問題。

修復方法：適配器會自動使用指數退避機制重連（2秒 → 5秒 → 10秒 → 30秒 → 60秒）。請確認您的憑證有效，且應用未被停用。同時檢查您的網絡是否允許出站 WebSocket 連接。

機器人離線​

原因：Hermes 網關未運行，或未能成功連接。

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

“No session_webhook available”​

原因：機器人嘗試回覆消息，但沒有可用的會話 webhook URL。這通常發生在 webhook 過期，或機器人在收到消息與發送回覆之間被重啟的情況下。

修復方法：向機器人發送一條新消息——每條傳入消息都會提供一個用於回覆的新會話 webhook。這是釘釘平臺的正常限制；機器人只能回覆最近收到的消息。

安全性​

注意

請始終設置 DINGTALK_ALLOWED_USERS 以限制可與機器人交互的用戶。若未設置，網關默認會拒絕所有用戶，這是一種安全措施。僅添加您信任的用戶 ID——授權用戶將擁有對 Agent 全部功能的完全訪問權限，包括工具使用和系統訪問。

有關保護您的 Hermes Agent 部署的更多信息，請參閱 安全指南。

注意事項​

  • 流模式：無需公網 URL、域名或 webhook 服務器。連接由您的機器通過 WebSocket 主動發起，因此可在 NAT 和防火牆後正常工作。
  • Markdown 格式回覆：回覆內容以釘釘的 Markdown 格式進行渲染，支持富文本顯示。
  • 消息去重：適配器在 5 分鐘窗口內對消息進行去重，防止重複處理同一消息。
  • 自動重連：若流連接中斷，適配器將自動使用指數退避機制重新連接。
  • 消息長度限制：每條回覆最多限制為 20,000 個字符，超出部分將被截斷。