CC-Switch/docs/user-manual/en/1-getting-started/1.5-settings.md

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.

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

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

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:

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.