Hermes Agent OpenRouter 报 model not found 怎么排查

先确认报错发生在哪里

model not found 可能发生在模型列表、会话启动、工作流执行或 Gateway 调用。不要只看最后一行错误，要确认是哪一步传错了模型名。

第一组检查

hermes model
hermes config show
hermes doctor

hermes model 打开选择器核对 Provider 和模型名，config show 看配置里实际写的是哪个模型，doctor 查 Key 和连通性。

如果 CLI 里模型能用，但 Gateway 里不能用，问题通常不在模型本身，而在 Gateway 进程没有加载最新环境变量。

常见原因

• 模型名写错，少了 provider 前缀或拼写不一致。
• API Key 没写进 ~/.hermes/.env，或写成了另一个 Provider 的变量名。Hermes 以这个文件为准，它会覆盖 shell 里 export 的同名变量。
• 配置改了但没有重启 Hermes 会话或后台进程。
• 当前模型被服务商下架、限流或区域不可用。
• 选择了上下文太小或不支持工具调用的模型。

推荐修复顺序

先换一个明确可用的模型跑短对话；再恢复你的目标模型；最后检查路由和限额。不要同时改模型名、API Key、Gateway 和 Prompt，否则无法判断到底是哪一步修好的。

记录下来

修好以后，把可用模型名、配置位置、重启方式和当天时间写进项目 README 或 Memory。下次出问题时，你能快速判断是配置变了，还是模型供应商变了。

先跑 model --refresh：重建模型列表缓存

hermes model 显示的列表来自本地缓存，不是每次实时拉取。OpenRouter 上架或下架模型后，缓存可能还停在旧状态，于是出现两种典型错位：照着列表选出的名字，请求时上游已经撤掉了；或者上游新增的模型，列表里迟迟看不到。遇到任何一种，先刷新：

hermes model --refresh

这条命令清掉缓存，重新请求各家的 /v1/models 重建列表。刷新完成后在新列表里重选一遍目标模型，再发起对话。如果刷新后列表里确实没有那个名字，结论就清楚了：问题出在上游供应侧，跟你的 Key、环境变量、会话状态都没关系，不必再来回折腾本地配置。顺带一提，--refresh 重拉的是各家 provider 的模型清单，不只 OpenRouter 一家；多 provider 并存时，谁家的清单过期都会制造同款报错，刷新一次等于把所有清单一起对齐。

用 fallback 把单点失效变成自动换线

排查可以慢慢做，正在跑的任务等不起。hermes fallback 用来配置主模型失败时的备用 provider 链：主模型报错，请求按链路顺序切到下一家，任务继续走完，不会卡死在一个失效模型上。

它的边界要分清楚：主模型返回 404（模型名写错或已下架）时，fallback 会立刻切到备用链，任务能继续走完——但备用链上每一级用的是它自己配置的模型，主模型的名字并没有因此修好，下一轮还是先失败再切换，所以它是排查的补充而不是替代。组链有两条实操规则：一是链上尽量放不同供应商，别把同一家的两个模型串在一起，否则一家整体故障会拖死整条链；二是链别拉太长，两三级足够，再长只会把真正的故障点埋得更深。每一级都得是你确实配置过认证的 provider，没配过的写上去也只是多一次失败。换线之后用 hermes logs 翻一下最近的日志，确认报错和恢复的时间点能对上。要把问题报给别人时，先跑 hermes dump 导出一份环境摘要随问题附上，比逐项口头描述配置省事，也更准确。

还没有真实场景？可以先领取 Free Starter 模板包，从低风险只读任务开始试跑。