Hermes agent Telegram 失聯，連線異常排查與穩定性優化指南

在部署 Hermes Agent 的實務經驗中，社群最常面臨的挑戰並非模型推論錯誤，而是 Telegram 終端突發的「無預警失聯」——更新後毫無反應、看似正常運作卻無法收發訊息。這類問題通常並非單點故障，而是涉及 Gateway 生命週期、輪詢（Polling）恢復機制、Bot Token 狀態以及 Telegram 端訊息路徑的綜合性異常。

換言之，當 Telegram 失去回應時，首要懷疑的應是「通訊鏈路中斷」，而非 Agent 的大腦（模型）出錯。

核心失聯情境與成因分析

情境一：更新與重啟失敗（Gateway 進程卡死）

在執行 hermes update 後，系統表面上顯示服務要求重啟成功，但實際上舊的 Gateway 進程仍在執行 Drain（排空）程序並最終導致 Timeout，使得新的 Gateway 無法順利接管。

• 關鍵警訊： 日誌出現 Telegram bot token already in use。這代表舊進程依然佔用著 Token，導致新進程啟動時陷入卡死。這是一種典型的「假性更新成功」，通訊鏈路實際上並未重新建立。

情境二：網路閃斷導致輪詢失效（Polling 未恢復）

在遭遇短暫的網路波動後，Telegram 的 Polling 機制未能自動恢復。這類 Bug 最難以察覺，因為伺服器、Docker 或桌面端皆顯示正常運行，系統也不一定會立刻報錯，但 Telegram 卻從斷線那一刻起陷入靜音。

• 排查核心： 若遇到「網路短暫中斷後徹底失聯」的狀況，請優先檢查 Polling 與重連機制（Reconnect Ladder），切勿先去修改模型設定。

情境三：特定訊息路徑異常（Edge Cases 限制）

並非整個 Telegram 服務停擺，而是特定類型的訊息傳遞出現障礙。這類問題在單純測試「私訊短字串」時極易被忽略，進而產生全面正常的誤判。

• 高風險區塊： 群組訊息、超級群組（Supergroups）、文件附件、長篇內容或工具串流。
• 常見限制： 在 Webhook 或 Deliver 路徑上，單一目標的限制常導致 Fan-out（廣播）行為變得緩慢且脆弱。

務實排查標準作業程序 (SOP)

遇到失聯狀況時，請依照以下標準順序進行排查，這比盲目重啟有效得多：

1. 檢視核心日誌： 開啟 ~/.hermes/logs/gateway.log，優先搜尋以下關鍵字以釐清底層狀態：
   • drain
   • TimedOut
   • already in use
   • network error
2. 重置 Token 與連線狀態： 確認 Bot Token 依然有效，並主動執行 hermes gateway setup，強制重新對齊 Telegram 端的配置。
3. 驗證權限與特殊環境： 檢查目標群組的權限、Privacy Mode 設定及訊息類型。特別針對超級群組、附件與長篇訊息進行獨立測試。

Hermes 官方 FAQ 亦明確指出，訊息未送達的最常見原因為網路不穩、Token 過期或平台設定有誤。在系統架構上，真正該優先處理的不是疊加更多的抽象層，而是務必將 Gateway、Token、輪詢與平台路徑 這四大基礎先穩固下來。

常見問題與解答 (FAQ)