Agentic Research
中文
English Edition/Tools

This article is not yet available in English. You are reading the Traditional Chinese original. The English edition will appear here once it is translated.

Browse articles that do have an English edition

把 AI Agent 接上 Telegram:最簡單的第一個渠道

2026/09/3018 min readBryan Chan閱讀中文原文
TopicsHermesTelegramMessagingTools

如果只接一個通訊渠道，從 Telegram 開始。理由很實際：建 Bot 免費、幾分鐘搞定；走官方 Bot API;不需要公網 IP、不需要掃 QR、不需要企業帳號；而且 Hermes 的 Telegram adapter 在官方能力矩陣裡幾乎全勾。做完這篇文章你會得到：一個跑在你自己機器上、用手機 Telegram 就能對話的 agent——它能讀檔案、執行指令，你傳語音它會轉成文字。全程大約 15–20 分鐘。

這裡用 Hermes Agent(Nous Research 開源的多渠道 agent 框架)當範例，但整套概念(取得 Bot 憑證、設定誰能跟它說話、跑一個常駐程序、驗證第一則訊息)對任何工具、任何渠道都通用。先在 Telegram 證明概念，再去挑戰微信、WhatsApp、飛書這些更難的渠道——難的從來不是接上，而是接上之後的信任邊界。

前提:Hermes 已安裝、至少配好一個模型。還沒裝的話，先照 安裝 Hermes Agent 做完再回來。

這個渠道的能力邊界

Hermes 官方文件為每個平台列了能力矩陣。把你可能接的五個渠道放在一起看，選渠道時這張表比任何介紹文都有用:

平台語音圖片檔案主題表情回應輸入中串流
Telegram✅✅✅✅—✅✅
WhatsApp(橋接)—✅✅——✅✅
WhatsApp Cloud API✅✅✅——✅—
Weixin(微信)✅✅✅——✅—
Feishu / Lark✅✅✅✅✅✅✅

(取自官方 Messaging Gateway 文件的平台對比表。「語音」指 TTS 語音回覆與/或語音訊息轉錄；「串流」指用訊息編輯實現的漸進式輸出。)

Telegram 這一行的意思是：語音、圖片、檔案、論壇主題、輸入中提示、串流輸出都支援，官方矩陣中唯一沒勾的是表情回應。另外三個行為值得先知道:

  • 超過 4,096 字元的回覆會自動拆成多則，帶 (1/3)、(2/3) 編號，不會被截斷;
  • 你發的語音訊息會由設定的 STT 自動轉錄成文字再交給 agent(本地 faster-whisper、Groq Whisper 或 OpenAI Whisper 三選一);
  • 預設用 long polling:gateway 主動向 Telegram 拉訊息，所以你的機器不需要公網位址。雲端部署另有 webhook 模式，新手不用碰。

前置需求

  • 一個 Telegram 帳號。
  • Hermes Agent 已安裝,Terminal（終端機） 裡跑得動 hermes 這個 CLI（命令列介面） 指令；模型還沒配的話，用 hermes model 選供應商、填 API Key。
  • 知道 環境變數與 .env 是什麼:Bot token 這類憑證最終落在 ~/.hermes/.env,不要寫死在任何程式碼或版本庫裡。
  • 15–20 分鐘，以及一個能收發 Telegram 訊息的手機或電腦。

步驟

把 Agent 接上 Telegram 的六個步驟Telegram 是最容易成功的第一个通道：向 BotFather 建立 Bot 拿到 token、查自己的數字 user ID、用設定精靈把兩者的憑證寫入、先前台啟動 gateway 並發一則訊息確認、確認通了再裝成常駐服務、最後選用設定 home channel。預設是 deny-by-default，只有列進允許名單的人能跟 Bot 說話。Telegram × Agent gatewayTelegram：@BotFather/newbot → 取名字 → 拿到 tokentoken 形如 123456:ABC-…查自己的數字 user ID不是 @username，是一串數字這個數字決定誰能跟 Bot 說話設定精靈寫入憑證token 與允許的 user ID 進設定檔不要把 token 貼進聊天視窗gateway 與常駐服務先前台跑，發一則訊息確認通通了再裝成常駐服務token 就是憑證，洩漏等於把 Bot 交出去示意圖，非截圖。只畫與當前步驟相關的區域，實際介面有更多選項。
1/6向 BotFather 建 Bot
第 1 步，共 6 步 向 BotFather 建 Bot
把 Agent 接上 Telegram 的流程示意（六步）

步驟一：向 BotFather 建立 Bot

打開 Telegram,搜尋 @BotFather(Telegram 官方的 Bot 管理帳號),發送 /newbot,依指示給兩個名字：顯示名稱(隨意)和 username(全域唯一、必須以 bot 結尾，例如 my_hermes_bot)。

預期輸出:BotFather 回一串 API token,形狀像這樣(官方文件的佔位範例):

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

這串 token 就是 Bot 的完整身分，誰拿到誰就能控制你的 Bot。不要把它貼進任何聊天視窗、不要 commit 進 git;萬一外洩，立刻在 BotFather 用 /revoke 作廢重發。

步驟二：查自己的數字 user ID

allowlist 認的是數字 ID,不是 username。向 @userinfobot 發任意訊息，它會直接回你的 ID。

預期輸出:一串數字，例如 123456789。記下來，下一步要用。

步驟三：用設定精靈寫入憑證

hermes gateway setup

預期輸出:一個方向鍵操作的互動清單，並顯示哪些平台已配置。選 Telegram,把 token 和上一步的 user ID 貼進去；精靈會把憑證寫進設定，最後問你要不要現在就啟動 gateway。

不想用精靈的話，手動在 ~/.hermes/.env 加兩行也一樣:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ   # 換成你自己的 token
TELEGRAM_ALLOWED_USERS=123456789                            # 換成你自己的 user ID

步驟四：前台啟動 gateway,發第一則訊息

hermes gateway

預期輸出:terminal 開始滾日誌，出現 Telegram 平台已連線的記錄(官方文件的說法是 Bot 應該在幾秒內上線)。這時打開 Telegram 找到你的 Bot,發 /help,再發 /whoami:

你:/help
Bot:(回覆可用指令清單)

你:/whoami
Bot:(回覆你在這個 scope 的權限層級與可用的斜槓指令)

再發一句「你好」,收到模型生成的回覆——渠道、gateway、模型這條鏈路就通了。注意 gateway 是一個背景程序，同時服務所有已配置的平台；之後接第二、第三個渠道，不需要再開一個程序。

步驟五：裝成常駐服務

前台執行適合除錯，日常使用裝成系統服務(Linux 是 systemd 使用者服務、macOS 是 launchd、Windows 是排程工作):

hermes gateway install
hermes gateway start
hermes gateway status

預期輸出:status 回報服務正在執行。Linux 上要開機自動啟動，改用 sudo hermes gateway install --system 裝成系統級服務。

macOS 有一個值得先知道的坑：安裝產生的 plist 在 ~/Library/LaunchAgents/ai.hermes.gateway.plist,它記錄的是安裝當下的 PATH。之後你才裝上 gateway 需要的工具(例如用 nvm 裝 Node、用 Homebrew 裝 ffmpeg),要重跑一次 hermes gateway install 把新 PATH 快照進去，否則服務裡的 gateway 找不到這些工具。

步驟六：設 home channel(選用)

在任何一個對話裡(私訊或群組)發 /sethome,把該對話標記為 home channel:排程任務的結果、gateway 重啟通知、其他平台 adapter 熔斷時的告警，都會送到這裡。

預期輸出:Bot 確認已把這個對話設為 home channel。順帶記兩個 ID 規則：群組 chat ID 是負數(例如 -1001234567890),私訊的 chat ID 就是你的 user ID。

誰可以跟你的 Bot 說話

這一節比前面所有步驟加起來都重要。你接上的是一個能在你機器上執行終端機指令的 agent——誰能跟它說話，等於誰能對你的機器下指令。

Hermes 的安全預設是：gateway 拒絕所有不在 allowlist、也沒有經 DM 配對的使用者。這是為「有終端機權限的 Bot」刻意設計的預設，不是 bug。控制分三層:

第一層:allowlist。 TELEGRAM_ALLOWED_USERS=123456789,987654321(逗號分隔),或全域的 GATEWAY_ALLOWED_USERS。另有 GATEWAY_ALLOW_ALL_USERS=true 可以全開——官方文件自己標明不建議，對一個能跑終端機指令的 Bot 請不要這樣做：那等於把你機器的命令列交給任何搜到你 Bot 的陌生人。

第二層:DM 配對。 不在 allowlist 的使用者私訊 Bot 時，會收到一次性配對碼，由你在機器上核准:

# 對方看到的訊息形如:Pairing code: XKGH5N7P
hermes pairing approve telegram XKGH5N7P
hermes pairing list                        # 查看待核准與已核准
hermes pairing revoke telegram 123456789   # 撤銷某人的存取

配對碼 1 小時過期、有速率限制、用密碼學亂數產生，不怕被人暴力猜碼。

第三層:admin 與一般使用者分級。 allowlist 回答「這個人能不能進門」,分級回答「進門之後能做什麼」。admin 能執行所有已註冊的斜槓指令；一般使用者能正常聊天，但只能執行你明確開放的指令，保底永遠只有 /help 和 /whoami。設定在 ~/.hermes/config.yaml:

gateway:
  platforms:
    telegram:
      extra:
        allow_from: ["123456789", "555555555"]
        allow_admin_from: ["123456789"]        # admin:全部斜槓指令
        user_allowed_commands: [status, model] # 一般使用者能跑的指令

allow_admin_from 沒設時，該 scope 的分級機制不啟用(維持舊行為:allowlist 內的人全權限)。私訊的 admin 不代表群組的 admin——兩個 scope 各自設定(群組用 group_allow_admin_from 與 group_user_allowed_commands)。任何人隨時可以發 /whoami 查自己的層級。

兩個 Telegram 特有的提醒:

  • 群組隱私模式:Telegram Bot 預設開啟 privacy mode,在群組裡只看得到 / 開頭的指令、對它自己訊息的回覆、以及進退群等服務訊息。要讓 Bot 看到群組全部訊息，得到 BotFather → /mybots → Bot Settings → Group Privacy 關掉，然後把 Bot 移出群組再重新拉進來(Telegram 會快取 Bot 入群當下的隱私狀態);或者直接把 Bot 設為群組管理員，管理員 Bot 永遠收到全部訊息。
  • Prompt Injection（提示詞注入）:接上渠道之後,agent 會讀到大量不可信的第三方文字——群組成員的訊息、轉發內容、它自己抓回來的網頁。惡意文字可能試圖操縱它去執行指令。allowlist 收緊、危險指令靠聊天裡的 /approve、/deny 確認關卡、不要把 Bot 拉進陌生人群組，是三道最基本的防線。

常見錯誤與修法

症狀原因修法
Bot 完全沒反應token 錯，或 gateway 沒在跑看 ~/.hermes/logs/gateway.log;核對 TELEGRAM_BOT_TOKEN
回覆「unauthorized」你的 user ID 不在 allowlist用 @userinfobot 重查數字 ID,補進 TELEGRAM_ALLOWED_USERS
群組裡 Bot 無視一般訊息privacy mode 預設開啟BotFather 關掉後把 Bot 移出群再重加；或設為群組管理員
憑證在 .env,adapter 卻沒啟動config.yaml 裡 platforms.telegram.enabled: false——明確停用優先於環境變數裡的憑證移除該鍵或改 true;啟動日誌會有一條 WARNING 告訴你憑證被忽略
/platform list 顯示 paused-by-breaker連續可重試失敗(斷網、限流、上游 5xx、websocket 斷線)觸發熔斷；熔斷器刻意不自動恢復，避免上游真的掛掉時反覆重連先確認上游恢復，再 /platform resume telegram
每次連線都報 Cannot connect to host 127.0.0.1:7890服務管理器啟動的 gateway 繼承了你互動式 terminal 看不到的代理設定(例如沒在跑的本地代理)config.yaml 設 gateway.trust_env: false 停用繼承的代理，再重啟 gateway;各平台專屬的代理變數仍會生效
語音訊息沒轉錄沒配 STT 提供者裝 faster-whisper 用本地轉錄，或設 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
語音回覆是音訊檔、不是語音氣泡Edge TTS 輸出 MP3,轉 Opus 需要 ffmpeg安裝 ffmpeg(brew install ffmpeg 或 sudo apt install ffmpeg)

進階診斷兩招:hermes gateway status 會報告「降級退出」與「心跳過期」這類看起來在跑、其實沒在調度的狀態;Linux/macOS 上 kill -USR2 <gateway pid> 會把所有執行緒的堆疊附加到 ~/.hermes/logs/gateway_faulthandler.log,gateway 不停機——卡住時用它看程序在做什麼。

最後一個安心機制:Hermes 有 delivery ledger(投遞帳本),最終回覆在送出前後會被持久記錄。gateway 若在「回覆已生成、平台還沒確認收到」之間崩潰，重啟後會補送而不是丟訊息(語意是 at-least-once);曾在發送中途恢復的訊息，會加上「♻️ Recovered reply — … may be a duplicate」的醒目前綴，明確告訴你可能是重複。補送有上限:3 次、24 小時時效，已投遞的紀錄 7 天後清理。不想要這層可以在 config.yaml 設 gateway.delivery_ledger: false。

下一步

More in Tools