# CC Switch Einrichtung

> **Zuletzt überprüft**: 2026-09-18 · 📄 Gemäß offizieller Dokumentation (CC Switch v3.20.3, veröffentlicht 2026-09-11)

## Auf einen Blick

| Eintrag | Details |
|---|---|
| Verfügbare Modelle | hängen vom verwalteten CLI selbst ab: Claude Code (Claude ✅), Codex (GPT ✅), OpenCode / [OpenClaw](/docs/ide/openclaw) / [Hermes Agent](/docs/ide/hermes-agent) — CC Switch ist kein Inferenz-Endpunkt; es schreibt nur die Konfigurationsdateien des jeweiligen CLIs |
| Protokoll & Base URL | je verwaltetes Ziel: Claude-Teil `https://api.qcode.cc/api` · Codex-Teil `https://api.qcode.cc/openai` |
| Konfigurationsoberfläche | in der App; landet in `~/.claude/settings.json`, `~/.codex/config.toml` usw. |
| Offizielle Dokumentation | [GitHub-Repository](https://github.com/farion1231/cc-switch) · [Benutzerhandbuch](https://github.com/farion1231/cc-switch/tree/main/docs/user-manual) |

[CC Switch](https://github.com/farion1231/cc-switch) ist eine plattformübergreifende Desktop-Anwendung (Windows / macOS / Linux), die API-Anbieterkonfigurationen für **9 Tools** von einer UI aus verwaltet: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, MiniMax Code (Liste aus dem offiziellen README; 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“ — er schreibt jede Anbieterkonfiguration in die Standard-Konfigurationsdatei des jeweiligen CLIs, überschreibt beim Aktivieren und tauscht zurück, wenn Sie wechseln. Dieses Verständnis verhindert das Missverständnis, dass mehrere Anbieter gleichzeitig aktiv sind.

## Voraussetzungen

- [Claude Code CLI](/docs/getting-started/installation) oder Codex CLI installiert
- Ein QCode.cc API-Key (beginnt mit `cr_`), erhältlich im [Dashboard](https://qcode.cc/dashboard)
- Derselbe Key funktioniert über mehrere Protokoll-Endpunkte (Anthropic, OpenAI, Gemini usw.) — siehe [Endpunkte & API-Formate](/docs/getting-started/endpoints-and-api-paths)

## CC Switch installieren

Laden Sie den Installer für Ihre Plattform von [GitHub Releases](https://github.com/farion1231/cc-switch/releases) herunter:

| Plattform | Paket |
|----------|---------|
| Windows 10+ | `CC-Switch-v{ver}-Windows.msi` oder portable `.zip` |
| macOS 12+ | `.dmg`-Paket; oder `brew install --cask cc-switch` (Wortlaut aus dem offiziellen README) |
| Linux | `.deb` / `.rpm` / `.AppImage`; Arch: `paru -S cc-switch-bin` |

Die genauen Installationsschritte und Signierungsdialoge pro Plattform folgen dem [Projekt-README](https://github.com/farion1231/cc-switch).

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

CC Switch starten → im **oberen App-Umschalter** **Claude** 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):

| Feld | Wert |
|-------|-------|
| Provider Name | `QCode.cc` |
| ANTHROPIC_BASE_URL | `https://api.qcode.cc/api` |
| ANTHROPIC_AUTH_TOKEN | Ihr QCode.cc API-Key (beginnt mit `cr_`) |

> **Warum `asia.qcode.cc`?** Das ist QCode.cc's Asien-Knoten (nächster von Korea / Taiwan / Hongkong) mit der geringsten Latenz für Nutzer in Festlandchina; wechseln Sie zurück zu `api.qcode.cc` (globale Route 53), falls er instabil ist. 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:

| Modell | Am besten für |
|-------|----------|
| `claude-sonnet-5` | **Täglicher Standard**, aktuelle ausgewogene Kategorie |
| `claude-opus-5` | Aktuelles Flaggschiff; hartes Reasoning und große Refactorings |
| `claude-sonnet-4-6` | Vorherige Sonnet-Generation, weiterhin verfügbar |
| `claude-opus-4-8` | Vorheriges Flaggschiff, weiterhin verfügbar |
| `claude-haiku-4-5` | Schnelle Q&A, gebündelte kleine Aufgaben |

Raten und Kontextgrößen: Lesen Sie sie live auf [qcode.cc/models](https://qcode.cc/models) — diese Seite kopiert bewusst keine Zahlen mehr. Die vollständige Modellpalette (GPT, Gemini, 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** im App-Umschalter oben → **„+“ 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.

| Feld | Wert |
|-------|-------|
| Anbietername | `qcode` (Kleinschreibung empfohlen, wird als TOML-Schlüssel verwendet) |
| Basis-URL | `https://api.qcode.cc/openai` |
| API-Key | Ihr QCode.cc API-Key |
| Standardmodell | `gpt-6-sol` (empfohlen) oder `gpt-5.6-terra` (für Programmierung) |

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

```toml
model_provider = "qcode"
model = "gpt-6-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-sol` / `gpt-6-luna` / `gpt-5.6-terra` / `gpt-5.6-sol` (Preise und Kontext: [qcode.cc/models](https://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.

## 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` (Backup).
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](https://github.com/farion1231/cc-switch) besagt, dass Claude Code **aktuell Anbieterdaten hot-switchen kann**; die offizielle [FAQ](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/5-faq/5.2-questions.md) und [Issue #3057](https://github.com/farion1231/cc-switch/issues/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:

| Anbietername | Basis-URL | API-Key | Zweck |
|---------------|----------|---------|---------|
| `QCode.cc (work)` | `https://api.qcode.cc/api` | Arbeits-Key | Team- / Abrechnungskonto |
| `QCode.cc (personal)` | `https://api.qcode.cc/api` | Persönlicher Key | Persönliche Projekte |

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 GPT-5.x. Die aktuellen Fähigkeiten finden Sie unter [qcode.cc/models](https://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](/docs/usage/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](/docs/advanced/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:

```bash
# 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](/docs/advanced/headless).

## Zu Gemini / Antigravity

Die visuelle Liste von CC Switch enthält Gemini CLI, aber beachten Sie: **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). Um Modelle der Gemini-Familie über QCode zu nutzen, wechseln Sie zu Antigravity:

- CC Switch pflegt Gemini CLI weiterhin als vollwertige App; der Einstieg ist derselbe wie bei Claude / Codex
- Die Schritt-für-Schritt-Einrichtung von Gemini über QCode finden Sie auf der Seite [Google Antigravity CLI](/docs/ide/antigravity); die genauen Keys richten sich nach der [offiziellen Dokumentation](https://antigravity.google/docs)

Zu den weiterhin erhältlichen und hier häufig genannten Gemini-Modellen gehören `gemini-2.5-pro` und `gemini-3.5-flash`. Jeder Multiplikator und der genaue Preis stammen von [qcode.cc/models](https://qcode.cc/models) – übernehmen Sie kein mündlich genanntes „2x“, sofern diese Seite es zum jeweiligen Zeitpunkt nicht ausweist.

## Ausweich-Endpunkte

Wenn der primäre Endpunkt nicht erreichbar ist, wechseln Sie zu einem alternativen Endpunkt (derselbe Key funktioniert überall):

| Endpunkt | Claude Base URL | Codex Base URL |
|----------|-----------------|----------------|
| International | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai` |
| Asien (empfohlen für China) | `https://asia.qcode.cc/api` | `https://asia.qcode.cc/openai` |
| Nordamerika / Europa | `https://us.qcode.cc/api` | `https://us.qcode.cc/openai` |

> 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.

## Gemeinsames Kontingent

Die Anbieter Claude und Codex in CC Switch teilen sich denselben QCode.cc-API-Key und greifen auf dasselbe Abo-Kontingent zu (siehe [Abrechnung](/docs/reference/billing)). Wenn Sie zwei Anbieter hinzufügen, wird Ihnen nicht doppelt berechnet. Wenn Sie mehrere 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:

| Anbietername | Rolle |
|---------------|------|
| `QCode.cc` | Globale Domain, primär |
| `QCode.cc (asia)` | Asien-Knoten (nächstgelegener von Korea / Taiwan / Hongkong), wenn die Verbindung vom Festland schwankt |
| `QCode.cc (work)` / `QCode.cc (personal)` | Zwei verschiedene `cr_`-Keys, getrennte Abrechnung |

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](https://github.com/farion1231/cc-switch/issues/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**.
4. Laut FAQ wirken Wechsel über das Tray bei der Gemini CLI sofort. Die Gemini CLI selbst ist EOL (siehe oben) – übertragen Sie diesen Satz nicht auf Claude / Codex.

### Parallel zum offiziellen Anthropic- / ChatGPT-Login

Offizielle README / FAQ:

1. Fügen Sie eine **Official Login**-Vorlage (Claude / Codex) oder **Google Official** (Gemini) hinzu
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](https://github.com/farion1231/cc-switch/issues/2992), [#4274](https://github.com/farion1231/cc-switch/issues/4274); dazu [#1656](https://github.com/farion1231/cc-switch/issues/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. **Gemeinsames Konfigurations-Snippet** (README-FAQ „Plugins nach einem Wechsel verschwunden“): Anbieter bearbeiten → Bereich „Gemeinsame Konfiguration“ → „Aus aktuellem Anbieter extrahieren“; lassen Sie später bei neuen Anbietern das Kontrollkästchen zum Schreiben der gemeinsamen Konfiguration aktiviert (Standard; die README bezeichnet es uneinheitlich („Write Shared Config“ / „Apply shared config“)). Der beim ersten Start importierte Standardanbieter sollte noch den ursprünglichen vollständigen Satz enthalten
4. **Manuelle Änderungen bei Claude**: Wenn Sie nur `~/.claude/settings.json` bearbeitet und nie in die gemeinsame Konfiguration extrahiert haben, stellen Sie sie aus Ihrem eigenen Backup / Time Machine / dem lokalen Verlauf Ihres Editors wieder her und fügen Sie sie dann in die gemeinsame Konfiguration ein. Die nächste Aktivierung führt nichts auf magische Weise zusammen

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**: Wenn Sie `~/.claude/settings.json` manuell bearbeitet haben, werden Ihre Änderungen beim Aktivieren überschrieben — sichern Sie die Datei vorher oder extrahieren Sie Ihre Änderungen in das gemeinsame Konfigurations-Snippet.

## 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 upstream nicht dokumentiert; 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](/docs/reference/troubleshooting). 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](https://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](https://github.com/farion1231/cc-switch/issues/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?

Ja. Beim Aktivieren überschreibt CC Switch die entsprechenden Felder in `~/.claude/settings.json` mit den Werten des jeweiligen Anbieters. In manchen Builds wurde berichtet, dass die gesamte Datei ersetzt wird und `enabledPlugins` / `hooks` verloren gehen ([#2992](https://github.com/farion1231/cc-switch/issues/2992), [#4274](https://github.com/farion1231/cc-switch/issues/4274)). Legen Sie zusätzliche Inhalte im gemeinsamen Konfigurations-Snippet ab, erstellen Sie vor dem Aktivieren ein Backup und stellen Sie es aus `~/.cc-switch/backups/` oder einer exportierten `.sql` wieder her, falls Einträge verschwinden.

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

Fügen Sie das **Official Login**-Preset hinzu → Aktivieren → CLI erneut öffnen → offizielle Abmeldung / Anmeldung durchführen. Bauen Sie keine manuelle Hybrid-Konfiguration („leere env-Variablen, aber den cr_-Key behalten“) zusammen.

## Nächste Schritte

- [WorkBuddy-Integration](/docs/ide/workbuddy) — Derselbe API-Key als Tencent WorkBuddy Custom Model
- [Claude-Code-Tutorial](/docs/getting-started/claude-code-tutorial) — Beherrschen Sie die Kern-Workflows mit Claude Code
- [Codex-Tutorial](/docs/ide/codex) — Vertiefen Sie Ihre Arbeit mit Codex CLI
- [VS-Code-Integration](/docs/ide/vscode) — Claude Code direkt im Editor nutzen
- [Subagents](/docs/advanced/subagents) — Hintergrund-Agenten mit dynamischen Workflows orchestrieren
- [Automatisierung & CI/CD](/docs/advanced/headless) — Headless-Modus und Skript-Integration
- [Abrechnung](/docs/reference/billing) — Tarife und Kontingente verstehen

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