Skip to content

2.2-switch.md

Latest commit

 

History

History
127 lines (81 loc) · 3.68 KB

2.2-switch.md

File metadata and controls

127 lines (81 loc) · 3.68 KB
Raw

2.2 Switch Provider

Switch from Main Interface

In the provider list, click the "Enable" button on the target provider card.

Switching Flow

  1. Click the "Enable" button
  2. CC Switch updates the configuration file
  3. The card status changes to "Currently Active"
  4. Claude/Gemini take effect immediately, Codex requires a terminal restart

Status Indicators

Status Display Description
Currently Active Blue border + label Current provider in the configuration file
Proxy Active Green border Provider actually in use during proxy mode
Normal Default style Inactive provider

Quick Switch via System Tray

Quickly switch providers via the system tray without opening the main interface.

Steps

  1. Right-click the CC Switch icon in the system tray
  2. Hover over the corresponding app submenu (e.g., "Claude · CurrentProvider")
  3. Click the provider name you want to switch to
  4. Switching completes with a brief tray notification

Tray Menu Structure

Starting from v3.13.0, the tray menu is refactored from a flat list into per-app submenus, with a dedicated submenu for each app:

Submenu Description
Claude All Claude providers (including Codex OAuth reverse proxy)
Codex All Codex providers
Gemini All Gemini providers

Benefits of the refactor:

  • Prevents menu overflow: With many providers, a flat list would exceed screen height; per-app submenus scale naturally
  • Submenu title shows the currently active provider and usage summary: You know at a glance which provider Claude / Codex / Gemini is using, plus available cached usage information, without opening the submenu
  • Per-app isolation: Switching Claude's provider doesn't disturb the Codex or Gemini view

Tip: The combination of background residency + Lightweight Mode + per-app submenus is especially suited for heavy users who frequently switch among multiple apps. See 1.5 Personalization → Lightweight Mode.

image-20260108004348993

Activation Methods

Claude Code

Takes effect immediately after switching, no restart needed.

Claude Code supports hot reload and automatically detects configuration file changes and reloads.

Codex

Requires restart after switching:

  • Close the current terminal window
  • Reopen the terminal

Gemini CLI

Takes effect immediately after switching, no restart needed.

Gemini CLI re-reads the .env file on each request.

Configuration File Changes

When switching providers, CC Switch modifies the following files:

Claude

~/.claude/settings.json

Modified content:

{
  "env": {
    "ANTHROPIC_API_KEY": "new API Key",
    "ANTHROPIC_BASE_URL": "new endpoint"
  }
}

Codex

~/.codex/auth.json
~/.codex/config.toml (if additional configuration exists)

Gemini

~/.gemini/.env
~/.gemini/settings.json

Handling Switch Failures

If switching fails, possible reasons:

Configuration File Is Locked

Another program is using the configuration file.

Solution: Close the running CLI tool and try switching again.

Insufficient Permissions

No write permission to the configuration file.

Solution: Check the permission settings of the configuration directory.

Invalid Configuration Format

The provider's JSON configuration has format errors.

Solution: Edit the provider, check and fix the JSON format.