Hermes Agent 为什么切模型总失败？从只显示一个 Provider 到 API Key 冲突的完整排查

Hermes Agent 这类工具，最容易把人绕晕的一类问题，不是模型不够强，而是模型明明就在那，你就是切不过去。最典型的症状有几个：/model 里只显示一个 provider；你明明想从 OpenRouter 切到 Anthropic，却发现列表里根本没有；或者新配了 custom endpoint，结果 Hermes 还是 stubborn 地沿着旧 provider 跑。更气人的是，有时候你甚至已经填了新 API Key，表面上也没报大错，但工具就是不按你预期切。

很多人第一反应是 Hermes 的模型切换做得太玄学。其实多数时候，不是玄学，是你把两套不同的入口、两类不同的配置来源，以及几种不同的 provider 状态混成了一锅。

先把最关键的误区砸碎

很多人会把 /model 当成全能切换器，觉得在会话里敲一下，就应该能新增 provider、跑 OAuth、输入 API Key、切到任何想要的模型。Hermes 官方文档明确说，不行。

• hermes model 是终端外的完整 provider 配置向导，用来新增 provider、跑 OAuth、输入 API Key、配置 custom endpoint
• 会话里的 /model 只能在你已经配置好的 provider 和模型之间切换

官方甚至把这件事做成了对照表：

| 操作 | 使用命令 | |------|---------| | Add a new provider | hermes model | | Enter/change API keys | hermes model | | Switch model mid-session | /model <name> |

也就是说，如果你只配置过 OpenRouter，那么 /model 里只出现 OpenRouter，并不是故障，而是系统在如实反映你的现状。

一、/model 只显示一个 Provider，不是坏了，是你真的只配了一个

这是最常见也最容易让人误会的场景。Hermes 官方 FAQ 直接把这个问题单独列出来，原话就是：/model only shows one provider / can not switch providers。

官方给出的原因也非常直接，因为 /model 只能切换你已经配置过的 provider。如果你之前只设过 OpenRouter，那它就只会给你看 OpenRouter；如果你只配了 custom endpoint，那就只能在 custom 下面切。它不会在会话里替你弹 OAuth，不会顺手帮你新增 Anthropic，也不会猜你可能也想连一下 OpenAI Codex。

正确修法其实很朴素：

1. 先退出当前会话
2. 在终端里跑：hermes model
3. 按向导去新增 provider、输入 key、跑 OAuth
4. 等新 provider 配好后，重新开一个新会话
5. 这时 /model 才会把它列出来

官方文档甚至专门提醒，添加新 provider 之后，要重新开始一个 chat session，这样 /model 才会显示所有已配置 provider。

很多人最大的时间浪费，不是在修 bug，而是在会话里硬敲 /model，试图让它完成它压根不负责的事情。

二、hermes model 才是真正的总开关

Hermes 的 provider 体系其实挺清楚。官方 Provider 文档列出的入口包括：

• Nous Portal
• OpenAI Codex
• GitHub Copilot
• GitHub Copilot ACP
• Anthropic
• OpenRouter
• AI Gateway

另外还明确说，Hermes 可以接任何 OpenAI-compatible API，所以自建或兼容端点同样能走。关键不在于它支不支持，而在于你得用对的方法把它配进去。

hermes model 之所以重要，是因为它不只是选模型，而是整个 provider setup wizard。你要做 OAuth、填 API Key、写 custom endpoint、切 base URL，本质上都在这里完成。

这也解释了另一个高频误判。很多人以为，自己在 .env 里零零散散写了几个 key，会话里再 /model 一下，Hermes 就会自动理解我现在有 OpenRouter、Anthropic、OpenAI Codex 三套链路。现实没这么浪漫。

官方明确说：config.yaml 是 provider、model 和 base URL 的事实来源（source of truth）。

这句话翻译成人话就是：不要指望 Hermes 通过你机器上东一块西一块的历史遗留配置来脑补完整状态。你应该要么用 hermes model 正式写进去，要么直接编辑 config.yaml。靠环境变量碎片化配置硬撑，多半会让后面的问题看起来像随机故障。

三、API Key 冲突比 Key 错了更阴

Hermes 官方 FAQ 对 API key not working 的排障写得很清楚：

常见原因包括：

• key 缺失
• key 过期
• key 设置错误
• 根本是给错 provider 了

官方还特别提醒：OpenAI 的 key 不能拿去配 OpenRouter，反过来也不行；同时要检查 ~/.hermes/.env 里有没有 conflicting entries。

这条提醒很关键，因为最烦人的问题往往不是没配置，而是你机器上有多个 provider 的 key，甚至旧 key 还留着，结果 Hermes 走的不是你以为那条。

这类故障的典型症状特别像闹鬼：

• 你明明刚填了一个 OpenRouter key，结果模型列表还是不对
• 或者你以为自己已经切到了 custom provider，输出却像还在走旧链路

实际上，这种时候第一反应不该是骂 Hermes，而是先看：

然后检查当前 provider 到底是谁，base URL 指向哪，.env 里是不是还有旧值。官方给的动作也很实在：不确定就重新跑 hermes model，或者直接用 hermes config set ... 明确写值。

排障最怕的，就是你以为系统正在按你的脑内配置运行，而真实配置文件压根不是那回事。

四、模型切不过去，有时不是 provider 问题，而是模型名本身就不对

Hermes 官方 FAQ 还单列了 Model not available / model not found。原因很朴素：

• 模型标识符写错了
• 或者当前 provider 根本没有这个模型

官方给的做法是：

1. 重新跑 hermes model 去看 provider 下有哪些可用模型
2. 再设置一个有效 model ID
3. 也支持在单次会话里用 hermes chat --model ... 指定

这个问题在多 provider 环境下尤其常见，因为不同 provider 的模型命名方式不完全一样。你在一个 provider 里能用的名字，放到另一个 provider 里未必认。

这一点在自定义端点场景里更明显。官方 Provider 文档写到，只要你已经配置过至少一个 custom endpoint，就可以在会话里用 /model custom:qwen-2.5 这种写法切模型。

注意这里的前提是至少一个 custom endpoint 已经配置好，而且模型名得和那个 endpoint 实际暴露的名字对得上。你要是 custom provider 本身都还没完成注册，或者模型名是自己脑补的，那 /model 再怎么敲也不会给你奇迹。

五、本地和 custom endpoint 最容易出现明明有模型，却切不出来

Hermes 官方 FAQ 在 Can I use it offline / with local models? 这一节给了一个非常实用的示例：

如果你走本地或兼容端点，可以在 hermes model 里选 Custom endpoint，填 http://localhost:11434/v1 这类 URL、API key 和模型名；也可以直接在 config.yaml 里写：

model:
  default: qwen3.5:27b
provider: custom
base_url: http://localhost:11434/v1

官方还特别提到，如果本地服务器只加载了一个模型，/model custom 可以自动检测它；同时强调 provider: custom 是 first-class provider，不是某个 alias。

这些信息连起来看，意思很明确：本地或兼容端点不是凑合支持，而是 Hermes 正式支持的一条路。问题在于，这条路越自由，越需要你把 base URL、模型名和 provider 身份明确写对。

很多本地用户的故障，根本不是切模型功能坏了，而是 endpoint 里到底暴露了什么模型、你给它起了什么名字、Hermes 又是按什么 provider 身份理解它，这三件事没对齐。尤其在 Ollama、vLLM、llama.cpp、SGLang 这类兼容 OpenAI 的服务里，兼容不等于自动帮你兜底理解一切。兼容意味着协议能讲通，不意味着配置可以乱写。

六、最省时间的排查顺序

如果你现在就在被 Hermes 切模型问题折腾，建议按这个顺序来：

第一步：分清加 provider 和切模型是两件事

• 新增 provider → 用 hermes model
• 会话里切已有模型 → 用 /model

这个界限不分清，后面全乱。

第二步：看当前配置是不是已经写进 config.yaml

别靠我记得我配过这种模糊记忆，直接：

官方都已经把 source of truth 说出来了，你就别再靠脑补运维。

第三步：查 API Key 是否冲突

特别是 ~/.hermes/.env 里是否有 provider 不匹配的 key，或者留着旧值没清掉。官方已经提醒过 conflicting entries，这不是小概率。

第四步：查模型名和 endpoint

• 模型名是不是当前 provider 真有
• custom endpoint 是不是已经注册成功
• base URL 指向对不对

结语

Hermes 切模型失败，绝大多数时候都不是切换器坏了，而是你把 provider 配置、会话切换、API key、model ID、custom endpoint 这几层事搅在了一起。

Hermes 官方其实已经把边界讲得很清楚了：

• hermes model 负责把路修出来
• /model 负责在已经修好的路上换车道
• config.yaml 才是事实来源
• .env 里的冲突项随时可能在背后给你使绊子

说到底，这类故障真正烦人的地方，不在于它报错，而在于它很像我明明已经快成功了。结果往往是，差的不是一点运气，差的是你没把配置逻辑彻底想明白。工具没那么冤，乱七八糟的 provider 状态才是幕后黑手。