mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-04 11:43:57 +08:00
docs: restructure user manual for i18n and add EN/JA translations
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
This commit is contained in:
Jason
@@ -0,0 +1,65 @@
|
||||
# 1.1 Introduction
|
||||
|
||||
## What is CC Switch
|
||||
|
||||
CC Switch is a cross-platform desktop application designed for developers who use AI coding tools. It helps you centrally manage configurations for five major AI coding tools: **Claude Code**, **Codex**, **Gemini CLI**, **OpenCode**, and **OpenClaw**.
|
||||
|
||||
## What Problems Does It Solve
|
||||
|
||||
In your daily development workflow, you may encounter these pain points:
|
||||
|
||||
- **Tedious multi-provider switching**: Using different API providers (official, proxy services) requires manually editing configuration files
|
||||
- **Scattered configurations**: Claude, Codex, Gemini, OpenCode, and OpenClaw each have independent configuration files in different formats
|
||||
- **No usage monitoring**: No visibility into how many API calls were made or how much they cost
|
||||
- **Service instability**: When a single provider goes down, your entire workflow is interrupted
|
||||
|
||||
CC Switch solves these problems through a unified interface.
|
||||
|
||||
## Core Features
|
||||
|
||||
### Provider Management
|
||||
- One-click switching between multiple API provider configurations
|
||||
- Preset templates for quickly adding common providers
|
||||
- Universal provider feature for sharing configurations across apps
|
||||
- Usage query and balance display
|
||||
- Endpoint speed testing
|
||||
|
||||
### Extensions
|
||||
- **MCP Servers**: Manage Model Context Protocol servers to extend AI capabilities
|
||||
- **Prompts**: Manage system prompt presets for quick scenario switching
|
||||
- **Skills**: Install and manage skill extensions
|
||||
|
||||
### Proxy & High Availability
|
||||
- Local proxy service for request logging and usage statistics
|
||||
- Automatic failover that switches to a backup provider when the primary one fails
|
||||
- Circuit breaker mechanism to prevent repeated retries against failing providers
|
||||
- Detailed token usage tracking and cost estimation
|
||||
|
||||
## Supported Applications
|
||||
|
||||
| Application | Description |
|
||||
|-------------|-------------|
|
||||
| **Claude Code** | Anthropic's official AI coding assistant |
|
||||
| **Codex** | OpenAI's code generation tool |
|
||||
| **Gemini CLI** | Google's AI command-line tool |
|
||||
| **OpenCode** | Open-source AI coding terminal tool |
|
||||
| **OpenClaw** | Open-source AI coding assistant (multi-provider gateway) |
|
||||
|
||||
## Supported Platforms
|
||||
|
||||
- **Windows** 10 and above
|
||||
- **macOS** 10.15 (Catalina) and above
|
||||
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
CC Switch is built with a modern technology stack:
|
||||
|
||||
- **Frontend**: React 18 + TypeScript + Tailwind CSS
|
||||
- **Backend**: Tauri 2 + Rust
|
||||
- **Data Storage**: SQLite (providers, MCP, Prompts) + JSON (device settings)
|
||||
|
||||
This architecture ensures:
|
||||
- Consistent cross-platform experience
|
||||
- Native-level performance
|
||||
- Secure local data storage
|
||||
@@ -0,0 +1,229 @@
|
||||
# 1.2 Installation Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Install Node.js
|
||||
|
||||
The CLI tools managed by CC Switch (Claude Code, Codex, Gemini CLI) require a Node.js environment.
|
||||
|
||||
**Recommended version**: Node.js 18 LTS or higher
|
||||
|
||||
#### Windows
|
||||
|
||||
1. Visit the [Node.js official website](https://nodejs.org/)
|
||||
|
||||
2. Download the LTS version installer
|
||||
|
||||
3. Run the installer and follow the prompts
|
||||
|
||||
4. Verify installation:
|
||||
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
```
|
||||
|
||||
#### macOS
|
||||
|
||||
```bash
|
||||
# Install with Homebrew
|
||||
brew install node
|
||||
|
||||
# Or use nvm (recommended)
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
nvm install --lts
|
||||
```
|
||||
|
||||
#### Linux
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Or use nvm
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
|
||||
nvm install --lts
|
||||
```
|
||||
|
||||
### Install CLI Tools
|
||||
|
||||
#### Claude Code
|
||||
|
||||
**Option 1: Homebrew (recommended for macOS)**
|
||||
|
||||
```bash
|
||||
brew install claude-code
|
||||
```
|
||||
|
||||
**Option 2: npm**
|
||||
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
#### Codex
|
||||
|
||||
**Option 1: Homebrew (recommended for macOS)**
|
||||
|
||||
```bash
|
||||
brew install codex
|
||||
```
|
||||
|
||||
**Option 2: npm**
|
||||
|
||||
```bash
|
||||
npm install -g @openai/codex
|
||||
```
|
||||
|
||||
#### Gemini CLI
|
||||
|
||||
**Option 1: Homebrew (recommended for macOS)**
|
||||
|
||||
```bash
|
||||
brew install gemini-cli
|
||||
```
|
||||
|
||||
**Option 2: npm**
|
||||
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Windows
|
||||
|
||||
### Installer
|
||||
|
||||
1. Visit the [Releases page](https://github.com/farion1231/cc-switch/releases)
|
||||
2. Download `CC-Switch-v{version}-Windows.msi`
|
||||
3. Double-click to run the installer
|
||||
4. Follow the prompts to complete installation
|
||||
|
||||
### Portable Version (No Installation Required)
|
||||
|
||||
1. Download `CC-Switch-v{version}-Windows-Portable.zip`
|
||||
2. Extract to any directory
|
||||
3. Run `CC-Switch.exe`
|
||||
|
||||
## macOS
|
||||
|
||||
### Option 1: Homebrew (Recommended)
|
||||
|
||||
```bash
|
||||
# Add tap
|
||||
brew tap farion1231/ccswitch
|
||||
|
||||
# Install
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update to the latest version:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Option 2: Manual Download
|
||||
|
||||
1. Download `CC-Switch-v{version}-macOS.zip`
|
||||
2. Extract to get `CC Switch.app`
|
||||
3. Drag it to the Applications folder
|
||||
|
||||
### First Launch Warning
|
||||
|
||||
Since the developer does not have an Apple Developer account, a "developer cannot be verified" warning may appear on first launch:
|
||||
|
||||
**Recommended solution**:
|
||||
Open Terminal and run the following command:
|
||||
```bash
|
||||
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
||||
```
|
||||
|
||||
**Alternative solution (via System Settings)**:
|
||||
1. Close the warning dialog
|
||||
2. Open "System Settings" > "Privacy & Security"
|
||||
3. Find the CC Switch prompt and click "Open Anyway"
|
||||
4. Reopen the app to use it normally
|
||||
|
||||
## Linux
|
||||
|
||||
### ArchLinux
|
||||
|
||||
Install using an AUR helper:
|
||||
|
||||
```bash
|
||||
# Using paru
|
||||
paru -S cc-switch-bin
|
||||
|
||||
# Or using yay
|
||||
yay -S cc-switch-bin
|
||||
```
|
||||
|
||||
### Debian / Ubuntu
|
||||
|
||||
1. Download `CC-Switch-v{version}-Linux.deb`
|
||||
2. Install:
|
||||
|
||||
```bash
|
||||
sudo dpkg -i CC-Switch-v{version}-Linux.deb
|
||||
|
||||
# If there are dependency issues
|
||||
sudo apt-get install -f
|
||||
```
|
||||
|
||||
### AppImage (Universal)
|
||||
|
||||
1. Download `CC-Switch-v{version}-Linux.AppImage`
|
||||
2. Add execute permission:
|
||||
|
||||
```bash
|
||||
chmod +x CC-Switch-v{version}-Linux.AppImage
|
||||
```
|
||||
|
||||
3. Run:
|
||||
|
||||
```bash
|
||||
./CC-Switch-v{version}-Linux.AppImage
|
||||
```
|
||||
|
||||
## Verify Installation
|
||||
|
||||
After installation, launch CC Switch:
|
||||
|
||||
1. The app window displays correctly
|
||||
2. A CC Switch icon appears in the system tray
|
||||
3. You can switch between Claude / Codex / Gemini apps
|
||||
|
||||
## Auto Update
|
||||
|
||||
CC Switch includes built-in auto-update functionality:
|
||||
|
||||
- Automatically checks for updates on startup
|
||||
- Displays an update prompt in the UI when a new version is available
|
||||
- Click to download and install
|
||||
|
||||
You can also manually check for updates in "Settings > About".
|
||||
|
||||
## Uninstall
|
||||
|
||||
### Windows
|
||||
|
||||
- Uninstall via "Settings > Apps"
|
||||
- Or run the uninstaller in the installation directory
|
||||
|
||||
### macOS
|
||||
|
||||
- Move `CC Switch.app` to Trash
|
||||
- Optional: Delete the configuration directory `~/.cc-switch/`
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
sudo apt remove cc-switch
|
||||
|
||||
# ArchLinux
|
||||
paru -R cc-switch-bin
|
||||
```
|
||||
@@ -0,0 +1,170 @@
|
||||
# 1.3 Interface Overview
|
||||
|
||||
## Main Interface Layout
|
||||
|
||||
|
||||
|
||||
## Top Navigation Bar
|
||||
|
||||
| # | Element | Description |
|
||||
|---|---------|-------------|
|
||||
| 1 | Logo | Click to visit the GitHub project page |
|
||||
| 2 | Settings Button | Open the settings page (shortcut `Cmd/Ctrl + ,`) |
|
||||
| 3 | Proxy Toggle | Start/stop the local proxy service |
|
||||
| 4 | App Switcher | Switch between Claude / Codex / Gemini / OpenCode / OpenClaw |
|
||||
| 5 | Feature Area | Skills / Prompts / MCP entry points |
|
||||
| 6 | Add Button | Add a new provider |
|
||||
|
||||
### App Switcher
|
||||
|
||||
Click the dropdown menu to switch the currently managed application:
|
||||
|
||||
- **Claude** - Manage Claude Code configuration
|
||||
- **Codex** - Manage Codex configuration
|
||||
- **Gemini** - Manage Gemini CLI configuration
|
||||
- **OpenCode** - Manage OpenCode configuration
|
||||
- **OpenClaw** - Manage OpenClaw configuration
|
||||
|
||||
After switching, the provider list displays the configurations for the selected application.
|
||||
|
||||
### Feature Area Buttons
|
||||
|
||||
| Button | Function | Visibility |
|
||||
|--------|----------|------------|
|
||||
| Skills | Skill extension management | Always visible |
|
||||
| Prompts | System prompt management | Always visible |
|
||||
| MCP | MCP server management | Always visible |
|
||||
|
||||
## Provider Cards
|
||||
|
||||
Each provider is displayed as a card, containing the following elements from left to right:
|
||||
|
||||
### Card Elements (Left to Right)
|
||||
|
||||
| # | Element | Icon | Description |
|
||||
|---|---------|------|-------------|
|
||||
| 1 | Drag Handle | ≡ | Hold and drag up/down to reorder providers |
|
||||
| 2 | Provider Icon | - | Displays provider brand icon with customizable color |
|
||||
| 3 | Provider Info | - | Name, notes/endpoint URL (clickable to open website) |
|
||||
| 4 | Usage Info | - | Shows remaining balance; displays plan count for multi-plan |
|
||||
| 5 | Enable Button | - | Switch to this provider |
|
||||
| 6 | Edit Button | - | Edit provider configuration |
|
||||
| 7 | Duplicate Button | - | Duplicate provider (create a copy) |
|
||||
| 8 | Speed Test Button | - | Test model availability and response speed |
|
||||
| 9 | Usage Query | - | Configure usage query script |
|
||||
| 10 | Delete Button | - | Delete provider (disabled when currently active) |
|
||||
|
||||
> **Tip**: The action buttons area (5-10) appears on hover and is hidden by default to keep the interface clean.
|
||||
|
||||
### Button Details
|
||||
|
||||
| Button | State Changes | Notes |
|
||||
|--------|---------------|-------|
|
||||
| **Enable** | Shows checkmark and disables when active | Changes to "Join/Joined" in failover mode |
|
||||
| **Edit** | Always available | Opens edit panel to modify configuration |
|
||||
| **Duplicate** | Always available | Creates a copy with `copy` suffix |
|
||||
| **Speed Test** | Shows loading animation during test | Only available when proxy service is running |
|
||||
| **Usage Query** | Always available | Configure custom usage query script |
|
||||
| **Delete** | Semi-transparent/disabled when active | Must switch to another provider first |
|
||||
|
||||
### Card States
|
||||
|
||||
| State | Border Color | Description |
|
||||
|-------|--------------|-------------|
|
||||
| **Currently Active** | Blue border | Current provider in normal mode |
|
||||
| **Proxy Active** | Green border | Provider actually in use during proxy takeover mode |
|
||||
| **Normal** | Default border | Inactive provider |
|
||||
| **In Failover** | Shows priority badge | e.g., P1, P2 indicates failover priority |
|
||||
|
||||
### Health Status Badges
|
||||
|
||||
In proxy mode, providers in the failover queue display health status:
|
||||
|
||||
| Badge | Color | Description |
|
||||
|-------|-------|-------------|
|
||||
| Healthy | Green | 0 consecutive failures |
|
||||
| Warning | Yellow | 1-2 consecutive failures |
|
||||
| Unhealthy | Red | 3+ consecutive failures, may trigger circuit breaker |
|
||||
|
||||
|
||||
## System Tray
|
||||
|
||||
CC Switch displays an icon in the system tray, providing quick access to operations.
|
||||
|
||||
### Tray Menu Structure
|
||||
|
||||
|
||||
|
||||
### Menu Functions
|
||||
|
||||
| Menu Item | Function |
|
||||
|-----------|----------|
|
||||
| Open Main Window | Show and focus the main window |
|
||||
| App Groups | Providers grouped by Claude/Codex/Gemini/OpenCode/OpenClaw |
|
||||
| Provider List | Click to switch; currently active one shows a checkmark |
|
||||
| Quit | Fully exit the application |
|
||||
|
||||
### Multi-language Support
|
||||
|
||||
The tray menu supports three languages, automatically switching based on settings:
|
||||
|
||||
| Language | Open Main Window | Quit |
|
||||
|----------|-----------------|------|
|
||||
| Chinese | Open Main Window | Quit |
|
||||
| English | Open main window | Quit |
|
||||
| Japanese | Open main window | Quit |
|
||||
|
||||
### Use Cases
|
||||
|
||||
Switching providers via the tray menu doesn't require opening the main window, suitable for:
|
||||
|
||||
- Frequently switching providers
|
||||
- Quick operations when the main window is minimized
|
||||
- Managing configurations while running in the background
|
||||
|
||||
## Settings Page
|
||||
|
||||
The settings page is divided into multiple tabs:
|
||||
|
||||
### General Tab
|
||||
|
||||
- Language settings (Chinese/English/Japanese)
|
||||
- Theme settings (System/Light/Dark)
|
||||
- Window behavior (launch on startup, close behavior)
|
||||
|
||||
### Advanced Tab
|
||||
|
||||
- Configuration directory settings
|
||||
- Proxy service configuration
|
||||
- Failover settings
|
||||
- Pricing configuration
|
||||
- Data import/export
|
||||
|
||||
### Usage Tab
|
||||
|
||||
- Request statistics overview
|
||||
- Trend charts
|
||||
- Request logs
|
||||
- Provider/model statistics
|
||||
|
||||
### About Tab
|
||||
|
||||
- Version information
|
||||
- Update check
|
||||
- Open source license
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Function |
|
||||
|----------|----------|
|
||||
| `Cmd/Ctrl + ,` | Open Settings |
|
||||
| `Cmd/Ctrl + F` | Search providers |
|
||||
| `Esc` | Close dialog/search |
|
||||
|
||||
## Search
|
||||
|
||||
Press `Cmd/Ctrl + F` to open the search bar:
|
||||
|
||||
- Search by name, notes, or URL
|
||||
- Real-time provider list filtering
|
||||
- Press `Esc` to close search
|
||||
@@ -0,0 +1,92 @@
|
||||
# 1.4 Quick Start
|
||||
|
||||
This section helps you complete the initial setup in 5 minutes.
|
||||
|
||||
## Step 1: Add a Provider
|
||||
|
||||
1. Click the **+** button in the top-right corner of the main interface
|
||||
2. Select your provider from the "Preset" dropdown
|
||||
- Common presets: Zhipu GLM, MiniMax, DeepSeek, Kimi, PackyCode
|
||||
- Or select "Custom" for manual configuration
|
||||
3. Enter your **API Key**
|
||||
4. Click "Add"
|
||||
|
||||
|
||||
|
||||
> **Tip**: Presets auto-fill the endpoint URL, so you only need to enter your API Key.
|
||||
|
||||
## Step 2: Switch Provider
|
||||
|
||||
After adding, the provider appears in the list.
|
||||
|
||||
**Option 1: Switch from the main interface**
|
||||
- Click the "Enable" button on the provider card
|
||||
|
||||
**Option 2: Quick switch via system tray**
|
||||
- Right-click the CC Switch icon in the system tray
|
||||
- Click the provider name directly
|
||||
|
||||
## Step 3: Activation
|
||||
|
||||
After switching providers, each CLI tool activates differently:
|
||||
|
||||
| Application | Activation Method |
|
||||
|-------------|-------------------|
|
||||
| Claude Code | Instant effect (supports hot reload) |
|
||||
| Codex | Requires closing and reopening the terminal |
|
||||
| Gemini | Instant effect (re-reads config on each request) |
|
||||
|
||||
### Claude Code First Launch Prompt
|
||||
|
||||
If Claude Code prompts you to **log in** or shows an onboarding wizard on first launch, enable the "Skip Claude Code first-run confirmation" option in CC Switch:
|
||||
|
||||
1. Open CC Switch "Settings > General"
|
||||
2. Enable the "Skip Claude Code first-run confirmation" toggle
|
||||
3. Restart Claude Code
|
||||
|
||||
|
||||
|
||||
> **Note**: This option writes the `skipIntroduction` field to `~/.claude/settings.json`, skipping the official onboarding flow.
|
||||
|
||||
## Verify Configuration
|
||||
|
||||
After restarting, launch the corresponding CLI tool and enter a simple question to test:
|
||||
|
||||
```bash
|
||||
# Claude Code - enter a test question after launching
|
||||
claude
|
||||
> Hello, please briefly introduce yourself
|
||||
|
||||
# Codex - enter a test question after launching
|
||||
codex
|
||||
> Hello, please briefly introduce yourself
|
||||
|
||||
# Gemini - enter a test question after launching
|
||||
gemini
|
||||
> Hello, please briefly introduce yourself
|
||||
```
|
||||
|
||||
If the AI responds normally, the configuration is successful.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Congratulations! You have completed the basic configuration. Next, you can:
|
||||
|
||||
- [Add more providers](../2-providers/2.1-add.md) - Configure multiple providers for easy switching
|
||||
- [Configure MCP servers](../3-extensions/3.1-mcp.md) - Extend AI tool capabilities
|
||||
- [Set up system prompts](../3-extensions/3.2-prompts.md) - Customize AI behavior
|
||||
- [Enable proxy service](../4-proxy/4.1-service.md) - Monitor usage and enable automatic failover
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Not taking effect after switching?
|
||||
|
||||
Make sure you restarted the terminal or CLI tool. The configuration file is updated at switch time, but running programs do not automatically reload it.
|
||||
|
||||
### Can't find a preset?
|
||||
|
||||
If your provider is not in the preset list, select "Custom" for manual configuration. See [Add Provider](../2-providers/2.1-add.md) for configuration format details.
|
||||
|
||||
### How to restore official login?
|
||||
|
||||
Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini), restart the client, and follow the login flow.
|
||||
@@ -0,0 +1,255 @@
|
||||
# 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](../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
|
||||
|
||||
Manage automatic backups:
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| Backup Interval | Time interval for automatic backups (hours) |
|
||||
| Retention Count | Number of backups to retain |
|
||||
|
||||
Supports viewing the backup list and restoring from backups.
|
||||
|
||||
### Cloud Sync (WebDAV)
|
||||
|
||||
Sync configurations across multiple devices via the WebDAV protocol.
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| Service Preset | Jianguoyun / Nextcloud / Synology / Custom |
|
||||
| Server URL | WebDAV server URL |
|
||||
| Username | Login username |
|
||||
| Password | Login password (app-specific password) |
|
||||
| Remote Directory | Remote storage path (default: `cc-switch-sync`) |
|
||||
| Profile Name | Device profile name (default: `default`) |
|
||||
| Auto Sync | Automatically upload changes when enabled |
|
||||
|
||||
Operations:
|
||||
|
||||
- **Test Connection**: Verify WebDAV configuration is correct
|
||||
- **Save**: Save configuration and auto-test
|
||||
- **Upload**: Upload local data to the remote server
|
||||
- **Download**: Download data from the remote server to local
|
||||
|
||||
> **Note**: Upload will overwrite remote data, and download will overwrite local data. Please confirm before proceeding.
|
||||
|
||||
### 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:
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user