Hermes Agent 常见报错大全：model not allowed、模型不存在、401、429 到底怎么修

Hermes Agent 真正难搞的地方，不是它会报错，而是不同报错看起来很像，根因却完全不同。

本文侧重点：Hermes Agent 常见报错的系统性修复指南，涵盖 model not allowed、模型不存在、401、429 等典型错误。本文是 Hermes 系列的排障篇，入门请参考 Hermes Agent 入门指南。

• model not allowed 往往不是单纯模型坏了
• 模型不存在 多半不是服务商抽风
• 401 也不一定只是 key 填错
• 429 更不是简单地等一会儿再试

如果你不先分层判断，最常见的结果就是：一顿改配置，结果越改越乱。

更关键的是，Hermes 的配置来源本来就分层：CLI 参数 优先级最高，其次是 ~/.hermes/config.yaml，再往下是 ~/.hermes/.env，而 OAuth 类凭据又单独放在 auth.json。官方也明确建议：密钥和 token 这类敏感信息放 .env，模型、provider、fallback 这类非敏感设置放 config.yaml。你如果把模型设置、endpoint、key 混着写，报错一定会开始串味。

所以这篇文章不讲空话，只解决一个实际问题：Hermes Agent 遇到 model not allowed、模型不存在、401、429 时，到底该从哪一层查、该改什么、哪些动作最有效。

先立一个判断框架：Hermes 的模型报错，大致分三层

第一层：模型名和 provider 的匹配层

也就是你选的模型 ID，对当前 provider 来说到底是不是合法的。这里最典型的就是模型不存在、切换失败、当前 provider 下没有这个模型。

Hermes 官方 FAQ 直接把 Model not available / model not found 的原因写成：模型标识符错误，或者该模型在当前 provider 上不可用。

第二层：鉴权和 endpoint 层

也就是请求有没有带对 key、是不是发到了对的 base URL、你以为在用 OpenRouter，实际上 Hermes 却在走 custom endpoint，或者反过来。

Hermes 的运行时文档写得非常明确：

• OPENROUTER_API_KEY 只会发往 openrouter.ai
• AI_GATEWAY_API_KEY 只会发往 Vercel AI Gateway
• OPENAI_API_KEY 则用于 custom endpoint 和某些 fallback 场景
• custom endpoint 不会自动复用 OPENROUTER_API_KEY

第三层：配额和运行时恢复层

这部分才对应 429、部分 5xx、临时掉线、速率限制这类问题。

Hermes 的 provider runtime 和 fallback 文档都说明了：

• 401/403/404 属于非重试型客户端错误
• 429/500/502/503 属于重试后可能触发 fallback 的错误
• 同 provider 内部还可以借助 credential pool 做 key 轮换

只要你先把报错放进这三层里，后面的处理会快很多。

一、model not allowed：很多时候不是模型没了，而是当前路由不允许你这么用

model not allowed 这类提示，最容易让人误以为是 Hermes 本身不支持某个模型。其实更常见的情况是，当前入口、当前 provider、当前 server allowlist 不允许这个模型通过。

Hermes 仓库里就能看到明确的限制逻辑：某些服务器侧工具会直接校验 allowed_models，不在列表里的模型会返回：

两个容易掉进去的坑

坑一：/model 展示的列表可能和实际配置不一致

最近公开 issue 已经指出，/model 可能会展示与你 config.yaml 不一致的 provider 和 model 列表。也就是说，界面上显示给你的可选项，未必真的和你当前配置、当前校验逻辑是一致的；如果你照着点，很可能就撞上看起来能选，实际上不允许的情况。

坑二：gateway 里错误的切换提示

公开 issue 显示，/provider 文案曾建议用户使用 <provider>:<model>，但实际支持的语法是：

所以你看到 model not allowed 时，先别急着换 key，先确认自己是不是用了错误的切换写法。

正确的处理顺序

# 先看当前真正生效的配置
hermes config
hermes model

再确认你是不是把一个只适用于辅助任务的 provider 值写到了主模型配置里。官方配置文档明确说了，main 这个 provider 只允许出现在 auxiliary、compression、fallback_model 这些块里，不能拿来做顶层 model.provider；如果你用的是自定义 OpenAI 兼容接口，顶层应该写 provider: custom。

一句话总结：model not allowed 先查路由和写法，再查权限，最后才查模型本身。

二、模型不存在：九成不是 Hermes 坏了，而是模型 ID 和 provider 对不上

这是 Hermes 用户最常碰到、也最容易被误解的一类。

官方 FAQ 已经给得很直接：Model not available / model not found 的根因，通常就是模型标识符写错，或者当前 provider 根本不提供这个模型。

官方建议的修法也很朴素：

1. 先用 hermes model 看当前 provider 下可用模型
2. 再设置一个有效模型
3. 或者在会话启动时显式指定 --model

真实案例

就在最近的公开 issue 里，就有人在 Hermes v0.8.0 上选择 glm-4.7、glm-5.1 时收到提示模型不存在，请检查模型代码的报错。这个例子说明了一件事：当 provider 端返回不存在时，很多时候根因在 provider 接收到了它不认识的模型 ID，而不是 Hermes 无法运行。

另一个容易把人带歪的细节

如果你的 ~/.hermes/.env 里放着某个 provider 的 key，近期 issue 表明 /model 可能会把这个 provider 自动显示出来，即便你并没有在 config.yaml 的 providers: 里显式配置它；而且它展示的 model list 还可能来自硬编码列表，不完全等于你真正允许或真正可用的模型。

换句话说，你眼前看到的列表，未必就是最终真相。

最稳的做法

所以碰到模型不存在，最稳的做法不是继续盲切模型，而是做三件事：

1. 先看 config.yaml 里当前主模型到底指向哪个 provider
2. 再看 .env 里有没有别的 provider key 让 /model 产生误导
3. 最后用 hermes model 重新选择一次，或者直接在命令里显式指定模型

如果你在 gateway 里切模型，记得避开 provider:model 这种旧提示写法，直接用：

这一步能少掉很多明明换了，结果其实没换对的假故障。

三、401：大多数不是模型问题，而是 key、OAuth 或 endpoint 走错了

401 在 Hermes 里最值得警惕，因为它最容易伪装成provider 挂了。

实际上，Hermes 的认证路径比很多人想的更严格：不同 endpoint 使用不同 key，custom endpoint 也不会自动帮你复用 OpenRouter 的 key。

官方运行时文档写得很明白：

• OPENROUTER_API_KEY 只发给 OpenRouter
• AI_GATEWAY_API_KEY 只发给 Vercel AI Gateway
• OPENAI_API_KEY 才用于 custom endpoint 和兜底路径

一个很常见的坑

你把 provider 切到了 custom，base URL 也改了，但还在 .env 里只放 OPENROUTER_API_KEY，然后一脸困惑地看着 401。

Hermes 不是没读到 key，而是那个 key 根本不会发往你当前的 endpoint。

正确修法

首先，把敏感信息放对地方。官方配置文档明确要求：

• API key、token、密码之类的敏感值放 ~/.hermes/.env
• hermes config set 会自动把 key 类配置写进 .env，普通配置写进 config.yaml

所以别再手动东一份西一份地改，容易把自己绕晕。

其次，要知道 Hermes 对 401 并不是完全无能为力。

Credential Pools 文档说明，遇到 401 auth expired 时，Hermes 会：

1. 优先尝试刷新 OAuth token
2. 刷新失败后，才会轮换到同 provider 的下一把 key
3. 如果整个 pool 都耗尽了，才会继续落到 fallback provider

还有一个近期已公开的问题也值得记住：某些 OAuth provider，比如 Nous Portal、OpenAI Codex、Copilot，曾经出现明明凭据已经写进 auth.json，但 /model 里就是不显示的 bug。这种情况下，你如果只盯着模型选择器，很容易误判成401 因为根本没登录成功。实际上，问题可能在 picker 本身。

401 的最短处理路径

不是换模型，而是：

1. 先确认当前 provider
2. 再确认当前 endpoint
3. 再确认key 在不在 .env 或 auth.json 的正确位置
4. 最后用 hermes auth list 看当前凭据池和当前活跃凭据

四、429：这不是简单的稍后再试，而是要看你有没有做好轮换和 fallback

Hermes 官方 FAQ 对 429 的解释很直接：你超过了 provider 的速率限制。

官方给出的处理方向也很标准：

• 等一会儿重试
• 升级套餐
• 或者切到别的 provider

但 Hermes 真正值得用的地方在于，它不只是报你一个 429，而是给了你两层恢复机制。

第一层：Credential Pools（同 provider 内轮换）

官方文档说明，同 provider 下如果你配置了多把 key，Hermes 会先尝试同 provider 内的轮换：

• 429 先对当前 key 做一次重试，如果连续触发，再切到下一把 key
• 401 会优先尝试 OAuth refresh
• 402 这种账单/额度问题则会立即换 key

第二层：Fallback Providers（跨 provider 切换）

官方文档明确说了，fallback 会在主 provider 遇到以下问题时自动切到备份 provider:model：

• rate limit（速率限制）
• 服务端过载
• auth 失败
• 连接掉线

Provider Runtime 进一步说明：

• 401/403/404 会立即触发非重试型 fallback
• 429/500/502/503 则是在达到重试阈值后进入 fallback

配置示例

所以如果你的 Hermes 经常报 429，真正专业的修法不是一句等会儿，而是把 fallback_model 配上：

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

官方已经明确写明，fallback_model 需要同时填写 provider 和 model，少一个都不会生效。

如果你是长期跑 gateway、bot 或自动任务的人，这一项几乎不是优化项，而是稳定性底线。

五、最短实战排障流程：先看这四步，别上来就删配置

Hermes 遇到这几类报错时，我建议你永远按同一顺序来。

先执行：

hermes config
hermes config check
hermes model
hermes auth list

这是因为官方文档已经把这些命令定义得很清楚：

• hermes config —— 看当前配置
• hermes config check —— 检查缺项
• hermes model —— 交互式配置 provider 和 model
• hermes auth list —— 列出当前凭据池和当前正在用的凭据

接着再问自己四个问题：

1. 是不是切模型时用了错误语法？
2. 是不是当前 provider 和当前 model 根本不匹配？
3. 是不是 key 放在了错误的位置，或者当前 endpoint 根本不会使用那把 key？
4. 是不是当前报错其实该交给 credential pool 或 fallback 去接管？

只要你按这个顺序走，绝大多数 model not allowed、模型不存在、401、429 都能被拆开，不会再混成一锅粥。

结语

Hermes Agent 的这些常见报错，表面上都长得像模型出问题了，但真正的分界线其实很清楚：

| 报错 | 核心处理方向 | |------|-------------| | model not allowed | 先查允许列表、切换语法和 provider 路由 | | 模型不存在 | 先查模型 ID 和 provider 是否匹配 | | 401 | 先查 key、OAuth、endpoint 和配置落点 | | 429 | 先查有没有启用 credential pool 和 fallback_model |

说到底，Hermes 的报错并不难修，难的是你别把四种完全不同的故障，拿同一种方式去处理。

只要你抓住模型匹配层、鉴权层、运行时恢复层这三条主线，很多看起来很玄的报错，最后都会变成几步非常具体的配置修复。

Hermes 系列延伸阅读

• Hermes Agent 上手指南：安装、模型配置、网关接入与第一次真正跑起来 - 入门指南
• Hermes Agent 模型堵塞怎么处理？一篇讲透报错提示、卡死原因与修复路径的实战指南 - 模型阻断问题

OpenClaw 参考（有限交叉引流）

• OpenClaw 常见报错总表：安装、模型、审批、权限一次看懂 - 报错分类参考
• OpenClaw 日志怎么看？一篇文章找到真正根因 - 日志排查技巧