Hermes Agent gateway 接入 Telegram 同 Slack：setup 指南

嗨，我係 Lena。老實講，每次有人問我「點樣將我個 agent 接入 Telegram？」我第一個反應永遠都係同一條問題：你嘅 CLI 真的已經穩定咗未？ 呢篇係寫俾準備跑一個真正 Hermes Agent gateway setup 嘅 builder，唔係一般 bot 教程。我哋會集中講 Telegram 同 Slack，其他平台只會喺有需要嘅地方提一提。

Hermes gateway 其實做緊乜嘢

同一個 agent，橫跨 CLI 同 messaging platforms

先將概念講清楚。Hermes 有兩個入口：一個係用 hermes 啟動嘅 terminal UI，另一個係用 hermes gateway 啟動嘅 background process。gateway 本質上係一個 unified adapter layer ——佢會同時連接你配置好嘅所有 messaging platforms，並將每條 message route 入同一個 AIAgent instance。換句話講，你喺 Telegram 度傾偈嗰個 agent，同你喺 Slack 度傾偈嗰個 agent，係同一個 agent，共用同一套 session store、memory、skills 同 cron schedule。

根據 official Hermes messaging gateway documentation，單一 gateway process 可以同時跑 Telegram、Slack、Discord、WhatsApp、Signal、Email、Matrix、Mattermost，同埋十幾個其他平台。每個 platform adapter 會接收 messages，透過 per-chat session store route，然後交俾 agent。所以我成日都話：gateway 係 fan-out layer，唔係另一個獨立大腦。

點解 gateway 唔應該係你 setup 嘅第一步

呢度係最多人跌落去嘅坑。佢哋一興奮，裝好 Hermes，就即刻想接 Telegram bot ——然後用三個鐘 debug 點解 messages「入咗去但冇出嚟」。我明，我都試過。gateway 依賴上游三樣嘢都要正確：model config、tool config、authorization config。如果任何一樣喺 CLI 入面已經壞咗，gateway 會繼承嗰個壞狀態，仲會令診斷難十倍，因為你而家望住嘅係 Telegram chat，而唔係一個 verbose terminal log。

所以我嘅經驗法則，而且我真係每次都會講：CLI 先，gateway 第二。先喺本地 hermes 入面跑通一段乾淨對話，然後先打開 BotFather。

喺 platform setup 之前，先準備穩定底座

先驗證 local chat、tools 同 model config

喺碰任何 platform token 之前，先喺會承載 gateway 嘅嗰部機上跑完呢份 checklist（最好係一部細 VPS ——你部 laptop 唔適合，因為 gateway 需要 24/7 持續運行）：

hermes model — 確認 provider 同 model 都連得到。如果你用 local model，確保 context length 至少有 64K。
hermes tools — 只啟用你真正需要嘅工具。每多一個 tool，之後嘅 blast radius 就大一點。
hermes — 開一段真實對話。叫佢跑一個 shell command、做一次 web search、寫一個 file。留意輸出。呢度有任何古怪，去到 Telegram 會古怪十倍。
hermes doctor — 俾內置 diagnostics 先捉 path、permission 同 dependency 問題。

只有呢四項都乾淨，我先會繼續。Hermes 維護者自己亦都喺 project's GitHub repository 強調呢點：文檔流程係 setup wizard → CLI → gateway，就係呢個順序。老實講，跳過呢步，係最多人放棄 Hermes 嘅原因。

逐步 setup Telegram 同 Slack

Tokens、permissions、pairing 同 target routing

而家到 platforms。我會將兩個並排講，因為佢哋嘅概念好相似——你建立 app、攞 tokens、設 scopes/allowlists、將 Hermes 指過去——但 實際操作 差好遠。假設佢哋一樣，就係好多人搞出 silent gateways 嘅原因。

Telegram

Telegram 係兩者之中比較快起到嘅。成個流程都喺 Telegram 自己入面：

打開同 @BotFather 嘅 chat。根據 official Telegram bots documentation，呢個係註冊 bot 同攞 token 嘅唯一官方方式。
發送 /newbot，揀一個 display name 同一個以 bot 結尾嘅 username，BotFather 就會俾你一個形如 123456789:ABCdef… 嘅 token。
透過 message @userinfobot 搵到你嘅 numeric user ID。唔好同你嘅 @username 搞亂——Hermes 係用 numeric ID 授權。
將兩樣都放入 ~/.hermes/.env：

Plain

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789

跑 hermes gateway start，然後 DM 個 bot。你應該幾秒內收到回覆。

有個細節好容易咬人：如果你之後想加隊友，有兩個選擇——將佢哋嘅 numeric IDs 加入 TELEGRAM_ALLOWED_USERS，或者用 DM pairing，即係 unknown users 會收到一次性 code，再由你用 hermes pairing approve telegram XKGH5N7P approve。呢個 pairing flow 喺 Hermes Telegram setup guide 有記錄，而且老實講，對 shared assistants 嚟講通常係更好嘅 default ——你唔使預先周圍追 user IDs。

Slack

Slack 就複雜啲。漏一步，bot 會在線，但喺 channels 入面完全冇聲。

去 api.slack.com/apps 建立一個新 app，第一次建議用 from scratch（唔好由 manifest 開始，你會學得快啲）。Classic Slack apps 已經喺 2025 年 3 月完全 deprecated，所以一定要用現代 Bolt-based flow。
喺 OAuth & Permissions → Bot Token Scopes 入面，至少加：app_mentions:read、chat:write、im:history、im:read、im:write、channels:history、groups:history、mpim:history。兩個 *:history scopes 係最常漏嘅——冇佢哋，bot 喺 DMs 可以運作，但會靜默忽略 channels 入面所有嘢。
喺 Socket Mode 入面打開。呢條係 Hermes 用嘅路徑，對幾乎所有 self-hosted setup 都係正確選擇——你嘅 gateway 唔需要公開 HTTP endpoint，佢會透過 WebSocket 主動撥出去。機制同理由喺 official Slack Socket Mode docs 講得好清楚。
喺 Basic Information → App-Level Tokens 入面，generate 一個帶 connections:write 嘅 token。呢個就係 xapp-… token。第 2 步嘅 bot token 係 xoxb-… token。兩個都要。
將 app install 到你嘅 workspace，然後將兩個 tokens 加上 SLACK_ALLOWED_USERS allowlist 都放入 ~/.hermes/.env。
喺你想佢活躍嘅 channel 入面 /invite @YourBot。佢唔會見到任何未被 invite 入去嘅 channel messages。

點樣驗證 inbound 同 outbound messaging 都 work

唔好只係發一句 "hi" 就當完成。我喺每個平台都會跑同一個三步驗證：

Inbound: 喺 DM 發一條普通 message。bot 應該要回覆。
Outbound: 叫 agent 跑一個 multi-step task（"search the web for X and summarize"）。留意 streaming/typing indicators ——如果冇出現，代表 adapter 連上咗，但 progress events 未接好。
Targeted delivery: 設定 SLACK_HOME_CHANNEL（或者喺 Telegram 跑 /sethome），然後 trigger 一個 cron job。如果 cron 發去錯地方，問題係你嘅 home config，唔係 schedule。

如果兩個平台三項都 pass，你先真係完成。如果只係第一項 pass，嗰個係 partial setup，實際用起上嚟一定會 fail。

各平台特定嘅 failure modes

我大部分 support 時間都花喺呢度，所以要留心。

Auth failures、missing adapters、wrong scopes、silent delivery issues

Telegram failure modes 通常係 token 或 allowlist 問題。revoked 或打錯嘅 token 會俾你一個乾淨 401——容易。更陰濕嘅係：token 正確，但冇設 TELEGRAM_ALLOWED_USERS。gateway 出於安全預設會 deny all users，所以 bot 睇落似死咗，其實只係照你配置做緊。如果你喺 firewall 後面，就設 HTTPS_PROXY 或 Telegram-specific proxy variable；gateway 會 graceful fallback，但你要俾佢一條出街嘅路。

Slack failure modes 多數集中喺 scopes。我每星期都見到同一個模式：bot 喺 DMs 會回覆，channels 就無視。呢個幾乎永遠係少咗 channels:history 或 groups:history scope，再加上 bot 未被 invite 入 channel。兩樣都要修；只修一樣唔夠。其他經典陷阱：

忘記 xapp- app-level token → Socket Mode 完全連唔上。
install 之後加咗 scopes，但冇 reinstall app → 新 scopes 實際上冇被 grant。Reinstall 係必須嘅。
用咗 2025 年 3 月之前嘅 classic app → 佢就係唔 work。重新 from scratch 建立。

有個跨平台 failure mode 都值得標出嚟：gateway service 自己死咗。喺 macOS，hermes gateway install 會 register 一個 launched plist。喺 Linux，你通常會用 systemd unit 包住佢。如果底層 service 冇 supervised，你嘅 "24/7 assistant" 其實只係一個 4 小時 assistant，下次部機 reboot 就死。

shared assistants 嘅 operational guardrails

邊個可以同 agent 講嘢、approval boundaries、blast radius

呢部分通常冇人想提前諗，直到太遲先嚟後悔。你將 agent 放上 Telegram 或 Slack 嗰一刻，任何有權接觸嗰個 chat surface 嘅人，都可以向一個跑喺你 server 上嘅 process 發 command。呢件事真係要尊重。

有幾條規則我從來唔破：

一定要設 explicit allowlist。 TELEGRAM_ALLOWED_USERS 同 SLACK_ALLOWED_USERS 唔係 optional ——冇佢哋，safe default 就係 denial，而你應該保持咁樣，直到你刻意作出選擇。GATEWAY_ALLOW_ALL_USERS=true 係一把 foot-gun，我一次都未見過有正當用途。
將 agent 跑喺 isolated terminal backend 入面。 Hermes 支援 Docker terminal backend，會 drop capabilities 同 disable privilege escalation。任何可以由外界 reach 到嘅 agent，我都只用呢個 setting。我 dev box 上嘅 CLI 可以有 raw shell；gateway-backed agent 唔應該有。
將 tokens 當 production secrets。 Bot tokens、app tokens 同 allowlist files 應該只放喺 ~/.hermes/.env，mode 係 600，唔好放其他地方。OWASP Secrets Management Cheat Sheet 對 rotation、centralized storage 同 least-privilege access 講得好深入——如果你係為 team 跑呢套，呢啲做法就唔再係 optional。
destructive actions 保留 approval prompts。 當 agent 想做危險操作，佢應該喺 chat 入面問，然後等 yes。唔好為咗「順啲」就關掉佢——呢個 prompt 救過我唔止一次，避免咗 rm -rf。
約束 blast radius。 Cron jobs 會 deliver 到 SLACK_HOME_CHANNEL 或 /sethome Telegram channel。唔好為咗「可見性」指去 public team channel ——指去只有 operators 喺入面嘅 private channel，再手動 forward summaries。

如果你唔係只係俾自己用，上線前請先寫低呢四條問題嘅答案：邊個可以同 agent 講嘢？佢唔問就可以做乜？佢嘅 outputs 會落喺邊度？邊個負責 rotate tokens？ 如果你冇辦法每條都用一句講清楚，就未準備好 share 出去。

FAQ

Slack 需要同時有 xoxb 同 xapp tokens 嗎？

需要。bot token（xoxb-…）用嚟 posting messages 同 Web API calls。app-level token（xapp-…，帶 connections:write）係用嚟為 Socket Mode 打開 WebSocket。少任何一個都會用唔同方式 fail ——少 bot token 就冇 replies；少 app token 就完全冇 inbound events。

一個 Hermes gateway 可以 serve 多個 Slack workspaces 嗎？

可以——Hermes 會將每個 team_id map 到自己嘅 WebClient 同 bot user ID，所以一個 gateway process 可以獨立 authenticate 入每個 workspace。呢個係 documented behavior，唔係 workaround。

我嘅 Telegram bot 喺 DMs 會回覆，但無視 group messages。點解？

預設情況下，Telegram bots 開咗 privacy mode，即係佢哋只會見到明確 mention 佢哋、或者 reply 佢哋嘅 messages。如果你想 bot 見到所有 group messages，就喺 BotFather 入面 disable privacy mode（/setprivacy → disable）。或者，直接 @mention 個 bot。

我應唔應該將 gateway 跑喺自己部 laptop？

唔好，真係唔好。Hermes 嘅重點就係佢唔應該綁住你部 laptop ——佢應該跑喺一部 $5 VPS 或類似 always-on 機器上。否則你每次合埋個蓋，bot 就死，大家就會開始唔信佢。

gateway setup 同 setup cron、profiles 係咪一樣？

唔係，但佢哋會互相疊加。gateway 穩咗之後，cron jobs 會自然 deliver 到你配置好嘅 platforms，personality profiles 亦會 propagate 到所有 surfaces。gateway 做啱咗，agent ecosystem 其餘部分大多就會順住 work。做錯咗，其他每個 feature 都會繼承嗰個壞狀態。

呢個就係老實版本。先喺 CLI 打好地基，再將 Telegram 或 Slack 疊上去，鎖好邊個 reach 到佢，唔好跳過嗰啲悶但重要嘅 verification steps ——佢哋係你今季買到最平嘅保險。