# 1.5 Personalization

This section describes how to configure CC Switch according to your preferences.

## Open Settings

- Click the **gear** button in the top-left corner
- Or use the shortcut `Cmd/Ctrl + ,`

## Language Settings

CC Switch supports four languages:

| Language | Description |
|----------|-------------|
| Simplified Chinese | Default language |
| Traditional Chinese | Traditional Chinese interface |
| English | English interface |
| Japanese | Japanese interface |

Language changes take effect immediately without restarting.

## Theme Settings

| Option | Description |
|--------|-------------|
| System | Automatically matches the system's dark/light mode |
| Light | Always use the light theme |
| Dark | Always use the dark theme |

## Window Behavior

### Launch on Startup

When enabled, CC Switch automatically runs when the system starts.

- **Windows**: Implemented via the registry
- **macOS**: Implemented via LaunchAgent
- **Linux**: Implemented via XDG autostart

### Close Behavior

| Option | Description |
|--------|-------------|
| Minimize to tray | Clicking the close button hides to the system tray |
| Exit directly | Clicking the close button fully exits the app |

"Minimize to tray" is recommended for convenient provider switching via the tray.

### Lightweight Mode

Starting from v3.13.0, CC Switch adds **Lightweight Mode** — a **tray-only** running state that minimizes desktop footprint when idle.

**How to enter**: Right-click the tray icon → click **Lightweight Mode**. The main window is **destroyed** (not just hidden), freeing UI resources and memory.

**How to exit**: Click **Open Main Window** from the tray menu, or trigger CC Switch via deep link / relaunch. The window is **rebuilt on demand**, with state preserved.

| Aspect | Minimize to Tray | Lightweight Mode |
|--------|------------------|------------------|
| UI process | Kept in memory | Fully destroyed |
| Idle resource footprint | Same as normal run | Near zero |
| Reopen speed | Instant (direct show) | Slightly slower (window rebuild) |
| Tray switching | Available | Available |
| Deep link wake | Available | Available (on-demand rebuild) |

> **Use case**: If CC Switch runs in the background for long periods and you mainly switch providers via the tray menu, enabling Lightweight Mode significantly reduces memory usage.

> **Note**: Lightweight Mode state is not persistent — the next normal launch returns to normal mode. Combine with Launch on Startup for long-term use.

### Claude Plugin Integration

When enabled, CC Switch automatically syncs the configuration to the VS Code Claude Code extension (writes `primaryApiKey` to `~/.claude/config.json`) when switching providers.

> **Use case**: If you use both Claude Code CLI and the VS Code extension, enable this option to keep both configurations in sync.

### Skip Claude Onboarding

When enabled, skips the Claude Code onboarding flow, suitable for users already familiar with Claude Code.

> **Note**: This option writes the `skipIntroduction` field to `~/.claude/settings.json`.

### App Visibility

Choose which applications to display in the app switcher. Each app can be toggled independently, but at least one must remain visible.

Configurable apps: Claude, Claude Desktop, Codex, Gemini, OpenCode, OpenClaw, Hermes.

> **Use case**: If you only use Claude Code and Codex CLI, you can hide the other apps to keep the interface clean.

### Skill Sync Method

Set the sync method when installing skills to each app's directory:

| Method | Description |
|--------|-------------|
| Symlink | Creates symbolic links pointing to skill source files; saves space, syncs in real-time |
| Copy | Copies skill files entirely to the target directory |

> **Recommended**: Symlink is the default method. Switch to Copy if you encounter permission issues.

### Terminal Settings

Choose the terminal application that CC Switch uses when opening a terminal.

Supported terminals (by platform):

| Platform | Terminal Options |
|----------|-----------------|
| macOS | Terminal, iTerm2, Alacritty, Kitty, Ghostty, WezTerm |
| Windows | CMD, PowerShell, Windows Terminal |
| Linux | GNOME Terminal, Konsole, Xfce4 Terminal, Alacritty, Kitty, Ghostty |

## Directory Configuration

### App Configuration Directory

The storage location for CC Switch's own data, defaulting to `~/.cc-switch/`.

### CLI Tool Directories

You can customize each CLI tool's configuration directory:

| Setting | Default | Description |
|---------|---------|-------------|
| Claude Directory | `~/.claude/` | Claude Code configuration directory |
| Codex Directory | `~/.codex/` | Codex configuration directory |
| Gemini Directory | `~/.gemini/` | Gemini CLI configuration directory |
| OpenCode Directory | `~/.config/opencode/` | OpenCode configuration directory |
| OpenClaw Directory | `~/.openclaw/` | OpenClaw configuration directory |
| Hermes Directory | `~/.hermes/` | Hermes configuration directory |

> **Note**: After changing directories, the app must be restarted, and the corresponding CLI tools must also be configured to use the same directory.

## Data Management

### Export Configuration

Click the "Export" button to save a SQL backup file containing:

- All provider configurations
- MCP server configurations
- Prompt presets
- Usage logs
- App settings

The exported file name format is `cc-switch-export-{timestamp}.sql`.

### Import Configuration

1. Click "Select File"
2. Select a previously exported backup file
3. Click "Import"
4. Confirm to overwrite existing configuration

> **Note**: Importing will overwrite existing configuration. It is recommended to export your current configuration as a backup first.

## Proxy Settings

Settings > Proxy Tab

The Proxy tab centralizes all proxy-related features:

### Local Proxy

Start/stop the local proxy service, configure the listen address and port. See [4.1 Proxy Service](../4-proxy/4.1-service.md) for details.

### Failover

Configure failover queues and automatic switching strategies by app (Claude/Codex/Gemini). See [4.3 Failover](../4-proxy/4.3-failover.md) for details.

### Pricing Rectifier

Configure model pricing correction rules for proxy billing statistics calibration.

### Global Outbound Proxy

Configure CC Switch's outbound HTTP/HTTPS proxy, applicable for scenarios where external API access requires a proxy.

## Advanced Settings

Settings > Advanced Tab

### Configuration Directories

Customize configuration file directories for each app. See the "Directory Configuration" section above for details.

### Data Management

Import/export configuration backups. See the "Data Management" section above for details.

### Backup & Restore

The Backup Management panel provides full control over database backups.

#### Auto-Backup Settings

| Setting | Options | Default |
|---------|---------|---------|
| Backup Interval | Disabled, 6h, 12h, 24h, 48h, 7d | 24 hours |
| Retention Count | 3, 5, 10, 15, 20, 30, 50 | 10 backups |

When an interval is set, CC Switch automatically backs up the database on schedule. Older backups beyond the retention count are automatically removed.

#### Backup List

The panel displays all existing backups with:
- **Display name** (auto-generated from timestamp, e.g., `db_backup_20260315_143000`)
- **Creation time**
- **File size** (e.g., "1.5 MB")

#### Backup Operations

| Action | Description |
|--------|-------------|
| **Backup Now** | Create a backup immediately |
| **Restore** | Restore the database from a selected backup. A safety backup of the current database is created automatically before restoring |
| **Rename** | Change the backup's display name |
| **Delete** | Permanently remove a backup (with confirmation) |

> **Important**: Restoring a backup overwrites the current database. A safety backup is always created before the restore operation, so you can recover if needed.

### Cloud Sync (WebDAV)

Sync configurations across multiple devices via the WebDAV protocol. Uses **v2 protocol** with dual-layer versioning for improved reliability.

| Setting | Description |
|---------|-------------|
| Service Preset | Jianguoyun / Nextcloud / Synology / Custom |
| Server URL | WebDAV server URL |
| Username | Login username |
| Password | Login password (app-specific password; saved credentials are preserved if left unchanged) |
| Remote Directory | Remote storage path (default: `cc-switch-sync`) |
| Profile Name | Device profile name (default: `default`) |
| Auto Sync | Enable automatic synchronization on a configurable interval |

#### Operations

| Action | Description |
|--------|-------------|
| **Test Connection** | Verify WebDAV URL, username, and password are valid |
| **Upload** | Upload local database to remote. Shows progress spinner |
| **Download** | Download remote database. Shows remote snapshot info (protocol version, DB version, timestamp, size) before confirming. A safety backup of the local database is created automatically before overwriting |

#### Auto-Sync

When **Auto Sync** is enabled:
- A confirmation dialog is shown on first activation
- CC Switch automatically syncs the database to WebDAV at the configured interval
- Sync status is displayed in the panel

#### Remote Snapshot Info

Before downloading, CC Switch displays details about the remote snapshot:
- Protocol version (v2)
- Database compatibility version
- Timestamp of the remote backup
- File size
- Compatibility status (warning if incompatible)

> **Note**: Upload overwrites remote data, and download overwrites local data. A safety backup is always created before downloading.

### Log Configuration

| Setting | Description |
|---------|-------------|
| Enable Logging | Enable/disable application logging |
| Log Level | error / warn / info / debug / trace |

Log level descriptions:

- **error** - Critical errors only
- **warn** - Warnings and errors
- **info** - General information (recommended)
- **debug** - Detailed debugging information
- **trace** - All verbose information

## OAuth Auth Center (Beta)

Settings > **OAuth Auth Center** Tab

Added in v3.13.0, the **OAuth Auth Center** (Beta) provides unified management for third-party OAuth credentials. It currently supports three account types:

| Account Type              | Purpose                                                    |
| ------------------------- | ---------------------------------------------------------- |
| **GitHub Copilot**        | Used with the Copilot reverse proxy                        |
| **ChatGPT (Codex OAuth)** | Used with the Codex OAuth reverse proxy; manage ChatGPT accounts |
| **xAI (Grok OAuth)**      | Used with the xAI Responses API reverse proxy                   |

**What you can do here**:

- Log in to ChatGPT / GitHub / xAI accounts via the Device Code flow
- View the list of logged-in accounts and authentication status
- Set a default account when managing multiple accounts
- Remove individual accounts or log out all accounts at once

The xAI integration uses the OAuth 2.0 Device Authorization Grant, not a loopback callback. Its network contract is explicit:

| Dependency | Endpoint |
| ---------- | -------- |
| OpenID discovery | `https://auth.x.ai/.well-known/openid-configuration` |
| Device authorization | `device_authorization_endpoint` from discovery (currently `https://auth.x.ai/oauth2/device/code`) |
| Token exchange / refresh | `token_endpoint` from discovery (currently `https://auth.x.ai/oauth2/token`) |
| Inference | `https://api.x.ai/v1/responses` |
| Model discovery | `https://api.x.ai/v1/models` |

There is no local callback port. Authentication and model requests use CC Switch's global outbound proxy configuration.

The xAI integration does **not** use an OAuth application registered to CC Switch. It reuses the public OAuth client identity and scopes registered for the official Grok CLI (`client_id: b1a00492-073a-47ea-816f-4c329264a828`, including `grok-cli:access`) to obtain account-backed API access.

> **Warning**: These account-backed reverse proxies use reverse-engineered OAuth integrations and carry account and Terms of Service risk. Reusing an upstream product's OAuth client may be unsupported and may cause the provider to restrict or suspend the account. Review the applicable provider terms and use these features at your own risk. For the existing Codex flow, also read [2.1 Add Provider → Codex OAuth Reverse Proxy](../2-providers/2.1-add.md#codex-oauth-reverse-proxy-claude-provider).

## About Page

Settings > About Tab

### Version Information

Displays the current CC Switch version number, with support for:

- Viewing release notes
- Checking for updates
- Downloading and installing new versions

### Local Environment Check

Automatically detects installed CLI tool versions:

| Tool | Detection Contents |
|------|-------------------|
| Claude | Current version, latest version |
| Codex | Current version, latest version |
| Gemini | Current version, latest version |
| OpenCode | Current version, latest version |
| OpenClaw | Current version, latest version |
| Hermes | Current version, latest version |

Click the "Refresh" button to re-detect. When an update is available, you can update a single tool or use "Update All". Missing tools show an install button. Installs and updates run silently in the background—the button shows progress and versions refresh automatically when done.

### Manual Install Commands

Provides quick commands to install/update CLI tools (collapsed by default; click the heading to expand):

```bash
npm i -g @anthropic-ai/claude-code@latest
npm i -g @openai/codex@latest
npm i -g @google/gemini-cli@latest
npm i -g opencode-ai@latest
npm i -g openclaw@latest
python3 -m pip install --upgrade "hermes-agent[web]"
```

Click the "Copy" button to copy to clipboard.
