Hermes Gateway 为什么连上 Telegram 还是不回消息？从 Token、Allowlist 到 Gateway 日志的完整排查

Hermes Agent 接 Telegram，最气人的不是装不上，而是 「看起来全都配好了，Bot 也能搜到，结果你发消息过去，它像看破红尘一样一句不回。」 这类问题最容易把人带偏，因为表面症状像模型失灵，实际上高频根因通常根本不在模型，而在 Gateway、授权、Token、日志或运行方式。

Hermes 官方 FAQ 对 「Bot not responding to messages」 的说明非常直接，常见原因就是三类：Gateway 没在运行、Bot 没授权成功、或者你的用户不在 allowlist 里。 官方给的第一套动作也很朴素：先看 hermes gateway status，再 hermes gateway start，再检查 ~/.hermes/logs/gateway.log。换句话说，Bot 不回消息时，第一反应不是换模型，而是把消息网关当成一套独立服务去查。

很多人会下意识觉得「Telegram Bot 不是已经连上了吗，为什么还要查 Gateway」。问题就在这里。Hermes 的消息系统不是一个静态 webhook 机器人，而是一个统一的 messaging gateway。官方文档写得很明确，这个 Gateway 是一个长期运行的后台进程，负责连接多个消息平台、处理会话、跑 cron、传递语音消息。Telegram 只是它接入的其中一个平台，不是整个系统本身。也就是说，你把 Bot 配出来，只是把门牌挂上去了；真正值班的是 Gateway。门牌在，值班员不在，当然没人搭理你。

一、先别猜，第一步就查 Gateway 是不是活着

Hermes 官方 FAQ 对 Telegram 这类「消息发过去没反应」的故障，给的第一步就是：

hermes gateway status
hermes gateway start
tail -f ~/.hermes/logs/gateway.log

这三个命令别嫌土，实际上最有用。gateway status 看的是服务是否在运行，gateway start 是把后台进程拉起来，gateway.log 则是最关键的线索来源。很多人最大的毛病不是不会排障，而是连日志都不看，就先开始怀疑产品。

要是 Gateway 根本没起来，或者起了又立刻报错退出，你在 Telegram 那边盯着聊天窗口当然什么都等不到。

如果你还没有确认 Hermes 的基础 CLI 链路是否通畅，建议先回到 Hermes 装好了却不工作怎么办，先把 Provider、基础会话和 Gateway 启动链路排干净。

如果你在 Windows 的 WSL2 环境里跑 Hermes，这一步还要再多想一层。Hermes 官方 FAQ 明确说过，WSL 下 systemd 支持并不总是稳定，hermes gateway start 这类依赖 systemd 的方式可能在 WSL 重启、机器休眠或 Windows 空闲后挂掉。官方给的务实建议不是死磕，而是直接用前台模式：

hermes gateway run

或者用 tmux、nohup 挂起来。这个建议非常务实，因为它承认了现实世界比理想设计更脏。

如果你就是想让 Gateway 在 Windows 上稳定常驻，官方甚至建议直接用 Task Scheduler，在登录时调用：

wsl -d Ubuntu -- bash -lc 'hermes gateway run'

这就已经不是「某个 bug 的临时绕过」，而是文档层面承认：WSL + 前台运行，比 systemd 版服务更可靠。

所以 Windows 用户第一原则不是「怎么原生硬装」，而是「先认命用 WSL2，再按官方最稳的方式跑」。

二、Bot 能搜到不等于 Token 配对了，先把凭证放回正确位置

Telegram 对 Hermes 来说，本质上还是一套凭证驱动的消息通道。Hermes 的配置文档写得很清楚：Secrets 比如 API keys、bot tokens、密码要放在 ~/.hermes/.env，非机密配置才放在 config.yaml。 这点很关键，因为很多人会把所有东西都塞进 config.yaml，然后困惑为什么 Gateway 不认。对 Hermes 而言，Bot Token 这类敏感值应该走 .env 或 hermes config set 这类会自动分流到正确文件的位置。

最稳的做法不是手工东改西改，而是用官方推荐的配置入口。CLI 命令参考里写得很清楚：

• hermes setup —— 全量或分步配置向导
• hermes config —— 显示、编辑和查询配置
• hermes logs —— 直接查看日志

如果你怀疑 Telegram Token 填错了，不要先重装 Hermes，先确认它到底写进了哪里。很多所谓「连上不回消息」，其实就是 Token 根本没进正确的配置文件，或者旧值还留在 .env 里抢优先级。

三、最容易被误判成「机器人坏了」的，其实是 Allowlist 和 DM Pairing 没过

这一步是 Telegram 场景最阴的坑，也是最容易把人带沟里的地方。Hermes 的消息网关文档写得很明确：默认情况下，Gateway 会拒绝所有不在 allowlist 中、也没有通过 DM pairing 的用户。 官方甚至特地强调，这是「安全默认值」，因为这个 Bot 背后可能有终端访问和工具执行能力。也就是说，如果你只是把 Bot 拉起来，却没处理授权逻辑，那么你给它发消息，它不理你，反而是正常表现。它不是傻，是在防你。

Hermes 给了两种主流办法：

办法一：传统 Allowlist

把允许访问的 Telegram 用户 ID 加进配置。

办法二：DM Pairing（更实用）

官方文档和 Tips 页面都写得很明白，未知用户私聊 Bot 时，会收到一个 一次性 pairing code；你再在 CLI 里执行：

hermes pairing approve telegram XKGH5N7P

批准之后，对方才正式有权使用 Bot。官方还提供了：

hermes pairing list                    # 查看待批准与已批准用户
hermes pairing revoke telegram <user_id>  # 撤销授权

很多人最容易犯的错，就是看到 Bot 能收到消息，就以为应该自动回复；实际上在默认安全策略下，它很可能先发了一个 pairing code，而你从来没在 CLI 里批准过。

如果是团队场景，Hermes 官方甚至专门有一篇 Team Telegram Assistant 教程，强调这个 Bot 是「secure by default」，并支持基于每个用户的授权方式。这说明 Telegram 不回消息这件事，在 Hermes 的设计里并不总是故障，有时恰恰是安全特性在正常工作。 你要是把「没人批准我」理解成「机器人坏了」，那确实很容易白折腾一晚上。

四、Bot 回复文本正常，但语音、图片、文件没反应，先看依赖和日志

Telegram 不是只有文字。Hermes 的 Telegram 文档写明了，它支持文本、语音、图片和文件附件；但「支持」不等于「你当前环境一定全都配齐了」。

Hermes 的语音模式文档就专门列了两种典型症状：

• 「Bot hears me but doesn't respond」
• 「Bot responds in text but not in voice channel」

官方给的排查方向很具体：

1. 先确认 STT 是否可用 —— 比如装了 faster-whisper，或者设置了 GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
2. 再确认当前 LLM 模型确实能访问
3. 最后继续看 ~/.hermes/logs/gateway.log

如果是文字能回、语音不回，官方还提醒检查 TTS provider 的 key 和额度，Edge TTS 是默认回退。

这说明一个很现实的规律：文本不回和多媒体不回，不一定是同一种故障。 文本不回，优先看 Gateway、Token、授权。语音不回，优先看 STT/TTS 依赖和日志。别把所有「不响应」都揉成一个问题去排，不然你会在错误方向上转很久。

五、Gateway 在跑，但 Telegram 还是没动静，日志里通常已经把答案写出来了

Hermes 官方在 FAQ、CLI 文档、语音文档里都反复把日志拿出来说，原因很简单：这是最快的真实线索。

• hermes logs —— CLI 命令参考里正式提供的日志查看入口
• tail -f ~/.hermes/logs/gateway.log —— FAQ 和语音文档反复强调的直接查看方式

对 Telegram 场景来说，日志里通常会把你最想知道的几类信息直接吐出来：

| 日志线索 | 含义 | |---------|------| | Bot Token 无效 | Token 配错了或过期了 | | 平台连接失败 | 网络问题或 Telegram API 异常 | | 授权拒绝 | 用户不在 allowlist 或 pairing 未批准 | | 消息被拒 | 安全策略拦截 | | 语音依赖缺失 | STT/TTS 没配好 | | 网络异常 | 防火墙、代理、DNS 问题 | | Webhook 或平台 API 报错 | Telegram 服务端问题 |

很多排障失败，并不是因为问题多难，而是因为用户根本没把「日志优先」当成基本习惯。Hermes 这种工具不是黑盒，它把配置、日志、配对状态和命令面都给你了。你要还是只会在 Telegram 里反复发「在吗」，那当然像在对空气喊话。

如果 Bot 本身已经能回消息，但一到执行命令就频繁卡在审批或被拒绝，可以继续看 Hermes 危险命令为什么总被拦，那篇专门解释危险命令和审批机制。

六、别把 Telegram 和 Webhook 搞混，Bot 不回消息多数时候和 Webhook 没关系

这里要专门说一句，因为很多人一看到「消息平台」就条件反射想到 webhook。Hermes 的 webhook 文档是用来接 GitHub、GitLab、JIRA、Stripe 这类外部事件，然后触发 Agent 去跑任务的。它确实也能把结果发回 Telegram 或 Discord，但这套 webhook adapter 本身不是 Telegram Bot 收消息的主通道。

Telegram 在 Hermes 里是通过消息网关接入的，和「外部服务 POST 一个 webhook 过来」不是同一回事。

这点看起来像细节，实际很重要。因为很多人会误把「Telegram 不回消息」排到公网入站 webhook、HMAC 校验、反向代理这些方向上，结果一路越查越远。对 Telegram Bot 本身的消息响应来说，最先该查的还是 Gateway 运行状态、Token、授权和日志，而不是先把 Nginx、Webhook Secret、第三方事件源全拉出来陪审。

七、一套最省时间的 Telegram 排查顺序，别乱了

如果你现在就遇到了 「Hermes 接上 Telegram 但不回消息」，最实用的顺序我建议就是下面这套。

第一步：先查 Gateway

hermes gateway status
hermes gateway start
tail -f ~/.hermes/logs/gateway.log

第二步：再查授权

确认你是走 allowlist，还是走 DM pairing。

如果是 pairing，看对方有没有收到 code，再用：

hermes pairing list
hermes pairing approve telegram <CODE>

第三步：然后查配置

确认 Telegram Token 这类 secret 是否真的写进了 ~/.hermes/.env，或者通过 hermes config set 写到了正确位置。非 secret 配置看 config.yaml。

第四步：如果你在 Windows / WSL2

优先改用 hermes gateway run 前台方式，而不是迷信 systemd 版后台服务。

第五步：如果文本回复正常，但语音或附件不正常

转去看 STT/TTS 依赖、额度和 gateway.log。

这套顺序的价值就在于，它先排「服务活没活」，再排「你有没有权限说话」，再排「配置写对没有」，最后才去看多媒体和更复杂的扩展。这样走，通常比到处搜报错快得多。

结语

Hermes 接 Telegram 后不回消息，绝大多数时候都不是「模型突然发脾气」，也不是「官方偷偷炸了」，而是你把消息网关、授权策略、Token 配置和运行环境中的某一层漏了。

Hermes 的设计本来就偏安全、偏服务化、偏长期运行，所以它不会像玩具 Bot 那样只靠一个 Token 就一路开闸。你没把 Gateway 拉起来，它就不值班；你没把用户授权，它就不搭理；你不看日志，它也不会自己跳出来替你写事故复盘。

世界很公平，麻烦也很公平。