Hermes Agent 常见报错与排查清单

先看日志，不要先猜

排错的第一步永远是找到完整日志。启动失败看依赖和环境变量；运行失败看输入源和模型返回；推送失败看消息平台权限和网络。

把问题拆成五段

不要把所有错误都叫“不能用”。更稳的方式是先定位失败发生在哪一段：环境、Provider、工作流、Gateway、权限。

环境：命令找不到、依赖缺失、路径错误
Provider：401、429、model not found、timeout
工作流：输入为空、格式不稳、工具调用失败
Gateway：Token、Chat ID、允许名单、后台进程
权限：Token 过高、写入动作未确认、敏感数据泄露

常见问题

• API Key 没有加载到当前运行环境。
• 模型额度不足或限流。
• VPS 时间不正确导致定时任务错过。
• 消息平台 Webhook 过期。
• Prompt 没有约束输出格式。
• 输入数据为空但没有兜底逻辑。

最小复现

把复杂工作流拆成三段：读取输入、调用模型、发送输出。哪一段失败，就只修哪一段。不要在一个巨大的自动化里同时改十个变量。

hermes doctor
hermes config check
printenv | grep API
curl -I "$MODEL_API_BASE"

常见恢复顺序

先确认 `hermes --version` 和 `hermes doctor`，再确认 Provider 短问答，再跑一个最小模板，最后才看 Gateway 和定时任务。CLI 都不稳定时，不要排查飞书或 Telegram；CLI 正常但消息平台不回复，再看 Gateway。

保存一份排错记录

每次修复后，把错误时间、触发命令、报错原文、修复动作和最终结果记录下来。很多团队真正节省时间的不是第一次修好，而是下次同类错误能 5 分钟内定位。

date: 2026-05-31
symptom: OpenRouter 429 during daily brief
scope: Provider
fix: reduce retry + shorten input
result: success after 1 retry

什么时候求助

当你能提供环境、复现步骤、错误日志和期望输出时，别人才能快速帮你定位。只说“不能用”通常无法排查。截图可以保留错误信息，但要先遮住 API Key、Webhook 和客户数据。

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