mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-10-26 01:34:51 +08:00
docs: translate key-field switching docs to English, Japanese and German
Brings the README FAQ (English, Japanese, German) and the English and Japanese user manuals in line with the Chinese master text. - README FAQ: switching no longer touches plugins, hooks and other shared settings; a model changed in the client resets on switching back; routing keeps the direct provider and writes it back on exit; the device-local files; the restart note now covers Gemini CLI. - Manual: the config editor section replaces backfill; the add dialog follows the same rules; quick toggles are marked global or per provider; the keys each app's switch changes; config ownership, malformed files and the first-write backup; routing writes back the direct provider; the Codex login is restored when switching back to an official card; Gemini auth follows the provider type.
This commit is contained in:
Jason committed
1 parent
59b851969e
commit
aa99584851
21 files changed
+340
-140
No files matched your search
@@ -335,6 +335,7 @@ For detailed guides on every feature, check out the **[User Manual](docs/user-ma
|
||||
### Provider Management
|
||||
|
||||
- **90+ provider presets** — Pick a preset and enter your key to add a provider, or create a custom configuration
|
||||
- **Key fields only** — Switching replaces only the connection details such as the endpoint, key, and model; plugins, hooks, MCP, settings you added yourself, and comments stay as they are
|
||||
- **Projects** — Save Claude Code's or Codex's current provider, MCP, Skills, and prompt files as a project (for Claude Desktop, only the provider is saved), then switch the whole setup in one click from the project switcher at the top of the main page or from the tray; when you switch to another project, the current state is automatically saved back to the previous project
|
||||
- **OAuth Authentication Center (Beta)** — Sign in to multiple GitHub Copilot, ChatGPT, and xAI (Grok) accounts in "Settings → Auth" and use those subscriptions as providers in Claude Code, Claude Desktop, and Codex (everything except Codex's OpenAI Official requires local routing). Using a subscription outside the official client may violate the vendor's terms of service; assess the risk yourself
|
||||
- **Third-party providers for Claude Desktop** — Connect directly to Anthropic-compatible endpoints; for non-Claude models, choose "Model Mapping" to map tiers like Sonnet, Opus, and Haiku to the provider's actual models through local routing
|
||||
@@ -344,7 +345,7 @@ For detailed guides on every feature, check out the **[User Manual](docs/user-ma
|
||||
### Local Routing & Failover
|
||||
|
||||
- **API format conversion** — Local routing converts requests between Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini Native: Claude Code and Claude Desktop can use OpenAI- or Gemini-format providers, and Codex and Grok Build can use Chat Completions or Anthropic Messages providers
|
||||
- **Per-tool toggle** — Local routing can be turned on separately for Claude Code, Codex, Gemini CLI, and Grok Build; once it's on, switching providers takes effect immediately for subsequent requests (Codex and Grok Build may still need a restart if the switch changes the model)
|
||||
- **Per-tool toggle** — Local routing can be turned on separately for Claude Code, Codex, Gemini CLI, and Grok Build; once it's on, switching providers takes effect immediately for subsequent requests (Codex, Gemini CLI, and Grok Build may still need a restart if the switch changes the model)
|
||||
- **Auto-failover** — Configure a failover queue for each tool; when a request fails, CC Switch automatically moves on to the next provider in the queue, backed by a circuit breaker and provider health monitoring
|
||||
- **Rectifier** — Automatically fixes certain requests that some upstreams can't handle (e.g. Thinking signatures, or falling back when images aren't supported)
|
||||
- Official providers (e.g. Claude Official) can't go through local routing (except Codex's OpenAI Official)
|
||||
@@ -392,16 +393,29 @@ CC Switch supports ten tools: **Claude Code**, **Claude Desktop**, **Codex**, **
|
||||
It depends on the tool:
|
||||
|
||||
- **Claude Code**: supports hot-switching of provider data — no restart needed.
|
||||
- **Codex, Gemini CLI, Grok Build**: restart your terminal or the CLI tool for changes to take effect (CC Switch reminds you after switching Codex or Grok Build). With local routing on, requests go to the new provider immediately, but Codex and Grok Build may still need a restart if the switch changes the model.
|
||||
- **Codex, Gemini CLI, Grok Build**: restart your terminal or the CLI tool for changes to take effect (CC Switch reminds you after switching Codex or Grok Build). With local routing on, requests go to the new provider immediately, but all three tools may still need a restart if the switch changes the model.
|
||||
- **Claude Desktop**: fully quit and reopen Claude Desktop; when using "Model Mapping", also keep CC Switch running.
|
||||
- **OpenCode, OpenClaw, Hermes, Pi, MiniMax Code**: these are coexist-mode tools — clicking "Add" ("Enable" for Pi) writes the provider into the tool's own config alongside the others; you then pick the model you want inside the tool.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>My plugin configuration disappeared after switching providers — what happened?</strong></summary>
|
||||
<summary><strong>Will switching providers change my plugins, hooks, or other settings?</strong></summary>
|
||||
|
||||
CC Switch uses a "Common Config Snippet" (available for Claude Code, Codex, and Gemini CLI) to share settings other than the API key, endpoint, and model — such as plugins, hooks, and environment variables — across providers. Edit a provider → click "Edit Common Config" → "Extract from Editor" to save these shared parts into the snippet; when creating a new provider, keep "Apply Common Config" checked (enabled by default) and the snippet is merged into the new provider's config. For Claude Code and Codex providers with "Apply Common Config" checked, CC Switch automatically re-extracts the shared parts from the current config when you switch away, so plugins you install inside the tool carry over to the next provider. Your original configuration is preserved in the default provider imported the first time you ran the app.
|
||||
No. When you switch providers for Claude Code, Codex, Gemini CLI, or Grok Build, CC Switch replaces only the **key fields** in the config file: the endpoint, key, model name, and API protocol (plus the reasoning effort for Codex and the auth method for Gemini CLI), along with a few compatibility options that belong to the provider (such as Claude Code's "Disable Artifact Tool" and the context window). Plugins, hooks, permissions, MCP, environment variables you added yourself, comments, and formatting all stay as they are and apply to every provider.
|
||||
|
||||
You can change these shared settings in the tool itself or by editing the config file by hand. You can also edit any provider in CC Switch: the editor shows "what the config file will look like after switching to this provider". When you save, the key fields are stored in that provider, and every other change is written to the config file and applies to every provider.
|
||||
|
||||
So the old "Common Config Snippet" is no longer needed, and its buttons have been removed. Settings that were in your snippet before the upgrade were already written into the config file when you switched, so they stay. Before CC Switch rewrites each config file for the first time, it also backs up the original to `~/.cc-switch/backups/live-first-write/`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>I changed the model inside the tool — why does it go back after I switch away and back?</strong></summary>
|
||||
|
||||
The model is a key field and belongs to the provider. A model you pick inside the tool (such as with `/model` in Claude Code) stays in effect until the next switch; when you switch, the model in the config file is replaced with the one saved in the target provider, and CC Switch doesn't save the model you picked back to the previous provider. To keep using a model long-term, edit that provider in CC Switch.
|
||||
|
||||
Older versions saved the whole config file back to the provider when you switched away. That no longer happens: it froze plugins and other shared settings into one provider, so they were lost when you switched to another one.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -430,7 +444,9 @@ Note: official providers can't be selected while local routing is on — Codex's
|
||||
|
||||
With local routing on, the tool's requests first go to CC Switch's local routing (`http://127.0.0.1:15721` by default), and CC Switch then forwards them to the provider you selected. That's why the tool's config file only contains the local address and the placeholder key `PROXY_MANAGED`; for Claude Code, the model name is also written as a fixed alias such as `claude-sonnet-5` (the `/model` menu still shows the real model name). The real provider address, key, and model are all stored in CC Switch.
|
||||
|
||||
In "Settings → Usage Statistics → Request Logs" you can see "requested model → actual model" for each request. When you turn local routing off, the config file is restored to the current provider's real configuration.
|
||||
In "Settings → Usage Statistics → Request Logs" you can see "requested model → actual model" for each request.
|
||||
|
||||
While local routing is on, switching changes the provider that local routing uses; the provider you were using before you turned it on stays the same and is labeled "Direct" on its card. When you turn local routing off, the config file is written back to this direct provider's configuration. Quitting CC Switch also writes back the direct provider first, and local routing is reconnected the next time CC Switch starts.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -462,8 +478,10 @@ By default, everything is stored in the `.cc-switch` folder in your home directo
|
||||
- **Skill Backups**: `skill-backups/` (created automatically before uninstalling or updating a skill, keeping the 20 most recent)
|
||||
- **OAuth login credentials**: `copilot_auth.json`, `codex_oauth_auth.json`, `xai_oauth_auth.json`
|
||||
- **Logs**: `logs/cc-switch.log` and `crash.log` — please attach them when reporting an issue
|
||||
- **Device state**: `live-state.json` (whether each tool is connected directly or through local routing, and what was last written), `codex-login-stash.json` (the official Codex login moved aside when you switch to a third-party provider, restored when you switch back to an official one)
|
||||
- **Original config files**: `backups/live-first-write/` (each tool's config file as it was before CC Switch first rewrote it)
|
||||
|
||||
After you change "CC Switch Configuration Directory" in "Settings → Advanced → Configuration Directory", all of the files above except `settings.json` are stored in the new directory. CC Switch doesn't move existing files automatically, so copy them over manually first.
|
||||
After you change "CC Switch Configuration Directory" in "Settings → Advanced → Configuration Directory", all of the files above except `settings.json`, the device state, and the original config files are stored in the new directory. CC Switch doesn't move existing files automatically, so copy them over manually first. `settings.json`, the device state, and the original config files belong to this computer only: they always stay in the default directory and are not included in cloud sync.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
+24
-6
@@ -335,6 +335,7 @@ Ausführliche Anleitungen zu allen Funktionen finden Sie im **[Benutzerhandbuch]
|
||||
### Anbieterverwaltung
|
||||
|
||||
- **90+ Anbieter-Presets** — Preset auswählen und Schlüssel eintragen, um einen Anbieter hinzuzufügen; alternativ können Sie eine eigene Konfiguration erstellen
|
||||
- **Nur Kernfelder** — Beim Wechsel werden nur die Verbindungsdaten wie Endpunkt, Schlüssel und Modell ersetzt; Plugins, Hooks, MCP, selbst hinzugefügte Einstellungen und Kommentare bleiben unverändert
|
||||
- **Projekte** — Speichern Sie den aktuellen Anbieter sowie MCP, Skills und Prompt-Dateien von Claude Code oder Codex als Projekt (bei Claude Desktop nur den Anbieter) und wechseln Sie später über den Projektumschalter oben auf der Hauptseite oder über das System-Tray mit einem Klick die gesamte Konfiguration; beim Wechsel zu einem anderen Projekt wird der aktuelle Zustand automatisch im bisherigen Projekt gespeichert
|
||||
- **OAuth Authentication Center (Beta)** — Melden Sie sich unter „Settings → Auth“ bei mehreren GitHub-Copilot-, ChatGPT- und xAI-(Grok-)Konten an und nutzen Sie die Abonnements als Anbieter in Claude Code, Claude Desktop und Codex (außer bei OpenAI Official in Codex ist dafür jeweils das lokale Routing erforderlich). Die Nutzung von Abonnements außerhalb der offiziellen Clients kann gegen die Nutzungsbedingungen des Herstellers verstoßen — bitte schätzen Sie das Risiko selbst ein
|
||||
- **Claude Desktop mit Drittanbietern** — Direkte Verbindung zu Anthropic-kompatiblen Endpunkten möglich; für Nicht-Claude-Modelle wählen Sie „Model Mapping“, dann bildet das lokale Routing Stufen wie Sonnet, Opus und Haiku auf die tatsächlichen Modelle des Anbieters ab
|
||||
@@ -344,7 +345,7 @@ Ausführliche Anleitungen zu allen Funktionen finden Sie im **[Benutzerhandbuch]
|
||||
### Lokales Routing & Failover
|
||||
|
||||
- **Formatkonvertierung** — Das lokale Routing konvertiert Anfragen zwischen Anthropic Messages, OpenAI Chat Completions, OpenAI Responses und Gemini Native: Claude Code und Claude Desktop können Anbieter im OpenAI- oder Gemini-Format nutzen, Codex und Grok Build Anbieter im Chat-Completions- oder Anthropic-Messages-Format
|
||||
- **Pro Werkzeug aktivierbar** — Für Claude Code, Codex, Gemini CLI und Grok Build lässt sich das lokale Routing jeweils einzeln aktivieren; danach wirkt ein Anbieterwechsel sofort auf die folgenden Anfragen (ändert der Wechsel das Modell, kann bei Codex und Grok Build trotzdem ein Neustart nötig sein)
|
||||
- **Pro Werkzeug aktivierbar** — Für Claude Code, Codex, Gemini CLI und Grok Build lässt sich das lokale Routing jeweils einzeln aktivieren; danach wirkt ein Anbieterwechsel sofort auf die folgenden Anfragen (ändert der Wechsel das Modell, kann bei Codex, Gemini CLI und Grok Build trotzdem ein Neustart nötig sein)
|
||||
- **Automatisches Failover** — Konfigurieren Sie für jedes Werkzeug eine Failover-Warteschlange; schlägt eine Anfrage fehl, wird automatisch der nächste Anbieter in der Warteschlange verwendet — ergänzt durch Circuit Breaker und Anbieter-Health-Monitoring
|
||||
- **Request-Rectifier** — Korrigiert automatisch bestimmte Anfragen, die mit dem Upstream nicht kompatibel sind (z. B. Thinking-Signaturen, Herabstufung, wenn keine Bilder unterstützt werden)
|
||||
- Offizielle Anbieter (z. B. Claude Official) können nicht über das lokale Routing laufen (ausgenommen OpenAI Official von Codex)
|
||||
@@ -392,16 +393,29 @@ CC Switch unterstützt zehn Werkzeuge: **Claude Code**, **Claude Desktop**, **Co
|
||||
Das hängt vom Werkzeug ab:
|
||||
|
||||
- **Claude Code**: unterstützt Hot-Switching von Anbieterdaten — kein Neustart nötig.
|
||||
- **Codex, Gemini CLI, Grok Build**: Starten Sie Ihr Terminal oder das CLI-Werkzeug neu, damit die Änderungen wirksam werden (bei Codex und Grok Build erinnert CC Switch Sie nach dem Wechsel daran). Mit aktiviertem lokalem Routing gehen Anfragen sofort an den neuen Anbieter; ändert der Wechsel jedoch das Modell, kann bei Codex und Grok Build trotzdem ein Neustart nötig sein.
|
||||
- **Codex, Gemini CLI, Grok Build**: Starten Sie Ihr Terminal oder das CLI-Werkzeug neu, damit die Änderungen wirksam werden (bei Codex und Grok Build erinnert CC Switch Sie nach dem Wechsel daran). Mit aktiviertem lokalem Routing gehen Anfragen sofort an den neuen Anbieter; ändert der Wechsel jedoch das Modell, kann bei allen drei Werkzeugen trotzdem ein Neustart nötig sein.
|
||||
- **Claude Desktop**: Beenden Sie Claude Desktop vollständig und öffnen Sie es erneut; bei Verwendung von „Model Mapping“ muss CC Switch außerdem weiterlaufen.
|
||||
- **OpenCode, OpenClaw, Hermes, Pi, MiniMax Code**: Dies sind Werkzeuge im Parallelmodus — ein Klick auf „Add“ (bei Pi „Enable“) trägt den Anbieter zusätzlich zu den bereits vorhandenen in die eigene Konfiguration des Werkzeugs ein; das gewünschte Modell wählen Sie anschließend im Werkzeug aus.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Meine Plugin-Konfiguration ist nach einem Anbieterwechsel verschwunden — was ist passiert?</strong></summary>
|
||||
<summary><strong>Ändert ein Anbieterwechsel meine Plugins, Hooks oder andere Einstellungen?</strong></summary>
|
||||
|
||||
CC Switch nutzt ein „Common Config Snippet“ (verfügbar für Claude Code, Codex und Gemini CLI), um Einstellungen außer API-Schlüssel, Endpunkt und Modell — etwa Plugins, Hooks und Umgebungsvariablen — zwischen Anbietern zu teilen. Bearbeiten Sie einen Anbieter und klicken Sie auf „Edit Common Config“ → „Extract from Editor“, um diese gemeinsamen Teile im Snippet zu speichern; lassen Sie beim Anlegen eines neuen Anbieters „Apply Common Config“ aktiviert (Standardeinstellung), dann wird das Snippet in die Konfiguration des neuen Anbieters übernommen. Bei Claude-Code- und Codex-Anbietern mit aktiviertem „Apply Common Config“ extrahiert CC Switch die gemeinsamen Teile beim Wechsel zu einem anderen Anbieter automatisch erneut aus der aktuellen Konfiguration, sodass Plugins, die Sie im Werkzeug installieren, zum nächsten Anbieter mitgenommen werden. Ihre ursprüngliche Konfiguration bleibt im Standardanbieter erhalten, der beim ersten Start der App importiert wurde.
|
||||
Nein. Beim Anbieterwechsel für Claude Code, Codex, Gemini CLI oder Grok Build ersetzt CC Switch in der Konfigurationsdatei nur die **Kernfelder**: Endpunkt, Schlüssel, Modellname und API-Protokoll (bei Codex zusätzlich die Reasoning-Stufe, bei Gemini CLI die Authentifizierungsmethode) sowie einige Kompatibilitätsoptionen, die zum Anbieter gehören (etwa „Disable Artifact Tool“ bei Claude Code und das Kontextfenster). Plugins, Hooks, Berechtigungen, MCP, selbst hinzugefügte Umgebungsvariablen, Kommentare und Formatierung bleiben unverändert und gelten für alle Anbieter.
|
||||
|
||||
Diese gemeinsamen Einstellungen können Sie direkt im Werkzeug ändern oder die Konfigurationsdatei von Hand bearbeiten. Sie können auch einen beliebigen Anbieter in CC Switch bearbeiten: Der Editor zeigt, „wie die Konfigurationsdatei nach dem Wechsel zu diesem Anbieter aussieht“. Beim Speichern werden die Kernfelder in diesem Anbieter gespeichert; alle anderen Änderungen werden in die Konfigurationsdatei geschrieben und gelten für alle Anbieter.
|
||||
|
||||
Das frühere „Common Config Snippet“ wird daher nicht mehr gebraucht, und die zugehörigen Schaltflächen wurden entfernt. Einstellungen, die vor dem Upgrade im Snippet standen, wurden beim Wechseln bereits in die Konfigurationsdatei geschrieben und bleiben dort erhalten. Bevor CC Switch eine Konfigurationsdatei zum ersten Mal umschreibt, sichert es außerdem das Original unter `~/.cc-switch/backups/live-first-write/`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Ich habe im Werkzeug das Modell gewechselt — warum ist es nach dem Hin- und Zurückwechseln wieder das alte?</strong></summary>
|
||||
|
||||
Das Modell ist ein Kernfeld und gehört zum Anbieter. Ein im Werkzeug gewähltes Modell (etwa mit `/model` in Claude Code) gilt bis zum nächsten Wechsel; beim Wechsel wird das Modell in der Konfigurationsdatei durch das im Zielanbieter gespeicherte ersetzt, und CC Switch speichert das im Werkzeug gewählte Modell nicht im vorherigen Anbieter. Wenn Sie ein Modell dauerhaft nutzen möchten, bearbeiten Sie diesen Anbieter in CC Switch.
|
||||
|
||||
Ältere Versionen haben beim Wegwechseln die gesamte Konfigurationsdatei in den Anbieter zurückgeschrieben. Das passiert nicht mehr: Dadurch wurden Plugins und andere gemeinsame Einstellungen in einem einzelnen Anbieter eingefroren und gingen beim Wechsel zu einem anderen Anbieter verloren.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -430,7 +444,9 @@ Hinweis: Solange das lokale Routing aktiviert ist, kann nicht zu offiziellen Anb
|
||||
|
||||
Bei aktiviertem lokalem Routing sendet das Werkzeug seine Anfragen zunächst an das lokale Routing von CC Switch (standardmäßig `http://127.0.0.1:15721`), und CC Switch leitet sie an den ausgewählten Anbieter weiter. Deshalb enthält die Konfigurationsdatei des Werkzeugs nur die lokale Adresse und den Platzhalterschlüssel `PROXY_MANAGED`; bei Claude Code wird der Modellname außerdem als fester Alias wie `claude-sonnet-5` eingetragen (im `/model`-Menü wird weiterhin der tatsächliche Modellname angezeigt). Die tatsächliche Anbieteradresse, der Schlüssel und das Modell sind in CC Switch gespeichert.
|
||||
|
||||
Unter „Settings → Usage Statistics → Request Logs“ sehen Sie für jede Anfrage „angefragtes Modell → tatsächliches Modell“. Nach dem Deaktivieren des lokalen Routings wird die Konfigurationsdatei wieder auf die echte Konfiguration des aktuellen Anbieters zurückgesetzt.
|
||||
Unter „Settings → Usage Statistics → Request Logs“ sehen Sie für jede Anfrage „angefragtes Modell → tatsächliches Modell“.
|
||||
|
||||
Solange das lokale Routing aktiv ist, wechseln Sie den Anbieter, den das lokale Routing verwendet; der Anbieter, den Sie vor dem Aktivieren genutzt haben, bleibt unverändert und ist auf seiner Karte mit „Direct“ gekennzeichnet. Nach dem Deaktivieren des lokalen Routings wird die Konfigurationsdatei auf die Konfiguration dieses direkten Anbieters zurückgeschrieben. Auch beim Beenden von CC Switch wird zuerst der direkte Anbieter zurückgeschrieben; beim nächsten Start verbindet sich das lokale Routing wieder.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -462,8 +478,10 @@ Standardmäßig liegen alle Daten im Ordner `.cc-switch` in Ihrem Benutzerverzei
|
||||
- **Skill-Backups**: `skill-backups/` (vor dem Deinstallieren oder Aktualisieren eines Skills automatisch erstellt, die 20 neuesten werden behalten)
|
||||
- **OAuth-Anmeldedaten**: `copilot_auth.json`, `codex_oauth_auth.json`, `xai_oauth_auth.json`
|
||||
- **Logs**: `logs/cc-switch.log` und `crash.log` — bitte fügen Sie sie bei Problemmeldungen bei
|
||||
- **Gerätezustand**: `live-state.json` (ob jedes Werkzeug direkt oder über das lokale Routing verbunden ist und was zuletzt geschrieben wurde), `codex-login-stash.json` (der offizielle Codex-Login, der beim Wechsel zu einem Drittanbieter beiseitegelegt und beim Zurückwechseln zu einem offiziellen Anbieter wiederhergestellt wird)
|
||||
- **Original-Konfigurationsdateien**: `backups/live-first-write/` (die Konfigurationsdateien der Werkzeuge, bevor CC Switch sie zum ersten Mal umgeschrieben hat)
|
||||
|
||||
Wenn Sie unter „Settings → Advanced → Configuration Directory“ das „CC Switch Configuration Directory“ ändern, werden alle oben genannten Dateien außer `settings.json` im neuen Verzeichnis abgelegt. CC Switch verschiebt vorhandene Dateien nicht automatisch; kopieren Sie sie vorher manuell dorthin.
|
||||
Wenn Sie unter „Settings → Advanced → Configuration Directory“ das „CC Switch Configuration Directory“ ändern, werden alle oben genannten Dateien außer `settings.json`, dem Gerätezustand und den Original-Konfigurationsdateien im neuen Verzeichnis abgelegt. CC Switch verschiebt vorhandene Dateien nicht automatisch; kopieren Sie sie vorher manuell dorthin. `settings.json`, der Gerätezustand und die Original-Konfigurationsdateien gehören nur zu diesem Rechner: Sie bleiben immer im Standardverzeichnis und werden nicht per Cloud synchronisiert.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
+24
-6
@@ -335,6 +335,7 @@ paru -S cc-switch-bin
|
||||
### プロバイダ管理
|
||||
|
||||
- **90 以上のプロバイダプリセット** — プリセットを選んでキーを入力するだけで追加。カスタム設定の作成も可能
|
||||
- **主要フィールドだけを変更** — 切り替え時に置き換えるのはリクエスト先アドレス、キー、モデルなどの接続情報だけ。プラグイン、フック、MCP、自分で追加した設定やコメントはそのまま残ります
|
||||
- **プロジェクト** — Claude Code または Codex の現在のプロバイダ、MCP、Skills、プロンプトファイルを 1 つのプロジェクトとして保存（Claude Desktop はプロバイダのみ保存）。以降はメインページ上部のプロジェクトスイッチャーやトレイから設定一式をワンクリックで切り替え。別のプロジェクトに切り替えると、現在の状態は自動的に元のプロジェクトへ保存
|
||||
- **OAuth 認証センター（Beta）** — 「設定 → 認証」で GitHub Copilot、ChatGPT、xAI（Grok）の複数アカウントにログインし、サブスクリプションをプロバイダとして Claude Code、Claude Desktop、Codex で利用（Codex の OpenAI Official 以外はすべてローカルルーティングの有効化が必要）。公式クライアント以外でサブスクリプションを使用すると、ベンダーの利用規約に違反する可能性があります。リスクはご自身で判断してください
|
||||
- **Claude Desktop でサードパーティを利用** — Anthropic 互換エンドポイントに直接接続可能。Claude 以外のモデルは「モデルマッピング」を選び、ローカルルーティング経由で Sonnet、Opus、Haiku などのティアをプロバイダの実際のモデルにマッピング
|
||||
@@ -344,7 +345,7 @@ paru -S cc-switch-bin
|
||||
### ローカルルーティング & フェイルオーバー
|
||||
|
||||
- **API 形式の変換** — ローカルルーティングが Anthropic Messages、OpenAI Chat Completions、OpenAI Responses、Gemini Native の間でリクエスト形式を変換。Claude Code と Claude Desktop は OpenAI 形式や Gemini 形式のプロバイダを、Codex と Grok Build は Chat Completions 形式や Anthropic Messages 形式のプロバイダを利用可能
|
||||
- **ツールごとに有効化** — Claude Code、Codex、Gemini CLI、Grok Build でそれぞれ個別にローカルルーティングを有効化可能。有効化すると、プロバイダの切り替えが以降のリクエストに即座に反映（切り替えでモデルが変わる場合、Codex と Grok Build は再起動が必要になることがあります）
|
||||
- **ツールごとに有効化** — Claude Code、Codex、Gemini CLI、Grok Build でそれぞれ個別にローカルルーティングを有効化可能。有効化すると、プロバイダの切り替えが以降のリクエストに即座に反映（切り替えでモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります）
|
||||
- **自動フェイルオーバー** — ツールごとにフェイルオーバーキューを設定し、リクエストが失敗するとキューの順に次のプロバイダへ自動で切り替え。サーキットブレーカーとプロバイダのヘルスモニタリングと連携
|
||||
- **整流器** — 一部の上流と互換性のないリクエストを自動で修正（Thinking 署名、画像非対応時のフォールバックなど）
|
||||
- 公式プロバイダ（Claude Official など）はローカルルーティングを経由できません（Codex の OpenAI Official を除く）
|
||||
@@ -392,16 +393,29 @@ CC Switch は **Claude Code**、**Claude Desktop**、**Codex**、**Gemini CLI**
|
||||
ツールによって異なります：
|
||||
|
||||
- **Claude Code**：プロバイダデータのホットスイッチに対応しており、再起動は不要です。
|
||||
- **Codex、Gemini CLI、Grok Build**：変更を反映するにはターミナルまたは CLI ツールを再起動してください（Codex と Grok Build は切り替え後に通知が表示されます）。ローカルルーティングを有効にしている場合、リクエストは即座に新しいプロバイダへ転送されますが、切り替えでモデルが変わる場合は Codex と Grok Build の再起動が必要になることがあります。
|
||||
- **Codex、Gemini CLI、Grok Build**：変更を反映するにはターミナルまたは CLI ツールを再起動してください（Codex と Grok Build は切り替え後に通知が表示されます）。ローカルルーティングを有効にしている場合、リクエストは即座に新しいプロバイダへ転送されますが、切り替えでモデルが変わる場合は、この 3 つのツールは再起動が必要になることがあります。
|
||||
- **Claude Desktop**：Claude Desktop を完全に終了してから再度開いてください。「モデルマッピング」を使用する場合は、CC Switch を起動したままにしておく必要もあります。
|
||||
- **OpenCode、OpenClaw、Hermes、Pi、MiniMax Code**：これらは共存型のツールです。「追加」（Pi では「有効化」）をクリックするとプロバイダがツール自身の設定に書き込まれ、他のプロバイダと共存します。その後、ツール内で使用するモデルを選んでください。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>プロバイダを切り替えた後、プラグイン設定が消えてしまいました。どうすればよいですか？</strong></summary>
|
||||
<summary><strong>プロバイダを切り替えると、プラグインやフックなどの設定も変わってしまいますか？</strong></summary>
|
||||
|
||||
CC Switch には「共通設定スニペット」機能（Claude Code、Codex、Gemini CLI に対応）があり、API キー・エンドポイント・モデル以外の設定（プラグイン、フック、環境変数など）をプロバイダ間で共有できます。プロバイダを編集し、「共通設定を編集」→「編集内容から抽出」をクリックすると、これらの共通部分がスニペットに保存されます。新しいプロバイダを作成する際は「共通設定を適用」にチェックを入れたまま（デフォルトで有効）にしておけば、スニペットが新しいプロバイダの設定にマージされます。「共通設定を適用」が有効な Claude Code と Codex のプロバイダでは、別のプロバイダへ切り替える際に CC Switch が現在の設定から共通部分を自動で再抽出するため、ツール内で新たにインストールしたプラグインも次のプロバイダに引き継がれます。元の設定は、アプリ初回起動時にインポートされたデフォルトプロバイダに保存されており、失われることはありません。
|
||||
変わりません。Claude Code、Codex、Gemini CLI、Grok Build でプロバイダを切り替えるとき、CC Switch が置き換えるのは設定ファイルの**主要フィールド**だけです。対象はリクエスト先アドレス、キー、モデル名、API プロトコル（Codex は推論レベル、Gemini CLI は認証方式も含む）と、プロバイダに合わせて切り替わる一部の互換オプション（Claude Code の「Artifact ツールを無効化」やコンテキストウィンドウなど）です。プラグイン、フック、権限、MCP、自分で追加した環境変数、コメント、書式はそのまま残り、すべてのプロバイダに適用されます。
|
||||
|
||||
これらの共有設定は、ツール内で変更しても、設定ファイルを直接編集しても構いません。CC Switch で任意のプロバイダを編集して変更することもできます。エディタには「このプロバイダに切り替えた後の設定ファイルの内容」が表示され、保存すると主要フィールドはそのプロバイダに保存され、それ以外の変更は設定ファイルに書き込まれてすべてのプロバイダに適用されます。
|
||||
|
||||
そのため、以前の「共通設定スニペット」は不要になり、関連するボタンは削除されました。アップグレード前にスニペットに入れていた設定は、切り替えの際にすでに設定ファイルへ書き込まれているので、そのまま残ります。また CC Switch は、各設定ファイルを初めて書き換える前に、元のファイルを `~/.cc-switch/backups/live-first-write/` にバックアップします。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>ツール内でモデルを変えたのに、別のプロバイダに切り替えて戻すと元に戻ってしまうのはなぜですか？</strong></summary>
|
||||
|
||||
モデルは主要フィールドで、プロバイダに属します。ツール内で変えたモデル（Claude Code の `/model` など）は次に切り替えるまで有効です。切り替えると、設定ファイルのモデルは切り替え先のプロバイダに保存されたものに置き換わり、ツール内で変えたモデルが元のプロバイダに保存し直されることはありません。特定のモデルを継続して使いたい場合は、CC Switch でそのプロバイダを編集してください。
|
||||
|
||||
以前のバージョンは、別のプロバイダへ切り替えるときに設定ファイル全体をプロバイダに保存し直していましたが、現在はそうしていません。その方式では、プラグインなどの共有設定が 1 つのプロバイダに固定されてしまい、別のプロバイダに切り替えると失われていたためです。
|
||||
|
||||
</details>
|
||||
|
||||
@@ -430,7 +444,9 @@ Codex では、CC Switch 内の「ChatGPT でログイン」から複数の Chat
|
||||
|
||||
ローカルルーティングを有効にすると、ツールのリクエストはまず CC Switch のローカルルーティング（デフォルトは `http://127.0.0.1:15721`）に送られ、そこから CC Switch が選択中のプロバイダへ転送します。そのため、ツールの設定ファイルにはローカルアドレスとプレースホルダーのキー `PROXY_MANAGED` だけが書き込まれます。Claude Code のモデル名も `claude-sonnet-5` のような固定のエイリアスになります（`/model` メニューには実際のモデル名が表示されます）。実際のプロバイダのアドレス、キー、モデルはすべて CC Switch に保存されています。
|
||||
|
||||
「設定 → 利用統計 → リクエストログ」では、各リクエストの「リクエストモデル → 実際のモデル」を確認できます。ローカルルーティングを無効にすると、設定ファイルは現在のプロバイダの実際の設定に戻ります。
|
||||
「設定 → 利用統計 → リクエストログ」では、各リクエストの「リクエストモデル → 実際のモデル」を確認できます。
|
||||
|
||||
ローカルルーティングを有効にしている間に切り替わるのは、ローカルルーティングが使うプロバイダです。有効にする前に使っていたプロバイダは変わらず、カードに「直接接続」と表示されます。ローカルルーティングを無効にすると、設定ファイルはこの直接接続のプロバイダの設定に書き戻されます。CC Switch を終了するときも先に直接接続のプロバイダを書き戻し、次回起動時にローカルルーティングへ接続し直します。
|
||||
|
||||
</details>
|
||||
|
||||
@@ -462,8 +478,10 @@ Codex では、CC Switch 内の「ChatGPT でログイン」から複数の Chat
|
||||
- **Skill バックアップ**: `skill-backups/`（スキルのアンインストールまたは更新の前に自動作成、最新 20 件を保持）
|
||||
- **OAuth ログイン認証情報**: `copilot_auth.json`、`codex_oauth_auth.json`、`xai_oauth_auth.json`
|
||||
- **ログ**: `logs/cc-switch.log` と `crash.log`（問題を報告する際は添付してください）
|
||||
- **この端末の状態**: `live-state.json`（各ツールが直接接続かローカルルーティング経由か、前回何を書き込んだか）、`codex-login-stash.json`（サードパーティのプロバイダに切り替えたときに退避した Codex の公式ログイン。公式プロバイダに戻すと復元されます）
|
||||
- **設定ファイルの原本**: `backups/live-first-write/`（CC Switch が各ツールの設定ファイルを初めて書き換える前の元のファイル）
|
||||
|
||||
「設定 → 詳細 → 設定ディレクトリ」で「CC Switch 設定ディレクトリ」を変更すると、`settings.json` 以外の上記ファイルはすべて新しいディレクトリに保存されるようになります。CC Switch は既存のファイルを自動では移動しないため、先に手動でコピーしておいてください。
|
||||
「設定 → 詳細 → 設定ディレクトリ」で「CC Switch 設定ディレクトリ」を変更すると、`settings.json`、この端末の状態、設定ファイルの原本以外の上記ファイルはすべて新しいディレクトリに保存されるようになります。CC Switch は既存のファイルを自動では移動しないため、先に手動でコピーしておいてください。`settings.json`、この端末の状態、設定ファイルの原本はこのコンピュータ専用のもので、常にデフォルトのディレクトリに置かれ、クラウド同期の対象にもなりません。
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ After switching providers, each CLI tool activates differently:
|
||||
| OpenClaw | Requires closing and reopening the terminal |
|
||||
| Hermes / Pi / MiniMax Code | Once added, the provider is written into the tool's configuration; for Pi and MiniMax Code, choose the model to use inside the tool; for Hermes, click "Enable" on the card to make it the current provider |
|
||||
|
||||
With local routing enabled, switching providers for Claude Code, Codex, Gemini CLI, and Grok Build takes effect immediately for subsequent requests; however, if the switch changes the model, Codex and Grok Build may still need a restart.
|
||||
With local routing enabled, switching providers for Claude Code, Codex, Gemini CLI, and Grok Build takes effect immediately for subsequent requests; however, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
|
||||
|
||||
### Claude Code First Launch Prompt
|
||||
|
||||
|
||||
@@ -115,8 +115,8 @@ Contains two toggles, both off by default:
|
||||
|
||||
**Keep official login for direct switches**:
|
||||
|
||||
- **Off**: When local routing is not enabled, every switch to a third-party provider deletes the entire `~/.codex/auth.json` (clearing the official login with it); after switching back to the official provider, you need to log in again
|
||||
- **On**: Direct switches to a third-party provider keep `~/.codex/auth.json`, so switching back to the official provider requires no new login
|
||||
- **Off**: When local routing is not enabled, every switch to a third-party provider deletes `~/.codex/auth.json`, so Codex has no official login while you use the third-party provider. Before deleting it, CC Switch stashes the login on this computer (`~/.cc-switch/codex-login-stash.json`, not included in cloud sync) and restores it automatically when you switch back to the official provider, so you don't need to log in again
|
||||
- **On**: Direct switches to a third-party provider keep `~/.codex/auth.json`, so the official login stays in place while you use the third-party provider and features that need it keep working
|
||||
|
||||
A third-party provider's API key is always written only to `~/.codex/config.toml` and never to `auth.json`; with local routing enabled, the official login is always kept. See the guide [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](../../../guides/codex-official-auth-preservation-guide-en.md).
|
||||
|
||||
|
||||
@@ -212,6 +212,8 @@ This feature is available in model-aware provider forms for **Claude Code / Clau
|
||||
|
||||
After selecting the "Custom" preset, you need to manually edit the JSON configuration.
|
||||
|
||||
> 💡 **What takes effect when you switch**: When you add a provider for Claude Code, Codex, Gemini CLI, or Grok Build, the editor shows "what the config file will look like after switching to this provider": the chosen preset applied on top of the tool's current config file. The key fields (endpoint, key, model name, API protocol, etc.) and a few compatibility options are stored in this provider; everything else is a global setting, and if you change it here, it is written straight to the config file when you add the provider and applies to every provider. The rules are the same as when editing; see [2.3 Edit Provider → Config Editor](./2.3-edit.md#config-editor).
|
||||
|
||||
### Claude Configuration Format
|
||||
|
||||
```json
|
||||
@@ -289,7 +291,7 @@ requires_openai_auth = true
|
||||
| `GOOGLE_GEMINI_BASE_URL` | No | Custom endpoint URL |
|
||||
| `GEMINI_MODEL` | No | Specify model |
|
||||
|
||||
> 💡 Authentication type is automatically detected by CC Switch (PackyCode API proxy / Google OAuth / generic API Key), no manual configuration needed.
|
||||
> 💡 The auth method is determined by the provider type: the Google official provider signs in with a Google account, and all other providers use an API key, so no manual configuration is needed. Providers that use Vertex AI can use `GOOGLE_API_KEY` or `GOOGLE_GENAI_USE_VERTEXAI` instead of `GEMINI_API_KEY`.
|
||||
|
||||
## Universal Provider
|
||||
|
||||
@@ -540,22 +542,25 @@ Added in v3.13.0. By default, CC Switch treats the configured `base_url` as a **
|
||||
|
||||
> 💡 **Tip**: When you turn this option off, path concatenation returns to the default behavior, and the provider no longer needs local routing because of the full URL.
|
||||
|
||||
### Claude Common Config Toggles
|
||||
### Claude Quick Toggles
|
||||
|
||||
When editing Claude providers, a set of **quick toggles** is available above the JSON editor:
|
||||
When adding or editing Claude providers, a set of **quick toggles** is available above the JSON editor:
|
||||
|
||||
| Toggle | Effect | Config Change |
|
||||
|--------|--------|---------------|
|
||||
| **Hide AI Attribution** | Clears commit/PR attribution metadata and session links | Sets `attribution: {commit: "", pr: "", sessionUrl: false}` |
|
||||
| **Teammates Mode** | Enables the agent teams feature | Sets `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` |
|
||||
| **Enable Tool Search** | Enables tool search functionality | Sets `env.ENABLE_TOOL_SEARCH = "true"` |
|
||||
| **Max Effort Thinking** | Sets effort level to max | Sets `env.CLAUDE_CODE_EFFORT_LEVEL = "max"` |
|
||||
| **Disable Auto-Upgrade** | Prevents Claude Code auto-updates | Sets `env.DISABLE_AUTOUPDATER = "1"` |
|
||||
| **Disable Artifact Tool** | Keeps the Artifact tool out of the request's tools array (some third-party gateways reject its schema and return 400 on every request) | Sets `env.CLAUDE_CODE_DISABLE_ARTIFACT = "1"` |
|
||||
| Toggle | Effect | Config Change | Scope |
|
||||
|--------|--------|---------------|-------|
|
||||
| **Hide AI Attribution** | Clears commit/PR attribution metadata and session links | Sets `attribution: {commit: "", pr: "", sessionUrl: false}` | Global |
|
||||
| **Teammates Mode** | Enables the agent teams feature | Sets `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` | Global |
|
||||
| **Enable Tool Search** | Enables tool search functionality | Sets `env.ENABLE_TOOL_SEARCH = "true"` | Per provider |
|
||||
| **Max Effort Thinking** | Sets effort level to max | Sets `env.CLAUDE_CODE_EFFORT_LEVEL = "max"` | Global |
|
||||
| **Disable Auto-Upgrade** | Prevents Claude Code auto-updates | Sets `env.DISABLE_AUTOUPDATER = "1"` | Global |
|
||||
| **Disable Artifact Tool** | Keeps the Artifact tool out of the request's tools array (some third-party gateways reject its schema and return 400 on every request) | Sets `env.CLAUDE_CODE_DISABLE_ARTIFACT = "1"` | Per provider |
|
||||
|
||||
When a toggle is unchecked, its corresponding config entry is removed entirely. Changes are reflected in the JSON editor in real-time.
|
||||
|
||||
Additionally, the **Apply Common Config** checkbox enables merging a global config snippet into the provider. Click **Edit Common Config** to customize the shared snippet.
|
||||
- **Global**: Written to `~/.claude/settings.json` on save and applies to every provider; it makes no difference which provider you change it in.
|
||||
- **Per provider**: Stored in this provider, written to the config file when you switch to it, and removed when you switch away. Third-party endpoints differ in how they support these two options, so they are set separately for each provider.
|
||||
|
||||
For how the rest of the editor is saved, see [2.3 Edit Provider → Config Editor](./2.3-edit.md#config-editor).
|
||||
|
||||
### Upstream Format and Model Mapping for Codex / Grok Build
|
||||
|
||||
|
||||
@@ -85,11 +85,13 @@ Restart Grok Build after switching; a notification appears when the switch succe
|
||||
|
||||
### With Local Routing On
|
||||
|
||||
When local routing is on, requests from Claude Code, Codex, Gemini CLI, and Grok Build are all forwarded through CC Switch, so switching providers applies to subsequent requests immediately. However, if the switch changes the model, Codex and Grok Build may still need a restart.
|
||||
When local routing is on, requests from Claude Code, Codex, Gemini CLI, and Grok Build are all forwarded through CC Switch, so switching providers applies to subsequent requests immediately. However, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
|
||||
|
||||
While local routing is on, switching changes the provider that local routing uses; the provider you were using before you turned it on stays the same and is labeled "Direct" on its card, and the config file is written back to it when you turn local routing off. See [4.2 App Routing](../4-proxy/4.2-routing.md#routing-and-provider-switching) for details.
|
||||
|
||||
## Configuration File Changes
|
||||
|
||||
When switching providers, CC Switch modifies the following files:
|
||||
When switching providers, CC Switch replaces only the **key fields** in the following files: the endpoint, key, model name, API protocol, and a few compatibility options that belong to the provider (such as the context window). Plugins, hooks, permissions, MCP, settings you added yourself, comments, and formatting all stay as they are. For exactly which keys each file changes, see [5.1 Configuration Files](../5-faq/5.1-config-files.md).
|
||||
|
||||
### Claude
|
||||
|
||||
@@ -97,7 +99,7 @@ When switching providers, CC Switch modifies the following files:
|
||||
~/.claude/settings.json
|
||||
```
|
||||
|
||||
Modified content:
|
||||
Modified content (only the key fields are shown; nothing else in the file is touched):
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
@@ -122,12 +124,16 @@ A third-party provider's API Key is written to that provider's `experimental_bea
|
||||
~/.gemini/settings.json
|
||||
```
|
||||
|
||||
In `.env`, only the key-field lines change; in `settings.json`, only the auth method (`security.auth.selectedType`) and the model name (`model.name`) change.
|
||||
|
||||
### Grok Build
|
||||
|
||||
```
|
||||
~/.grok/config.toml
|
||||
```
|
||||
|
||||
Only the default model (`default` under `[models]`) and the `[model."<name>"]` table that CC Switch writes change.
|
||||
|
||||
### Claude Desktop
|
||||
|
||||
Writes Claude Desktop's 3P profile configuration (on macOS under `~/Library/Application Support/Claude-3p/`); see [2.6 Claude Desktop](./2.6-claude-desktop.md) for details.
|
||||
|
||||
@@ -36,21 +36,54 @@ The icon library includes common AI service provider and technology icons, suppo
|
||||
|
||||
### Configuration
|
||||
|
||||
JSON-formatted configuration content, including:
|
||||
For the API key, endpoint URL, model, and other form fields, as well as the config editor at the bottom of the panel, see [Config Editor](#config-editor) below.
|
||||
|
||||
- API Key
|
||||
- Endpoint URL
|
||||
- Other environment variables
|
||||
## Config Editor
|
||||
|
||||
### Editing the Currently Active Provider
|
||||
For Claude Code, Codex, Gemini CLI, and Grok Build, the bottom of the edit panel shows **what the tool's config file will look like after switching to this provider**:
|
||||
|
||||
When editing the currently active provider, a special "backfill" mechanism applies:
|
||||
| App | Editor |
|
||||
|-----|--------|
|
||||
| Claude Code | `~/.claude/settings.json` |
|
||||
| Codex | `~/.codex/config.toml` (the key is in the API Key field above and isn't repeated in the editor) |
|
||||
| Gemini CLI | `~/.gemini/.env` and `~/.gemini/settings.json` |
|
||||
| Grok Build | `~/.grok/config.toml` |
|
||||
|
||||
1. When opening the edit panel, the latest content is read from the live configuration file
|
||||
2. If you manually modified the configuration in the CLI tool, those changes are synced back
|
||||
3. After saving, modifications are written to the live configuration file
|
||||
The editor's content falls into two groups, and a line above the editor lists what the first group covers for this app:
|
||||
|
||||
This ensures CC Switch and CLI tool configurations stay in sync.
|
||||
- **Follows the provider**: key fields such as the endpoint, key, model name, and API protocol, plus a few compatibility options that belong to the provider (such as the context window). The editor shows this provider's own values, and they are stored in this provider on save.
|
||||
- **Global settings**: everything else, such as plugins, hooks, permissions, MCP, and environment variables you added yourself. The editor shows what's in the tool's config file right now, and on save they are written straight to the config file and apply to every provider.
|
||||
|
||||
The rules are exactly the same whether you edit the current provider or another one: no matter which provider you edit, changes to global settings are written to the config file immediately. With local routing on, the key fields in the editor also show the provider's own real endpoint and key, not the local routing address.
|
||||
|
||||
### Settings Changed in the Tool
|
||||
|
||||
- **Global settings**: if you change them in the tool (for example, by installing a plugin), you'll see the change when you open the edit panel, and switching providers won't touch them.
|
||||
- **Key fields**: a model you pick temporarily in the tool (for example, with `/model` in Claude Code) isn't saved back to the provider; after you switch away and back, it returns to the value saved in the provider. To change it for good, edit the provider here.
|
||||
|
||||
> 💡 Older versions read the whole config file back into the provider ("backfill") when you edited the current provider. The new version no longer backfills: shared settings already live in the config file and don't need to be stored in any one provider.
|
||||
|
||||
### Config File Changed While Editing
|
||||
|
||||
When you save, CC Switch submits only the settings you changed in the editor and checks each one: has this setting been changed in the config file by the tool or another program since you opened the edit panel?
|
||||
|
||||
- Not changed: it is written directly.
|
||||
- Changed: a "The config file changed while you were editing" dialog lists those settings and lets you choose "Keep external changes" or "Overwrite with my edits". Your other changes are saved as usual.
|
||||
|
||||
Settings you didn't change aren't submitted, so they won't overwrite anything the tool wrote in the meantime.
|
||||
|
||||
### Settings That Don't Take Effect When Switching
|
||||
|
||||
Backfill in older versions, deep link imports, or old presets may have left settings other than key fields stored in a provider. These settings aren't written to the config file, and they are listed below the editor:
|
||||
|
||||
- **Claude Code, Gemini CLI**: click an item to add it to the editor above; on save it is written to the config file as a global setting.
|
||||
- **Codex, Grok Build**: click an item to copy its TOML, and paste it into the editor above if you need it.
|
||||
|
||||
The original values stored in the provider aren't deleted.
|
||||
|
||||
### When the Config File Can't Be Read
|
||||
|
||||
If the tool's config file has a format error, the editor shows the content stored in the provider instead and explains why at the top. Fix the config file, then reopen the edit panel.
|
||||
|
||||
## Auto-Fetch Models
|
||||
|
||||
@@ -62,9 +95,9 @@ When editing a provider, you can auto-fetch the available model list from the pr
|
||||
|
||||
See [2.1 Add Provider — Auto-Fetch Models](./2.1-add.md#auto-fetch-models) for full details.
|
||||
|
||||
## Common Config Toggles (Claude)
|
||||
## Quick Toggles (Claude)
|
||||
|
||||
When editing a Claude provider, quick toggle switches are available above the JSON editor for common settings like Tool Search, Disable Auto Upgrade, Teammates, and High Effort. See [2.1 Add Provider — Claude Common Config Toggles](./2.1-add.md#claude-common-config-toggles) for details.
|
||||
When editing a Claude provider, quick toggle switches are available above the JSON editor for common settings like Tool Search, Disable Auto-Upgrade, Teammates, and Max Effort Thinking. "Enable Tool Search" and "Disable Artifact Tool" are per provider; the rest are global settings. See [2.1 Add Provider — Claude Quick Toggles](./2.1-add.md#claude-quick-toggles) for details.
|
||||
|
||||
## Modify API Key
|
||||
|
||||
@@ -152,8 +185,9 @@ Configuration uses JSON format, and the editor provides:
|
||||
|
||||
1. Click the "Save" button
|
||||
2. If the form detects a non-blocking issue, a "save anyway" prompt appears; confirming still saves the provider
|
||||
3. If this is the currently active provider, the configuration is immediately written to the live file
|
||||
4. Restart the CLI tool for changes to take effect
|
||||
3. Changes to global settings are written to the config file immediately, whether or not you're editing the current provider
|
||||
4. Changes to key fields are stored in the provider. Without local routing, if you're editing the current provider, they are also written to the config file; with local routing on, if you're editing the provider that routing is using and the change affects what local routing writes to the config file (such as the model name), the config file is updated as well
|
||||
5. Whether you need to restart the tool is the same as for switching providers; see [2.2 Switch Provider](./2.2-switch.md)
|
||||
|
||||
## Cancel Editing
|
||||
|
||||
|
||||
@@ -203,7 +203,7 @@ Turn off the local routing toggle at the top of each app page (requires "Show Ro
|
||||
|
||||
When local routing stops, CC Switch will:
|
||||
|
||||
1. Restore each app's configuration to its state before routing was enabled
|
||||
1. Write each app's config file back to the direct provider (the one in use before routing was enabled, labeled "Direct" on its card)
|
||||
2. Save request logs
|
||||
3. Close all connections
|
||||
|
||||
|
||||
@@ -84,9 +84,9 @@ GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
**Grok Build configuration change**: the request address in `~/.grok/config.toml` changes to `http://127.0.0.1:15721/grokbuild/v1`. If Grok Build is currently signed in with its official login (no custom model configuration in `config.toml`), enabling routing skips the rewrite.
|
||||
**Grok Build configuration change**: the request address in the routing provider's model table in `~/.grok/config.toml` changes to `http://127.0.0.1:15721/grokbuild/v1`. Grok Build's official account can't be used through local routing: enabling routing while the official provider is current reports an error, so switch to a third-party provider first.
|
||||
|
||||
While routing is on, the API Key in the config file is replaced with the placeholder `PROXY_MANAGED`; the real Key is injected by local routing when it forwards requests.
|
||||
While routing is on, the API Key in the config file is replaced with the placeholder `PROXY_MANAGED`; the real Key is injected by local routing when it forwards requests. As with switching providers, enabling routing changes only these key fields; nothing else in the config file is touched.
|
||||
|
||||
### Request Forwarding
|
||||
|
||||
@@ -115,6 +115,8 @@ When routing is enabled, the main interface shows the following changes:
|
||||
| Routing Active | Green | Provider actually used by routing |
|
||||
| Normal | Default | Unused provider |
|
||||
|
||||
In routing mode, the direct provider's card also carries a "Direct" label, meaning this is the provider the config file returns to when you disable routing.
|
||||
|
||||
## Disable Routing
|
||||
|
||||
### Steps
|
||||
@@ -126,9 +128,11 @@ When routing is enabled, the main interface shows the following changes:
|
||||
|
||||
When disabling routing, CC Switch will:
|
||||
|
||||
1. Restore the app configuration to its pre-routing state
|
||||
1. Write the app's config file back to the direct provider (the one in use before routing was enabled, labeled "Direct" on its card), without relying on a backup taken when routing was enabled
|
||||
2. Save current request logs
|
||||
|
||||
Quitting CC Switch also writes the config file back to the direct provider first, while the routing toggle stays as it is; local routing is reconnected the next time CC Switch starts.
|
||||
|
||||
## Routing and Provider Switching
|
||||
|
||||
### Switching Providers in Routing Mode
|
||||
@@ -141,6 +145,8 @@ When switching providers in routing mode:
|
||||
|
||||
This is a major advantage of routing mode: provider switching takes effect instantly. After switching Codex or Grok Build, the interface still prompts you to restart; with routing on, you can skip the restart as long as the switch doesn't change the model.
|
||||
|
||||
In routing mode, switching changes only the provider that routing uses; the direct provider stays the same, is labeled "Direct" on its card, and is what you return to when you disable routing. If what the new provider writes to the config file (the local address, model name, etc.) is the same as before, switching doesn't touch the config file; if it differs (for example, a different model name), CC Switch updates the config file first, and Codex, Gemini CLI, and Grok Build then need a restart to use the new model.
|
||||
|
||||
### Switching Without Routing
|
||||
|
||||
When switching providers without routing:
|
||||
@@ -186,7 +192,7 @@ In routing mode, CLI tools must be able to access the local routing address.
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
Before enabling routing, CC Switch backs up the original configuration and restores it when disabled.
|
||||
Routing doesn't rely on a backup: when you disable routing, CC Switch writes the config file again from the direct provider. Separately, before CC Switch rewrites each config file for the first time, it backs up the original to `~/.cc-switch/backups/live-first-write/`.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
||||
@@ -12,15 +12,20 @@ Customizable location in settings (for cloud sync).
|
||||
|
||||
```
|
||||
~/.cc-switch/
|
||||
├── cc-switch.db # SQLite database (SSOT)
|
||||
├── settings.json # Device-level settings
|
||||
├── skills/ # Master copies of skills (when the storage location is "CC Switch")
|
||||
├── skill-backups/ # Skill backups (created on uninstall)
|
||||
├── backups/ # Database backups and environment variable backups
|
||||
├── logs/ # App diagnostic logs (cc-switch.log and rotated files)
|
||||
└── crash.log # Crash log
|
||||
├── cc-switch.db # SQLite database (SSOT)
|
||||
├── settings.json # Device-level settings
|
||||
├── live-state.json # Device state: whether each tool is direct or on local routing, and what was last written
|
||||
├── codex-login-stash.json # Stashed official Codex login (restored when you switch back to an official provider)
|
||||
├── skills/ # Master copies of skills (when the storage location is "CC Switch")
|
||||
├── skill-backups/ # Skill backups (created on uninstall)
|
||||
├── backups/ # Database backups and environment variable backups
|
||||
│ └── live-first-write/ # Each tool's config file as it was before CC Switch first rewrote it
|
||||
├── logs/ # App diagnostic logs (cc-switch.log and rotated files)
|
||||
└── crash.log # Crash log
|
||||
```
|
||||
|
||||
`settings.json`, `live-state.json`, `codex-login-stash.json`, and `backups/live-first-write/` belong to this computer only: they always stay in `~/.cc-switch/`, don't move with the "CC Switch Configuration Directory" setting, and aren't included in cloud sync.
|
||||
|
||||
### Database Contents
|
||||
|
||||
`cc-switch.db` is a SQLite database that stores:
|
||||
@@ -109,6 +114,8 @@ Default: `~/.claude/`
|
||||
| `env.ANTHROPIC_BASE_URL` | API endpoint (optional) |
|
||||
| `env.ANTHROPIC_AUTH_TOKEN` | Alternative authentication method |
|
||||
|
||||
When switching providers, CC Switch changes only the key fields in `settings.json`: connection and auth variables in `env` such as `ANTHROPIC_*` and `AWS_*`, protocol selectors such as `CLAUDE_CODE_USE_BEDROCK`, and top-level keys such as `model` and `apiKeyHelper`, plus a few compatibility options that belong to the provider (such as `CLAUDE_CODE_DISABLE_ARTIFACT` and the context window). `permissions`, `hooks`, `enabledPlugins`, `statusLine`, and everything else are left alone.
|
||||
|
||||
### MCP Configuration
|
||||
|
||||
MCP server configuration is in `~/.claude.json`:
|
||||
@@ -142,7 +149,7 @@ Default: `~/.codex/`
|
||||
|
||||
### auth.json
|
||||
|
||||
`auth.json` only holds the OpenAI official ChatGPT login credentials, written by Codex's `codex login`. When you switch to a third-party provider, CC Switch does **not** write the third-party API Key into this file. When local routing is off, whether a direct switch keeps the official login is controlled by "Settings → General → Codex App Enhancements → Keep official login for direct switches" (off by default, meaning `auth.json` is deleted); while local routing is on, the official login is always kept.
|
||||
`auth.json` only holds the OpenAI official ChatGPT login credentials, written by Codex's `codex login`. When you switch to a third-party provider, CC Switch does **not** write the third-party API Key into this file. When local routing is off, whether a direct switch keeps the official login is controlled by "Settings → General → Codex App Enhancements → Keep official login for direct switches" (off by default, meaning `auth.json` is deleted); while local routing is on, the official login is always kept. Before deleting it, CC Switch stashes this login in `~/.cc-switch/codex-login-stash.json` and puts it back unchanged when you switch back to the official provider, so you don't need to log in again.
|
||||
|
||||
### config.toml
|
||||
|
||||
@@ -163,7 +170,9 @@ command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
A third-party provider's API Key is written to `experimental_bearer_token` under the corresponding `[model_providers.<id>]`. While local routing is on, it is replaced with the placeholder `PROXY_MANAGED`. For providers with model mapping configured, a `model_catalog_json` entry pointing to `cc-switch-model-catalog.json` is also written.
|
||||
Every third-party provider is written as the `[model_providers.custom]` table, with the API Key in that table's `experimental_bearer_token`. While local routing is on, it is replaced with the placeholder `PROXY_MANAGED`. For providers with model mapping configured, a `model_catalog_json` entry pointing to `cc-switch-model-catalog.json` is also written.
|
||||
|
||||
When switching providers, CC Switch changes only the key fields in `config.toml`: top-level keys such as `model_provider`, `model`, and the reasoning effort, the `[model_providers.custom]` table, and a few compatibility options (such as `model_context_window` and `web_search`). `[mcp_servers]`, `[projects]`, your own other provider tables, comments, and formatting are left alone.
|
||||
|
||||
## Gemini CLI Configuration
|
||||
|
||||
@@ -204,6 +213,10 @@ GEMINI_MODEL=gemini-pro
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `mcpServers` | MCP server configuration |
|
||||
| `security.auth.selectedType` | Auth method: `oauth-personal` for the Google official provider, `gemini-api-key` for all others |
|
||||
| `model.name` | Model name |
|
||||
|
||||
When switching providers, CC Switch changes only the key-field lines in `.env` (`GEMINI_API_KEY`, `GEMINI_MODEL`, `GOOGLE_*`, etc.), leaving variables you added yourself, comments, and line order alone; in `settings.json` it changes only the two keys `security.auth.selectedType` and `model.name`. Both files are updated together in a single operation.
|
||||
|
||||
## OpenCode Configuration
|
||||
|
||||
@@ -237,7 +250,9 @@ Default: `~/.grok/`
|
||||
└── sessions/ # Session logs
|
||||
```
|
||||
|
||||
Grok Build is a switch-mode app; CC Switch rewrites `config.toml` when switching providers.
|
||||
Grok Build is a switch-mode app. When switching providers, CC Switch changes only `default` under `[models]` in `config.toml` and the `[model."<name>"]` table it points to; `[mcp_servers]` and other model tables you added yourself are left alone.
|
||||
|
||||
When switching away, CC Switch deletes the table it wrote last time (the table name is recorded in `~/.cc-switch/live-state.json`), not whichever table `default` points to now. So even if you changed the default model in Grok Build's `/settings`, switching away won't delete your own table by mistake or leave the previous provider's table behind.
|
||||
|
||||
## Hermes Configuration
|
||||
|
||||
@@ -361,34 +376,41 @@ Default: `~/.minimax/` (can be set with the `MINIMAX_DATA_DIR` or `MAVIS_DATA_DI
|
||||
|
||||
CC Switch only manages nodes in `custom_provider` whose `kind` is omitted or set to `custom`; MiniMax official account nodes are managed by MiniMax Code itself. A provider referenced by MiniMax Code's default model can't be deleted or disabled. Before writing, CC Switch acquires the directory lock `config.yaml.lock`, which is compatible with MiniMax Code.
|
||||
|
||||
## Configuration Priority
|
||||
## Who Manages What
|
||||
|
||||
CC Switch's priority when modifying configurations:
|
||||
The config files of Claude Code, Codex, Gemini CLI, and Grok Build are managed in two parts:
|
||||
|
||||
1. **CC Switch Database** - Single source of truth (SSOT)
|
||||
2. **Live Configuration Files** - Written when switching providers
|
||||
3. **Backfill Mechanism** - Reads from live files when editing the current provider
|
||||
| Part | Includes | Stored in | Changed by |
|
||||
|------|----------|-----------|------------|
|
||||
| Key fields | Endpoint, key, model name, API protocol, etc., plus a few compatibility options that belong to the provider | Each provider in the CC Switch database | CC Switch, which replaces them with the target provider's values when switching |
|
||||
| Global settings | Everything else: plugins, hooks, permissions, MCP, settings you added yourself, comments | The tool's own config file | You and the tool; CC Switch writes them only when you change them through the edit panel |
|
||||
|
||||
For exactly which keys each app changes, see the app sections above.
|
||||
|
||||
## Manual Configuration Editing
|
||||
|
||||
### Safe to Edit Manually
|
||||
|
||||
- CLI tool configuration files (will be backfilled by CC Switch)
|
||||
- CC Switch's `settings.json`
|
||||
- **Global settings in the tool's config file**: edit them directly. Switching providers won't touch them, and you don't need to sync them back into CC Switch.
|
||||
- **CC Switch's `settings.json`**
|
||||
|
||||
### Replaced Even If You Edit Them
|
||||
|
||||
- **Key fields in the tool's config file** (endpoint, key, model, etc.): a value you edit by hand stays in effect until the next switch; switching replaces it with the target provider's value, and CC Switch doesn't save it back to the provider. To change it for good, edit that provider in CC Switch.
|
||||
|
||||
### Not Recommended to Edit Manually
|
||||
|
||||
- `cc-switch.db` database file
|
||||
- `live-state.json`, `codex-login-stash.json`
|
||||
- Backup files
|
||||
|
||||
### Sync After Editing
|
||||
### When a Config File Has a Format Error
|
||||
|
||||
If you manually edit CLI tool configurations:
|
||||
CC Switch writes a config file only if it can read it correctly. If a manual edit breaks the config file (for example, a missing comma in JSON), switching reports "Cannot parse … (line N, column M) … Nothing was written, so your configuration is unchanged" and every file stays as it was. Fix it at the reported position, then switch again.
|
||||
|
||||
1. Open CC Switch
|
||||
2. Edit the corresponding provider
|
||||
3. You will see the manual changes have been backfilled
|
||||
4. Save to sync to the database
|
||||
### Backup Before the First Write
|
||||
|
||||
Before CC Switch rewrites a tool's config file for the first time, it backs up the original to `~/.cc-switch/backups/live-first-write/`, once per file. If your configuration doesn't look as expected after upgrading, you can recover the pre-upgrade original from there.
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
|------|-------------|
|
||||
| [2.1-add.md](./2-providers/2.1-add.md) | Using presets, custom configuration, universal providers |
|
||||
| [2.2-switch.md](./2-providers/2.2-switch.md) | Main UI switching, tray switching, activation methods |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, backfill mechanism |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, global settings and edit conflicts |
|
||||
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | Drag-to-reorder, duplicate provider, delete |
|
||||
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | Usage query, remaining balance, multi-plan display |
|
||||
| [2.6-claude-desktop.md](./2-providers/2.6-claude-desktop.md) | Claude Desktop third-party providers, direct mode, and model mapping |
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
| OpenClaw | ターミナルの再起動が必要 |
|
||||
| Hermes / Pi / MiniMax Code | プロバイダーを追加するとツールの設定に書き込まれます。Pi と MiniMax Code ではツール側で使用するモデルを選択し、Hermes ではカードの「有効化」をクリックして現在のプロバイダーに設定できます |
|
||||
|
||||
ローカルルーティングを有効にしている場合、Claude Code、Codex、Gemini CLI、Grok Build でのプロバイダー切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex と Grok Build は再起動が必要になることがあります。
|
||||
ローカルルーティングを有効にしている場合、Claude Code、Codex、Gemini CLI、Grok Build でのプロバイダー切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
|
||||
|
||||
### Claude Code の初回インストール時の注意
|
||||
|
||||
|
||||
@@ -115,8 +115,8 @@ CC Switch が Skills のマスターコピーを保存するディレクトリ
|
||||
|
||||
**直接切替時に公式ログインを保持**：
|
||||
|
||||
- **オフ**：ローカルルーティングを使っていない場合、サードパーティのプロバイダーに切り替えるたびに `~/.codex/auth.json` 全体が削除されます（公式ログインも消えます）。公式に戻したら再ログインが必要です
|
||||
- **オン**：サードパーティのプロバイダーに直接切り替えても `~/.codex/auth.json` を保持するため、公式に戻したときに再ログインは不要です
|
||||
- **オフ**：ローカルルーティングを使っていない場合、サードパーティのプロバイダーに切り替えるたびに `~/.codex/auth.json` が削除され、サードパーティのプロバイダーを使っている間、Codex には公式ログインがありません。削除の前に CC Switch はログインをこのマシンに一時保存し（`~/.cc-switch/codex-login-stash.json`、クラウド同期の対象外）、公式プロバイダーに戻したときに自動で復元するため、再ログインは不要です
|
||||
- **オン**：サードパーティのプロバイダーに直接切り替えても `~/.codex/auth.json` を保持します。サードパーティのプロバイダーを使っている間も公式ログインが残るため、公式ログインが必要な機能を引き続き使えます
|
||||
|
||||
サードパーティプロバイダーの API Key は常に `~/.codex/config.toml` にのみ書き込まれ、`auth.json` には書き込まれません。ローカルルーティングを有効にしている場合、公式ログインは常に保持されます。詳しくはガイド [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](../../../guides/codex-official-auth-preservation-guide-ja.md) を参照してください。
|
||||
|
||||
|
||||
@@ -212,6 +212,8 @@ MiniMax Code のプリセットは Pi のプリセットカタログから派生
|
||||
|
||||
「カスタム」プリセットを選択した場合、JSON 設定を手動で編集する必要があります。
|
||||
|
||||
> 💡 **切り替えで反映される内容**：Claude Code、Codex、Gemini CLI、Grok Build でプロバイダーを追加するとき、エディタには「このプロバイダーに切り替えた後の設定ファイルの姿」が表示されます。選んだプリセットを、ツールの既存の設定ファイルに重ねたものです。主要フィールド（リクエスト先アドレス、Key、モデル名、API プロトコルなど）と一部の互換オプションはこのプロバイダーに保存されます。それ以外の内容はグローバル設定で、ここで変更すると追加時にそのまま設定ファイルに書き込まれ、すべてのプロバイダーに適用されます。ルールは編集時と同じです。[2.3 プロバイダーの編集 → 設定エディタ](./2.3-edit.md#設定エディタ) を参照してください。
|
||||
|
||||
### Claude 設定形式
|
||||
|
||||
```json
|
||||
@@ -289,7 +291,7 @@ requires_openai_auth = true
|
||||
| `GOOGLE_GEMINI_BASE_URL` | いいえ | カスタムエンドポイントアドレス |
|
||||
| `GEMINI_MODEL` | いいえ | モデルの指定 |
|
||||
|
||||
> 認証タイプは CC Switch が自動的に検出します（PackyCode API プロキシ / Google OAuth / 汎用 API Key）。手動設定は不要です。
|
||||
> 認証方式はプロバイダーの種類で決まります。Google 公式プロバイダーは Google アカウントでログインし、それ以外のプロバイダーは API Key を使用します。手動設定は不要です。Vertex AI を使うプロバイダーでは、`GEMINI_API_KEY` の代わりに `GOOGLE_API_KEY` または `GOOGLE_GENAI_USE_VERTEXAI` を使用できます。
|
||||
|
||||
## 統一プロバイダー
|
||||
|
||||
@@ -540,22 +542,25 @@ v3.13.0 で追加された高度なオプション。デフォルトでは、CC
|
||||
|
||||
> 💡 **ヒント**：このオプションを無効にすると、パス連結はデフォルトの動作に戻り、このプロバイダーも完全 URL を理由にローカルルーティングを必要としなくなります。
|
||||
|
||||
### Claude 共通設定クイックトグル
|
||||
### Claude クイックトグル
|
||||
|
||||
Claude プロバイダーの編集時、JSON エディタの上部に **クイックトグル** が利用できます：
|
||||
Claude プロバイダーの追加・編集時、JSON エディタの上部に **クイックトグル** が利用できます：
|
||||
|
||||
| トグル | 効果 | 設定変更 |
|
||||
|------|------|------|
|
||||
| **AI署名を非表示** | コミット/PR の帰属メタデータとセッションリンクをクリア | `attribution: {commit: "", pr: "", sessionUrl: false}` を設定 |
|
||||
| **Teammates モード** | エージェントチーム機能を有効化 | `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` を設定 |
|
||||
| **Tool Search を有効化** | ツール検索機能を有効化 | `env.ENABLE_TOOL_SEARCH = "true"` を設定 |
|
||||
| **最大強度思考** | エフォートレベルを max に設定 | `env.CLAUDE_CODE_EFFORT_LEVEL = "max"` を設定 |
|
||||
| **自動アップグレードを無効化** | Claude Code の自動更新を防止 | `env.DISABLE_AUTOUPDATER = "1"` を設定 |
|
||||
| **Artifact ツールを無効化** | Artifact ツールをリクエストの tools 配列に含めない（一部のサードパーティゲートウェイはそのスキーマ検証に失敗し、すべてのリクエストで 400 を返す） | `env.CLAUDE_CODE_DISABLE_ARTIFACT = "1"` を設定 |
|
||||
| トグル | 効果 | 設定変更 | 適用範囲 |
|
||||
|------|------|------|------|
|
||||
| **AI署名を非表示** | コミット/PR の帰属メタデータとセッションリンクをクリア | `attribution: {commit: "", pr: "", sessionUrl: false}` を設定 | グローバル |
|
||||
| **Teammates モード** | エージェントチーム機能を有効化 | `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` を設定 | グローバル |
|
||||
| **Tool Search を有効化** | ツール検索機能を有効化 | `env.ENABLE_TOOL_SEARCH = "true"` を設定 | プロバイダーごと |
|
||||
| **最大強度思考** | エフォートレベルを max に設定 | `env.CLAUDE_CODE_EFFORT_LEVEL = "max"` を設定 | グローバル |
|
||||
| **自動アップグレードを無効化** | Claude Code の自動更新を防止 | `env.DISABLE_AUTOUPDATER = "1"` を設定 | グローバル |
|
||||
| **Artifact ツールを無効化** | Artifact ツールをリクエストの tools 配列に含めない（一部のサードパーティゲートウェイはそのスキーマ検証に失敗し、すべてのリクエストで 400 を返す） | `env.CLAUDE_CODE_DISABLE_ARTIFACT = "1"` を設定 | プロバイダーごと |
|
||||
|
||||
トグルのチェックを外すと、対応する設定エントリが完全に削除されます。変更は JSON エディタにリアルタイムで反映されます。
|
||||
|
||||
また、**共通設定を適用** チェックボックスを有効にすると、グローバル設定スニペットをプロバイダーにマージできます。**共通設定を編集** をクリックして共有スニペットをカスタマイズできます。
|
||||
- **グローバル**：保存すると `~/.claude/settings.json` に書き込まれ、すべてのプロバイダーに適用されます。どのプロバイダーで変更しても同じです。
|
||||
- **プロバイダーごと**：このプロバイダーに保存され、このプロバイダーに切り替えたときに設定ファイルに書き込まれ、別のプロバイダーに切り替えると削除されます。この 2 項目への対応はサードパーティのエンドポイントによって異なるため、プロバイダーごとに設定します。
|
||||
|
||||
エディタのその他の内容の保存ルールは [2.3 プロバイダーの編集 → 設定エディタ](./2.3-edit.md#設定エディタ) を参照してください。
|
||||
|
||||
### Codex / Grok Build の上流フォーマットとモデルマッピング
|
||||
|
||||
|
||||
@@ -85,11 +85,13 @@ Gemini CLI はリクエストごとに `.env` ファイルを再読み込みし
|
||||
|
||||
### ローカルルーティング有効時
|
||||
|
||||
ローカルルーティングを有効にすると、Claude Code、Codex、Gemini CLI、Grok Build のリクエストはすべて CC Switch 経由で転送されるため、プロバイダーの切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex と Grok Build は再起動が必要になることがあります。
|
||||
ローカルルーティングを有効にすると、Claude Code、Codex、Gemini CLI、Grok Build のリクエストはすべて CC Switch 経由で転送されるため、プロバイダーの切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
|
||||
|
||||
ローカルルーティングが有効な間に切り替わるのは、ローカルルーティングが使うプロバイダーです。有効にする前に使っていたプロバイダーはそのまま残り、カードに「直接接続」と表示されます。ローカルルーティングを無効にすると、設定ファイルはそのプロバイダーに書き戻されます。詳しくは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md#ルーティングとプロバイダーの切り替え) を参照してください。
|
||||
|
||||
## 設定ファイルの変更
|
||||
|
||||
プロバイダーを切り替える際、CC Switch は以下のファイルを変更します：
|
||||
プロバイダーを切り替える際、CC Switch は以下のファイルの**主要フィールド**だけを置き換えます：リクエスト先アドレス、Key、モデル名、API プロトコル、およびプロバイダーに付随する一部の互換オプション（コンテキストウィンドウなど）。プラグイン、Hook、権限、MCP、自分で追加した設定、コメントや書式はそのまま残ります。各ファイルで具体的にどのキーを変更するかは [5.1 設定ファイルの説明](../5-faq/5.1-config-files.md) を参照してください。
|
||||
|
||||
### Claude
|
||||
|
||||
@@ -97,7 +99,7 @@ Gemini CLI はリクエストごとに `.env` ファイルを再読み込みし
|
||||
~/.claude/settings.json
|
||||
```
|
||||
|
||||
変更内容：
|
||||
変更内容（主要フィールドのみを示しています。ファイル内のその他の内容は変更されません）：
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
@@ -122,12 +124,16 @@ Gemini CLI はリクエストごとに `.env` ファイルを再読み込みし
|
||||
~/.gemini/settings.json
|
||||
```
|
||||
|
||||
`.env` は主要フィールドの行だけを変更し、`settings.json` は認証方式（`security.auth.selectedType`）とモデル名（`model.name`）だけを変更します。
|
||||
|
||||
### Grok Build
|
||||
|
||||
```
|
||||
~/.grok/config.toml
|
||||
```
|
||||
|
||||
変更するのはデフォルトモデル（`[models]` の `default`）と、CC Switch が書き込んだ `[model."<名前>"]` テーブルだけです。
|
||||
|
||||
### Claude Desktop
|
||||
|
||||
Claude Desktop の 3P プロファイル設定に書き込みます（macOS では `~/Library/Application Support/Claude-3p/` 配下）。詳しくは [2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。
|
||||
|
||||
@@ -36,21 +36,54 @@ CC Switch は豊富なアイコンカスタマイズ機能を提供していま
|
||||
|
||||
### 設定情報
|
||||
|
||||
JSON 形式の設定内容（以下を含む）：
|
||||
フォームの API Key、エンドポイントアドレス、モデルなどと、パネル下部の設定エディタについては、下の [設定エディタ](#設定エディタ) を参照してください。
|
||||
|
||||
- API Key
|
||||
- エンドポイントアドレス
|
||||
- その他の環境変数
|
||||
## 設定エディタ
|
||||
|
||||
### 現在有効なプロバイダーの編集
|
||||
Claude Code、Codex、Gemini CLI、Grok Build の編集パネル下部には、**このプロバイダーに切り替えた後のツールの設定ファイルの姿**が表示されます：
|
||||
|
||||
現在有効なプロバイダーを編集する場合、特別な「バックフィル」機能があります：
|
||||
| アプリ | エディタ |
|
||||
|------|--------|
|
||||
| Claude Code | `~/.claude/settings.json` |
|
||||
| Codex | `~/.codex/config.toml`（Key は上の API Key 入力ボックスにあり、エディタには重複して表示されません） |
|
||||
| Gemini CLI | `~/.gemini/.env` と `~/.gemini/settings.json` |
|
||||
| Grok Build | `~/.grok/config.toml` |
|
||||
|
||||
1. 編集パネルを開くと、live 設定ファイルから最新の内容を読み取る
|
||||
2. CLI ツールで手動で設定を変更した場合、その変更が同期される
|
||||
3. 保存すると、変更が live 設定ファイルに書き込まれる
|
||||
エディタの内容は 2 種類に分かれます。エディタの上にある 1 行の説明に、このアプリで 1 種類目に含まれるものが列挙されています：
|
||||
|
||||
これにより、CC Switch と CLI ツールの設定が常に同期されます。
|
||||
- **プロバイダーに合わせて切り替わるもの**：リクエスト先アドレス、Key、モデル名、API プロトコルなどの主要フィールドと、プロバイダーに付随する一部の互換オプション（コンテキストウィンドウなど）。このプロバイダー自身の値が表示され、保存するとこのプロバイダーに保存されます。
|
||||
- **グローバル設定**：それ以外のすべての内容（プラグイン、Hook、権限、MCP、自分で追加した環境変数など）。ツールの設定ファイルの現在の内容が表示され、保存するとそのまま設定ファイルに書き込まれ、すべてのプロバイダーに適用されます。
|
||||
|
||||
現在のプロバイダーを編集する場合も、他のプロバイダーを編集する場合も、ルールはまったく同じです。どのプロバイダーを編集していても、グローバル設定を変更するとすぐに設定ファイルに書き込まれます。ローカルルーティングが有効な場合も、エディタの主要フィールドにはプロバイダー自身の実際のアドレスと Key が表示され、ローカルルーティングのアドレスは表示されません。
|
||||
|
||||
### ツール側で変更した設定
|
||||
|
||||
- **グローバル設定**：ツール側で変更した内容（プラグインのインストールなど）は、編集パネルを開けばそのまま表示され、プロバイダーを切り替えても変更されません。
|
||||
- **主要フィールド**：ツール側で一時的に変えたモデル（Claude Code の `/model` など）はプロバイダーに保存されず、別のプロバイダーに切り替えてから戻すと、プロバイダーに保存された値に戻ります。恒久的に変更したい場合は、ここでプロバイダーを編集してください。
|
||||
|
||||
> 💡 旧バージョンでは、現在のプロバイダーを編集するときに設定ファイル全体をプロバイダーに読み戻していました（「バックフィル」）。新バージョンではバックフィルを行いません。共有設定はもともと設定ファイルに残っているため、特定のプロバイダーに保存する必要がないからです。
|
||||
|
||||
### 編集中に設定ファイルが変更された場合
|
||||
|
||||
保存時、CC Switch はエディタで変更した設定だけを書き込み対象とし、1 件ずつ確認します：編集パネルを開いた後に、その設定が設定ファイル内でツールや他のプログラムによって変更されていないかどうかです。
|
||||
|
||||
- 変更されていない：そのまま書き込みます。
|
||||
- 変更されている：「編集中に設定ファイルが変更されました」が表示され、該当する設定が一覧表示されます。「外部の変更を残す」か「自分の編集で上書き」を選択してください。その他の変更は通常どおり保存されます。
|
||||
|
||||
変更していない設定は書き込み対象にならないため、その間にツールが書き込んだ内容を上書きすることはありません。
|
||||
|
||||
### 切り替えで反映されない設定
|
||||
|
||||
旧バージョンの「バックフィル」、ディープリンクでのインポート、古いプリセットによって、プロバイダーに主要フィールド以外の設定が保存されていることがあります。これらの設定は設定ファイルに書き込まれず、エディタの下に一覧表示されます：
|
||||
|
||||
- **Claude Code、Gemini CLI**：項目をクリックすると上のエディタに追加され、保存するとグローバル設定として設定ファイルに書き込まれます。
|
||||
- **Codex、Grok Build**：項目をクリックするとその TOML がコピーされるので、必要に応じて上のエディタに貼り付けてください。
|
||||
|
||||
プロバイダーに保存された元の値は削除されません。
|
||||
|
||||
### 設定ファイルを読み込めない場合
|
||||
|
||||
ツールの設定ファイルの形式に誤りがある場合、エディタには代わりにプロバイダーに保存された内容が表示され、上部に原因が表示されます。設定ファイルを修正してから、編集パネルを開き直してください。
|
||||
|
||||
## モデル自動取得
|
||||
|
||||
@@ -62,9 +95,9 @@ JSON 形式の設定内容（以下を含む）：
|
||||
|
||||
詳しくは [2.1 プロバイダーの追加 - モデル自動取得](./2.1-add.md#モデル自動取得) をご覧ください。
|
||||
|
||||
## 共通設定クイックトグル（Claude）
|
||||
## クイックトグル（Claude）
|
||||
|
||||
Claude プロバイダーの編集時、JSON エディタの上部にツール検索、自動アップグレード無効化、チームメイト、高強度などの共通設定のクイックトグルスイッチが利用できます。詳しくは [2.1 プロバイダーの追加 - Claude 共通設定クイックトグル](./2.1-add.md#claude-共通設定クイックトグル) をご覧ください。
|
||||
Claude プロバイダーの編集時、JSON エディタの上部にツール検索、自動アップグレード無効化、チームメイト、最大強度思考などのよく使う設定のクイックトグルスイッチが利用できます。このうち「Tool Search を有効化」と「Artifact ツールを無効化」はプロバイダーごとの設定で、それ以外はグローバル設定です。詳しくは [2.1 プロバイダーの追加 - Claude クイックトグル](./2.1-add.md#claude-クイックトグル) をご覧ください。
|
||||
|
||||
## API Key の変更
|
||||
|
||||
@@ -152,8 +185,9 @@ Claude プロバイダーの編集時、JSON エディタの上部にツール
|
||||
|
||||
1. 「保存」ボタンをクリック
|
||||
2. フォームが非ブロッキングな問題を検出した場合、「それでも保存」の確認が表示されます。確認すると保存できます
|
||||
3. 現在有効なプロバイダーの場合、設定は即座に live ファイルに書き込まれる
|
||||
4. CLI ツールを再起動して反映
|
||||
3. グローバル設定の変更は、編集しているのが現在のプロバイダーかどうかに関係なく、すぐに設定ファイルに書き込まれます
|
||||
4. 主要フィールドの変更はプロバイダーに保存されます。ローカルルーティングが無効な場合、現在のプロバイダーを編集していれば、設定ファイルにも同時に書き込まれます。ローカルルーティングが有効な場合、ルーティングが使用中のプロバイダーを編集していて、かつその変更がローカルルーティングの設定ファイルへの書き込み内容に影響するとき（モデル名など）は、設定ファイルも合わせて更新されます
|
||||
5. ツールの再起動が必要かどうかは、プロバイダーの切り替えと同じです。[2.2 プロバイダーの切り替え](./2.2-switch.md) を参照してください
|
||||
|
||||
## 編集のキャンセル
|
||||
|
||||
|
||||
@@ -203,7 +203,7 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
|
||||
ローカルルーティングの停止時、CC Switch は以下を実行します：
|
||||
|
||||
1. 各アプリの設定をルーティング有効化前の状態に復元
|
||||
1. 各アプリの設定ファイルを直接接続のプロバイダー（ルーティング有効化前に使っていた、カードに「直接接続」と表示されているもの）に書き戻す
|
||||
2. リクエストログを保存
|
||||
3. すべての接続を閉じる
|
||||
|
||||
|
||||
@@ -84,9 +84,9 @@ GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
**Grok Build 設定の変更**：`~/.grok/config.toml` のリクエスト先アドレスが `http://127.0.0.1:15721/grokbuild/v1` に変わります。Grok Build が現在公式ログイン状態（`config.toml` にカスタムモデル設定がない）の場合、ルーティングを有効にしても書き換えはスキップされます。
|
||||
**Grok Build 設定の変更**：`~/.grok/config.toml` 内の、ルーティングで使うプロバイダーのモデルテーブルのリクエスト先アドレスが `http://127.0.0.1:15721/grokbuild/v1` に変わります。Grok Build の公式アカウントはローカルルーティング経由では使用できません。現在公式プロバイダーを使っている場合、ルーティングを有効にするとエラーになるため、先にサードパーティのプロバイダーに切り替えてください。
|
||||
|
||||
ルーティング中、設定ファイル内の API Key はプレースホルダー `PROXY_MANAGED` に置き換えられ、実際の Key はローカルルーティングが転送時に付与します。
|
||||
ルーティング中、設定ファイル内の API Key はプレースホルダー `PROXY_MANAGED` に置き換えられ、実際の Key はローカルルーティングが転送時に付与します。プロバイダーの切り替えと同様に、ルーティングを有効にしても変更されるのはこれらの主要フィールドだけで、設定ファイル内のその他の内容は変更されません。
|
||||
|
||||
### リクエストの転送
|
||||
|
||||
@@ -115,6 +115,8 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
| ルーティングアクティブ | 緑 | ルーティングが実際に使用しているプロバイダー |
|
||||
| 通常 | デフォルト | 使用されていないプロバイダー |
|
||||
|
||||
ルーティングモードでは、直接接続のプロバイダーのカードに「直接接続」ラベルも表示されます。ルーティングを無効にすると、このプロバイダーに戻ることを示しています。
|
||||
|
||||
## ルーティングの無効化
|
||||
|
||||
### 操作手順
|
||||
@@ -126,9 +128,11 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
|
||||
ルーティングを無効にすると、CC Switch は以下を実行します：
|
||||
|
||||
1. アプリの設定をルーティング前の状態に復元
|
||||
1. アプリの設定ファイルを直接接続のプロバイダー（ルーティング有効化前に使っていた、カードに「直接接続」と表示されているもの）に書き戻す。ルーティング有効化時のバックアップには依存しない
|
||||
2. 現在のリクエストログを保存
|
||||
|
||||
CC Switch を終了するときも、まず設定ファイルを直接接続のプロバイダーに書き戻し、ルーティングのスイッチはそのまま維持します。次回 CC Switch を起動したときに、ローカルルーティングに再接続します。
|
||||
|
||||
## ルーティングとプロバイダーの切り替え
|
||||
|
||||
### ルーティングモードでのプロバイダー切り替え
|
||||
@@ -141,6 +145,8 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
|
||||
これがルーティングモードの大きなメリットです：プロバイダーの切り替えが即座に反映されます。Codex や Grok Build を切り替えた後も画面には再起動の案内が表示されますが、ルーティングが有効で、切り替えによってモデルが変わらない限り、再起動しなくても構いません。
|
||||
|
||||
ルーティングモードで切り替わるのは、ルーティングが使うプロバイダーだけです。直接接続のプロバイダーはそのまま残り、カードに「直接接続」と表示され、ルーティングを無効にするとそのプロバイダーに戻ります。新しいプロバイダーが設定ファイルに書き込む内容（ローカルアドレス、モデル名など）が以前と同じであれば、切り替えても設定ファイルは変更されません。異なる場合（モデル名が違うなど）は、CC Switch が先に設定ファイルを更新します。このとき Codex、Gemini CLI、Grok Build は、新しいモデルを使うために再起動が必要です。
|
||||
|
||||
### 非ルーティングモードでのプロバイダー切り替え
|
||||
|
||||
非ルーティングモードでプロバイダーを切り替える場合：
|
||||
@@ -186,7 +192,7 @@ OpenAI や Gemini フォーマットのプロバイダーを Claude Code で使
|
||||
|
||||
### 設定のバックアップ
|
||||
|
||||
ルーティングを有効にする前に、CC Switch は元の設定をバックアップし、無効化時に復元します。
|
||||
ルーティングの有効化はバックアップに依存しません。ルーティングを無効にすると、CC Switch は直接接続のプロバイダーに基づいて設定ファイルを書き直します。また、CC Switch は各設定ファイルを初めて書き換える前に、元のファイルを `~/.cc-switch/backups/live-first-write/` にバックアップします。
|
||||
|
||||
## よくある質問
|
||||
|
||||
|
||||
@@ -12,15 +12,20 @@
|
||||
|
||||
```
|
||||
~/.cc-switch/
|
||||
├── cc-switch.db # SQLite データベース（SSOT）
|
||||
├── settings.json # デバイスレベルの設定
|
||||
├── skills/ # スキルのマスターコピーディレクトリ（保存場所に「CC Switch」を選んだ場合）
|
||||
├── skill-backups/ # スキルバックアップ（アンインストール時に作成）
|
||||
├── backups/ # データベースと環境変数のバックアップ
|
||||
├── logs/ # アプリの診断ログ（cc-switch.log とローテーションファイル）
|
||||
└── crash.log # クラッシュログ
|
||||
├── cc-switch.db # SQLite データベース（SSOT）
|
||||
├── settings.json # デバイスレベルの設定
|
||||
├── live-state.json # このマシンの状態：各ツールが直接接続かローカルルーティング経由か、前回何を書き込んだか
|
||||
├── codex-login-stash.json # 一時保存された Codex 公式ログイン（公式プロバイダーに戻したときに復元）
|
||||
├── skills/ # スキルのマスターコピーディレクトリ（保存場所に「CC Switch」を選んだ場合）
|
||||
├── skill-backups/ # スキルバックアップ（アンインストール時に作成）
|
||||
├── backups/ # データベースと環境変数のバックアップ
|
||||
│ └── live-first-write/ # 各ツールの設定ファイルを CC Switch が初めて書き換える前の元ファイル
|
||||
├── logs/ # アプリの診断ログ（cc-switch.log とローテーションファイル）
|
||||
└── crash.log # クラッシュログ
|
||||
```
|
||||
|
||||
`settings.json`、`live-state.json`、`codex-login-stash.json` と `backups/live-first-write/` はこのマシン専用です。常に `~/.cc-switch/` にあり、設定の「CC Switch 設定ディレクトリ」を変更しても移動せず、クラウド同期の対象にもなりません。
|
||||
|
||||
### データベースの内容
|
||||
|
||||
`cc-switch.db` は SQLite データベースで、以下を保存しています：
|
||||
@@ -109,6 +114,8 @@
|
||||
| `env.ANTHROPIC_BASE_URL` | API エンドポイント（任意） |
|
||||
| `env.ANTHROPIC_AUTH_TOKEN` | 代替認証方式 |
|
||||
|
||||
プロバイダーを切り替えるとき、CC Switch が変更するのは `settings.json` の主要フィールドだけです：`env` 内の `ANTHROPIC_*`、`AWS_*` などの接続・認証変数、`CLAUDE_CODE_USE_BEDROCK` のようなプロトコル選択、およびトップレベルの `model`、`apiKeyHelper` など。加えて、プロバイダーに付随する一部の互換オプション（`CLAUDE_CODE_DISABLE_ARTIFACT`、コンテキストウィンドウなど）も変更します。`permissions`、`hooks`、`enabledPlugins`、`statusLine` などその他の内容は変更されません。
|
||||
|
||||
### MCP 設定
|
||||
|
||||
MCP サーバーの設定は `~/.claude.json` にあります：
|
||||
@@ -142,7 +149,7 @@ MCP サーバーの設定は `~/.claude.json` にあります：
|
||||
|
||||
### auth.json
|
||||
|
||||
`auth.json` には OpenAI 公式の ChatGPT ログイン認証情報だけが保存され、Codex の `codex login` によって書き込まれます。サードパーティのプロバイダーに切り替えても、CC Switch はサードパーティの API Key をこのファイルに**書き込みません**。ローカルルーティングを使わずに直接切り替える場合、公式ログインを保持するかどうかは「設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持」で決まります（デフォルトはオフ、つまり `auth.json` を削除）。ローカルルーティングが有効な間は、公式ログインは常に保持されます。
|
||||
`auth.json` には OpenAI 公式の ChatGPT ログイン認証情報だけが保存され、Codex の `codex login` によって書き込まれます。サードパーティのプロバイダーに切り替えても、CC Switch はサードパーティの API Key をこのファイルに**書き込みません**。ローカルルーティングを使わずに直接切り替える場合、公式ログインを保持するかどうかは「設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持」で決まります（デフォルトはオフ、つまり `auth.json` を削除）。ローカルルーティングが有効な間は、公式ログインは常に保持されます。削除する前に、CC Switch はこのログインを `~/.cc-switch/codex-login-stash.json` に一時保存し、公式プロバイダーに戻したときにそのまま復元するため、再ログインは不要です。
|
||||
|
||||
### config.toml
|
||||
|
||||
@@ -163,7 +170,9 @@ command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
サードパーティプロバイダーの API Key は、対応する `[model_providers.<id>]` の `experimental_bearer_token` に書き込まれます。ローカルルーティングが有効な間は、プレースホルダー `PROXY_MANAGED` に置き換えられます。モデルマッピングを設定したプロバイダーでは、`cc-switch-model-catalog.json` を指す `model_catalog_json` も書き込まれます。
|
||||
サードパーティプロバイダーは常に `[model_providers.custom]` というテーブルに書き込まれ、API Key はこのテーブルの `experimental_bearer_token` にあります。ローカルルーティングが有効な間は、プレースホルダー `PROXY_MANAGED` に置き換えられます。モデルマッピングを設定したプロバイダーでは、`cc-switch-model-catalog.json` を指す `model_catalog_json` も書き込まれます。
|
||||
|
||||
プロバイダーを切り替えるとき、CC Switch が変更するのは `config.toml` の主要フィールドだけです：`model_provider`、`model`、推論レベルなどのトップレベルキーと `[model_providers.custom]` テーブル、および一部の互換オプション（`model_context_window`、`web_search` など）。`[mcp_servers]`、`[projects]`、自分で追加した他のプロバイダーテーブル、コメントや書式は変更されません。
|
||||
|
||||
## Gemini CLI の設定
|
||||
|
||||
@@ -204,6 +213,10 @@ GEMINI_MODEL=gemini-pro
|
||||
| フィールド | 説明 |
|
||||
|------|------|
|
||||
| `mcpServers` | MCP サーバー設定 |
|
||||
| `security.auth.selectedType` | 認証方式：Google 公式プロバイダーは `oauth-personal`、それ以外は `gemini-api-key` |
|
||||
| `model.name` | モデル名 |
|
||||
|
||||
プロバイダーを切り替えるとき、CC Switch が変更するのは `.env` の主要フィールドの行（`GEMINI_API_KEY`、`GEMINI_MODEL`、`GOOGLE_*` など）だけで、自分で追加した変数、コメント、行の順序は変更されません。`settings.json` で変更するのは `security.auth.selectedType` と `model.name` の 2 つのキーだけです。2 つのファイルは同じ操作の中でまとめて更新されます。
|
||||
|
||||
## OpenCode の設定
|
||||
|
||||
@@ -237,7 +250,9 @@ GEMINI_MODEL=gemini-pro
|
||||
└── sessions/ # セッションログ
|
||||
```
|
||||
|
||||
Grok Build は切り替え型アプリで、CC Switch はプロバイダーの切り替え時に `config.toml` を書き換えます。
|
||||
Grok Build は切り替え型アプリです。プロバイダーを切り替えるとき、CC Switch が変更するのは `config.toml` の `[models]` の `default` と、それが指す `[model."<名前>"]` テーブルだけです。`[mcp_servers]` や自分で追加した他のモデルテーブルは変更されません。
|
||||
|
||||
別のプロバイダーに切り替えるとき、CC Switch が削除するのは前回自分が書き込んだテーブル（テーブル名は `~/.cc-switch/live-state.json` に記録されています）で、`default` が現在どのテーブルを指しているかで削除対象を決めるわけではありません。そのため、Grok Build の `/settings` でデフォルトモデルを変更していても、切り替え時に自分で追加したテーブルを誤って削除したり、前のプロバイダーのテーブルを削除し忘れたりすることはありません。
|
||||
|
||||
## Hermes の設定
|
||||
|
||||
@@ -361,34 +376,41 @@ CC Switch は `models.json` に明示的に書かれたプロバイダーノー
|
||||
|
||||
CC Switch が管理するのは、`custom_provider` のうち `kind` が省略されているか `custom` のノードだけです。MiniMax の公式アカウントのノードは MiniMax Code 自身が管理します。MiniMax Code のデフォルトモデルから参照されているプロバイダーは、削除や無効化ができません。書き込む前に、CC Switch は MiniMax Code と互換性のあるディレクトリロック `config.yaml.lock` を取得します。
|
||||
|
||||
## 設定の優先順位
|
||||
## どの設定を誰が管理するか
|
||||
|
||||
CC Switch が設定を変更する際の優先順位：
|
||||
Claude Code、Codex、Gemini CLI、Grok Build の設定ファイルは、2 つの部分に分けて管理されます：
|
||||
|
||||
1. **CC Switch データベース** - 単一事実源 (SSOT)
|
||||
2. **Live 設定ファイル** - プロバイダー切り替え時に書き込み
|
||||
3. **バックフィル機能** - 現在のプロバイダーの編集時に Live ファイルから読み取り
|
||||
| 部分 | 含まれるもの | 保存場所 | 変更する人 |
|
||||
|------|------|----------|--------|
|
||||
| 主要フィールド | リクエスト先アドレス、Key、モデル名、API プロトコルなど、およびプロバイダーに付随する一部の互換オプション | CC Switch データベース内の各プロバイダー | 切り替え時に CC Switch が切り替え先プロバイダーの値に置き換える |
|
||||
| グローバル設定 | それ以外のすべての内容：プラグイン、Hook、権限、MCP、自分で追加した設定、コメント | ツール自身の設定ファイル | ユーザーとツール。CC Switch は編集パネルから変更したときだけ書き込む |
|
||||
|
||||
各アプリで具体的にどのキーを変更するかは、上の各アプリのセクションを参照してください。
|
||||
|
||||
## 手動での設定編集
|
||||
|
||||
### 手動編集可能なもの
|
||||
|
||||
- CLI ツールの設定ファイル（CC Switch がバックフィルする）
|
||||
- CC Switch の `settings.json`
|
||||
- **ツールの設定ファイル内のグローバル設定**：そのまま編集して構いません。プロバイダーを切り替えても変更されず、CC Switch に戻って同期する必要もありません。
|
||||
- **CC Switch の `settings.json`**
|
||||
|
||||
### 変更しても置き換えられるもの
|
||||
|
||||
- **ツールの設定ファイル内の主要フィールド**（アドレス、Key、モデルなど）：手動で変更した値は次の切り替えまで有効ですが、切り替え時に切り替え先プロバイダーの値に置き換えられ、CC Switch がプロバイダーに保存し直すことはありません。恒久的に変更したい場合は、CC Switch でそのプロバイダーを編集してください。
|
||||
|
||||
### 手動編集を推奨しないもの
|
||||
|
||||
- `cc-switch.db` データベースファイル
|
||||
- `live-state.json`、`codex-login-stash.json`
|
||||
- バックアップファイル
|
||||
|
||||
### 編集後の同期
|
||||
### 設定ファイルの形式に誤りがある場合
|
||||
|
||||
CLI ツールの設定を手動で編集した場合：
|
||||
CC Switch は設定ファイルを正しく読み込めるときだけ書き込みます。手動編集で設定ファイルが壊れた場合（JSON のカンマが抜けているなど）、切り替え時に「Cannot parse … (line N, column M) … Nothing was written, so your configuration is unchanged」と表示されます。解析できなかった位置と、設定を上書きしないよう今回は何も書き込まなかったことを示すメッセージで、すべてのファイルは元のままです。表示された位置を修正してから、もう一度切り替えてください。
|
||||
|
||||
1. CC Switch を開く
|
||||
2. 対応するプロバイダーを編集
|
||||
3. 手動変更の内容がバックフィルされていることを確認
|
||||
4. 保存してデータベースに同期
|
||||
### 初回書き込み前のバックアップ
|
||||
|
||||
CC Switch はツールの設定ファイルを初めて書き換える前に、元のファイルを `~/.cc-switch/backups/live-first-write/` にバックアップします。バックアップはファイルごとにこの 1 回だけです。アップグレード後に設定が想定と違っていた場合は、ここからアップグレード前の元のファイルを取り戻せます。
|
||||
|
||||
## 設定の移行
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
|------|------|
|
||||
| [2.1-add.md](./2-providers/2.1-add.md) | プリセットの使用、カスタム設定、統一プロバイダー |
|
||||
| [2.2-switch.md](./2-providers/2.2-switch.md) | メイン画面での切り替え、トレイでの切り替え、反映方法 |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | 設定の編集、API Key の変更、バックフィル機能 |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | 設定の編集、API Key の変更、グローバル設定と編集の競合 |
|
||||
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | ドラッグで並べ替え、プロバイダーの複製、削除 |
|
||||
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | 使用量クエリ、残額表示、複数プラン表示 |
|
||||
| [2.6-claude-desktop.md](./2-providers/2.6-claude-desktop.md) | Claude Desktop サードパーティプロバイダー、直結モード、モデルマッピング |
|
||||
|
||||
Reference in new issue
Block a user