企業微信回調模式——自建應用 | Easy Understand Hermes Agent

這篇教學將教你如何把 Hermes Agent 接入企業微信，讓它以「自建應用」的身分出現在你的企業微信側邊欄裡，像一位真正的同事一樣接收任務並回覆結果。

兩種接入方式，先分清

Hermes 支援兩種企業微信接入方式，就像「加群聊天」和「正式入職」的區別：

企業微信機器人（Bot）：透過 WebSocket 連線，設定簡單，適合群聊場景。
企業微信回調（Callback，即本文）：以自建應用的形式存在，使用者在企業微信側邊欄裡能直接看到它，支援多公司路由。

執行 hermes gateway setup 並選擇 WeCom Callback 可進行引導式設定。

它是怎麼運作的？

想像一下，你給這位「同事」發了一則訊息：

企業微信把加密的訊息推送到你的伺服器（回調 URL）
Hermes 解密訊息，交給 AI 智慧體處理
伺服器立即回覆「收到」（使用者端無感知）
智慧體開始思考（通常需要 3–30 分鐘）
處理完成後，透過企業微信 API 主動把結果發給你

準備工作

一個企業微信管理員帳號
一台公網可達的伺服器（或用 ngrok 等內網穿透工具）
Python 套件 aiohttp 和 httpx（預設安裝已包含）

第 1 步：在企業微信後台建立自建應用

登入企業微信管理後台 → 應用管理 → 建立應用
記下頁面頂部的 企業 ID（Corp ID）
在應用設定裡建立 企業金鑰（Corp Secret）
在應用概覽頁找到 Agent ID
在「接收訊息」模組設定回調 URL：
- URL：http://你的公網IP:8645/wecom/callback
- Token：隨機產生一個（後台會提供）
- EncodingAESKey：產生一個金鑰（後台會提供）

第 2 步：設定環境變數

在 .env 檔案中新增以下內容：

WECOM_CALLBACK_CORP_ID=你的企業ID
WECOM_CALLBACK_CORP_SECRET=你的企業金鑰
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=你的回調Token
WECOM_CALLBACK_ENCODING_AES_KEY=你的43位AES金鑰

# 可選設定
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

第 3 步：啟動閘道

hermes gateway

（若已註冊系統服務，可用 hermes gateway start）

啟動後，適配器會開啟一個 HTTP 伺服器。企業微信會先透過 GET 請求驗證 URL，之後透過 POST 推送訊息。

多應用路由（進階）

如果公司有多個部門、多個自建應用，可以在 config.yaml 中設定 apps 清單：

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."

系統會按 corp_id:user_id 區分使用者，確保訊息路由到正確的應用。

存取控制

# 只允許指定使用者使用
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi

# 或允許所有使用者
WECOM_CALLBACK_ALLOW_ALL_USERS=true

常見問題

簽章驗證失敗？ 檢查 Token 和 EncodingAESKey 是否從後台完整複製，注意 .env 中 = 兩側不要有空格。

回調 URL 無法存取？ 確認反向代理或隧道已正確轉發 /wecom/callback 路徑，且 URL 為 HTTPS（企業微信拒絕 HTTP）。

連接埠無法存取？ 查看日誌確認監聽位址。如果綁定在 127.0.0.1，需要用 Cloudflare Tunnel 或 nginx 做反向代理。

小總結

透過回調模式接入企業微信，相當於給企業配備了一位 7×24 小時線上的 AI 同事。雖然它目前只支援文字輸入、回覆有延遲（3–30 分鐘），但作為非同步任務處理工具已經足夠強大。

下篇預告：我們將介紹如何設定企業微信機器人的 WebSocket 接入方式，讓你在群聊裡也能隨時召喚 AI 助手！