Agentic Research
EN
首頁/工具/把 AI Agent 接上 Telegram:最簡單的第一個渠道

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

2026/09/3018 分鐘Bryan Chan最後更新 2026/09/30
這篇屬於工具主題HermesTelegramMessagingTools

如果只接一個通訊渠道，從 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 訊息的手機或電腦。

步驟

步驟一：向 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。

下一步

同主題 · 其他形態

看主題地圖全部組合

同形態 · 其他主題

把 AI Agent 接上飛書/Lark:新手的第一個企業渠道把 AI Agent 接上微信：能力邊界、帳號風險與完整步驟