Claude Code Router – Claude Code zu jedem Modell routen oder den Router vollständig überspringen

Die meisten Menschen, die nach Claude Code Router suchen, möchten eines von zwei verschiedenen Dingen: Claude Code über mehrere Modellanbieter routen oder Claude Code einfach günstiger als zum Listenpreis von Anthropic ausführen. Nur für das erste benötigen Sie den Router. Claude Code liest ANTHROPIC_BASE_URL nativ, daher reichen für das zweite drei Umgebungsvariablen und überhaupt keine zusätzliche Software.

Diese Anleitung behandelt beide Wege, mit den exakten Variablennamen, der Falle bei den Zugangsdaten, die einen stillen 401 erzeugt, und einer ehrlichen Liste dessen, was hinter jedem Gateway nicht mehr funktioniert. Wenn Sie kürzlich eine andere CCR-Anleitung gelesen haben, springen Sie zuerst zu Option B: Die config.json, die diese Artikel bearbeiten lassen, ist nicht mehr die Konfiguration, die der Router liest.

Welche Variante benötigen Sie tatsächlich?

Der Router ist ein lokaler Dienst: ein weiterer Prozess, den Sie ausführen, konfigurieren und aktuell halten müssen — und seit 2026 eine Desktop-App mit eigener Oberfläche statt einer Datei, die Sie bearbeiten. Dieser Aufwand lohnt sich, wenn Sie tatsächlich Routing über mehrere Anbieter, Abrechnung pro Anfrage oder eine Modellauswahl auf Subagent-Ebene benötigen. Er lohnt sich nicht, wenn eine Basis-URL ausgereicht hätte.

Option A — der Austausch der Basis-URL (keine Installation)

Kunavo stellt die native Anthropic Messages API unter /v1/messages bereit, dem Endpunkt, den Claude Code aufruft. Verweisen Sie darauf:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL ist nur der Ursprung – Claude Code hängt /v1/messages selbst an; geben Sie keinen Pfad an. Behalten Sie die Modellzeilen bei: Der integrierte Standard von Claude Code und sein Alias opus verweisen beide auf das neueste Opus. Wenn Kunavo dieses Modell noch nicht anbietet, liefert die erste Anfrage 404 zurück. Der Alias sonnet fordert Sonnet 5.5 an, das Kunavo nicht anbietet. Ohne die Zeile ANTHROPIC_DEFAULT_SONNET_MODEL /model sonnet, die Ausführungsphase von opusplan und jeden Subagenten mit model: sonnet liefern alle Anfragen 404 zurück. Der Alias opus ist auf Opus 5.5 (claude-opus-5-5) festgelegt; dafür ist Claude Code v2.1.280 oder höher erforderlich – führen Sie claude update aus, wenn Ihre Version älter ist. Rufen Sie den Schlüssel nach der Registrierung und dem Aufladen von 10 $ im Dashboard ab; er wird nur einmal angezeigt.

Welche Zugangsdatenvariable — und warum sie wichtig ist

Claude Code sendet die beiden Zugangsdatenvariablen in unterschiedlichen HTTP-Headern, und ein Schlüssel in dem Header, den der Server nicht liest, schlägt mit 401 fehl:

Bevorzugen Sie ANTHROPIC_AUTH_TOKEN aus einem konkreten Grund: ANTHROPIC_API_KEY benötigt eine einmalige Genehmigung in einer interaktiven Sitzung, und ein Schlüssel, den Sie einmal abgelehnt haben, wird danach ohne erneute Nachfrage ignoriert — ein verwirrender Fehler, bei dem die Variable eindeutig gesetzt und ebenso eindeutig ungenutzt ist. Die Modellerkennung entscheidet dies bei Kunavo nicht. Die Gateway-Modellerkennung von Claude Code sendet nur das Bearer-Token, wenn ANTHROPIC_AUTH_TOKEN gesetzt ist, und verwendet andernfalls x-api-key; der /v1/models-Endpunkt von Kunavo liest den Schlüssel aus beiden Headern.

Dauerhaft übernehmen

Shell-Exporte gelten nur für dieses Terminal und alles, was daraus gestartet wird — ein über das Dock geöffneter Editor sieht sie nicht, ebenso wenig Hintergrund-Agents. Legen Sie die Werte in einer Einstellungsdatei ab, um alles abzudecken:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Verwenden Sie ~/.claude/settings.json für alle Projekte. Legen Sie niemals einen Schlüssel in die .claude/settings.json eines Projekts — diese Datei wird in das Repository übernommen.

Überprüfen Sie es, bevor Sie darauf vertrauen

Testen Sie zuerst den Endpunkt direkt, damit ein Fehler auf die Konfiguration und nicht auf Claude Code verweist:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Starten Sie anschließend claude aus derselben Shell und führen Sie /status aus. Eine Zeile Anthropic base URL, die api.kunavo.com anzeigt, und eine Zeile Auth token, die Ihre Variable nennt, bestätigen, dass beide Hälften aktiv sind.

Ein benutzerdefiniertes Modell festlegen — den Slug ausdrücklich auswählen

Kunavo löst Modell-Slugs durch exakte Übereinstimmung auf und verwendet keine Aliase für Namen mit Datumszusatz, daher liefert claude-sonnet-4-5-20250929 den Status 404, während claude-sonnet-5 erfolgreich ist. Setzen Sie immer ANTHROPIC_MODEL, statt sich auf den integrierten Standard zu verlassen:

Die Alias-Variablen ermöglichen Routing pro Aufgabe ganz ohne Router: ANTHROPIC_DEFAULT_OPUS_MODEL unterstützt den Alias opus und den Planmodus, ANTHROPIC_DEFAULT_SONNET_MODEL unterstützt sonnet und die Ausführungsphase von opusplan, und ANTHROPIC_DEFAULT_HAIKU_MODEL unterstützt haiku sowie die Hintergrundarbeit von Claude Code – die Zusammenfassungen und Titel, die unauffällig Kosten verursachen. Diese Variable auf claude-haiku-4-5 zu setzen, ist die einzelne wertvollste Konfigurationszeile. (ANTHROPIC_SMALL_FAST_MODEL ist die veraltete Schreibweise derselben Einstellung.)

Optional: jedes Modell in der Auswahl anzeigen

Setzen Sie CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 (Claude Code v2.1.129+), und Claude Code fragt beim Start GET /v1/models ab und fügt die gefundenen Modelle der /model-Auswahl mit der Kennzeichnung From gateway hinzu. Kunavo stellt diesen Endpunkt bereit, sodass jedes aktivierte Claude-Modell angezeigt wird und /model zu einem Live-Menü statt zu einer von Hand gepflegten Liste wird. Dafür funktioniert jede der beiden Zugangsdatenvariablen — siehe oben.

Option B — claude-code-router, wie es jetzt tatsächlich funktioniert

Beginnen Sie hier, denn fast alles, was über CCR geschrieben wurde, beschreibt eine Version, die es nicht mehr gibt. Der Router bestand früher aus einer JSON-Datei und dem Befehl ccr code. Heute ist er eine lokale Steuerungsebene mit Desktop-App, Verwaltungsoberfläche, Anfrageprotokollen und einem Modell-Gateway — und die config.json, die jede Anleitung zeigt, konfiguriert ihn nicht mehr.

CCR speichert seine Laufzeitkonfiguration in ~/.claude-code-router/config.sqlite (%APPDATA%\claude-code-router\config.sqlite unter Windows). Eine veraltete config.json wird einmal als Migrationsquelle gelesen, wenn noch keine SQLite-Konfiguration vorhanden ist. Nach diesem ersten Lauf wirkt sich das Bearbeiten nicht auf die laufende Konfiguration aus — ohne Fehler und ohne Warnung. Ihr sorgfältig eingefügter Providers-Block ist schlicht nicht die Konfiguration.

Das umfasst diese Seite vor dem 06.09.2026: Das JSON-Snippet, das hier früher stand, war falsch – und zwar auf eine Art, die einen ganzen Nachmittag kostet, weil nichts darauf hinweist, dass es ignoriert wurde. Die Konfiguration erfolgt jetzt in der Benutzeroberfläche (oder als Sicherung unter Einstellungen → Daten exportieren – kopieren Sie keine Live-SQLite-Dateien, während CCR läuft).

Installieren und starten

CCR wird auf zwei Wegen bereitgestellt: als Desktop-App aus den GitHub-Releases (Tray, automatische Updates, Desktop-Integrationen) und als npm-CLI für Headless- oder überwachte Bereitstellungen. Beide verwenden dasselbe Konfigurationsverzeichnis.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Kunavo hinzuzufügen bedeutet einen Provider-Eintrag – Providers → Add provider, Voreinstellung Other / custom API endpoint, Endpunkt https://api.kunavo.com, Ihren sk-kn--Schlüssel – und ein Agent Config → Add profile → Claude Code-Profil. Die Version mit allen einzelnen Feldern, einschließlich Check Connection und der Modellerkennung, finden Sie auf der Claude Code Router-Integrationsseite. Der Rest dieses Abschnitts behandelt, was diese Seite nicht abdeckt: Zugangsdaten, Kosten und Fehlerbilder.

Drei Zugangsdaten – und welche davon für einen 401-Fehler verantwortlich ist

So wirkt eine funktionierende Einrichtung am häufigsten fehlerhaft. CCR verfügt über drei separate Geheimnisse, die jeweils einen anderen Hop authentifizieren:

Auch die Zuordnung der Ports führt häufig zu Verwirrung: Die Verwaltung verwendet standardmäßig 127.0.0.1:3458 und das Modell-Gateway 127.0.0.1:3456. Eine auf 3458 gerichtete Basis-URL erreicht die Benutzeroberfläche, nicht das Gateway. (Docker führt beide absichtlich hinter einem einzigen Nginx-Endpunkt zusammen, weshalb die Docker-Anweisungen anders aussehen.) Eine erreichbare Benutzeroberfläche bedeutet nicht, dass das Gateway funktioniert: Prüfen Sie /health unter der Gateway-Adresse und bestätigen Sie, dass Server Running anzeigt.

Auf die Zuordnung pro Tier kommt es an

Claude Code fragt nicht nach einem Modell, sondern nach einem Stufe – die Hauptschleife benötigt Sonnet oder Opus, während Hintergrundaufgaben (Subagenten, Suche, Zusammenfassungen, Unterhaltungstitel) das kleine, schnelle Modell verwenden. Ein Claude-Code-Profil in Agent Config stellt dafür separate Felder bereit: ein standardmäßiges Model sowie optionale Überschreibungen für Fable, Opus, Sonnet und Haiku, die jeweils einen Provider/model-Wert akzeptieren. Lassen Sie ein Tier leer, wählt Claude Code es selbst aus.

Lesen Sie diese Tabelle, bevor Sie die Modellzuordnung einer anderen Person kopieren, denn die naheliegende Aufteilung ist der erste Hebel: claude-sonnet-5 kostet auf Kunavo 50 % weniger als claude-opus-5-5 ($1.40 / $7.00 gegenüber $2.80 / ). Der zweite Hebel ist die Haiku-Stufe: Mit $0.70 / $3.50 ist sie 2× günstiger als Sonnet 5 und verarbeitet ein Volumen, das Sie nie sehen – jeder Subagent, jeder Durchlauf zur Dateisortierung, jeder generierte Titel. claude-sonnet-4-6 ist nicht mehr das günstige Sonnet: Mit $2.10 / $10.50 kostet es 50 % mehr als Sonnet 5. Deshalb setzen die obigen Snippets ANTHROPIC_MODEL=claude-sonnet-5.

Subagenten-Routing – was die Tier-Zuordnung nicht leisten kann

Tier-Überschreibungen legen alle Subagenten auf ein Modell fest. CCR kann feiner unterscheiden: Wenn eine Claude-Code-Anfrage der integrierten Route entspricht, fügt es die Liste der verfügbaren Modelle in die Agent-/Task-Toolbeschreibung ein, und Claude Code stellt dem Prompt jedes gestarteten Agenten ein Tag voran, das das gewünschte Modell benennt:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR entfernt das Tag und leitet diese eine Anfrage entsprechend weiter. So kann ein Such-Subagent auf Haiku laufen, während ein Review-Subagent Opus verwendet – je nach Aufgabe ausgewählt statt fest zugeordnet. Die Umschaltung wird leicht übersehen: Der Mechanismus ist deaktiviert, bis mindestens ein Modell auf der Models-Seite eine Description besitzt. Ohne Beschreibungen fügt CCR nichts ein, und jeder Subagent fällt still auf den Profilstandard zurück. Formulieren Sie die Beschreibungen nach der Eignung für die Aufgabe – „Codesuche, Dateisichtung, günstige parallele Subagenten“ für Haiku, „Architekturanalyse, Überprüfung mit hohem Risiko“ für Opus. Wenn es funktioniert, zeigen die Anfrageprotokolle builtin:claude-code-subagent als Routenbegründung.

Protokollauswahl und ihre Cache-Kosten

CCR prüft den Endpunkt und wählt ein Wire-Protokoll. Geben Sie den reinen Ursprung https://api.kunavo.com an, verwendet es Anthropic Messages; geben Sie https://api.kunavo.com/v1 an, verwendet es das OpenAI-kompatible Format. Beide Oberflächen sind mit demselben Schlüssel aktiv, und Sie können die automatische Erkennung in den erweiterten Einstellungen überschreiben.

Bevorzugen Sie die Anthropic-Messages-Form. Sie behält cache_control im Wire-Format bei, sodass Prompt-Caching das Modell erreicht und gecachter Input mit 10 % des Input-Tarifs berechnet wird (so funktioniert es) – bei einer Agentenschleife, die in jedem Schritt ein stabiles Präfix erneut sendet, ist dies die größte einzelne verfügbare Einsparung. Der ehrliche Vorbehalt: Ein Router im Pfad bearbeitet weiterhin Anfragen. CCR entfernt die Billing-Header-Systemnachricht, die Claude Code einfügt, und fügt bei aktiviertem Subagenten-Routing die Modellliste in Toolbeschreibungen ein. Beides liegt vor Ihren Cache-Grenzen, sodass jede Änderung an diesen Inhalten einen Cache-Miss verursacht, während das neue Präfix aufgewärmt wird. Danach bleibt es stabil – dennoch ist dies ein echter Grund dafür, dass Option A geringfügig besser cached als Option B, zusätzlich dazu, dass sie weniger Betriebsaufwand verursacht.

Fallback: Wiederholung oder Ausweichmodell

Die Option Default on failure auf der Routing-Seite sollten Sie festlegen, bevor Sie sie benötigen. Retry sendet die Anfrage bei 408, 409, 429 und 5xx erneut an dasselbe Modell, berücksichtigt Retry-After und verwendet ansonsten ein exponentielles Backoff von 1 s bis zu einem Limit von 30 s. Fallback targets durchläuft eine geordnete Liste von Ersatzmodellen und wird bei jedem 4xx oder 5xx ausgelöst – unter der Annahme, dass „Modell nicht gefunden“ oder eine Provider-Zurückweisung nur das aktuelle Ziel betreffen kann. Einzelne Regeln können die globale Einstellung überschreiben. Bei einem Fallback enthält die Antwort x-ccr-fallback-attempts und x-ccr-fallback-model, sodass Sie nachträglich erkennen können, was passiert ist.

Überprüfen, ob es tatsächlich im Pfad liegt

Starten Sie Claude Code über das Profil, senden Sie eine Nachricht und öffnen Sie anschließend Request logs in CCR. Die Zeile zeigt request model (wonach Claude Code gefragt hat), resolved provider und resolved model (wohin die Anfrage ging) – dieses Dreifache ist der Beweis. In der CLI listet /model die Modelle auf, die CCR bereitstellt. Wenn Claude Code antwortet, aber keine Protokollzeile erscheint, haben Sie Claude Code selbst statt über CCR gestartet, und der Geltungsbereich des Profils ist Only opened from CCR.

Was eine Coding-Sitzung kostet

Claude Code sendet System-Prompt, Unterhaltung und neuen Dateikontext bei jedem Schritt erneut, sodass sich der Preis pro Token schnell summiert. Zu den Kunavo-Tarifen für claude-sonnet-5:

Das sind vor Prompt-Caching ungefähr 30% Rabatt auf das Hauptmodell. Die vollständigen Tarife finden Sie im Claude-API-Preisleitfaden, und der Kostenrechner verwendet Ihre eigenen Tokenzahlen.

Was weiterhin funktioniert – und was nicht

Wenn Sie Claude Code auf ein beliebiges Gateway richten, ändert sich einiges. Die Liste ist kurz und Sie sollten sie kennen, bevor Sie sich festlegen:

Bei der letzten Zeile: Die Tokenzählung ist der einzige Endpunkt, den Anthropics eigene Gateway-Spezifikation als optional kennzeichnet, und Claude Code schätzt die Kontextnutzung lokal, wenn er fehlt. Kunavo stellt /v1/messages/count_tokens derzeit nicht bereit, daher ist Ihr /context-Wert eine Schätzung und keine exakte Zählung. Über diesen Wert hinaus wird nichts beeinträchtigt – automatische Kompaktierung und die Sitzung selbst bleiben unverändert.

Fehlerbehebung

Der Pfad der Basis-URL

…und wenn der Router im Pfad liegt

Fehlerbehebungen für einzelne Fehler der API selbst finden Sie auf den Troubleshooting-Seiten zu ungültigem API-Schlüssel und Ratenbegrenzung.

Häufig gestellte Fragen