# 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](../1-getting-started/1.5-settings.md).

![image-20260108004348993](../../assets/image-20260108004348993.png)

## 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:
```json
{
  "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.