Du hast deinen Relay `Anthropic` genannt — und er bekam den offiziellen Key


Du hast einen Relay-Endpoint in config.yaml eingetragen, um Kosten zu sparen, und ihn nach dem Naheliegenden benannt: OpenRouter, weil das die API ist, die er weiterleitet. Zwei Wochen später hat sich an der Rechnung nichts bewegt, und der Relay-Betreiber schreibt dir: Warum ist dein offizieller Key auf meinem Server aufgetaucht? Du schaust in die Config. Die base_url zeigt eindeutig auf seine Domain.

Du hast dich nicht vertippt. Das Problem war, wem der Name gehörte. Wenn ein providers:-Key mit dem Namen eines eingebauten Providers kollidiert, kamen der Modellwechsel-Pfad und der Pfad, der die Anfrage tatsächlich verschickt, früher zu unterschiedlichen Ergebnissen: Der eine validierte deinen Endpoint, der andere schickte an den eingebauten Host mit dem eingebauten Credential. Zwei Codepfade, zwei Antworten — und etwas fiel durch die Lücke dazwischen.

Eine Namenskollision, zwei auseinanderlaufende Pfade

providers: ist der Ort, an dem du deinen eigenen Endpoint in der Config deklarierst:

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

Im Normalfall sollten der Wechsel per /model, ein Speichern im Dashboard und die tatsächliche Anfrage im nächsten Turn alle auf denselben Endpoint mit demselben Key zeigen. Ein kollidierender Name riss das auseinander.

Seit #151042 glich resolve_user_provider die providers:-Keys case-insensitiv ab, also trafen Anthropic: und OpenRouter: ab dann den Eintrag des Nutzers. Der Wechsel-Pfad machte danach Folgendes: /model validierte deinen Endpoint und speicherte model.provider: Anthropic. Im nächsten Turn kanonisierte die Runtime den nackten eingebauten Namen auf den eingebauten Provider (_select_named_custom_provider → _shadowed_by_builtin), und die Anfrage ging an api.anthropic.com — mit deinem eingebauten Key.

Bei OpenRouter war es auf andere Weise schlimmer: Die Anfrage ging tatsächlich an deine URL, aber sie trug OPENROUTER_API_KEY. Genau diesen Key hat der Relay-Betreiber gesehen.

Der Fix: ein Prädikat, gelesen von drei Aufrufstellen

Die Entscheidung der Maintainer lautete „der Nutzereintrag gewinnt“, und sie ist präzise formuliert:

Ein nackter Provider-Name in beliebiger Schreibweise (openrouter, OpenRouter, anthropic, Anthropic, deepseek, …), dessen unter diesem Namen geführter providers:-Eintrag eine eigene base_url deklariert, meint den Eintrag des Nutzers. Ein gleichnamiger Block ohne Endpoint — reines Tuning — behält den eingebauten.

Diese Regel lebt in einer einzigen Funktion, builtin_name_user_entry() in 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)."""

Der entscheidende Ausdruck ist „das eine Prädikat“: Wechsel, Dashboard-Speichern und doctor lesen dieselbe Entscheidung, sodass der Endpoint, der validiert wird, immer der Endpoint ist, auf dem der nächste Turn läuft. Die persistierte Identität folgt daraus:

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)

Also persistiert /model auf dem Key Anthropic nun custom:Anthropic, und die Runtime löst diese Identität zurück auf deine base_url und dein Credential auf. Beide Seiten sind sich einig.

Derselbe Commit schloss ein leiseres Loch: Ein eingebauter env/pool-Key wird nie an eine model.base_url geschickt, die ein providers:-Eintrag mit eigenem Credential besitzt. Das deckt den api-key-Pfad der Registry, den pool-entry-Pfad und den Anthropic-env-Pfad ab. Es gibt eine bewusste Ausnahme — ein Eintrag ohne Credential behält das alte #10622-Mirror-Verhalten, also „nutze den eingebauten Key gegen deinen eigenen Mirror“.

Eine doctor-Warnung sagt es jetzt laut

Nach dem Fix hört eine Config wie diese auf, still zu deinen Gunsten aufzulösen, ohne es zu sagen:

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 gibt aus (aus _warn_builtin_name_owned_by_entry):

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

und bietet zwei Auswege an: die Identität explizit setzen mit hermes config set model.provider custom:openrouter, oder providers.openrouter.base_url entfernen, um wieder den eingebauten Provider zu nutzen. Die Warnung ist nützlich, weil sie beide Fakten nennt, die du brauchst — die Adresse, die tatsächlich angesprochen wird, und die Identität, die du verwenden solltest — statt dich raten zu lassen.

Was du auf deiner eigenen Maschine prüfen solltest

Wenn deine config.yaml einen providers:-Abschnitt hat, investiere zwei Minuten in drei Dinge:

  1. Schau dir die Key-Namen an. openai, anthropic, openrouter, deepseek, gemini, xai, lmstudio in jeder Groß- oder Kleinschreibung zählen als Kollision.
  2. Lass hermes doctor laufen und achte auf die Warnung, dass der Provider auf deinem eigenen providers:-Endpoint läuft statt auf dem eingebauten.
  3. Wenn du wirklich einen eingebauten Namen auf deinen eigenen Relay zeigen lassen willst, funktionieren beide Wege: schreib model.provider in der Form custom: plus Key, oder benenne den Key einfach um, etwa in my-relay — der providers:-Key ist nur dein Label.

Umgekehrt: Wenn du für einen eingebauten Provider nur ein längeres Timeout oder einen zusätzlichen Header wolltest, dann setz keine base_url in diesen Block. Ein gleichnamiger Block ohne Endpoint behält die eingebaute Semantik, und diese Hintertür bleibt laut der Entscheidung ausdrücklich erhalten.

Die eigentliche Lehre

In einem Config-System trägt ein „Name“ meist drei Aufgaben gleichzeitig: ein Label für Menschen, ein Routing-Key für das Programm und einen Credential-Scope. Sobald nutzergewählte Namen mit eingebauten Namen überlappen dürfen, streiten diese drei Aufgaben miteinander — und der Fehlermodus ist selten ein Fehler. Er ist das stille Senden an die falsche Stelle, was besonders übel ist, wenn das Gesendete ein Credential ist.

Er zeigt sich außerdem nie beim ersten Gebrauch, weil auf dem Happy Path beide Codepfade übereinstimmen. Auseinander laufen sie erst in den Momenten, in denen die Identität neu hergeleitet wird: beim Modellwechsel, beim Neuladen einer Session, beim Bearbeiten der Config über das Dashboard.

Status: auf main, nicht in v0.23.1

PR #152465 wurde am 2026-11-10 um 21:26 UTC gemerged; der Tag v0.23.1 endet bei einem Commit vom 11-10 00:24 UTC. Der Fix ist vorerst nur auf main — Source-Installationen, die main folgen, haben ihn, v0.23.1 und älter nicht.

Update (17.11.2026): Diese Änderungen sind mit v0.23.2 (16. November) erschienen – ein hermes update bringt sie. Die Formulierung „nicht in v0.23.1“ oben ist eine Momentaufnahme vom Veröffentlichungstag.

Bis dahin ist der sichere Zug einfach der, einen providers:-Eintrag nicht nach einem eingebauten Provider zu benennen. Umbenennen kostet funktional nichts; es kostet nur den Komfort, die eigene Config lesen zu können.

Wenn du tiefer einsteigen willst: model overrides deckt die Verhaltensschalter pro Modell ab, secret encryption erklärt, wo Credentials wirklich liegen und wie sie entpackt werden, und der Walkthrough zu den drei neuen Providern hat echte providers:-Blöcke zum Vergleichen. Auf der Befehlseite sind die Config-Referenz und die doctor-Referenz die zwei Seiten, die diese Änderung direkt berührt.