Vous aviez appelé votre relais `Anthropic` — et c'est la clé officielle qui est partie


Vous avez ajouté un endpoint relais dans config.yaml pour réduire les coûts, et vous l’avez nommé de la façon la plus évidente : OpenRouter, puisque c’est l’API qu’il relaie. Deux semaines plus tard, la facture n’a pas bougé et l’opérateur du relais vous écrit : pourquoi ta clé officielle est-elle apparue sur mon serveur ? Vous vérifiez la config. Le base_url pointe clairement vers leur domaine.

Vous n’avez pas fait de faute de frappe. Le problème était la propriété du nom. Quand une clé de providers: entre en collision avec le nom d’un provider intégré, le chemin de changement de modèle et le chemin qui envoie réellement la requête aboutissaient à des conclusions différentes : l’un validait votre endpoint, l’autre envoyait vers l’hôte intégré avec le credential intégré. Deux chemins de code, deux réponses, et quelque chose est passé par le trou entre les deux.

Une collision de nom, deux chemins qui divergent

providers: est l’endroit où vous déclarez votre propre endpoint dans la config :

providers:
  OpenRouter:
    base_url: https://relay.example.com/v1
    key_env: RELAY_API_KEY
    default_model: some-model

Dans le cas normal, le changement via /model, l’enregistrement depuis le dashboard et la requête réelle du tour suivant devraient tous viser le même endpoint avec la même clé. Un nom en collision séparait tout cela.

Depuis #151042, resolve_user_provider comparait les clés de providers: sans tenir compte de la casse, donc Anthropic: et OpenRouter: se mettaient à toucher l’entrée de l’utilisateur. Le chemin de changement faisait alors ceci : /model validait votre endpoint et enregistrait model.provider: Anthropic. Au tour suivant, le runtime canonicalisait le nom intégré nu vers le provider intégré (_select_named_custom_provider → _shadowed_by_builtin), donc la requête partait vers api.anthropic.com — en portant votre clé intégrée.

Avec OpenRouter, c’était pire d’une autre manière : la requête partait bien vers votre URL, mais elle portait OPENROUTER_API_KEY. C’est la clé que l’opérateur du relais a vue.

Le correctif : un seul prédicat, lu par trois sites d’appel

L’arbitrage du mainteneur était « l’entrée utilisateur gagne », et il est formulé précisément :

Un nom de provider nu, quelle que soit la casse (openrouter, OpenRouter, anthropic, Anthropic, deepseek, …), dont l’entrée providers: portant ce nom déclare son propre base_url, désigne l’entrée de l’utilisateur. Un bloc de même nom sans endpoint — du réglage seulement — conserve le provider intégré.

Cette règle vit dans une seule fonction, builtin_name_user_entry() dans 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 formule qui compte est « le seul prédicat » : le changement, l’enregistrement depuis le dashboard et doctor lisent la même décision, donc l’endpoint validé est toujours celui sur lequel tourne le tour suivant. L’identité persistée suit :

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)

Donc /model sur la clé Anthropic persiste custom:Anthropic, et le runtime résout cette identité vers votre base_url et votre credential. Les deux côtés sont d’accord.

Le même commit a fermé un trou plus discret : une clé env/pool intégrée n’est jamais envoyée vers un model.base_url que possède une entrée providers: dotée de son propre credential. Cela couvre le chemin api-key du registre, celui des entrées de pool et celui de l’env Anthropic. Il existe une exception délibérée — une entrée sans credential garde l’ancien comportement miroir de #10622, c’est-à-dire « utiliser la clé intégrée contre votre propre miroir ».

Un avertissement de doctor le dit maintenant à voix haute

Après le correctif, une config comme celle-ci cesse de se résoudre en silence en faveur de l’utilisateur sans le signaler :

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 affiche (depuis _warn_builtin_name_owned_by_entry) :

⚠ model.provider 'openrouter' runs on your providers.openrouter endpoint, not the built-in
  (https://relay.example.com/v1)

et propose deux issues : énoncer l’identité explicitement avec hermes config set model.provider custom:openrouter, ou supprimer providers.openrouter.base_url pour revenir au provider intégré. L’avertissement est utile parce qu’il nomme les deux faits dont vous avez besoin — l’adresse réellement visée et l’identité que vous devriez utiliser — au lieu de vous laisser les déduire.

Ce qu’il faut vérifier sur sa propre machine

Si votre config.yaml contient une section providers:, passez deux minutes sur trois points :

  1. Regardez les noms de clé. openai, anthropic, openrouter, deepseek, gemini, xai, lmstudio, quelle que soit la capitalisation, comptent comme des collisions.
  2. Lancez hermes doctor et cherchez l’avertissement runs on your providers.<key> endpoint.
  3. Si vous voulez vraiment qu’un nom intégré pointe vers votre propre relais, les deux routes fonctionnent : écrivez model.provider sous la forme custom:<key>, ou renommez simplement la clé en quelque chose comme my-relay — la clé de providers: n’est que votre étiquette.

À l’inverse, si tout ce que vous vouliez était un timeout plus long ou un header supplémentaire pour un provider intégré, ne mettez pas de base_url dans ce bloc. Un bloc de même nom sans endpoint conserve la sémantique du provider intégré, et cette échappatoire est explicitement préservée par l’arbitrage.

La vraie leçon

Dans un système de config, un « nom » porte généralement trois rôles à la fois : une étiquette pour les humains, une clé de routage pour le programme et une portée de credential. Dès qu’on autorise des noms choisis par l’utilisateur à chevaucher des noms intégrés, ces trois rôles se disputent — et le mode de défaillance est rarement une erreur. C’est un envoi discret au mauvais endroit, ce qui est particulièrement fâcheux quand ce qu’on envoie est un credential.

Et cela n’apparaît jamais au premier usage, parce que sur le chemin heureux les deux chemins de code sont d’accord. La divergence ne survient qu’aux moments où l’identité est redérivée : changement de modèle, rechargement d’une session, édition de la config via le dashboard.

Statut : sur main, pas dans la v0.23.1

La PR #152465 a été fusionnée le 2026-11-10 à 21:26 UTC ; le tag v0.23.1 s’arrête à un commit du 11-10 à 00:24 UTC. Le correctif reste donc réservé à main pour l’instant — les installations depuis les sources qui suivent main l’ont, la v0.23.1 et les versions antérieures non.

Mise à jour (17/11/2026) : ces changements sont sortis dans la v0.23.2 (16 novembre) : un hermes update les récupère. Le « pas dans la v0.23.1 » ci-dessus est un instantané du jour de publication.

D’ici là, la précaution consiste simplement à ne pas nommer une entrée providers: d’après un provider intégré. Renommer ne coûte rien fonctionnellement ; cela ne coûte que le confort de lire sa propre config.

Si vous voulez aller plus loin : les surcharges de modèle couvrent les commutateurs de comportement par modèle, le chiffrement des secrets explique où vivent réellement les credentials et comment ils sont déballés, et le tour d’horizon des trois nouveaux providers contient de vrais blocs providers: à comparer. Côté commandes, la référence config et la référence doctor sont les deux pages que ce changement touche directement.