mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-30 02:14:43 +08:00
Jason
a058ebeafc
Refresh the user manual to cover the v3.13.0 feature set so users can discover and correctly use new functionality without cross-referencing the release notes. All three language versions are updated line-by-line symmetric. Highlights: - Lightweight Mode: tray-only running state added in 1.5-settings, with a comparison table against "Minimize to tray" and a new OAuth Auth Center (Beta) section - Quota & Balance display restructured in 2.5-usage-query: split into auto-query (Claude/Codex/Gemini official, Copilot, Codex OAuth) vs manual-enable (Token Plan, third-party balances). Explains why manual enabling is required: the same API URL may expose both plan-quota and balance query modes - Codex OAuth reverse proxy: full usage guide in 2.1-add with two entry points (Add Provider panel / OAuth Auth Center), Device Code login flow, token auto-refresh, multi-account management, quota display, common failures, and risk notice - Full URL Endpoint Mode: new advanced option in 2.1-add - Per-app tray submenus: 2.2-switch refactored to reflect the 5-app submenu structure and cross-link to Lightweight Mode - Skills workflow: remove obsolete "automatic update not supported" section in 3.3-skills, add SHA-256 update detection, single/batch update, storage location switch, and skills.sh registry search - Directory picker for Claude terminal resume in 3.4-sessions - Usage stats in 4.4-usage: document the new CLI session log source (no proxy required) and per-app filtering for Claude/Codex/Gemini; note CNY->USD pricing corrections and MiniMax quota fixes - Stream Check coverage extended to OpenCode/OpenClaw in 4.5-model-test - New FAQs in 5.2-questions: quota visibility (auto vs manual), Codex OAuth risks and login flow, deep link wake in Lightweight Mode - v3.13.0 highlights navigation block added to top-level README and each per-language README; version bumped to v3.13.0 / 2026-04-08
333 lines
12 KiB
Markdown
333 lines
12 KiB
Markdown
# 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.
|