Claude Code Router 3.1.1: Installation, Routing und Fehlerbehebung

Du möchtest Claude Code mit DeepSeek, OpenRouter, Gemini, Kimi, Z.AI/GLM oder einem anderen kompatiblen Endpoint verbinden, aber die gefundene Anleitung verlangt noch config.json und ccr code. Oder die Oberfläche öffnet sich, während das Gateway auf 127.0.0.1:3456 nicht startet. Diese Anleitung folgt dem aktuellen Ablauf von Version 3.1.1 und führt von der Installation bis zu einem geprüften Claude-Code-Profil, einschließlich einer klaren Diagnose für häufige Fehler.

Prüfe zuerst die Version: 3.1.1 basiert nicht mehr auf einer manuell gepflegten config.json

Provider, Routen und Agent Profiles werden in der aktuellen Version über die Web UI eingerichtet. Am 26. September 2026 zeigt das npm-Tag latest auf Version 3.1.1. Das Paket speichert seine Hauptkonfiguration in config.sqlite und erzeugt gateway.config.json für das laufende Gateway, wie die npm-Registry-Metadaten und das aktuelle Projekt-README zeigen.

Dieser Versionsunterschied erklärt zwei häufige Sackgassen. Die aktuelle CLI-Referenz startet einen Agenten mit ccr <profile-name-or-id> und führt ccr code nicht auf. gateway.config.json ist außerdem eine generierte Datei und keine Konfigurationsquelle, die du manuell pflegen solltest. Wenn ein Tutorial config.json oder ccr code verlangt, prüfe zuerst die dazugehörige CCR-Generation, bevor du den Fehler für ein Installationsproblem hältst.

Bereite Node.js, einen Upstream-Provider und Claude Code vor

Du brauchst Node.js 22 oder neuer, Zugang zu einem Modelldienst und eine lokale Claude-Code-Installation. CCR routet Anfragen; es installiert Claude Code nicht und API-Zugang ist nicht dasselbe wie ein Claude.ai- oder Claude-Max-Abonnement.

Prüfe zuerst Node.js:

node --version

Aktualisiere Node.js, wenn die Hauptversion kleiner als 22 ist. Als Upstream kannst du ein integriertes Preset wie OpenRouter, DeepSeek, Gemini, Moonshot/Kimi oder Z.AI verwenden oder einen benutzerdefinierten Endpoint mit unterstütztem OpenAI-compatible- oder Anthropic-compatible-Protokoll hinzufügen.

Installiere die npm-CLI und prüfe den Befehl vor der Konfiguration

Rufe direkt nach der globalen Installation die Hilfe auf. So trennst du ein npm- oder PATH-Problem von einem Provider- oder Routing-Problem.

npm install -g @musistudio/claude-code-router
ccr --help

Aktualisieren und deinstallieren:

npm install -g @musistudio/claude-code-router@latest
npm uninstall -g @musistudio/claude-code-router

Das Entfernen des npm-Pakets löscht lokale Konfigurationen und Datenbanken nicht. Das Datenverzeichnis liegt unter macOS/Linux in ~/.claude-code-router und unter Windows in %APPDATA%\claude-code-router.

Konfiguriere in dieser Reihenfolge: Provider → Check Connection → Client Key → Routing → Server → Profile → Ende-zu-Ende-Test

Bringe zuerst eine einzige Standardroute zum Laufen. Wenn du mehrere Provider, rewrites, retries und fallbacks gleichzeitig einrichtest, lassen sich ein 401, eine falsche Model ID und ein Protokollfehler kaum auseinanderhalten.

Öffne die Verwaltungsoberfläche:

ccr ui

Die UI verwendet standardmäßig http://127.0.0.1:3458, das Modell-Gateway http://127.0.0.1:3456. Nutze die authentifizierte URL, die CCR ausgibt oder öffnet. Ist 3458 belegt, kann CCR einen späteren Management-Port wählen und die tatsächliche Adresse anzeigen.

1. Füge den Upstream unter Providers hinzu

Verwende ein Preset, wenn eines vorhanden ist; nutze custom endpoint nur bei Bedarf. Unter Providers → Add Provider wählst du den Dienst, trägst dessen eigenen API Key ein, bestimmst das richtige Protokoll und fügst Model ID hinzu, die für dein Konto tatsächlich verfügbar sind.

Leite das Protokoll nicht aus dem Marketingnamen des Modells ab. Anthropic Messages, OpenAI Chat/Responses und Gemini verwenden unterschiedliche Formate. Base URL, Protokoll und Model ID müssen zur aktuellen Dokumentation des Upstream-Dienstes passen.

Führe nach dem Speichern des Providers Check Connection aus. Das ist nur eine Upstream-Prüfung; sie bestätigt nicht den gesamten Weg Claude Code → CCR gateway → Routing → Provider.

2. Erzeuge einen CCR client key unter API Keys

Ein CCR client key ist nicht der management token. Der management token schützt Web UI und RPC API; der client key authentifiziert Modellanfragen, die Claude Code an das Gateway sendet. Behandle jede URL mit ccr_web_token wie ein Passwort und kopiere sie nicht in Logs, Tickets oder Chats.

3. Richte zuerst eine Standardroute ein

Verknüpfe die Standardroute mit genau einem Provider, der Check Connection bestanden hat, und einem Modell dieses Providers. Speichere die Route, sende aber noch keine Claude-Code-Anfrage; starte zuerst das Gateway und erstelle das Agent Profile.

Erst nachdem die Ende-zu-Ende-Anfrage aus Schritt 6 erfolgreich war, solltest du unter Routing Bedingungen, retries, request rewrites oder geordnete fallbacks ergänzen. Füge jeweils nur ein Verhalten hinzu und teste erneut. Ein fallback-Modell muss außerdem die benötigten Tools, den Kontext und das Protokoll unterstützen; zwei Chatmodelle sind nicht automatisch austauschbar.

4. Starte und prüfe das Gateway unter Server

Eine geöffnete UI beweist nicht, dass das Gateway auf 3456 nutzbar ist. Starte es unter Server und notiere die angezeigte clientseitige URL. Standardmäßig ist das http://127.0.0.1:3456; verwende die tatsächlich von CCR angezeigte URL. Falls der Start fehlschlägt, führe CCR im Vordergrund aus:

ccr serve

Die Vordergrundausgabe hilft, einen Portkonflikt von einem unvollständigen Provider, einem fehlenden Modell oder lokalen Dateiberechtigungen zu unterscheiden.

5. Erstelle und aktiviere ein Claude-Code-Agent-Profile

Die aktuelle CLI startet Claude Code über ein aktiviertes Agent Profile. Erstelle unter Agent Profiles ein Claude-Code-Profil, wähle das in der Standardroute verwendete Modell des Providers, der Check Connection bestanden hat, speichere es und aktiviere es. Im CCR-Modus verbindet sich Claude Code mit dem unter Server angezeigten CCR gateway (standardmäßig http://127.0.0.1:3456), nicht mit der URL des Upstream-Providers. Der Name ist frei wählbar, zum Beispiel Claude - Review.

Start per Name oder ID:

ccr "Claude - Review"

Claude-Code-spezifische Argumente gehören hinter --, damit CCR sie nicht als eigene Optionen interpretiert:

ccr "Claude - Review" cli -- --model sonnet

Ersetze Claude - Review durch den tatsächlichen Profilnamen oder die Profil-ID.

6. Sende eine Claude-Code-Anfrage und prüfe danach Logs

Jetzt erfolgt der erste echte Ende-zu-Ende-Test. Sende über das gestartete Profile eine einfache Anfrage in Claude Code und bestätige in Logs, dass der erwartete Provider und das Modell gewählt wurden und der Status erfolgreich ist.

Check Connection beim Provider prüft nur die Upstream-Verbindung. Die reale Anfrage validiert zusätzlich CCR client key, Gateway, Routing, Agent Profile und den Modellaufruf.

Unterscheide ccr start, ui, serve und stop

Für den Alltag eignen sich ccr ui oder ccr start, für die Diagnose ccr serve.

Befehl	Bester Einsatz	Verhalten
ccr start	Dauerhafter Hintergrundbetrieb	Startet den detached Management-Service und das Gateway und gibt eine authentifizierte URL aus
ccr ui	Lokale interaktive Einrichtung	Verwendet einen vorhandenen Hintergrunddienst oder startet ihn und öffnet die UI
ccr serve	Fehlersuche oder Process Supervisor	Läuft im Vordergrund und zeigt Start- sowie Anfragefehler; ccr web ist ein Alias
ccr stop	Hintergrundoptionen neu setzen	Stoppt den durch start oder ui gestarteten detached Service

start, ui und serve unterstützen --host, --port, --open/--no-open und --gateway/--no-gateway. --port bezeichnet den bevorzugten Management-Port und nicht automatisch den Modell-Gateway-Port 3456.

Behebe „ccr: command not found“ über Node und den globalen npm-bin-Pfad

Prüfe Runtime und globales Prefix, bevor du mehrfach neu installierst. Führe aus:

node --version
npm prefix -g

Node.js muss mindestens Version 22 haben, und das globale npm-Verzeichnis für ausführbare Dateien muss im PATH der aktuellen Shell stehen. Öffne nach der Installation ein neues Terminal, da manche Shells Befehlspfade zwischenspeichern.

Wenn du zusätzlich die Desktop-App installiert hast, beachte: Sie stellt den verwandten Befehl ccr-app bereit. Das hier beschriebene npm-Paket installiert ccr; ein vorhandenes ccr-app beweist nicht, dass die npm-CLI im PATH liegt.

Behebe ein Gateway, das nicht auf 127.0.0.1:3456 lauscht

Kläre zuerst, ob das Gateway nicht gestartet ist oder ein anderer Prozess den Port belegt. Eine funktionierende UI auf 3458 sagt nichts über 3456 aus.

Unter macOS/Linux:

lsof -nP -iTCP:3456 -sTCP:LISTEN

Unter Windows:

netstat -ano | findstr :3456

Wenn ein alter CCR-Prozess oder ein anderes Programm den Port belegt, identifiziere vor dem Beenden die PID. Starte anschließend ccr serve, gehe zu Server zurück und prüfe, ob Provider, Modell und client key vorhanden sind, bevor du das Gateway erneut startest.

Behebe 401, model not found und Protokollfehler mit drei Zuordnungen

Prüfe Anmeldedaten, Protokoll und Model ID in dieser Reihenfolge. Häufige Fehler sind ein management token anstelle des client key, ein CCR client key im Upstream-Provider oder eine OpenAI-compatible-Route zu einem Anthropic-compatible-Endpoint.

Gehe so vor:

1. Claude Code authentifiziert sich bei CCR mit einem CCR client key, nicht mit ccr_web_token.
2. Der Provider-Eintrag enthält den eigenen API Key des Upstream-Dienstes.
3. Das gewählte Protokoll passt zum Endpoint.
4. Die geroutete Model ID existiert für diesen Provider und dieses Konto.
5. Logs löst den erwarteten Provider und das erwartete Modell auf.

Verlasse dich nicht nur auf die letzte Claude-Code-Fehlermeldung. CCR Logs kann zeigen, ob der Fehler bei Client-Authentifizierung, Routenauflösung, Upstream-Authentifizierung oder Modellaufruf entstanden ist.

Behebe fehlende Profile und Hintergrunddienste mit alten Optionen

Nur aktivierte Agent Profiles lassen sich starten. Die Namenssuche ignoriert Groß- und Kleinschreibung und akzeptiert bereinigte Namen; bei Mehrdeutigkeit brauchst du die ID. Speichere das Profil erneut, wenn der generierte Launcher fehlt.

Ein wiederverwendeter Hintergrundprozess übernimmt keine neuen host-, port- oder gateway-Optionen. Stoppe und erstelle ihn neu:

ccr stop
ccr start --host 127.0.0.1 --port 3458

Darum kann ein Befehl erfolgreich enden, während der Service weiterhin die alten Einstellungen nutzt.

Nutze ANTHROPIC_BASE_URL direkt, wenn du nur einen Endpoint brauchst

Eine direkte Einrichtung ist meist einfacher bei genau einem Anthropic-compatible-Endpoint, einem Hauptmodell und ohne bedingtes Routing, fallback, gemeinsame Logs oder mehrere Profile. Richte ANTHROPIC_BASE_URL, die Authentifizierungsvariable und das Modell-Mapping nach der Claude-Code-Dokumentation des Providers ein, ohne ein lokales Gateway hinzuzufügen.

CCR ist passender, wenn mindestens einer dieser Punkte gilt:

• du wechselst zwischen DeepSeek, OpenRouter, Gemini, Kimi, Z.AI oder custom endpoints;
• unterschiedliche Aufgaben oder Profile sollen unterschiedliche Modelle nutzen;
• du brauchst retries, Bedingungen, rewrites oder geordneten fallback;
• du willst aufgelöste Routen, Status, tokens, latency und Fehler zentral sehen;
• mehrere Clients sollen ein lokales Gateway teilen.

Situation	Bevorzugte Lösung
Ein stabiler Anthropic-compatible-Endpoint	Direktes ANTHROPIC_BASE_URL
Mehrere Provider, Modelle oder Profile	CCR
Sichtbarkeit der Route jeder Anfrage erforderlich	CCR
Schnellster Weg zu einem einzelnen Dienst	Direkt starten und bei wachsendem Workflow zu CCR wechseln

Beispiel für einen kompatiblen Endpoint: BetterToken in CCR

BetterToken ist eine mögliche benutzerdefinierte Anthropic-compatible-Option, nicht die einzige Lösung. Trage unter CCR Providers https://bettertoken.ai in das Upstream-Feld API endpoint/Base URL ein — nicht als Claude-Code-Base-URL — und hänge kein /v1 an. Wähle ausdrücklich Anthropic Messages, trage deinen eigenen BetterToken API Key und eine verfügbare Model ID ein, speichere den Provider und führe Check Connection aus.

Mit CCR verbindet sich Claude Code mit dem unter Server angezeigten CCR gateway, normalerweise http://127.0.0.1:3456. Starte das Agent Profile, sende eine Anfrage und bestätige in Logs, dass sie zum vorgesehenen BetterToken-Modell geroutet wurde. Richte Claude Code in diesem Modus nicht direkt auf https://bettertoken.ai, sonst wird CCR umgangen.

Nur wenn du CCR bewusst weglässt und dich direkt mit diesem einzelnen Endpoint verbindest, solltest du der BetterToken-Dokumentation für Claude Code folgen und die Base URL unter macOS/Linux direkt setzen:

export ANTHROPIC_BASE_URL="https://bettertoken.ai"

In PowerShell:

$env:ANTHROPIC_BASE_URL="https://bettertoken.ai"

In diesem Direktmodus müssen Authentifizierungsvariable und Modell-Mapping weiterhin aus der aktuellen Dokumentation stammen. Verwende für Claude Code nicht die OpenAI-compatible-Base-URL https://www.bettertoken.ai/v1.

Schütze lokale Zugangsdaten und sichere die Datenbank korrekt

Lass den Management-Listener auf 127.0.0.1, solange Fernzugriff nicht ausdrücklich gewollt ist. Nutze für Fernzugriff eine Firewall oder ein privates Netzwerk und TLS an einem vertrauenswürdigen Reverse Proxy. Stelle das Gateway nicht ohne CCR client keys ins externe Netz.

Upstream-Zugangsdaten, Logs und Runtime-Datenbanken liegen im lokalen CCR-Verzeichnis. Bearbeite oder kopiere config.sqlite nicht, während CCR darauf schreibt. Verwende den UI-Export oder stoppe CCR vor einem Dateisystem-Backup.

Prüfe den gesamten Anfrageweg und nicht nur die Oberfläche

Erfolg bedeutet, dass eine Claude-Code-Anfrage die erwartete Route genommen und normal geantwortet hat. Prüfe:

• node --version zeigt 22 oder neuer;
• ccr --help läuft;
• Providers enthält mindestens einen Upstream, der Check Connection bestanden hat;
• API Keys enthält einen CCR client key;
• Server zeigt ein laufendes Gateway und die clientseitige URL (standardmäßig http://127.0.0.1:3456);
• das Agent Profile ist gespeichert und aktiviert;
• ccr <profile-name-or-id> startet Claude Code;
• eine reale Claude-Code-Anfrage wurde gesendet und Logs zeigt den erwarteten Provider, das Modell und einen erfolgreichen Status;
• jede neue Route oder jeder fallback wurde erneut getestet.

Diese Reihenfolge hält Installation, Authentifizierung, Routing und Agent-Start als getrennte Schichten. Bei einem Fehler reparierst du die verantwortliche Schicht, statt CCR neu zu installieren oder wahllos eine veraltete config.json zu bearbeiten.