Hermes Agent gateway 接入 Telegram 和 Slack：一份 setup 指南

嗨，我是 Lena。说实话，每次有人问我"怎么把我的 agent 接到 Telegram 里？"，我第一反应永远都是同一个问题：你的 CLI 真的已经稳定了吗？ 这篇文章是写给那些准备跑一个真实 Hermes Agent gateway setup 的 builder 的，不是泛泛而谈的 bot 教程。我们会重点看 Telegram 和 Slack，其他平台只在必要的地方带一下。

Hermes gateway 到底在做什么

同一个 agent，横跨 CLI 和消息平台

先把概念捋清楚。Hermes 有两个入口：一个是你用 hermes 启动的终端 UI，另一个是你用 hermes gateway 启动的后台进程。gateway 本质上是一个统一的 adapter layer ——它会同时连接你配置好的所有消息平台，并把每条消息路由到同一个 AIAgent instance。换句话说，你在 Telegram 里聊天的那个 agent，和你在 Slack 里聊天的那个 agent，是同一个 agent，共用同一套 session store、memory、skills 和 cron schedule。

根据 official Hermes messaging gateway documentation，单个 gateway 进程可以同时跑 Telegram、Slack、Discord、WhatsApp、Signal、Email、Matrix、Mattermost，以及十几个其他平台。每个平台 adapter 接收消息，通过 per-chat session store 路由，再交给 agent。所以我总会这样说：gateway 是 fan-out layer，不是另一个独立的大脑。

为什么 gateway 不应该是你的第一步 setup

这里是大多数人踩坑的地方。他们一兴奋，装好 Hermes，就立刻去接 Telegram bot ——然后花三个小时 debug 为什么消息"进去了但没出来"。我懂，我也踩过。gateway 依赖三个上游东西都正确：model config、tool config、authorization config。只要其中任何一个在 CLI 里就是坏的，gateway 会继承这个坏状态，还会让诊断难十倍，因为你现在盯着的是 Telegram chat，而不是信息量很大的 terminal log。

所以我的经验法则，也是我每次都会重复的一句话：CLI 先行，gateway 第二。先在本地 hermes 里跑通一次干净的对话，然后再打开 BotFather。

在平台 setup 之前，先准备稳定底座

先验证本地 chat、tools 和 model config

在碰任何平台 token 之前，先在准备承载 gateway 的那台机器上跑完这份 checklist（最好是一台小 VPS ——你的笔记本不合适，因为 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

现在进入平台部分。我会把这两者并排讲，因为它们的概念很像——你创建 app，拿 tokens，设置 scopes/allowlists，把 Hermes 指过去——但它们的 操作细节 差很多。把它们当成同一种东西，往往就是 silent gateways 的开始。

Telegram

Telegram 是这两个里面更快能跑起来的。整个流程都在 Telegram 自己里面完成：

打开和 @BotFather 的聊天。根据 official Telegram bots documentation，这是注册 bot 并获取 token 的唯一官方方式。
发送 /newbot，选择 display name 和一个以 bot 结尾的 username，然后 BotFather 会给你一个形如 123456789:ABCdef… 的 token。
通过给 @userinfobot 发消息找到你的 numeric user ID。不要把它和你的 @username 混在一起——Hermes 按 numeric ID 授权。
把两者都放进 ~/.hermes/.env：

Plain

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789

运行 hermes gateway start，然后私信这个 bot。几秒内你应该就能收到回复。

一个很容易咬人的细节：如果你之后想加队友，有两个选择——把他们的 numeric IDs 加进 TELEGRAM_ALLOWED_USERS，或者使用 DM pairing，让未知用户拿到一次性 code，再由你用 hermes pairing approve telegram XKGH5N7P 批准。这个 pairing flow 在 Hermes Telegram setup guide 里有记录，而且说实话，对 shared assistants 来说它通常是更好的默认方式——你不需要提前到处追 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 下面，生成一个带 connections:write 的 token。这就是 xapp-… token。第 2 步里的 bot token 是 xoxb-… token。两个都需要。
把 app 安装到你的 workspace，然后把两个 tokens 加上 SLACK_ALLOWED_USERS allowlist 都放进 ~/.hermes/.env。
在你希望它生效的 channel 里执行 /invite @YourBot。它看不到任何没有被邀请进去的 channel 消息。

如何验证 inbound 和 outbound messaging 都正常

不要只发一句 "hi" 就宣布结束。我在每个平台上都会跑同样的三步验证：

Inbound: 在 DM 里发一条普通消息。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），然后触发一个 cron job。如果 cron 发到了错误地方，问题在你的 home config，不在 schedule。

如果两个平台上这三项都通过，才算真的完成。只有第一项通过的话，你得到的是一个 partial setup，真实使用时一定会出问题。

平台特定的 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 出于安全默认会拒绝所有用户，所以 bot 看起来死了，其实只是严格执行了你的配置。如果你在 firewall 后面，设置 HTTPS_PROXY 或 Telegram-specific proxy variable；gateway 会优雅 fallback，但你得给它一条出去的路。

Slack failure modes 基本集中在 scopes。每周我都会看到同一种模式：bot 在 DMs 里回复，但忽略 channels。这几乎永远是缺少 channels:history 或 groups:history scope，再加上 bot 没被邀请进 channel。两个都要修，只修一个不够。其他经典坑：

忘了 xapp- app-level token → Socket Mode 根本连不上。
安装后又加了 scopes，但没有 reinstall app → 新 scopes 实际上没有被授予。Reinstall 是必须的。
用了 2025 年 3 月之前的 classic app → 它就是不能工作。重新从头创建。

还有一个跨平台 failure mode 值得点出来：gateway service 自己挂了。在 macOS 上，hermes gateway install 会注册一个 launched plist。在 Linux 上，你通常会用 systemd unit 包起来。如果底层 service 没有被 supervised，你的 "24/7 assistant" 其实就是一个 4 小时 assistant，下次机器重启它就死了。

shared assistants 的 operational guardrails

谁可以和 agent 说话、approval boundaries、blast radius

这是没人想提前思考、但一出事就太晚的部分。你把 agent 放到 Telegram 或 Slack 上的那一刻，任何能接触到这个 chat surface 的人，都可以向一个运行在你 server 上的进程发命令。这件事值得真正认真对待。

有几条规则我从不打破：

永远设置明确的 allowlist。 TELEGRAM_ALLOWED_USERS 和 SLACK_ALLOWED_USERS 不是可选项——没有它们，安全默认值就是 denial，你应该一直保持这样，直到自己做出明确选择。GATEWAY_ALLOW_ALL_USERS=true 是一把 foot-gun，我一次都没见过它有合理使用场景。
把 agent 跑在隔离的 terminal backend 里。 Hermes 支持 Docker terminal backend，会 drop capabilities 并禁用 privilege escalation。任何能从外部触达的 agent，我只用这个设置。我开发机上的 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 讲得很深——如果你是给团队跑这套，这些实践就不再是可选项。
destructive actions 保留 approval prompts。 当 agent 想做危险操作时，它应该在 chat 里询问并等待 yes。不要为了"更顺滑"而关掉它——这个 prompt 不止一次救我免于 rm -rf。
约束 blast radius。 Cron jobs 会投递到 SLACK_HOME_CHANNEL 或 /sethome Telegram channel。不要为了"可见性"把它们指到公开 team channel ——指到只有 operators 在的 private channel，然后手动转发 summaries。

如果你不是只给自己用，上线前请先把这四个问题的答案写下来：谁可以和 agent 说话？它不用询问就能做什么？它的输出会落到哪里？谁负责轮换 tokens？ 如果你不能每个问题都用一句话回答清楚，就还没准备好把它分享出去。

FAQ

Slack 需要同时有 xoxb 和 xapp tokens 吗？

需要。bot token（xoxb-…）用于 posting messages 和 Web API calls。app-level token（xapp-…，带 connections:write）负责为 Socket Mode 打开 WebSocket。少任何一个都会以不同方式失败——bot token 缺失意味着没有回复；app token 缺失意味着根本没有 inbound events。

一个 Hermes gateway 能服务多个 Slack workspaces 吗？

可以——Hermes 会把每个 team_id 映射到自己的 WebClient 和 bot user ID，所以一个 gateway 进程可以独立认证到多个 workspace。这是 documented behavior，不是 workaround。

我的 Telegram bot 在 DMs 里会回复，但忽略 group messages。为什么？

默认情况下，Telegram bots 开启了 privacy mode，也就是说它们只能看到明确 mention 它们、或回复给它们的消息。如果你希望 bot 看到所有 group messages，就在 BotFather 里关闭 privacy mode（/setprivacy → disable）。或者，直接 @mention 这个 bot。

我应该把 gateway 跑在自己的笔记本上吗？

别，真的别。Hermes 的重点就是它不应该绑在你的笔记本上——它应该跑在一台 $5 VPS 或类似的 always-on 机器上。否则每次你合上盖子，bot 就死了，大家也会慢慢不再信任它。

gateway setup 和设置 cron、profiles 是一回事吗？

不是，但它们会叠加。gateway 稳了之后，cron jobs 会自然投递到你配置好的平台，personality profiles 也会传播到所有 surfaces。gateway 做对了，agent ecosystem 里的其他部分基本就会顺着工作。gateway 做错了，其他所有 feature 都会继承这个坏状态。

这就是诚实版本。先在 CLI 里打好地基，再把 Telegram 或 Slack 叠上去，锁定谁能触达它，不要跳过那些无聊的验证步骤——它们是你这个季度能买到的最便宜保险。