# 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 three languages:

| Language | Description |
|----------|-------------|
| Simplified Chinese | Default language |
| 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, Codex, Gemini, OpenCode, OpenClaw.

> **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 | `~/.opencode/` | OpenCode configuration directory |
| OpenClaw Directory | `~/.openclaw/` | OpenClaw 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 backup file containing:

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

The backup file is in JSON format and can be viewed with a text editor.

### 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 two 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 |

**What you can do here**:

- Log in to ChatGPT / GitHub 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

> **Note**: Both features use reverse-engineered OAuth flows and carry account risk and Terms of Service risk. Before using, please read the full risk notice in [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 |

Click the "Refresh" button to re-detect.

### One-click Install Commands

Provides quick commands to install/update CLI tools:

```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@latest
npm i -g openclaw@latest
```

Click the "Copy" button to copy to clipboard.