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 changes take effect immediately without restarting.

Theme Settings

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

"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.

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:

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):

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:

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 for details.

Failover

Configure failover queues and automatic switching strategies by app (Claude/Codex/Gemini). See 4.3 Failover 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

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

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.

Operations

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

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:

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.

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:

Click the "Refresh" button to re-detect.

One-click Install Commands

Provides quick commands to install/update CLI tools:

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.