Dokumentation

CC Switch

CC Switch wechselt Claude Code und Codex über eine Desktop-App zwischen Anbietern. Kunavo wird als Custom Configuration eingerichtet — Service-Root, Bearer-Authentifizierung, natives Anthropic Messages, kein lokales Routing.

Drei Felder und zwei Dropdowns. https://api.kunavo.com als Endpunkt, Ihr sk-kn-…-Schlüssel und — der Teil, den die meisten Anleitungen auslassen — API Format auf Anthropic Messages (Native) und Auth Field auf ANTHROPIC_AUTH_TOKEN belassen. Kunavo spricht die Messages API nativ, daher ist aufseiten von Claude Code kein lokales Routing erforderlich.

CC Switch → Registerkarte Claude Code → Add provider

Provider Name   Kunavo
API Key         sk-kn-...
API Endpoint    https://api.kunavo.com      <- service root, no /v1, no trailing slash

Advanced Options
  API Format    Anthropic Messages (Native) <- the default; do NOT switch
  Auth Field    ANTHROPIC_AUTH_TOKEN (Default)

Der Endpunkt ist der Service-Root: kein /v1, kein abschließender Schrägstrich. Clients im Anthropic-Stil fügen /v1/messages selbst hinzu — deshalb sieht dieses Feld anders aus als in jedem OpenAI-Beispiel, wo /v1 zur Basis-URL gehört. Eine vollständige Erklärung finden Sie auf der Seite zu ANTHROPIC_BASE_URL.

Schritt für Schritt (Tab „Claude Code“)

Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
Öffnen Sie CC Switch im Tab Claude Code auf oberster Ebene und klicken Sie auf die Plus-Schaltfläche. Behalten Sie den Standardwert Custom Configuration bei, statt eine Voreinstellung zu verwenden.
Tragen Sie Provider Name, API Key und API Endpoint = https://api.kunavo.com ein.
Klappen Sie Advanced Options auf und prüfen Sie, ob API Format auf Anthropic Messages (Native) und Auth Field auf ANTHROPIC_AUTH_TOKEN (Default) gesetzt ist. Beides sind Standardwerte; es geht darum, sie zu überprüfen, nicht zu ändern.
Speichern Sie und Activate. Auf der Karte sollte kein Needs Routing-Marker erscheinen — dieser Marker wird nur bei Anbietern angezeigt, deren Protokoll übersetzt werden muss.

Warum es keinen Marker „Needs Routing“ gibt

Die lokale Route von CC Switch dient dazu, Protokolle zu überbrücken. Claude Code sendet Anthropic-Messages-Anfragen an /v1/messages; ein Gateway, das nur OpenAI Chat Completions oder die Responses API bereitstellt, kann darauf nicht antworten. Daher wandelt die Route die Anfrage beim Senden und die Antwort beim Zurückkommen um. Dabei werden Streaming-Ereignisse, Tool-Aufrufe und die Thinking-Konfiguration neu geformt — das funktioniert, bringt aber ein weiteres bewegliches Teil zwischen Ihrem Editor und dem Modell mit sich.

Kunavo stellt POST /v1/messages direkt bereit, daher muss aufseiten von Claude Code nichts umgewandelt werden: Der Anbieter bleibt auf Anthropic Messages (Native) und die Route kommt überhaupt nicht zum Einsatz. Unter demselben Schlüssel stellt Kunavo außerdem POST /v1/chat/completions und POST /v1/responses bereit, wodurch die unten beschriebene Codex-Richtung möglich wird.

CC Switch-Tab	Format einstellen auf	Lokales Routing
Claude Code	`Anthropic Messages (Native)`	Nicht erforderlich
Codex	`Anthropic Messages (routing required)`	Erforderlich — die Route schreibt /responses in /v1/messages um

Claude-Modelle in Codex ausführen

Diese Richtung behandeln die Anleitungen zu anderen Anbietern nicht. Codex kommuniziert mit der OpenAI Responses API; verweist man es direkt auf einen /v1/messages-Endpunkt, erhält man daher einen 404-Fehler. CC Switch löst das, indem Codex über die lokale Route geleitet und die Anfrage übersetzt wird. Im Tab Codex gibt es keine Anthropic-Voreinstellung, daher ist auch dies eine Custom Configuration:

CC Switch → Registerkarte Codex → Add provider

Provider Name      Kunavo
API Key            sk-kn-...
API Request URL    https://api.kunavo.com
Default Model      claude-sonnet-5

Advanced Options
  Upstream Format  Anthropic Messages (routing required)

Die Anleitung von CC Switch enthält einen Warnhinweis, den man wiederholen sollte: Manche Anbieter beschränken ihre Claude API auf den Claude Code-Client, sodass ein solcher Schlüssel bei Verwendung über Codex einen Fehler auslösen kann. Bei Kunavo ist das nicht der Fall — derselbe sk-kn-…-Schlüssel bedient sowohl die Messages- als auch die Responses-Schnittstelle, und für keine davon gibt es eine Client-Zulassungsliste. Wenn Sie die Übersetzung ganz umgehen möchten, kann die Codex CLI auch direkt auf Kunavos native /v1/responses-Schnittstelle zugreifen; diesen Weg finden Sie auf der Seite zur Codex CLI.

Modellzuordnung

CC Switch ordnet die drei Stufen von Claude Code echten Modell-IDs zu. Füllen Sie alle drei sowie Default fallback model aus — nicht zugeordnete Anfragen werden andernfalls unter dem ursprünglichen Claude-Namen weitergeleitet und schlagen beim Upstream fehl. Die Preise sind USD pro 1M Token, Eingabe / Ausgabe, und werden live aus dem Katalog abgerufen.

Stufe	Modell-ID	Kunavo: Ein- und Ausgabe	Warum
Haiku	`claude-haiku-4-5`	$0.70 / $3.50	Claude Code leitet Hintergrund-Teilaufgaben hierher weiter — die günstigste Stufe ist die richtige
Sonnet	`claude-sonnet-5`	$1.40 / $7.00	Der bewährte Standard für Bearbeitungen
Opus	`claude-opus-5-5`	$2.80 / $14.00	Änderungen auf Architekturebene

Lassen Sie das Kontrollkästchen 1M deaktiviert, sofern die Stufe nicht tatsächlich ein Kontextfenster von einer Million Token bietet. Einen Kontext anzugeben, den der Upstream nicht hat, erweitert nichts — der Fehler tritt dadurch lediglich mitten in einem langen Gespräch auf.

Überprüfen, bevor Sie die App debuggen

Mit einem Anfragepaar lässt sich feststellen, ob ein Fehler am Schlüssel, am Endpunkt oder an CC Switch liegt. Wenn beide 200 zurückgeben, liegt alles, was noch nicht funktioniert, an einem Feld im Formular — fast immer an Auth Field oder einem /v1, das nicht in den Endpunkt gehört.

# Settles whether a failure is the key, the endpoint, or CC Switch.
# 200 + a JSON list of model ids means the same key works in the app.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

# The Anthropic face, which is the one the Claude Code tab actually calls.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Referenz

CC Switch ist Open Source unter github.com/farion1231/cc-switch. Die obigen Feldnamen und das beschriebene Verhalten stammen aus den eigenen Anleitungen — der Routing-Anleitung für Claude Code und der Routing-Anleitung für Codex. In beiden steht, dass sie für Version 3.17.0 und höher gelten. Bei älteren Versionen sieht das Formular anders aus; prüfen Sie den Info-Bereich der App, wenn ein hier genanntes Feld fehlt. Kunavos Seite ist unter der Messages API, Chat Completions und dem Integrations-Hub dokumentiert.

Häufig gestellte Fragen

Wie füge ich in CC Switch einen benutzerdefinierten Anbieter hinzu?

Klicken Sie auf der Registerkarte „Claude Code“ auf die Plus-Schaltfläche, behalten Sie „Custom Configuration“ bei und füllen Sie „Provider Name“, „API Key“ und „API Endpoint“ aus. „API Endpoint“ ist der Dienststamm des Gateways ohne abschließenden Schrägstrich. Für Kunavo lautet er https://api.kunavo.com, ohne /v1. Öffnen Sie anschließend „Advanced Options“ und prüfen Sie zwei Felder: „API Format“ und „Auth Field“. Diese beiden Felder entscheiden darüber, ob der Anbieter überhaupt funktioniert, werden aber in den meisten Einrichtungsanleitungen ausgelassen.

Muss das lokale Routing von CC Switch für Kunavo aktiviert sein?

Nein. Das lokale Routing dient der Übersetzung zwischen Protokollen: Es wandelt die Anfrage /v1/messages von Claude Code in OpenAI Responses oder Chat Completions um, wenn der Upstream nur diese Formate unterstützt. Kunavo bietet die Anthropic Messages API nativ unter https://api.kunavo.com/v1/messages an. Daher bleibt das API-Format auf dem Standardwert „Anthropic Messages (Native)“, auf der Anbieterkachel erscheint nie die Markierung „Needs Routing“, und Anfragen gehen direkt an den Upstream. Ein Gateway, das nur Chat Completions anbietet, muss dagegen für jede Anfrage das lokale Routing verwenden.

Warum enthält der API-Endpunkt kein /v1, obwohl es in den OpenAI-Beispielen vorkommt?

Weil die beiden Konventionen absichtlich unterschiedlich sind. Clients im Anthropic-Stil hängen /v1/messages selbst an und benötigen daher nur den Ursprung — https://api.kunavo.com. OpenAI-SDKs setzen voraus, dass /v1 bereits in base_url enthalten ist, und benötigen daher https://api.kunavo.com/v1. Die Registerkarte „Claude Code“ von CC Switch verwendet die Anthropic-Konvention, daher wird /v1 weggelassen. Eine Verwechslung ist der häufigste Einrichtungsfehler bei allen Clients. Auf der Seite zu ANTHROPIC_BASE_URL werden beide Formen erläutert.

Sollte ich als Auth Field ANTHROPIC_API_KEY festlegen?

Nein — behalten Sie den Standardwert ANTHROPIC_AUTH_TOKEN bei. Damit sendet CC Switch Authorization: Bearer <key>. Wenn Sie ANTHROPIC_API_KEY auswählen, wird stattdessen ein x-api-key-Header gesendet, den Kunavo ebenfalls problemlos auswertet. Der Header ist also nicht das Problem, sondern die Freigabe. Claude Code fragt in einer interaktiven Sitzung einmalig nach einer Freigabe, bevor es ANTHROPIC_API_KEY verwendet. Wird der Schlüssel dort abgelehnt, wird er anschließend ignoriert. Das führt zu einem Authentifizierungsfehler, der wie ein falscher Schlüssel aussieht, obwohl der Schlüssel korrekt ist.

Kann ich Claude-Modelle über CC Switch in Codex ausführen?

Ja, und diesen Teil lassen die meisten Anleitungen zu Anbietern aus. Fügen Sie auf der Registerkarte „Codex“ eine „Custom Configuration“ mit der API Request URL https://api.kunavo.com und einem Default Model wie claude-sonnet-5 hinzu. Legen Sie dann unter „Advanced Options“ als Upstream Format „Anthropic Messages (routing required)“ fest. Für diese Richtung muss lokales Routing aktiviert sein, da Codex die Responses API verwendet und die Route /responses in /v1/messages umschreibt. In der Anleitung von CC Switch steht, dass manche Anbieter ihre Claude API auf den Claude Code-Client beschränken und solche Schlüssel über Codex fehlschlagen. Bei Kunavo ist das nicht der Fall: Derselbe sk-kn- Schlüssel funktioniert für beide Zugriffswege.

Welche Modell-IDs trage ich in die Modellzuordnung von CC Switch ein?

Verwende die Katalog-IDs von Kunavo. Eine gute Standardaufteilung ist claude-haiku-4-5 ($0.70 / $3.50 pro 1 Mio. Token) auf der Haiku-Stufe, da Claude Code Hintergrundaufgaben dorthin sendet; claude-sonnet-5 ($1.40 / $7.00) auf Sonnet; und claude-opus-5-5 ($2.80 / $14.00) auf Opus. Fülle immer auch das Standard-Fallback-Modell aus – CC Switch leitet nicht passende Anfragen unter dem ursprünglichen Claude-Namen weiter, wenn du das Feld leer lässt, und diese schlagen beim Upstream fehl. Die aktuelle Liste ist unter GET /v1/models verfügbar.

Wo speichert CC Switch meinen API-Schlüssel?

Im eigenen Speicher, nicht in der Konfiguration des Clients. CC Switch speichert Anbieter in ~/.cc-switch/cc-switch.db. Wenn das lokale Routing einen Client übernimmt, schreibt es nur die lokale Routing-Adresse in ~/.claude/settings.json und trägt im Authentifizierungseintrag einen Platzhalter ein. Der echte Schlüssel wird beim Weiterleiten von der Route eingefügt. Das ist eine Eigenschaft von CC Switch, nicht von Kunavo. Sie sollten es wissen, weil der eingefügte Schlüssel nicht dem Schlüssel entspricht, der in der Datei steht, die Sie möglicherweise gerade committen wollen.