Hermes Agent Gateway 不回复：Telegram、飞书、企业微信排查清单

先分清两类问题

Gateway 不回复通常分两类：消息没有进入 Hermes，或者 Hermes 收到了消息但模型调用失败。前者看平台配置和权限，后者看进程日志和模型 Provider。

平台侧检查

• Bot Token 或 Webhook 是否仍然有效。
• 发送消息的用户或群是否在允许列表里。
• Chat ID、群 ID、频道 ID 是否填对。
• 企业微信或飞书是否把机器人加入了正确群聊。
• 平台是否需要重新保存回调地址或签名密钥。

Hermes 侧检查

hermes config check
hermes doctor
hermes gateway status

如果有后台进程，先看最近 50 行日志。没有日志时，不要继续猜，先让 Gateway 以可见方式启动一次。

模型侧检查

如果平台能收到命令但一直没有最终输出，常见原因是 API Key 失效、模型限流、上下文过长或工作流卡在工具调用。先用 CLI 跑同样输入，确认模型和工作流本身能完成。

最小复现

先只测试 `/status` 或最短问答，再测试日报工作流。不要一开始就测试长报告、文件读取和外部 API，这会把排查面扩大。

先认进程模式，再决定去哪找日志

同样是"不回复"，前台模式和服务模式的排查入口完全不同，所以第一步是想清楚这台机器上 gateway 是怎么被拉起来的。装过 `gateway install` 的，它是 systemd（Linux）或 launchd（macOS）服务，终端上什么都看不到，日志文件就是唯一现场；WSL、Docker、Termux 这三类环境官方推荐的本来就是前台 run，系统里根本不存在服务单元，按 systemd 思路去找只会绕远路。

分诊链是三层：`hermes status` 给出包含 gateway 在内的全组件总览，先确认到底是 gateway 一个组件挂了还是整套都不对——provider 那一栏不正常的话，机器人会表现成"收得到却答不出"，这锅不该 gateway 背。第二层 `hermes logs` 过滤日志文件，按出问题的时间点找平台关键字；一台机器跑了多个 profile 的话，先用 `gateway list` 看清是哪个 profile 的 gateway 在值班，免得对着别的实例查半天。日志里也没线索，才进入下一节的前台复现。

服务停下来，前台跑一遍

hermes gateway stop
hermes gateway run

把服务停掉，用前台 run 加载同一份配置，然后从平台里发一条消息过来——只发一条，连发几条会让终端输出搅在一起，反而看不清是哪条触发的错。前台复现的价值在于错误实时滚在眼前：凭证被拒、目标不存在、模型超时，每一类都有完整原文，而不是事后从日志里拼凑。定位修完之后，把进程交还给服务：

hermes gateway start
hermes gateway restart

`start` 负责把服务拉回来；之后每次改动配置，都跟一次 `restart` 让进程重读。服务模式下有相当一部分"明明改好了还是不回"，根因就是改动只存在于磁盘上，跑着的进程从没加载过它。restart 之后回到分诊链的第一层，把组件总览再过一遍、群里再发一条消息收到回复，这一轮排查才算真正闭环，而不是"看起来好了"。翻日志时还有个省时间的细节：先锁定不回复发生的时间窗，只读那几分钟的记录，从文件头读到尾是排查里最贵的走法。

还没有真实场景？可以先领取 [Free Starter 模板包](/free-template-pack)，从低风险只读任务开始试跑。