釘釘接入——國內辦公必備 | Easy Understand Hermes Agent

這篇教學帶你一步步把 Hermes Agent 接入釘釘，讓 AI 助手在你的企業聊天視窗裡隨叫隨到。

先搞懂：機器人進群後怎麼表現？

場景	行為
私聊（1對1）	每條訊息都回覆，不用 @ 它
群聊	只有 @ 它才回覆，否則裝啞巴
多人共用的群	預設每個人有獨立對話記憶，互不干擾

這個「每人獨立記憶」的開關在 config.yaml 裡控制：

group_sessions_per_user: true   # true=各聊各的，false=全群共享一份聊天記錄

準備工作：裝依賴

打開終端機，執行：

cd ~/.hermes/hermes-agent && uv pip install -e ".[dingtalk]"

裝不上的話，手動裝這三個套件也行：dingtalk-stream（釘釘官方串流模式 SDK）、httpx（發訊息用的 HTTP 用戶端）、alibabacloud-dingtalk（釘釘開放平台 SDK，用於 AI 卡片、表情回應等）。

第1步：建立釘釘應用

開啟釘釘開發者後台，用管理員帳號登入。
點擊 應用開發 → 企業內部應用 → 建立應用（選 H5 微應用或機器人）。
填個名稱，比如 Hermes Agent，描述隨意。
建立成功後，進入 憑證與基礎資訊，找到 Client ID（AppKey） 和 Client Secret（AppSecret），立刻複製儲存——密鑰只顯示一次，丟了只能重新產生。

第2步：啟用機器人能力

在應用設定頁找到 新增能力 → 機器人，啟用它。然後在 訊息接收模式 裡選 Stream Mode（串流模式）。

為什麼推薦串流模式？ 它就像你家水管直接接自來水公司，不需要自己挖井（不用公開 IP、不用網域、不用配 webhook 伺服器）。機器人從你電腦主動撥號連上釘釘伺服器，在公司防火牆後面、家裡 NAT 網路下都能跑。

第3步：找到你的釘釘 User ID

釘釘 User ID 是一串字母數字混合的字串，由企業管理員指派。找法有兩種：

問管理員：在釘釘管理後台的 通訊錄 → 成員 裡能看到。
自己查：啟動閘道後給機器人發條訊息，終端機日誌裡會印出 sender_id，那就是你的 ID。

第4步：設定 Hermes Agent

推薦用互動式設定，一條指令搞定：

hermes gateway setup

選擇 DingTalk，然後二選一：

掃碼授權（推薦）：終端機會印出一個 QR Code，用釘釘手機版掃一下，Client ID 和 Secret 自動寫入 ~/.hermes/.env，不用去開發者後台翻。
手動貼上：把剛才複製的 Client ID、Client Secret 和允許使用的 User ID 貼進去。

小提示：掃碼時釘釘授權頁可能顯示 openClaw 字樣，這是釘釘官方範本還沒適配 Hermes 導致的，不影響使用，機器人完全屬於你自己的企業。

不想用精靈？手動改設定檔也行。 在 ~/.hermes/.env 裡加：

DINGTALK_CLIENT_ID=你的AppKey
DINGTALK_CLIENT_SECRET=你的AppSecret
DINGTALK_ALLOWED_USERS=你的UserID   # 多個用逗號分隔

選用設定（~/.hermes/config.yaml）：

gateway:
  platforms:
    dingtalk:
      extra:
        require_mention: true   # 群裡必須 @ 才回覆
        allowed_users:          # 白名單，只讓這些人用
          - user-id-1

啟動閘道

hermes gateway

幾秒鐘內機器人就連上釘釘了。私聊或群裡 @ 它試試。

加分項：AI 卡片與表情回應

AI 卡片：在 config.yaml 裡配 card_template_id，回覆會變成結構化卡片，支援串流刷新內容。
表情回應：機器人思考時自動加 🤔，回覆完變成 🥳，處理狀態一目了然。

常見問題

機器人不回覆：檢查機器人能力是否啟用、Stream Mode 是否選中、你的 User ID 是否在白名單裡。
報錯 dingtalk-stream not installed：pip install dingtalk-stream httpx 補裝。
報錯缺少 Client ID/Secret：確認 .env 檔案裡兩個變數都填了，然後重新啟動閘道。

總結一下：建立應用 → 啟用機器人 → 拿到 User ID → 設定憑證 → 啟動閘道，五步搞定。串流模式免公開 IP、免網域，對國內使用者特別友善。

下篇預告：訊息平台接入系列還沒完——下一期我們聊聊 飛書接入，同樣是國內辦公剛需，看看 Hermes 在飛書裡又有什麼新玩法。