CC Switch Einrichtung

CC Switch auf QCode.cc für Claude Code und Codex CLI zeigen: Formulare, Multi-Tarif-Wechsel, Koexistenz mit offiziellem Login, Schalter, die nicht greifen, und Wiederherstellung einer überschriebenen Konfiguration

Brauchen Sie einen API-Key? Registrieren →·Endpunkte & Base-URLs →

Zuletzt überprüft: 2026-10-15 · 📄 Gemäß offizieller Dokumentation (CC Switch v4.0.12, veröffentlicht 2026-10-14; Abschnitte zu Download und CLI am 2026-10-15 mit README und Releases abgeglichen)

Auf einen Blick¶

CC Switch ist eine plattformübergreifende Desktop-Anwendung (Windows / macOS / Linux), die API-Anbieterkonfigurationen für 10 Tools von einer UI aus verwaltet: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code (Liste aus dem offiziellen README, Stand 2026-10-15; die Screenshots im Handbuch hinken leicht hinterher). Dieses Handbuch zeigt, wie Sie QCode.cc als benutzerdefinierten Anbieter in CC Switch hinzufügen, wie Sie mit einem Klick zwischen mehreren Anbietern/Konten wechseln, und behandelt häufige Anwendungsfälle sowie Fehlerbehebung.

Warum CC Switch verwenden¶

• Kein manuelles Bearbeiten von Konfigurationsdateien: Visuelle Formulare ersetzen settings.json / config.toml
• Ein-Klick-Anbieterwechsel: Wechseln Sie sofort zwischen qcode.cc, dem offiziellen Anthropic-Anbieter und lokalen Proxys
• Claude + Codex Ökosystem: Verwalten Sie sowohl Claude Code als auch Codex CLI Konfigurationen in einer einzigen App
• Multi-Konto / Multi-Tarif-Verwaltung: Speichern Sie mehrere Konfigurationen für denselben Anbieter (z. B. einen Arbeits-API-Key und einen persönlichen API-Key) und wechseln Sie jederzeit
• System-Tray-Shortcuts: Wechseln Sie Anbieter über das Tray-Menü, ohne das Hauptfenster zu öffnen

Im Kern ist CC Switch ein „Konfigurationsprofil-Umschalter“: Jeder Anbieter ist ein Profil, und beim Wechsel werden in der Konfigurationsdatei des Ziel-CLIs nur die Schlüsselfelder ersetzt (Endpunkt, Key, Modellname, Protokoll usw.); alles andere bleibt erhalten (offizielles README). Es ist immer nur ein Anbieter aktiv – so vermeiden Sie das Missverständnis, mehrere Anbieter wirkten gleichzeitig.

Voraussetzungen¶

• Claude Code CLI oder Codex CLI installiert
• Ein QCode.cc API-Key (beginnt mit cr_), erhältlich im Dashboard
• Derselbe Key funktioniert über mehrere Protokoll-Endpunkte (Anthropic, OpenAI usw.) — siehe Endpunkte & API-Formate

Website, Download und Installation je Betriebssystem¶

Stand 2026-10-15 nennt das offizielle CC-Switch-README ccswitch.io als einzige offizielle Website. Quellcode und Installationspakete liegen im GitHub-Repository, auf der Seite Releases; die neueste Version ist v4.0.12 (veröffentlicht am 2026-10-14). Laden Sie nur von diesen beiden Stellen herunter.

Systemvoraussetzungen (offizielles README):

• Windows: Windows 10 und neuer
• macOS: macOS 12 (Monterey) und neuer
• Linux: x86_64 oder ARM64 mit glibc 2.35+ und WebKitGTK 4.1, z. B. Ubuntu 22.04+, Debian 12+, aktuelles Fedora; RHEL / Rocky / Alma 8–9 werden noch nicht unterstützt

In den Dateinamen unten steht {version} für die neueste Version auf der Releases-Seite (z. B. 4.0.12):

Flatpak gehört nicht zu den offiziellen Releases; laut README lässt es sich aus der .deb selbst bauen (siehe flatpak/README.md im Repository). Danach geht es unten mit „Claude-Anbieter konfigurieren“ weiter.

Kommandozeile (CLI): offiziell keine, aber ein Community-CLI für CC Switch¶

Stand 2026-10-15 gibt es von CC Switch selbst keine offizielle Kommandozeilenversion. Die offizielle FAQ hält fest, dass CC Switch nur als Desktop-App mit grafischer Oberfläche erscheint. Für Server, SSH-Sitzungen und Rechner ohne Desktop empfiehlt das offizielle README das von der Community gepflegte CC Switch CLI — ein CLI-Fork von CC Switch, den ein anderer Autor eigenständig veröffentlicht; es ist kein offizielles CC-Switch-Produkt. Diese Seite hat seine Funktionen nicht einzeln getestet; lesen Sie vor dem Einsatz sein README.

Installation (laut README dieses Projekts; die neueste Version am 2026-10-15 ist v5.11.1):

# macOS / Linux: Homebrew
brew install cc-switch-cli

# oder das Installationsskript (installiert nach ~/.local/bin; lesen Sie das Skript vorher)
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

Unter Windows laden Sie von der Releases-Seite cc-switch-cli-windows-x64.zip herunter, entpacken es und legen cc-switch.exe in ein Verzeichnis im PATH.

Grundlegende Nutzung:

cc-switch                             # Vollbild-Terminaloberfläche (TUI)
cc-switch provider list               # Anbieter auflisten
cc-switch provider add                # Anbieter hinzufügen (Feldwerte: siehe die Abschnitte zu Claude / Codex unten)
cc-switch provider switch <id>        # Anbieter wechseln
cc-switch use <id>                    # Kurzform der vorigen Zeile
cc-switch --app codex provider list   # --app wählt das Tool; Standard ist claude
cc-switch start claude <id>           # Claude nur für diesen Start mit diesem Anbieter starten, ohne die globale Einstellung zu ändern

--app akzeptiert claude (Standard), codex sowie opencode, hermes, openclaw, pi und weitere. Dieses CLI teilt sich standardmäßig das Datenverzeichnis ~/.cc-switch mit der Desktop-App; die von ihm unterstützte Datenbankversion hinkt der Desktop-App manchmal hinterher — bei „database version is too new“ aktualisieren Sie das CLI oder warten, bis es nachzieht.

Wenn Sie auch das CLI nicht installieren möchten, können Sie die Konfigurationsdateien von Hand bearbeiten: für Claude Code siehe das vollständige Claude-Code-Tutorial, für Codex das vollständige Codex-Tutorial; Base URL und Key sind dieselben wie auf dieser Seite.

Claude-Anbieter konfigurieren (für Claude Code)¶

CC Switch starten → in der Seitenleiste Claude Code wählen → oben rechts auf „+“ (Anbieter hinzufügen) klicken → im anbieterspezifischen Tab im Preset-Dropdown Benutzerdefiniert wählen → die Konfigurations-JSON im Panel bearbeiten (UI-Formulierungen ändern sich zwischen Versionen; richten Sie sich nach dem, was Ihr Build anzeigt):

Warum asia.qcode.cc? Das ist der Asien-Endpunkt von QCode.cc und passt für Nutzer in Festlandchina; ist er schlecht erreichbar, verwenden Sie api.qcode.cc. Derselbe Key funktioniert über alle drei Domains: api / asia / us.

Nach dem Speichern klicken Sie auf der Karte auf Aktivieren (die Aktionsbuttons der Karte erscheinen beim Überfahren mit der Maus), um ihn zum aktuellen Claude-Anbieter zu machen. CC Switch schreibt ANTHROPIC_BASE_URL und ANTHROPIC_AUTH_TOKEN automatisch in ~/.claude/settings.json. Führen Sie claude in Ihrem Terminal aus, um die Verbindung zu überprüfen.

Standardmodell auswählen¶

QCode.cc bietet eine vollständige Reihe von Flaggschiff- bis Leichtgewichtsmodellen. Wechseln Sie in Claude Code mit /model, oder geben Sie es direkt in der Konfiguration an:

Raten und Kontextgrößen: Lesen Sie sie live auf qcode.cc/models — diese Seite kopiert bewusst keine Zahlen mehr. Die vollständige Modellpalette (GPT und China-Familienmodelle) finden Sie auf derselben Seite. Seit v3.20.3 bietet der Claude-Anbieter-Editor zusätzlich ein Rollen-zu-Modell-Mapping-Panel (Sonnet / Opus / Fable / Haiku / Subagent) mit einem Ein-Klick-Button zur Anwendung auf alle Rollen.

Codex-Anbieter konfigurieren (für Codex CLI)¶

Wählen Sie Codex in der Seitenleiste → „+“ Anbieter hinzufügen → Benutzerdefiniert → wie folgt ausfüllen:

⚠️ Im Codex-Anbietereditor gibt es einen Schalter „Needs Local Routing“ für Anbieter, die nur Chat Completions unterstützen. Lassen Sie ihn bei QCode deaktiviert — QCode bedient das Responses-Protokoll nativ, und eine Aktivierung würde einen dauerhaft laufenden lokalen Proxy erfordern.

CC Switch erzeugt die entsprechende ~/.codex/config.toml und ~/.codex/auth.json:

model_provider = "qcode"
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true

Speichern Sie, klicken Sie auf Aktivieren und führen Sie codex aus, um die Verbindung zu überprüfen. GPT-Modell-Optionen: gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra (Preise und Kontext: qcode.cc/models). Lesen Sie die Codex-CLI-Version über codex --version auf Ihrem System ab; verlassen Sie sich nicht auf einen historischen Wert auf dieser Seite.

Codex-Desktop-App (Codex app)¶

Fazit: Die Codex-Desktop-App liest dieselbe ~/.codex/config.toml, die CC Switch schreibt. Wenn Sie QCode wie oben als Codex-Anbieter eingerichtet haben, nutzen Desktop-App und Kommandozeilenversion also dieselbe Konfiguration. (Anmeldung und Authentifizierung in der Desktop-App wurden auf dieser Seite nicht getestet.) Grundlage:

1. Die offizielle OpenAI-Dokumentation (Use API/provider credentials through a gateway) hält fest: Die macOS-App liest dieselbe ~/.codex/config.toml, und nach dem Speichern der Anbietereinstellungen wird die App neu gestartet; unter Windows lautet die Datei %USERPROFILE%\.codex\config.toml, auch dort ist ein Neustart der App nötig.
2. Das offizielle CC-Switch-README verlangt, die Codex-Desktop-App vollständig zu beenden und neu zu öffnen (unter macOS ⌘Q; das Fenster zu schließen genügt nicht). Dieser Satz steht im Abschnitt zum Aggregationsmodus über das Aktualisieren der Modellliste; auch beim Wechsel eines gewöhnlichen Anbieters ist es sinnvoll, die App vollständig zu beenden und neu zu öffnen.

So lassen Sie die Desktop-App über QCode laufen:

1. Fügen Sie im Tab Codex von CC Switch den QCode-Anbieter wie im vorigen Abschnitt hinzu und aktivieren Sie ihn („Enable“; Base URL https://api.qcode.cc/openai, wire_api = "responses").
2. Beenden Sie die Codex-Desktop-App vollständig und öffnen Sie sie erneut.
3. Prüfen Sie in der App, dass das gewählte Modell ein bei QCode verfügbares GPT-Modell ist (z. B. gpt-6.1-sol). Auch die OpenAI-Dokumentation empfiehlt, in der Desktop-App das gewählte Modell und die Konfiguration zu prüfen.

Zwei Hinweise:

• Die OpenAI-Dokumentation warnt, dass eine im Terminal gesetzte Umgebungsvariable für eine vom Desktop gestartete App möglicherweise nicht verfügbar ist. Wenn Sie CC Switch nicht nutzen, sondern die config.toml selbst schreiben und den Key per Umgebungsvariable übergeben, stellen Sie sicher, dass der App-Prozess diese Variable sieht.
• Stand 2026-10-15 nennt die OpenAI-Dokumentation die Desktop-App „ChatGPT desktop app“; in der App wählen Sie ChatGPT oder Codex. Die Builds für macOS und Windows gibt es unter chatgpt.com/download, für Linux eine eigene offizielle Installationsanleitung. Wie sich in der Desktop-App die Anmeldung mit einem ChatGPT-Konto und ein benutzerdefinierter Anbieter vertragen, beschreiben diese offiziellen Seiten nicht; diese Seite trifft dazu keine Aussage.

Zwischen mehreren Anbietern/Konten wechseln¶

Der Kernnutzen von CC Switch ist das Wechseln. Ein häufiges Setup:

1. Speichern Sie unter dem Claude-Tab mehrere Anbieter, z. B. QCode.cc (primär), QCode.cc (asia) (Festlandsknoten), Anthropic Official (zum Vergleich).
2. Zum Wechseln klicken Sie auf Aktivieren auf der Karte des Zielanbieters — CC Switch schreibt den entsprechenden ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN in ~/.claude/settings.json.
3. Die neue Konfiguration wirksam machen: Die offizielle README besagt, dass Claude Code aktuell Anbieterdaten hot-switchen kann; die offizielle FAQ und Issue #3057 dokumentieren den anderen Fall — settings.json auf der Festplatte ist bereits neu, aber die laufende Sitzung greift weiterhin den alten Anbieter. Falls die aktuelle Sitzung noch auf dem alten Knoten liegt, schließen Sie sie und öffnen Sie ein neues Terminal, bevor Sie claude erneut ausführen. Codex und andere CLIs: immer das Terminal neu öffnen (FAQ).
4. Codex funktioniert nach demselben Prinzip: Das Umschalten des aktiven Eintrags im Codex-Tab schreibt ~/.codex/config.toml neu.

Tray-Verknüpfung: CC Switch bleibt im System-Tray; seit v3.13.0 ist das Rechtsklick-Menü in pro-App-Untermenüs gruppiert (Claude / Codex / Gemini), jedes Untermenü ist mit dem aktuell aktivierten Anbieter und einer Nutzungszusammenfassung betitelt — klicken Sie einen Anbieternamen an, um zu wechseln. Das Tray-Umschalten schreibt dieselben Live-Dateien wie Aktivieren im Hauptfenster; Fallstricke stehen unter „Nach der Verbindung“ unten.

Mehrkonto-/Mehrtarif-Beispiel¶

Speichern Sie zwei Konfigurationen für dasselbe QCode.cc-Konto, jeweils mit einem anderen API-Key:

Beim Wechseln des aktiven Anbieters wechseln Sie nahtlos zwischen den beiden Kontingenten, ohne die Abrechnung zu vermischen.

Anwendungsfälle¶

• Instabiles Netzwerk in China: Verwenden Sie asia.qcode.cc als primären Anbieter und wechseln Sie per Klick auf den globalen api.qcode.cc, wenn es zu Schwankungen kommt.
• Anbieter vergleichen: Führen Sie dieselbe Aufgabe über QCode.cc und den offiziellen Anthropic-Anbieter aus, um Antworten und Kosten zu vergleichen.
• Team-/private Trennung: Verwenden Sie verschiedene Keys, um Team- und private Nutzung sauber zu trennen.
• Claude + Codex gemeinsam: Verwalten Sie Claude Code und Codex CLI in einer App, jeweils auf den Endpunkt mit Anthropic-Protokoll bzw. OpenAI-Protokoll ausgerichtet.

Erweiterte Claude-Code-Funktionen (funktionieren weiterhin über QCode)¶

CC Switch wechselt nur den Anbieter; die eigenen Fähigkeiten von Claude Code bleiben davon unberührt. Nach der Verbindung mit QCode funktionieren die folgenden Funktionen wie gewohnt (sie laufen auf dem Modell, mit dem Claude Code konfiguriert ist):

Bildeingabe: Anforderungen aus Screenshots / Diagrammen verstehen¶

Claude Code kann Bilder an Modelle mit Vision-Unterstützung übergeben: Fügen Sie ein Bild per Strg+V ein, ziehen Sie es per Drag-and-drop in das Fenster oder verweisen Sie in Ihrem Prompt auf einen Bilddateipfad. Typische Einsatzzwecke:

• Eine Oberfläche anhand eines Mockups / Screenshots aufbauen
• Fehler anhand eines Fehler-Screenshots debuggen
• Architekturdiagramme und Charts lesen

Zu den Modellen mit Vision-Unterstützung über QCode gehören claude-opus-5 / claude-sonnet-5 sowie die weiterhin erhältlichen Modelle claude-opus-4-8 / claude-sonnet-4-6 und die GPT-Familie (z. B. gpt-6.1-sol, gpt-5.6-terra). Die aktuellen Fähigkeiten finden Sie unter qcode.cc/models.

Hinweis: Hier geht es um Bild-Eingabe (Verstehen), nicht um Bild-Generierung. Wenn ein Modell Bilder erzeugen soll, verwenden Sie das Modell gpt-image-2 – siehe Bildgenerierung mit gpt-image-2.

Dynamische Workflows (Orchestrierung von Sub-Agenten im Hintergrund)¶

Nehmen Sie das Schlüsselwort ultracode in Ihren Prompt auf (oder bitten Sie einfach darum, einen „Workflow auszuführen“), um die dynamischen Workflows von Claude Code auszulösen: Dabei werden Dutzende bis Hunderte Sub-Agenten parallel im Hintergrund orchestriert – ideal für Reviews, Migrationen und Recherchen über die gesamte Codebasis. Die Agenten laufen im Hintergrund weiter, während Sie weiterarbeiten; Durchläufe sehen Sie mit dem Befehl /workflows. Diese Funktion läuft auf dem Modell, mit dem Claude Code konfiguriert ist – sie funktioniert also auch, wenn Claude Code auf QCode zeigt. Weiterführend: Subagents.

Headless-Modus / Ausgabe für die Automatisierung¶

Führen Sie in Skripten und CI einen einmaligen Lauf mit -p aus und geben Sie ein Ausgabeformat an:

# Structured JSON (incl. result / total_cost_usd / usage / session_id), parse with jq
claude -p "Summarize test coverage in this repo" --output-format json | jq '.result'

# Newline-delimited streaming JSON events, good for real-time pipes
claude -p "Review src/ for security risks" --output-format stream-json

Weitere Hinweise zu Pipes und CI finden Sie unter Automatisierung & CI/CD.

Zu Gemini / Antigravity¶

Die Liste von CC Switch enthält Gemini CLI, aber QCode bietet derzeit keine Gemini-Modelle an; Sie müssen in CC Switch für QCode also nichts unter Gemini einrichten. Nutzen Sie stattdessen Claude, GPT oder China-Familienmodelle; welche Modelle Sie aufrufen können, steht auf qcode.cc/models.

Zur Einordnung: Google hat Gemini CLI eingestellt (EOL 2026-06-18 für Pro-/Gratis-Tarife; kostenpflichtige Enterprise-Keys sind nicht betroffen), Nachfolger ist die Google Antigravity CLI (verfügbar seit 2026-05-19). CC Switch pflegt Gemini CLI weiterhin als vollwertige App mit demselben Einstieg wie bei Claude / Codex; das betrifft nur Ihr eigenes Google-Konto oder andere Quellen und hat mit QCode nichts zu tun.

Endpunkt passend zum Netzwerk wählen¶

Die drei Endpunkte funktionieren mit demselben Key. Wählen Sie den, der zu Ihrem Netzwerk passt; ist einer schlecht erreichbar, tragen Sie einen anderen als Base URL ein.

Selbsttest: Wenn Sie den Pfad einer Base URL direkt aufrufen, erhalten Sie 401 – das ist erwartet. Es bedeutet, dass der Pfad korrekt ist und nur die Authentifizierung fehlt.

Ein Key für Claude und Codex¶

Die Anbieter Claude und Codex in CC Switch können denselben QCode.cc-API-Key verwenden. QCode rechnet pro Token ab; die Preise je Modell stehen auf qcode.cc/models (Regeln unter Abrechnung). Wenn Sie zwei Anbieter hinzufügen, wird Ihnen nicht doppelt berechnet. Wenn Sie Anbieter mit unterschiedlichen Keys angelegt haben, wird jeder Key separat abgerechnet.

Nach der Verbindung: wechseln, parallel nutzen, wiederherstellen¶

Dieser Abschnitt behandelt den Verkehr nach der Einrichtung, den Suchanfragen zu „CC Switch“ tatsächlich bringen. Wie Sie das Formular ausfüllen, steht weiter oben; hier geht es darum, was passiert, nachdem es gelaufen ist.

Mehrere Tarife / mehrere Keys¶

Ein Anbieter = eine BASE_URL + Key + (bei Codex) Modell. Für dasselbe QCode-Konto können Sie mehrere Einträge anlegen, zum Beispiel:

Es ist immer nur ein Anbieter aktiv – CC Switch schreibt nicht zwei Konfigurationen gleichzeitig in ~/.claude/settings.json. Um das offizielle Anthropic und QCode zu vergleichen, klicken Sie abwechselnd auf Aktivieren. Erwarten Sie nicht, dass beide gleichzeitig live sind.

Die CLI hat den neuen Anbieter nicht übernommen¶

Prüfen Sie in dieser Reihenfolge; geben Sie nicht zuerst dem Key die Schuld:

1. Öffnen Sie ~/.claude/settings.json (bzw. ~/.codex/config.toml für Codex) und vergewissern Sie sich, dass ANTHROPIC_BASE_URL / base_url dem soeben aktivierten Eintrag entspricht.
2. Datei geändert, Sitzung nicht: Dieses Verhalten beschreibt Issue #3057 – Claude Code kopiert den env-Block aus settings.json beim Prozessstart. Eine laufende Sitzung liest ihn nicht neu ein. Schließen Sie das aktuelle claude / codex und öffnen Sie ein neues Terminal.
3. Die offizielle README besagt, dass Claude Code inzwischen per Hot-Switch wechselt. Falls Ihr Build das unterstützt, können Sie den Neustart überspringen; wenn weiterhin der alte Knoten angesprochen wird, öffnen Sie die Sitzung neu.

Parallel zum offiziellen Anthropic- / ChatGPT-Login¶

Offizielle README / FAQ:

1. Wechseln Sie zum eingebauten offiziellen Anbieter in der Liste (Claude Official / OpenAI Official; falls gelöscht, aus den Vorlagen wieder hinzufügen)
2. Klicken Sie auf Aktivieren
3. Öffnen Sie die zugehörige CLI neu und führen Sie deren eigenes Abmelden / Anmelden (bzw. OAuth) durch
4. Danach können Sie zwischen dem offiziellen Login und dem benutzerdefinierten Anbieter QCode.cc hin- und herwechseln

Führen Sie offizielles OAuth und ein QCode-ANTHROPIC_AUTH_TOKEN nicht manuell in settings.json zusammen – beim Aktivieren überschreibt CC Switch die Felder, die es selbst verwaltet. Der Wechsel zwischen mehreren offiziellen Codex-Konten folgt der README: Codex kann zwischen verschiedenen offiziellen Anbietern wechseln.

Stolperfallen beim Wechsel über das Tray¶

• Fehlendes Symbol: macOS – Einstellungen der Menüleiste; Windows – Überlaufbereich der Taskleiste; unter Linux kann libappindicator nötig sein (offizielle FAQ)
• Lightweight Mode (Tray-Menü): Das Hauptfenster wird zerstört (nicht ausgeblendet), nur das Tray bleibt; der Modus wird nicht gespeichert – ein normaler Start führt zurück in den regulären Modus; der erste ccswitch://-Deep-Link baut das Fenster neu auf und ist etwas langsamer (offizielle FAQ, seit v3.13.0)
• Tray-Klick, CLI unverändert: Das Tray schreibt dieselben Live-Dateien wie Aktivieren. Es beendet ein laufendes claude nicht. Öffnen Sie die Sitzung wie oben beschrieben neu
• Suffixe wie (asia) / (work) halten das Tray-Menü übersichtlich

Die Konfiguration wurde überschrieben – so holen Sie sie zurück¶

Beim Aktivieren / Übernehmen schreibt CC Switch Anbieterfelder in die Live-Dateien der CLI. Mehrere Issues (#2992, #4274; dazu #1656, ein Feature-Wunsch für Merge-Schreibverhalten) melden ein vollständiges Überschreiben der Datei, bei dem Schlüssel verloren gingen, die CC Switch nicht gehören (enabledPlugins, hooks, statusLine, permissions, …). Plugin-Dateien bleiben oft auf der Festplatte; sie werden nur nicht mehr geladen, weil enabledPlugins fehlt.

Wiederherstellungswege, die Sie nachprüfen können (offizielle README / Benutzerhandbuch, keine Drittanbieter-Beschwörung):

1. App-Backups: ~/.cc-switch/backups/ (rotierend; laut offiziellem Text: die letzten 10)
2. Ein von Ihnen erstellter Export: Der Einstellungsexport heißt z. B. cc-switch-export-{timestamp}.sql; ein Import überschreibt die aktuelle DB – exportieren Sie vor dem Import erneut
3. Das „Gemeinsame Konfigurations-Snippet“ gibt es nicht mehr: Seit v4.0 ist die Funktion entfallen (offizielles README: die zugehörigen Schaltflächen wurden entfernt). Beim Wechsel werden nur die Schlüsselfelder ersetzt – Endpunkt, Key, Modellname, Protokoll –, alles andere bleibt; Einstellungen, die vor dem Upgrade im Snippet standen, wurden beim Wechsel bereits in die Konfigurationsdatei geschrieben und bleiben deshalb erhalten. Bevor CC Switch die Konfigurationsdatei eines Tools zum ersten Mal neu schreibt, sichert es die Originaldatei nach ~/.cc-switch/backups/live-first-write/
4. Manuelle Änderungen bei Claude: Seit v4.0 gehen sie beim Wechsel in der Regel nicht verloren; wenn Sie eine ältere Version nutzen und nur ~/.claude/settings.json bearbeitet haben, stellen Sie die Datei aus Ihrem eigenen Backup / Time Machine / dem lokalen Verlauf des Editors wieder her

Die eigene DB von CC Switch ist ~/.cc-switch/cc-switch.db; die Geräte-UI-Einstellungen liegen in ~/.cc-switch/settings.json. Das Löschen der Letzteren setzt nur die UI zurück; Claude-Hooks stellt es nicht wieder her.

Praktische Tipps¶

• Namen mit Suffixen: Fügen Sie Anbieter-Namen Suffixe wie (asia) / (work) hinzu, damit der Wechsel über die Taskleiste auf einen Blick eindeutig ist.
• Datei prüfen, dann neue Sitzung öffnen: Verlassen Sie sich auf ~/.claude/settings.json / ~/.codex/config.toml; ein laufender Prozess lädt die Konfiguration nicht heiß neu (FAQ / #3057).
• Kein Schrägstrich am Ende: QCode erfordert Base-URLs ohne / am Ende (anderenfalls bauen SDKs fehlerhafte Pfade im Stil //v1/...).
• Keys getrennt halten: CC Switch speichert API-Keys pro Anbieter unabhängig voneinander; vergessen Sie nicht, jeden einzelnen beim Austausch der Keys zu aktualisieren.
• Konfiguration sichern: Seit v4.0 werden beim Wechsel nur die Schlüsselfelder ersetzt, Ihre eigenen Ergänzungen bleiben in der Regel erhalten; bei älteren Versionen sichern Sie vorher besser.

FAQ¶

Die Schaltfläche „Enable“ lässt sich nach dem Speichern nicht anklicken¶

Prüfen Sie der Reihe nach: ① Das Endpoint-Feld ist nicht leer; ② Das JSON / TOML im Panel ist syntaktisch gültig (manuelle Bearbeitungen sind die häufigste Ursache für Fehler); ③ Entfernen Sie einen / am Ende der Base-URL (QCode-Endpoints erfordern keinen. CC Switchs eigene Behandlung von Schrägstrichen am Ende ist in der CC-Switch-Dokumentation nicht beschrieben; diese Reihenfolge basiert auf unseren Erfahrungen).

Jede Claude-Code-Anfrage liefert 400 bei 2.1.265–2.1.267 (Artifact-Schema)¶

Claude Code 2.1.265–2.1.267 wurde mit einem Artifact-Tool-Schema ausgeliefert, das strenge Gateways direkt ablehnen (400, Invalid schema for function 'Artifact'). Seit CC Switch 3.20.3 (2026-09-11) bietet der Claude-Anbieter-Editor einen Schnellumschalter „Disable Artifact Tool“, der env.CLAUDE_CODE_DISABLE_ARTIFACT="1" schreibt. Der offizielle Fix für Claude Code ist das Upgrade auf ≥2.1.268; siehe Fehlerbehebung. Wir haben die jeweiligen Wechselwirkungen auf QCode-Seite nicht im Detail nachgestellt — falls Sie davon betroffen sind, eröffnen Sie ein Ticket mit der Request-ID.

401-Unauthorized-Fehler¶

1. Stellen Sie sicher, dass der API-Key mit cr_ beginnt und keine führenden oder nachgestellten Leerzeichen enthält
2. Prüfen Sie unter qcode.cc/dashboard, ob der Key gültig ist
3. Wenn Claude 401 zurückgibt, Codex aber funktioniert (oder umgekehrt), wurde der Key bei einem der Anbieter falsch eingegeben — CC Switch speichert API-Keys pro Anbieter unabhängig voneinander

Anbieterwechsel hat keine Wirkung gezeigt¶

Prüfen Sie zunächst, ob die aktive Datei bereits den neuen Anbieter anzeigt. Wenn die Datei geändert wurde, schließen Sie die aktuelle claude- / codex-Sitzung und öffnen Sie eine neue (offizielle FAQ; #3057). Klicken Sie nicht nur auf das Tray-Symbol und tippen Sie im alten Fenster weiter.

Codex hängt beim Start endlos¶

Stellen Sie sicher, dass base_url der QCode-Endpoint-Konvention folgt und auf /openai endet (nicht /openai/v1). wire_api = "responses" muss beibehalten werden. Häufigster Fehler: Das top-level model_provider fehlt oder stimmt nicht mit dem [model_providers.xxx]-Tabellennamen überein — Codex fällt dann stillschweigend auf den eingebauten OpenAI-Endpoint zurück (offizielles Issue #7263 dokumentiert das Symptom).

Kann ich Claude und Codex gleichzeitig nutzen?¶

Ja. CC Switch schreibt die Claude-Konfiguration nach ~/.claude/ und die Codex-Konfiguration nach ~/.codex/. Beide Konfigurationen sind vollständig unabhängig. Führen Sie claude und codex bei Bedarf in separaten Terminals aus.

Ich habe settings.json manuell bearbeitet — geht das beim Aktivieren verloren?¶

Seit v4.0 in der Regel nicht: Beim Wechsel werden nur die Schlüsselfelder ersetzt (Endpunkt, Key, Modellname, Protokoll usw.); Plugins, Hooks, Berechtigungen und von Ihnen ergänzte Umgebungsvariablen bleiben erhalten (FAQ des offiziellen README). Bei Versionen vor v4.0 gab es Berichte, dass die ganze Datei ersetzt wurde und enabledPlugins / hooks verloren gingen (#2992, #4274); sichern Sie bei älteren Versionen vorher und stellen Sie verlorene Einträge aus ~/.cc-switch/backups/ (inklusive live-first-write/) oder einer exportierten .sql wieder her.

Wie wechsle ich zurück zur offiziellen Anthropic-Anmeldung?¶

Wechseln Sie zum eingebauten offiziellen Anbieter (Claude Official / OpenAI Official; falls gelöscht, aus den Vorlagen wieder hinzufügen) → Aktivieren → CLI erneut öffnen → offizielle Abmeldung / Anmeldung durchführen. Bauen Sie keine manuelle Hybrid-Konfiguration („leere env-Variablen, aber den cr_-Key behalten“) zusammen.

Aggregationsmodus in v4.0 und ccswitch://-Import in v4.0.10 (2026-10)¶

CC Switch hat v4.0.0 am 2026-10-04 und v4.0.10 am 2026-10-12 veröffentlicht (Datum den beiden Release-Seiten entnommen: v4.0.0 und v4.0.10). Alle Zitate unten stehen wörtlich so in den englischen Release-Notes-Dateien im Repository: docs/release-notes/v4.0.0-en.md und docs/release-notes/v4.0.10-en.md; die beiden Release-Seiten oben dienen nur den Datumsangaben, dort steht die chinesische Fassung. Wir haben nichts davon selbst nachgestellt und keinen einzigen Import-Link ausgeführt.

Aggregationsmodus (v4.0.0)¶

The new Aggregation mode puts models from several providers into one Claude Code or Codex model picker, so you can switch between them right inside the client

add a few providers, and their models all show up together in the Claude Code or Codex model picker

Whichever model you pick, the request goes straight to that provider, without ever leaving the client.

Sie können also mehrere Modell-Dienste hinzufügen, deren Modelle erscheinen gemeinsam in einer Modellauswahl, und die Anfrage geht an den Dienst des gewählten Modells — ohne den Client zu verlassen. Dieselben Notes halten fest, dass Sie den Modus selbst einschalten, dass er derzeit nur Claude Code und Codex unterstützt, dass er pro gewähltem Modell verteilt und dass es kein Failover gibt:

Aggregation is opt-in and currently supports Claude Code and Codex. It routes each request by the model you pick, and does not offer failover.

Zur Oberfläche beschreiben die Notes drei Reiter oben auf jeder App-Seite — Direct / Routing / Aggregation — und betonen, dass ein Klick auf einen Reiter nur die Ansicht ändert und Ihre Konfiguration anfasst; auf der Karte sind es Add und Remove, dazu die Wahl eines Dienstes als Standard für Anfragen, die kein aggregiertes Modell nennen:

Every app page has three tabs at the top: Direct / Routing / Aggregation. Clicking a tab only changes what you're looking at and never touches your config

Click "Add" or "Remove" on a provider card, then choose one provider as the default to handle requests that don't name an aggregated model

Für die Bezahlung pro Token sind zwei Punkte wesentlich. Erstens warnen die Notes: ein Modellwechsel mitten in der Sitzung ist möglich, aber jedes neue Modell muss seinen Prompt-Cache neu aufbauen, wodurch die erste Runde nach dem Wechsel spürbar teurer ausfällt (wörtlich: You can change to another model partway through a session. Note that after each switch, the new model has to build its prompt cache again, so the first turn after switching costs noticeably more). Die Preise je Modell bei QCode stehen auf https://qcode.cc/models. Zweitens: Ändert sich die Modellauswahl, werden Sie zum Neustart des Clients aufgefordert, und bei Codex CLI lässt sich der Hintergrunddienst per Klick im Banner neu starten.

When the model list changes you're prompted to restart the client, and Codex CLI users can restart the background service from the banner in one click

v4.0.0 hat auch das Schreiben der Einstellungen geändert — relevant, wenn Sie die Dateien von Hand pflegen:

switching providers now replaces only the key fields instead of rewriting the whole file

ccswitch://-Deep-Link-Import (v4.0.10)¶

Die Notes zu v4.0.10 bezeichnen sich als sechster Fix-Release der 4.0-Linie, im Kern geht es um Ein-Klick-Import-Links:

The sixth fix release for 4.0 stable

This release focuses on one-click import links (ccswitch:// deep links)

Gefixt wurde das Verhalten, wenn man so einen Link anklickt, während die App nicht läuft. Die Notes listen das einzeln:

On Windows and Linux, clicking a one-click import link while CC Switch was not open used to start the app, but the import confirmation dialog did not appear

in lightweight mode the link was also lost when the window was recreated

On macOS the same link brought up the confirmation dialog twice

Links are now stored first and only count as handled once the confirmation dialog has been shown, so they are not lost if something interrupts along the way, and an older link arriving later does not overwrite a newer one.

Im Bestätigungsdialog wählen Sie jetzt zusätzlich, ob direkt nach dem Import umgeschaltet wird. Die Notes sagen, dass dieser Schalter standardmäßig aus ist und dass der Dialog bei eingeschaltetem Schalter darauf hinweist, dass Client-Anfragen an die im Link stehende Adresse gehen (wörtlich: The confirmation dialog lets you choose whether to switch right after import und off by default; when it is on, the dialog warns that client requests will be sent to the address in the link).

Zu den API-Formaten steht in den Notes:

Non-native formats for Claude Code, Codex and Grok Build need local routing to be on; combinations an app does not support are rejected when the link is parsed

Für Sie heißt das: Wenn Sie eine QCode-Adresse per Deep Link in Claude Code oder Codex importieren, prüfen Sie zuerst das im Link deklarierte API-Format (anthropic / openai_chat / openai_responses / gemini_native). Das lokale Routing müssen Sie nur dann vorab einschalten, wenn dieses Format für die betreffende App nicht nativ ist (zum Beispiel openai_chat in Claude Code); Kombinationen, die die App nicht unterstützt, scheitern schon beim Einlesen. Welche Adresse auf QCode-Seite gilt, steht unverändert in der Endpunkt-Tabelle oben und unter Endpunkte und API-Pfade: https://api.qcode.cc/api für Claude, https://api.qcode.cc/openai/v1 für GPT und chinesische Modelle; Claude darf nicht über die OpenAI-kompatible Adresse. Derselbe Release hat außerdem Betreiberhandreichungen auf Chinesisch, Englisch und Japanisch sowie einen Online-Link-Generator veröffentlicht (wörtlich: Site owner guides in Chinese, English and Japanese and an online link generator are also published); dessen Ausgaben zeigen wir hier nicht.

Nächste Schritte¶

• WorkBuddy-Integration — Derselbe API-Key als Tencent WorkBuddy Custom Model
• Claude-Code-Tutorial — Beherrschen Sie die Kern-Workflows mit Claude Code
• Codex-Tutorial — Vertiefen Sie Ihre Arbeit mit Codex CLI
• VS-Code-Integration — Claude Code direkt im Editor nutzen
• Subagents — Hintergrund-Agenten mit dynamischen Workflows orchestrieren
• Automatisierung & CI/CD — Headless-Modus und Skript-Integration
• Abrechnung — Tarife und Kontingente verstehen

Sie haben noch keinen QCode.cc API-Key? Besuchen Sie qcode.cc/pricing, um einen Tarif auszuwählen — ein einziger Key treibt sowohl Claude Code als auch Codex CLI innerhalb von CC Switch.

Enterprise →