把中转代理起名叫 Anthropic 之后,你的官方 Key 被发去了那个地址

你为了省钱在 config.yaml 里加了一个中转地址,名字取得很自然:OpenRouter,反正它转发的是同一个 API。过了两周,账单没降下来,反而收到中转站老板一条消息:“你怎么把官方 Key 发过来了?“你翻配置,base_url 明明写的是他的域名。
这不是你写错了一个字母。问题在于“这个名字算谁的”——当 providers: 里的 key 和 Hermes 内置厂商重名时,切换模型的路径和真正发请求的路径曾经各算各的:一边用你的地址校验,另一边用内置地址和内置 Key 发送。两条路在不同时刻得出不同结论,中间就漏了东西。
一次名字碰撞,两条路径分叉
providers: 是 config 里自己声明 endpoint 的地方,长这样:
providers:
OpenRouter:
base_url: https://relay.example.com/v1
key_env: RELAY_API_KEY
default_model: some-model
正常情况下,/model 切换、仪表盘保存、下一轮真正发请求,三处应该指向同一个 endpoint、用同一把 Key。重名把这件事拆开了。
从 #151042 起,resolve_user_provider 对 providers: 的 key 做大小写不敏感匹配。于是 Anthropic:、OpenRouter: 这种写法开始命中用户条目。切换路径的表现是:/model 校验了你的 endpoint,然后保存 model.provider: Anthropic。而下一轮的运行时会把裸的内置名收敛到内置厂商上(_select_named_custom_provider → _shadowed_by_builtin),于是请求去了 api.anthropic.com,带的却是内置 Key。
对 OpenRouter 这种写法更糟:请求确实去了你的 URL,但带的是 OPENROUTER_API_KEY。你的中转站老板看到的那把 Key,就是这么来的。
修复的核心:一个判定,三处共用
维护者(Teknium)裁定的是“用户条目优先”,规则写得很清楚:
任何一个大小写形式的裸厂商名(openrouter、OpenRouter、anthropic、Anthropic、deepseek …),只要 providers: 下同名条目自己声明了 base_url,它就指用户条目**;只有同名但没有 endpoint 的块(纯调参,比如只改超时)才保留内置厂商。**
这条规则落在一个函数里,hermes_cli/runtime_provider_custom.py 的 builtin_name_user_entry():
def builtin_name_user_entry(name: str, providers: Any) -> Optional[str]:
"""Config key of the enabled ``providers:`` entry a bare built-in ``name`` routes to, else None.
The one predicate the switch, the dashboard save and doctor read, so validation and the next
turn agree: the entry wins when it declares its own base_url (#151775)."""
关键在于“the one predicate”:切换、仪表盘保存、doctor 三处读同一个判断,所以校验的 endpoint 一定就是下一轮真正跑的 endpoint。保存的身份也随之变成 custom:<key>:
def persisted_provider_id(provider: str, providers: Any) -> str:
owner = builtin_name_user_entry(provider, providers)
return provider if owner is None else custom_provider_slug(owner, owner)
于是 /model 在 Anthropic 这个 key 上保存的是 custom:Anthropic,运行时按 custom: 身份找回你的 base_url 和你的凭据,两端一致。
同一个提交还补了一个更隐蔽的口子:**内置的 env/pool Key 永远不会被发到一个由 providers: 条目自己拥有凭据的 model.base_url 上。**这条覆盖了 registry 的 api-key 路径、pool 条目路径和 Anthropic 的 env 路径。只有一种情况例外——条目没有声明凭据时,保留原来 #10622 的镜像行为,也就是“用内置 Key 打你自己的镜像”。
顺手多了一个警告,hermes doctor 会说出来
修完之后,下面这种配置不再“默默地算你的”:
model:
provider: openrouter
base_url: https://relay.example.com/v1
providers:
openrouter:
base_url: https://relay.example.com/v1
key_env: RELAY_API_KEY
hermes doctor 会打印一条警告(来自 _warn_builtin_name_owned_by_entry):
⚠ model.provider 'openrouter' runs on your providers.openrouter endpoint, not the built-in
(https://relay.example.com/v1)
并给出两句处理建议:要么显式改成 hermes config set model.provider custom:openrouter,要么删掉 providers.openrouter.base_url 用回内置厂商。这句警告的价值在于它点名了两件事——真正被打的地址,以及你该用的身份——而不是让你猜。
你该检查什么
如果你的 config.yaml 里有 providers: 段,花两分钟做三件事:
- 看 key 名。凡是
openai、anthropic、openrouter、deepseek、gemini、xai、lmstudio这些内置名(不分大小写),都算“重名”。 - 跑一次
hermes doctor,看有没有上面那条runs on your providers.<key> endpoint。 - 如果你本来就想要“用内置名走自己的代理”,两条路都行:把
model.provider写成custom:<key>,或者干脆把 key 改成my-relay这种不撞名的名字——反正providers:的 key 只是你自己的标签。
反过来说,如果你只是想给内置厂商调个超时、加个 header,不要在那个块里写 base_url。没有 base_url 的同名块保留内置语义,这也是本次裁定里明确留下的逃生门。
这件事的真正教训
配置系统里,“名字”往往同时承担三种角色:给人看的标签、给程序用的路由键、给凭据用的作用域。一旦允许用户自定义的名字和内置名字重叠,这三种角色就会打架,而打架的结果通常不是报错,是悄悄发错地方——尤其危险的是发错的是凭据。
这类问题不会在第一次使用时暴露,因为两条路径在“刚好都正确”的情况下行为一致。它只在切换模型、重启会话、仪表盘改配置这些“身份被重新推导”的时刻分叉。
状态:在 main 上,还没进 v0.23.1
PR #152465 于 2026-11-10 21:26 UTC 合并,v0.23.1 的 tag 停在 11-10 00:24 UTC 的提交上,所以这个修复目前只存在于 main:源码安装跟着 main 跑的人已经生效,用 v0.23.1 及更早版本的人还没有。
更新(2026-11-17):这里说的改动已随 v0.23.2 发布(2026-11-16),
hermes update就能拿到。上文「不在 v0.23.1 里」是发布当时的快照。
在等的这段时间,最稳妥的做法是不要用内置名做 providers: 的 key——改名不影响任何功能,只影响你自己看配置时的那点舒适度。
想继续往下读,模型覆盖配置那篇 讲的是 model_overrides 怎么按模型改行为,密钥加密那篇 讲凭据到底存在哪、怎么被解出来,而 三家新 provider 的上手记录 里有真实的 providers: 写法可以对照。命令层面,config 参考 和 doctor 参考 是这次改动直接涉及的两页。