Le pusiste `Anthropic` a tu relay — y le llegó la key oficial

Agregaste un endpoint relay en config.yaml para bajar costos y le pusiste el nombre obvio: OpenRouter, porque es la API a la que reenvía. Dos semanas después la factura no se movió y el operador del relay te escribe: ¿por qué apareció tu key oficial en mi servidor? Revisas la config. El base_url apunta claramente a su dominio.
No te equivocaste en ningún carácter. El problema era de quién era el nombre. Cuando una clave de providers: choca con el nombre de un provider integrado, el camino de cambio de modelo y el camino que de verdad envía la petición llegaban a conclusiones distintas: uno validaba tu endpoint, el otro enviaba al host integrado con la credencial integrada. Dos rutas de código, dos respuestas, y algo se cayó por la grieta entre las dos.
Un choque de nombres, dos caminos que se separan
providers: es donde declaras tu propio endpoint en la config:
providers:
OpenRouter:
base_url: https://relay.example.com/v1
key_env: RELAY_API_KEY
default_model: some-model
En el caso normal, el cambio con /model, un guardado desde el dashboard y la petición real del turno siguiente deberían apuntar al mismo endpoint con la misma key. Un nombre en colisión separaba todo eso.
Desde #151042, resolve_user_provider emparejaba las claves de providers: sin distinguir mayúsculas, así que Anthropic: y OpenRouter: empezaron a pegarle a la entrada del usuario. El camino de cambio hacía entonces esto: /model validaba tu endpoint y guardaba model.provider: Anthropic. En el turno siguiente el runtime canonizaba el nombre integrado desnudo hacia el provider integrado (_select_named_custom_provider → _shadowed_by_builtin), así que la petición se iba a api.anthropic.com — llevando tu key integrada.
Con OpenRouter era peor de otra forma: la petición sí salía hacia tu URL, pero llevaba OPENROUTER_API_KEY. Esa es la key que vio el operador del relay.
El fix: un predicado que leen tres puntos de llamada
El criterio de los maintainers fue “la entrada del usuario gana”, y está enunciado con precisión:
Un nombre de provider desnudo, en cualquier capitalización (openrouter, OpenRouter, anthropic, Anthropic, deepseek, …), cuya entrada en providers: bajo ese nombre declare su propio base_url, significa la entrada del usuario. Un bloque con el mismo nombre pero sin endpoint — solo ajustes — conserva el integrado.
Esa regla vive en una sola función, builtin_name_user_entry() en hermes_cli/runtime_provider_custom.py:
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)."""
La frase que importa es “el único predicado”: el cambio de modelo, el guardado del dashboard y doctor leen la misma decisión, así que el endpoint que se valida es siempre el endpoint sobre el que corre el turno siguiente. La identidad persistida sigue esa lógica:
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)
Entonces /model sobre la clave Anthropic persiste custom:Anthropic, y el runtime resuelve esa identidad de vuelta a tu base_url y tu credencial. Los dos lados coinciden.
El mismo commit cerró un agujero más silencioso: una key de entorno o de pool integrada nunca se envía a un model.base_url que pertenece a una entrada de providers: con credencial propia. Eso cubre el camino de api-key del registry, el del pool-entry y el del entorno de Anthropic. Hay una excepción deliberada: una entrada sin credencial mantiene el viejo comportamiento de espejo de #10622, o sea “usar la key integrada contra tu propio mirror”.
Ahora un warning de doctor lo dice en voz alta
Después del fix, una config como esta deja de resolverse en silencio a favor del usuario sin avisar:
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 imprime (desde _warn_builtin_name_owned_by_entry):
⚠ model.provider 'openrouter' runs on your providers.openrouter endpoint, not the built-in
(https://relay.example.com/v1)
y ofrece dos salidas: declarar la identidad de forma explícita con hermes config set model.provider custom:openrouter, o borrar providers.openrouter.base_url para volver a usar el provider integrado. El warning sirve porque nombra los dos datos que necesitas — la dirección que realmente se está usando y la identidad que deberías estar usando — en vez de dejarte deducirlos.
Qué revisar en tu propia máquina
Si tu config.yaml tiene una sección providers:, dedícale dos minutos a tres cosas:
- Mira los nombres de las claves.
openai,anthropic,openrouter,deepseek,gemini,xai,lmstudioen cualquier capitalización cuentan como colisiones. - Corre
hermes doctory busca el warningruns on your providers.<key> endpoint. - Si de verdad quieres apuntar un nombre integrado a tu propio relay, las dos rutas funcionan: escribe
model.providercomocustom:<key>, o simplemente renombra la clave a algo comomy-relay— la clave deproviders:es solo tu etiqueta.
Al revés: si lo único que querías era un timeout más largo o un header extra para un provider integrado, no pongas base_url en ese bloque. Un bloque con el mismo nombre pero sin endpoint conserva la semántica del integrado, y esa válvula de escape queda explícitamente preservada por el criterio.
La lección de fondo
En un sistema de config, un “nombre” suele cargar con tres trabajos a la vez: etiqueta para humanos, clave de ruteo para el programa y alcance de credencial. En el momento en que los nombres elegidos por el usuario pueden solaparse con los nombres integrados, esos tres trabajos se pelean — y el modo de falla casi nunca es un error. Es enviar en silencio al lugar equivocado, lo cual es especialmente malo cuando lo que se envía es una credencial.
Tampoco aparece en el primer uso, porque en el camino feliz las dos rutas coinciden. Solo divergen en los momentos en que la identidad se vuelve a derivar: cambiar de modelo, recargar una sesión, editar la config desde el dashboard.
Estado: en main, no en v0.23.1
El PR #152465 se fusionó el 2026-11-10 a las 21:26 UTC; el tag v0.23.1 se queda en un commit del 11-10 a las 00:24 UTC. El fix es solo de main por ahora — las instalaciones desde fuente que siguen main lo tienen, v0.23.1 y anteriores no.
Actualización (17/11/2026): estos cambios salieron en la v0.23.2 (16 de noviembre):
hermes updatelos trae. Lo de «no está en la v0.23.1» es una foto del momento de la publicación.
Mientras tanto, lo prudente es simplemente no ponerle a una entrada de providers: el nombre de un provider integrado. Renombrar no cuesta nada en funcionalidad; solo cuesta la comodidad de leer tu propia config.
Si quieres ir más a fondo: overrides de modelo cubre los switches de comportamiento por modelo, cifrado de secretos explica dónde viven realmente las credenciales y cómo se descifran, y el recorrido por los tres providers nuevos tiene bloques providers: reales para comparar. Del lado de comandos, la referencia de config y la referencia de doctor son las dos páginas que este cambio toca directamente.