mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-02 18:41:35 +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.
|
||||
@@ -0,0 +1,354 @@
|
||||
# 2.1 Add Provider
|
||||
|
||||
## Open the Add Panel
|
||||
|
||||
Click the **+** button in the top-right corner of the main interface to open the Add Provider panel.
|
||||
|
||||
The panel has two tabs:
|
||||
- **App-specific Provider**: Only for the currently selected app (Claude/Codex/Gemini/OpenCode/OpenClaw)
|
||||
- **Universal Provider**: Shared configuration across apps
|
||||
|
||||
## Add Using Presets
|
||||
|
||||
Presets are pre-configured provider templates that only require an API Key to use.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Select a provider from the "Preset" dropdown
|
||||
2. Name and endpoint are auto-filled
|
||||
3. Enter your **API Key**
|
||||
4. (Optional) Add notes
|
||||
5. Click "Add"
|
||||
|
||||
### Common Presets
|
||||
|
||||
#### Claude Presets
|
||||
|
||||
| Preset Name | Description |
|
||||
|-------------|-------------|
|
||||
| Claude Official | Log in with an Anthropic official account |
|
||||
| DeepSeek | DeepSeek model |
|
||||
| Zhipu GLM | Zhipu AI GLM model |
|
||||
| Zhipu GLM en | Zhipu AI (English version) |
|
||||
| Bailian | Alibaba Cloud Bailian (Qwen) |
|
||||
| Kimi | Moonshot Kimi model |
|
||||
| Kimi For Coding | Kimi coding-specific model |
|
||||
| ModelScope | ModelScope community |
|
||||
| KAT-Coder | KAT-Coder model |
|
||||
| Longcat | Longcat AI |
|
||||
| MiniMax | MiniMax model |
|
||||
| MiniMax en | MiniMax (English version) |
|
||||
| DouBaoSeed | DouBao Seed model |
|
||||
| BaiLing | BaiLing AI |
|
||||
| AiHubMix | AiHubMix aggregation service |
|
||||
| SiliconFlow | SiliconFlow |
|
||||
| SiliconFlow en | SiliconFlow (English version) |
|
||||
| DMXAPI | DMXAPI proxy service |
|
||||
| PackyCode | PackyCode proxy service |
|
||||
| Cubence | Cubence service |
|
||||
| AIGoCode | AIGoCode service |
|
||||
| RightCode | RightCode service |
|
||||
| AICodeMirror | AICodeMirror service |
|
||||
| OpenRouter | Aggregation routing service |
|
||||
| Nvidia | Nvidia AI service |
|
||||
| Xiaomi MiMo | Xiaomi MiMo model |
|
||||
|
||||
> The preset list may be updated with new versions. Refer to the actual list shown in the app.
|
||||
|
||||
#### Codex Presets
|
||||
|
||||
| Preset Name | Description |
|
||||
|-------------|-------------|
|
||||
| OpenAI Official | Log in with an OpenAI official account |
|
||||
| Azure OpenAI | Azure OpenAI service |
|
||||
| AiHubMix | AiHubMix aggregation service |
|
||||
| DMXAPI | DMXAPI proxy service |
|
||||
| PackyCode | PackyCode proxy service |
|
||||
| Cubence | Cubence service |
|
||||
| AIGoCode | AIGoCode service |
|
||||
| RightCode | RightCode service |
|
||||
| AICodeMirror | AICodeMirror service |
|
||||
| OpenRouter | Aggregation routing service |
|
||||
|
||||
#### Gemini Presets
|
||||
|
||||
| Preset Name | Description |
|
||||
|-------------|-------------|
|
||||
| Google Official | Log in with Google OAuth |
|
||||
| PackyCode | PackyCode proxy service |
|
||||
| Cubence | Cubence service |
|
||||
| AIGoCode | AIGoCode service |
|
||||
| AICodeMirror | AICodeMirror service |
|
||||
| OpenRouter | Aggregation routing service |
|
||||
| Custom | Manually configure all parameters |
|
||||
|
||||
#### OpenCode Presets
|
||||
|
||||
| Preset Name | Description |
|
||||
|-------------|-------------|
|
||||
| DeepSeek | DeepSeek model |
|
||||
| Zhipu GLM | Zhipu AI GLM model |
|
||||
| Zhipu GLM en | Zhipu AI (English version) |
|
||||
| Bailian | Alibaba Cloud Bailian |
|
||||
| Kimi k2.5 | Moonshot Kimi-k2.5 model |
|
||||
| Kimi For Coding | Kimi coding-specific model |
|
||||
| ModelScope | ModelScope community |
|
||||
| KAT-Coder | KAT-Coder model |
|
||||
| Longcat | Longcat AI |
|
||||
| MiniMax | MiniMax model |
|
||||
| MiniMax en | MiniMax (English version) |
|
||||
| DouBaoSeed | DouBao Seed model |
|
||||
| BaiLing | BaiLing AI |
|
||||
| Xiaomi MiMo | Xiaomi MiMo model |
|
||||
| AiHubMix | AiHubMix aggregation service |
|
||||
| DMXAPI | DMXAPI proxy service |
|
||||
| OpenRouter | Aggregation routing service |
|
||||
| Nvidia | Nvidia AI service |
|
||||
| PackyCode | PackyCode proxy service |
|
||||
| Cubence | Cubence service |
|
||||
| AIGoCode | AIGoCode service |
|
||||
| RightCode | RightCode service |
|
||||
| AICodeMirror | AICodeMirror service |
|
||||
| OpenAI Compatible | OpenAI-compatible interface |
|
||||
| Oh My OpenCode | Oh My OpenCode service |
|
||||
|
||||
> The preset list is continuously updated. Refer to the actual list shown in the app.
|
||||
|
||||
#### OpenClaw Presets
|
||||
|
||||
| Preset Name | Description |
|
||||
|-------------|-------------|
|
||||
| DeepSeek | DeepSeek model |
|
||||
| Zhipu GLM | Zhipu AI GLM model |
|
||||
| Zhipu GLM en | Zhipu AI (English version) |
|
||||
| Qwen Coder | Qwen coding model |
|
||||
| Kimi k2.5 | Moonshot Kimi-k2.5 model |
|
||||
| Kimi For Coding | Kimi coding-specific model |
|
||||
| MiniMax | MiniMax model |
|
||||
| MiniMax en | MiniMax (English version) |
|
||||
| KAT-Coder | KAT-Coder model |
|
||||
| Longcat | Longcat AI |
|
||||
| DouBaoSeed | DouBao Seed model |
|
||||
| BaiLing | BaiLing AI |
|
||||
| Xiaomi MiMo | Xiaomi MiMo model |
|
||||
| AiHubMix | AiHubMix aggregation service |
|
||||
| DMXAPI | DMXAPI proxy service |
|
||||
| OpenRouter | Aggregation routing service |
|
||||
| ModelScope | ModelScope community |
|
||||
| SiliconFlow | SiliconFlow |
|
||||
| SiliconFlow en | SiliconFlow (English version) |
|
||||
| Nvidia | Nvidia AI service |
|
||||
| PackyCode | PackyCode proxy service |
|
||||
| Cubence | Cubence service |
|
||||
| AIGoCode | AIGoCode service |
|
||||
| RightCode | RightCode service |
|
||||
| AICodeMirror | AICodeMirror service |
|
||||
| AICoding | AICoding service |
|
||||
| CrazyRouter | CrazyRouter service |
|
||||
| SSSAiCode | SSSAiCode service |
|
||||
| AWS Bedrock | AWS Bedrock service |
|
||||
| OpenAI Compatible | OpenAI-compatible interface |
|
||||
|
||||
## Custom Configuration
|
||||
|
||||
After selecting the "Custom" preset, you need to manually edit the JSON configuration.
|
||||
|
||||
### Claude Configuration Format
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "your-api-key",
|
||||
"ANTHROPIC_BASE_URL": "https://api.example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | Yes | API key |
|
||||
| `ANTHROPIC_BASE_URL` | No | Custom endpoint URL |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | No | Alternative authentication method to API_KEY |
|
||||
|
||||
### Codex Configuration Format
|
||||
|
||||
Codex uses two configuration files:
|
||||
|
||||
**1. auth.json** (`~/.codex/auth.json`) - Stores API key:
|
||||
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "your-api-key"
|
||||
}
|
||||
```
|
||||
|
||||
**2. config.toml** (`~/.codex/config.toml`) - Stores model and endpoint configuration:
|
||||
|
||||
```toml
|
||||
# Basic configuration
|
||||
model_provider = "custom"
|
||||
model = "gpt-5.2"
|
||||
model_reasoning_effort = "high"
|
||||
disable_response_storage = true
|
||||
|
||||
# Custom provider configuration
|
||||
[model_providers.custom]
|
||||
name = "custom"
|
||||
base_url = "https://api.example.com/v1"
|
||||
wire_api = "responses"
|
||||
requires_openai_auth = true
|
||||
```
|
||||
|
||||
**auth.json field descriptions**:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `OPENAI_API_KEY` | Yes | API key |
|
||||
|
||||
**config.toml field descriptions**:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `model_provider` | Yes | Model provider name (must match `[model_providers.xxx]`) |
|
||||
| `model` | Yes | Model to use (e.g., `gpt-5.2`, `gpt-4o`) |
|
||||
| `model_reasoning_effort` | No | Reasoning effort: `low` / `medium` / `high` |
|
||||
| `disable_response_storage` | No | Whether to disable response storage |
|
||||
| `base_url` | Yes | API endpoint URL |
|
||||
| `wire_api` | No | API protocol type (usually `responses`) |
|
||||
| `requires_openai_auth` | No | Whether to use OpenAI authentication |
|
||||
|
||||
|
||||
### Gemini Configuration Format
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"GEMINI_API_KEY": "your-api-key",
|
||||
"GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `GEMINI_API_KEY` | Yes | API key |
|
||||
| `GOOGLE_GEMINI_BASE_URL` | No | Custom endpoint URL |
|
||||
| `GEMINI_MODEL` | No | Specify model |
|
||||
|
||||
> Authentication type is automatically detected by CC Switch (PackyCode API proxy / Google OAuth / generic API Key), no manual configuration needed.
|
||||
|
||||
## Universal Provider
|
||||
|
||||
Universal providers can share configurations across Claude/Codex/Gemini/OpenCode/OpenClaw, suitable for proxy services that support multiple API formats.
|
||||
|
||||
### Create a Universal Provider
|
||||
|
||||
1. Switch to the "Universal Provider" tab
|
||||
2. Click "Add Universal Provider"
|
||||
3. Fill in the common configuration:
|
||||
- Name
|
||||
- API Key
|
||||
- Endpoint URL
|
||||
4. Check the apps to sync to (Claude/Codex/Gemini/OpenCode/OpenClaw)
|
||||
5. Save
|
||||
|
||||
### Sync Mechanism
|
||||
|
||||
Universal providers automatically sync to the selected apps:
|
||||
|
||||
- After modifying a universal provider, all linked app configurations are updated
|
||||
- After deleting a universal provider, linked app configurations are also deleted
|
||||
|
||||
### Save and Sync
|
||||
|
||||
When editing a universal provider, you can choose:
|
||||
|
||||
| Action | Description |
|
||||
|--------|-------------|
|
||||
| Save | Save configuration only, without immediate sync |
|
||||
| Save and Sync | Save configuration and immediately sync to all enabled apps |
|
||||
|
||||
### Manual Sync
|
||||
|
||||
If you need to manually trigger a sync:
|
||||
|
||||
1. Click the "Sync" button on the universal provider card
|
||||
2. Confirm the sync operation
|
||||
3. Configuration will overwrite the linked provider in each app
|
||||
|
||||
## Import Providers
|
||||
|
||||
CC Switch supports two ways to import provider configurations:
|
||||
|
||||
### Option 1: Deep Link Import
|
||||
|
||||
One-click import via `ccswitch://` protocol links:
|
||||
|
||||
1. Click or visit the deep link
|
||||
2. CC Switch opens automatically and shows the import confirmation
|
||||
3. Preview the configuration information
|
||||
4. Click "Confirm Import"
|
||||
|
||||
**Getting deep links**:
|
||||
- Obtain from shared links by others
|
||||
- Create using the [online generator tool](https://farion1231.github.io/cc-switch/deplink.html)
|
||||
|
||||
### Option 2: Database Backup Import
|
||||
|
||||
Batch import from SQL backup files:
|
||||
|
||||
1. Open "Settings > Advanced > Data Management"
|
||||
2. Click "Select File"
|
||||
3. Select a previously exported `.sql` backup file
|
||||
4. Click "Import"
|
||||
5. Confirm to overwrite existing configuration
|
||||
|
||||
**Imported contents**:
|
||||
- All provider configurations
|
||||
- MCP server configurations
|
||||
- Prompt presets
|
||||
- Usage logs
|
||||
|
||||
> **Note**: Importing will overwrite the existing database. It is recommended to export your current configuration as a backup first. The exported file name format is `cc-switch-export-{timestamp}.sql`.
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### Custom Icon
|
||||
|
||||
Click the icon area to the left of the name to:
|
||||
|
||||
- Select a preset icon
|
||||
- Customize icon color
|
||||
|
||||
### Website Link
|
||||
|
||||
Enter the provider's website or console URL for quick access:
|
||||
|
||||
- Click the link icon on the provider card to open directly
|
||||
- Useful for checking balance, obtaining API keys, etc.
|
||||
|
||||
### Notes
|
||||
|
||||
Add notes such as:
|
||||
|
||||
- Account purpose (personal/work)
|
||||
- Plan information
|
||||
- Expiration date
|
||||
|
||||
Notes are displayed on the provider card and are searchable.
|
||||
|
||||
### Endpoint Speed Test
|
||||
|
||||
After adding a provider, you can speed-test API endpoints:
|
||||
|
||||
1. Click the "Speed Test" button on the provider card
|
||||
2. Add multiple endpoint URLs in the speed test panel
|
||||
3. Click "Test" to run the test
|
||||
4. Select the endpoint with the lowest latency
|
||||
|
||||
**Test results**:
|
||||
- Green: Latency < 500ms (Excellent)
|
||||
- Yellow: Latency 500-1000ms (Fair)
|
||||
- Red: Latency > 1000ms (Slow)
|
||||
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
# 2.2 Switch Provider
|
||||
|
||||
## Switch from Main Interface
|
||||
|
||||
In the provider list, click the "Enable" button on the target provider card.
|
||||
|
||||
### Switching Flow
|
||||
|
||||
1. Click the "Enable" button
|
||||
2. CC Switch updates the configuration file
|
||||
3. The card status changes to "Currently Active"
|
||||
4. Claude/Gemini take effect immediately, Codex requires a terminal restart
|
||||
|
||||
### Status Indicators
|
||||
|
||||
| Status | Display | Description |
|
||||
|--------|---------|-------------|
|
||||
| Currently Active | Blue border + label | Current provider in the configuration file |
|
||||
| Proxy Active | Green border | Provider actually in use during proxy mode |
|
||||
| Normal | Default style | Inactive provider |
|
||||
|
||||
## Quick Switch via System Tray
|
||||
|
||||
Quickly switch providers via the system tray without opening the main interface.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Right-click the CC Switch icon in the system tray
|
||||
2. Find the corresponding app (Claude/Codex/Gemini/OpenCode) in the menu
|
||||
3. Click the provider name you want to switch to
|
||||
4. Switching completes with a brief tray notification
|
||||
|
||||
### Tray Menu Structure
|
||||
|
||||
|
||||
|
||||
## Activation Methods
|
||||
|
||||
### Claude Code
|
||||
|
||||
**Takes effect immediately after switching**, no restart needed.
|
||||
|
||||
Claude Code supports hot reload and automatically detects configuration file changes and reloads.
|
||||
|
||||
### Codex
|
||||
|
||||
Requires restart after switching:
|
||||
- Close the current terminal window
|
||||
- Reopen the terminal
|
||||
|
||||
### Gemini CLI
|
||||
|
||||
**Takes effect immediately after switching**, no restart needed.
|
||||
|
||||
Gemini CLI re-reads the `.env` file on each request.
|
||||
|
||||
## Configuration File Changes
|
||||
|
||||
When switching providers, CC Switch modifies the following files:
|
||||
|
||||
### Claude
|
||||
|
||||
```
|
||||
~/.claude/settings.json
|
||||
```
|
||||
|
||||
Modified content:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "new API Key",
|
||||
"ANTHROPIC_BASE_URL": "new endpoint"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex
|
||||
|
||||
```
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml (if additional configuration exists)
|
||||
```
|
||||
|
||||
### Gemini
|
||||
|
||||
```
|
||||
~/.gemini/.env
|
||||
~/.gemini/settings.json
|
||||
```
|
||||
|
||||
## Handling Switch Failures
|
||||
|
||||
If switching fails, possible reasons:
|
||||
|
||||
### Configuration File Is Locked
|
||||
|
||||
Another program is using the configuration file.
|
||||
|
||||
**Solution**: Close the running CLI tool and try switching again.
|
||||
|
||||
### Insufficient Permissions
|
||||
|
||||
No write permission to the configuration file.
|
||||
|
||||
**Solution**: Check the permission settings of the configuration directory.
|
||||
|
||||
### Invalid Configuration Format
|
||||
|
||||
The provider's JSON configuration has format errors.
|
||||
|
||||
**Solution**: Edit the provider, check and fix the JSON format.
|
||||
@@ -0,0 +1,145 @@
|
||||
# 2.3 Edit Provider
|
||||
|
||||
## Open the Edit Panel
|
||||
|
||||
1. Find the provider card you want to edit
|
||||
2. Hover over the card to reveal action buttons
|
||||
3. Click the "Edit" button
|
||||
|
||||
## Editable Content
|
||||
|
||||
### Basic Information
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Name | Provider display name |
|
||||
| Notes | Additional notes |
|
||||
| Website Link | Provider website or console URL |
|
||||
| Icon | Custom icon and color |
|
||||
|
||||
### Icon Customization
|
||||
|
||||
CC Switch provides rich icon customization features:
|
||||
|
||||
#### Icon Picker
|
||||
|
||||
1. Click the icon area to open the icon picker
|
||||
2. Use the search box to search icons by name
|
||||
3. Click to select the desired icon
|
||||
|
||||
The icon library includes common AI service provider and technology icons, supporting:
|
||||
- Fuzzy search by name
|
||||
- Icon name tooltips
|
||||
- Real-time preview of selected icon
|
||||
|
||||
|
||||
|
||||
### Configuration
|
||||
|
||||
JSON-formatted configuration content, including:
|
||||
|
||||
- API Key
|
||||
- Endpoint URL
|
||||
- Other environment variables
|
||||
|
||||
### Editing the Currently Active Provider
|
||||
|
||||
When editing the currently active provider, a special "backfill" mechanism applies:
|
||||
|
||||
1. When opening the edit panel, the latest content is read from the live configuration file
|
||||
2. If you manually modified the configuration in the CLI tool, those changes are synced back
|
||||
3. After saving, modifications are written to the live configuration file
|
||||
|
||||
This ensures CC Switch and CLI tool configurations stay in sync.
|
||||
|
||||
## Modify API Key
|
||||
|
||||
When editing a provider, you can modify the key directly in the **API Key** input field:
|
||||
|
||||
1. Click the "Edit" button on the provider card
|
||||
2. Enter the new key in the "API Key" input field
|
||||
3. Click "Save"
|
||||
|
||||
> **Tip**: The API Key input field supports a show/hide toggle. Click the eye icon on the right to view the full key.
|
||||
|
||||
## Modify Endpoint URL
|
||||
|
||||
When editing a provider, you can modify the URL directly in the **Endpoint URL** input field:
|
||||
|
||||
1. Click the "Edit" button on the provider card
|
||||
2. Enter the new URL in the "Endpoint URL" input field
|
||||
3. Click "Save"
|
||||
|
||||
### Endpoint URL Format
|
||||
|
||||
| Application | Format Example |
|
||||
|-------------|----------------|
|
||||
| Claude | `https://api.example.com` |
|
||||
| Codex | `https://api.example.com/v1` |
|
||||
| Gemini | `https://api.example.com` |
|
||||
|
||||
## Add Custom Endpoints
|
||||
|
||||
Providers can be configured with multiple endpoints for:
|
||||
|
||||
- Testing multiple addresses during speed tests
|
||||
- Backup endpoints for failover
|
||||
|
||||
### Auto-collection
|
||||
|
||||
When adding a provider, CC Switch automatically extracts endpoint URLs from the configuration.
|
||||
|
||||
### Manual Addition
|
||||
|
||||
When editing a provider, in the "Endpoint Management" area you can:
|
||||
|
||||
- Add new endpoints
|
||||
- Delete existing endpoints
|
||||
- Set a default endpoint
|
||||
|
||||
## JSON Editor
|
||||
|
||||
Configuration uses JSON format, and the editor provides:
|
||||
|
||||
- Syntax highlighting
|
||||
- Format validation
|
||||
- Error messages
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Missing quotes**:
|
||||
```json
|
||||
// Wrong
|
||||
{ env: { KEY: "value" } }
|
||||
|
||||
// Correct
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
**Trailing comma**:
|
||||
```json
|
||||
// Wrong
|
||||
{ "env": { "KEY": "value", } }
|
||||
|
||||
// Correct
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
**Unclosed brackets**:
|
||||
```json
|
||||
// Wrong
|
||||
{ "env": { "KEY": "value" }
|
||||
|
||||
// Correct
|
||||
{ "env": { "KEY": "value" } }
|
||||
```
|
||||
|
||||
## Save and Activate
|
||||
|
||||
1. Click the "Save" button
|
||||
2. If this is the currently active provider, the configuration is immediately written to the live file
|
||||
3. Restart the CLI tool for changes to take effect
|
||||
|
||||
## Cancel Editing
|
||||
|
||||
Click "Cancel" or press the `Esc` key to close the edit panel. All modifications will be discarded.
|
||||
@@ -0,0 +1,76 @@
|
||||
# 2.4 Sort & Duplicate
|
||||
|
||||
## Drag to Reorder
|
||||
|
||||
Adjust the display order of providers by dragging.
|
||||
|
||||
### Steps
|
||||
|
||||
1. Move the mouse to the **≡** drag handle on the left side of the provider card
|
||||
2. Hold the left mouse button
|
||||
3. Drag up or down to the target position
|
||||
4. Release the mouse to complete reordering
|
||||
|
||||
### Reorder Uses
|
||||
|
||||
- **Prioritize frequently used**: Place frequently used providers at the top of the list
|
||||
- **Failover order**: Sorting affects the default order of the failover queue
|
||||
|
||||
## Duplicate Provider
|
||||
|
||||
Quickly create a copy of a provider, useful for:
|
||||
|
||||
- Creating variations based on existing configurations
|
||||
- Backing up current configurations
|
||||
- Creating test configurations
|
||||
|
||||
### Steps
|
||||
|
||||
1. Hover over the provider card to reveal action buttons
|
||||
2. Click the "Duplicate" button
|
||||
3. A copy is automatically created with a `copy` name suffix
|
||||
4. Edit the copy to modify the configuration
|
||||
|
||||
### Duplicated Content
|
||||
|
||||
Duplication creates a complete copy, including:
|
||||
|
||||
| Content | Duplicated |
|
||||
|---------|------------|
|
||||
| Name | Yes (with `copy` suffix) |
|
||||
| Configuration | Fully duplicated |
|
||||
| Notes | Yes |
|
||||
| Website Link | Yes |
|
||||
| Icon | Yes |
|
||||
| Endpoint List | Yes |
|
||||
| Sort Position | Inserted below the original provider |
|
||||
|
||||
### After Duplication
|
||||
|
||||
After duplication, you typically need to modify:
|
||||
|
||||
1. **Name**: Change to a meaningful name
|
||||
2. **API Key**: If using a different account
|
||||
3. **Endpoint**: If using a different service
|
||||
|
||||
## Delete Provider
|
||||
|
||||
### Steps
|
||||
|
||||
1. Hover over the provider card to reveal action buttons
|
||||
2. Click the "Delete" button
|
||||
3. Confirm deletion
|
||||
|
||||
### Deletion Confirmation
|
||||
|
||||
A confirmation dialog appears before deletion, showing:
|
||||
|
||||
- Provider name
|
||||
- Warning that deletion cannot be undone
|
||||
|
||||
### Deletion Restrictions
|
||||
|
||||
- **Currently active provider**: Can be deleted, but it is recommended to switch to another provider first
|
||||
- **Universal provider**: Deleting will also remove linked app configurations
|
||||
|
||||
|
||||
@@ -0,0 +1,181 @@
|
||||
# 2.5 Usage Query
|
||||
|
||||
## Overview
|
||||
|
||||
The usage query feature allows you to configure custom scripts to query a provider's remaining balance, used amount, and other information in real time.
|
||||
|
||||
**Use cases**:
|
||||
- Check API account remaining balance
|
||||
- Monitor plan usage
|
||||
- Multi-plan balance summary display
|
||||
|
||||
## Open Configuration
|
||||
|
||||
1. Hover over the provider card to reveal action buttons
|
||||
2. Click the "Usage Query" button (chart icon)
|
||||
3. Opens the usage query configuration panel
|
||||
|
||||
## Enable Usage Query
|
||||
|
||||
At the top of the configuration panel, enable the "Enable Usage Query" toggle.
|
||||
|
||||
## Preset Templates
|
||||
|
||||
CC Switch provides three preset templates:
|
||||
|
||||
### Custom Template
|
||||
|
||||
Fully customizable request and extraction logic, suitable for special API formats.
|
||||
|
||||
### Generic Template
|
||||
|
||||
Suitable for most providers with standard API formats:
|
||||
|
||||
```javascript
|
||||
({
|
||||
request: {
|
||||
url: "{{baseUrl}}/user/balance",
|
||||
method: "GET",
|
||||
headers: {
|
||||
"Authorization": "Bearer {{apiKey}}",
|
||||
"User-Agent": "cc-switch/1.0"
|
||||
}
|
||||
},
|
||||
extractor: function(response) {
|
||||
return {
|
||||
isValid: response.is_active || true,
|
||||
remaining: response.balance,
|
||||
unit: "USD"
|
||||
};
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Configuration parameters**:
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| API Key | Authentication key (optional, uses provider's key if empty) |
|
||||
| Base URL | API base URL (optional, uses provider's endpoint if empty) |
|
||||
|
||||
### New API Template
|
||||
|
||||
Designed specifically for New API-type proxy services:
|
||||
|
||||
```javascript
|
||||
({
|
||||
request: {
|
||||
url: "{{baseUrl}}/api/user/self",
|
||||
method: "GET",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
"Authorization": "Bearer {{accessToken}}",
|
||||
"New-Api-User": "{{userId}}"
|
||||
},
|
||||
},
|
||||
extractor: function (response) {
|
||||
if (response.success && response.data) {
|
||||
return {
|
||||
planName: response.data.group || "Default Plan",
|
||||
remaining: response.data.quota / 500000,
|
||||
used: response.data.used_quota / 500000,
|
||||
total: (response.data.quota + response.data.used_quota) / 500000,
|
||||
unit: "USD",
|
||||
};
|
||||
}
|
||||
return {
|
||||
isValid: false,
|
||||
invalidMessage: response.message || "Query failed"
|
||||
};
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**Configuration parameters**:
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| Base URL | New API service URL |
|
||||
| Access Token | Access token |
|
||||
| User ID | User ID |
|
||||
|
||||
## General Configuration
|
||||
|
||||
### Timeout
|
||||
|
||||
Request timeout in seconds, default 10 seconds.
|
||||
|
||||
### Auto Query Interval
|
||||
|
||||
Interval for automatically refreshing usage data (minutes):
|
||||
- Set to `0` to disable auto query
|
||||
- Range: 0-1440 minutes (up to 24 hours)
|
||||
- Only effective when the provider is in "Currently Active" status
|
||||
|
||||
## Extractor Return Format
|
||||
|
||||
The extractor function must return an object containing the following fields:
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `isValid` | boolean | No | Whether the account is valid, defaults to true |
|
||||
| `invalidMessage` | string | No | Message when invalid |
|
||||
| `remaining` | number | Yes | Remaining balance |
|
||||
| `unit` | string | Yes | Unit (e.g., USD, CNY, times) |
|
||||
| `planName` | string | No | Plan name (supports multi-plan) |
|
||||
| `total` | number | No | Total balance |
|
||||
| `used` | number | No | Used amount |
|
||||
| `extra` | object | No | Additional information |
|
||||
|
||||
## Test Script
|
||||
|
||||
After configuration, click the "Test Script" button to verify:
|
||||
|
||||
1. Sends a request to the configured URL
|
||||
2. Executes the extractor function
|
||||
3. Displays the returned result or error message
|
||||
|
||||
## Display
|
||||
|
||||
After successful configuration, the provider card displays:
|
||||
|
||||
- **Single plan**: Directly shows remaining balance
|
||||
- **Multi-plan**: Shows plan count, click to expand for details
|
||||
|
||||
## Variable Placeholders
|
||||
|
||||
The following placeholders can be used in scripts and are automatically replaced at runtime:
|
||||
|
||||
| Placeholder | Description |
|
||||
|-------------|-------------|
|
||||
| `{{apiKey}}` | Configured API Key |
|
||||
| `{{baseUrl}}` | Configured Base URL |
|
||||
| `{{accessToken}}` | Configured Access Token (New API) |
|
||||
| `{{userId}}` | Configured User ID (New API) |
|
||||
|
||||
## Common Provider Configuration Examples
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
### Query Failed
|
||||
|
||||
**Check**:
|
||||
1. Is the API Key correct
|
||||
2. Is the Base URL correct
|
||||
3. Is the network accessible
|
||||
4. Is the timeout sufficient
|
||||
|
||||
### Empty Response Data
|
||||
|
||||
**Check**:
|
||||
1. Does the extractor function have a `return` statement
|
||||
2. Does the response data structure match the extractor
|
||||
3. Use "Test Script" to view the raw response
|
||||
|
||||
### Format Failed
|
||||
|
||||
When there is a script syntax error, clicking the "Format" button will indicate the error location.
|
||||
|
||||
## Notes
|
||||
|
||||
- Usage queries consume a small amount of API request quota
|
||||
- Set a reasonable auto query interval to avoid frequent requests
|
||||
- Sensitive information (API Key, Token) is securely stored locally
|
||||
@@ -0,0 +1,209 @@
|
||||
# 3.1 MCP Server Management
|
||||
|
||||
## What is MCP
|
||||
|
||||
MCP (Model Context Protocol) is a protocol that allows AI tools to access external data sources and tools. Through MCP servers, you can enable AI to:
|
||||
|
||||
- Access file systems
|
||||
- Make network requests
|
||||
- Query databases
|
||||
- Call external APIs
|
||||
|
||||
## Open the MCP Panel
|
||||
|
||||
Click the **MCP** button in the top navigation bar.
|
||||
|
||||
## Panel Overview
|
||||
|
||||
|
||||
|
||||
## Add MCP Server
|
||||
|
||||
### Using Preset Templates
|
||||
|
||||
1. Click the **+** button in the top-right corner
|
||||
2. Select a template from the "Preset" dropdown
|
||||
3. Modify the configuration as needed
|
||||
4. Click "Save"
|
||||
|
||||
|
||||
|
||||
### Common Presets
|
||||
|
||||
| Preset | Package Name | Description |
|
||||
|--------|-------------|-------------|
|
||||
| fetch | mcp-server-fetch | HTTP request tool that enables AI to fetch web content |
|
||||
| time | @modelcontextprotocol/server-time | Time tool that provides current time information |
|
||||
| memory | @modelcontextprotocol/server-memory | Memory tool that enables AI to store and retrieve information |
|
||||
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | Chain-of-thought tool that enhances AI reasoning |
|
||||
| context7 | @upstash/context7-mcp | Documentation search tool for querying technical docs |
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
After selecting "Custom", fill in:
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| Server ID | Yes | Unique identifier |
|
||||
| Name | No | Display name |
|
||||
| Description | No | Function description |
|
||||
| Transport Type | Yes | stdio / http / sse |
|
||||
| Command | Yes* | Required for stdio type |
|
||||
| Arguments | No | Command-line arguments |
|
||||
| URL | Yes* | Required for http/sse type |
|
||||
| Headers | No | Request headers for http/sse type |
|
||||
| Environment Variables | No | Environment variables passed to the server |
|
||||
|
||||
## Transport Types
|
||||
|
||||
### stdio (Standard I/O)
|
||||
|
||||
The most common type, communicating by launching a local process.
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"],
|
||||
"env": {}
|
||||
}
|
||||
```
|
||||
|
||||
**Requirements**:
|
||||
- The corresponding command must be installed (e.g., `uvx`, `npx`)
|
||||
- The server program must be in PATH
|
||||
|
||||
### http
|
||||
|
||||
Communicates with a remote server via HTTP protocol.
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://localhost:8080/mcp"
|
||||
}
|
||||
```
|
||||
|
||||
### sse (Server-Sent Events)
|
||||
|
||||
Communicates with a server via SSE protocol, supporting real-time push.
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://localhost:8080/sse"
|
||||
}
|
||||
```
|
||||
|
||||
## App Binding
|
||||
|
||||
Each MCP server can independently control which apps it is enabled for.
|
||||
|
||||
### Toggle Description
|
||||
|
||||
| Toggle | Effect | Configuration File Path |
|
||||
|--------|--------|------------------------|
|
||||
| Claude | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
|
||||
| Codex | Sync to Codex | `~/.codex/config.toml`'s `[mcp_servers]` |
|
||||
| Gemini | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
|
||||
| OpenCode | Sync to OpenCode | `~/.opencode/config.json`'s `mcpServers` |
|
||||
|
||||
> **Note**: OpenClaw does not currently support MCP server management. MCP functionality is currently only supported for Claude, Codex, Gemini, and OpenCode.
|
||||
|
||||
### Toggle Implementation
|
||||
|
||||
When enabling an app's toggle, CC Switch will:
|
||||
|
||||
1. **Update database**: Set the server's `apps.claude/codex/gemini/opencode` status to `true`
|
||||
2. **Sync to live configuration**: Write the server configuration to the corresponding app's configuration file
|
||||
3. **Take effect immediately**: The new MCP server is automatically loaded the next time the CLI tool starts
|
||||
|
||||
When disabling an app's toggle, CC Switch will:
|
||||
|
||||
1. **Update database**: Set the corresponding app status to `false`
|
||||
2. **Remove from live configuration**: Delete the server from the app's configuration file
|
||||
3. **Take effect immediately**: The MCP server is no longer loaded the next time the CLI tool starts
|
||||
|
||||
### Sync Conditions
|
||||
|
||||
MCP server sync only executes when the corresponding app is installed:
|
||||
|
||||
- **Claude**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
|
||||
- **Codex**: Requires `~/.codex/` directory to exist
|
||||
- **Gemini**: Requires `~/.gemini/` directory to exist
|
||||
- **OpenCode**: Requires `~/.opencode/` directory to exist
|
||||
|
||||
> **Tip**: If a CLI tool is not installed, enabling its toggle will not cause an error, but the configuration will not be written.
|
||||
|
||||
When the toggle is disabled, the configuration is removed from the file.
|
||||
|
||||
## Edit Server
|
||||
|
||||
1. Click the "Edit" button on the right side of the server row
|
||||
2. Modify the configuration
|
||||
3. Click "Save"
|
||||
|
||||
Changes are immediately synced to enabled app configuration files.
|
||||
|
||||
## Delete Server
|
||||
|
||||
1. Click the "Delete" button on the right side of the server row
|
||||
2. Confirm deletion
|
||||
|
||||
After deletion, the configuration is removed from all app configuration files.
|
||||
|
||||
## Import Existing Configurations
|
||||
|
||||
If you have already configured MCP servers in CLI tools, you can import them into CC Switch:
|
||||
|
||||
1. Click the "Import" button
|
||||
2. Select the app to import from (Claude/Codex/Gemini/OpenCode)
|
||||
3. CC Switch reads the existing configuration and imports it
|
||||
|
||||
## Configuration File Formats
|
||||
|
||||
### Claude (`~/.claude.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Codex (`~/.codex/config.toml`)
|
||||
|
||||
```toml
|
||||
[mcp_servers.mcp-fetch]
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
### Gemini (`~/.gemini/settings.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Server Fails to Start
|
||||
|
||||
Check:
|
||||
- Is the command properly installed (e.g., `uvx`)
|
||||
- Is the command in PATH
|
||||
- Are the arguments correct
|
||||
|
||||
### Configuration Not Taking Effect
|
||||
|
||||
Ensure:
|
||||
- The corresponding app toggle is enabled
|
||||
- The CLI tool has been restarted
|
||||
@@ -0,0 +1,160 @@
|
||||
# 3.2 Prompts Management
|
||||
|
||||
## Overview
|
||||
|
||||
The Prompts feature manages system prompt presets. System prompts influence the AI's behavior and response style.
|
||||
|
||||
With CC Switch, you can:
|
||||
|
||||
- Create multiple prompt presets
|
||||
- Quickly switch prompts for different scenarios
|
||||
- Sync prompt configurations across devices
|
||||
|
||||
## Open the Prompts Panel
|
||||
|
||||
Click the **Prompts** button in the top navigation bar.
|
||||
|
||||
## Panel Overview
|
||||
|
||||
|
||||
|
||||
## Create a Preset
|
||||
|
||||
### Steps
|
||||
|
||||
1. Click the **+** button in the top-right corner
|
||||
2. Enter a preset name
|
||||
3. Write the prompt in the Markdown editor
|
||||
4. Click "Save"
|
||||
|
||||
### Markdown Editor
|
||||
|
||||
The editor provides:
|
||||
|
||||
- Syntax highlighting
|
||||
- Live preview
|
||||
- Common format shortcuts
|
||||
|
||||
### Prompt Writing Tips
|
||||
|
||||
**Structured format**:
|
||||
|
||||
```markdown
|
||||
# Role Definition
|
||||
|
||||
You are a professional code review expert.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
- Code quality analysis
|
||||
- Performance optimization suggestions
|
||||
- Security vulnerability detection
|
||||
|
||||
## Response Style
|
||||
|
||||
- Clear and concise
|
||||
- Provide specific examples
|
||||
- Give improvement suggestions
|
||||
|
||||
## Notes
|
||||
|
||||
- Do not modify business logic
|
||||
- Maintain consistent code style
|
||||
```
|
||||
|
||||
## Activate a Preset
|
||||
|
||||
### How to Activate
|
||||
|
||||
Click the toggle switch on the preset item to change its activation status.
|
||||
|
||||
### Single Activation
|
||||
|
||||
Only one preset can be active at a time. Activating a new preset automatically deactivates the previous one.
|
||||
|
||||
### Sync Target
|
||||
|
||||
After activation, the prompt is written to the corresponding app's file:
|
||||
|
||||
| Application | File Path |
|
||||
|-------------|-----------|
|
||||
| Claude | `~/.claude/CLAUDE.md` |
|
||||
| Codex | `~/.codex/AGENTS.md` |
|
||||
| Gemini | `~/.gemini/GEMINI.md` |
|
||||
| OpenCode | `~/.opencode/AGENTS.md` |
|
||||
| OpenClaw | `~/.openclaw/AGENTS.md` |
|
||||
|
||||
## Edit a Preset
|
||||
|
||||
1. Click the "Edit" button on the preset item
|
||||
2. Modify the name or content
|
||||
3. Click "Save"
|
||||
|
||||
If the currently active preset is edited, changes are immediately synced to the configuration file.
|
||||
|
||||
## Delete a Preset
|
||||
|
||||
1. Click the "Delete" button on the preset item
|
||||
2. Confirm deletion
|
||||
|
||||
Active presets cannot be deleted. Deactivate the preset first before deleting.
|
||||
|
||||
## Smart Backfill
|
||||
|
||||
CC Switch provides a smart backfill protection mechanism to ensure your manual modifications are not lost.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Before switching presets, automatically reads the current configuration file content
|
||||
2. Compares file content with the preset in the database
|
||||
3. If the content differs, it means the user has manually modified it
|
||||
4. Saves the manually modified content to the current preset
|
||||
5. Then switches to the new preset
|
||||
|
||||
### Protection Scenarios
|
||||
|
||||
| Scenario | Handling |
|
||||
|----------|----------|
|
||||
| Directly editing `CLAUDE.md` in CLI | Changes auto-saved to current preset |
|
||||
| Modifying config file with external editor | Changes auto-saved to current preset |
|
||||
| Switching to another preset | Current changes saved first, then switched |
|
||||
|
||||
### Technical Details
|
||||
|
||||
The backfill mechanism triggers at these moments:
|
||||
|
||||
- **When switching presets**: Saves current live file content to the current preset
|
||||
- **When editing the current preset**: Reads latest content from the live file
|
||||
- **On first launch**: Automatically imports existing live file content
|
||||
|
||||
### Notes
|
||||
|
||||
- Backfill only triggers when switching to a different preset
|
||||
- If no preset is currently active, backfill is not triggered
|
||||
- Backfill failure does not affect the switching process
|
||||
|
||||
## Cross-app Usage
|
||||
|
||||
Prompts are managed separately per app:
|
||||
|
||||
- When switched to Claude, Claude's presets are shown
|
||||
- When switched to Codex, Codex's presets are shown
|
||||
- When switched to Gemini, Gemini's presets are shown
|
||||
- When switched to OpenCode, OpenCode's presets are shown
|
||||
- When switched to OpenClaw, OpenClaw's presets are shown
|
||||
|
||||
To use the same prompt across multiple apps, you need to create them separately.
|
||||
|
||||
## Import & Export
|
||||
|
||||
### Share via Deep Link
|
||||
|
||||
You can generate deep links to share presets:
|
||||
|
||||
```
|
||||
ccswitch://import/prompt?data=<base64-encoded preset>
|
||||
```
|
||||
|
||||
### Via Configuration Export
|
||||
|
||||
Exporting configuration includes all presets, which can be restored upon import.
|
||||
@@ -0,0 +1,207 @@
|
||||
# 3.3 Skills Management
|
||||
|
||||
## Overview
|
||||
|
||||
Skills are reusable capability extensions that give AI tools specialized abilities in specific domains.
|
||||
|
||||
Skills exist as folders containing:
|
||||
|
||||
- Prompt templates
|
||||
- Tool definitions
|
||||
- Example code
|
||||
|
||||
## Supported Applications
|
||||
|
||||
Skills are supported across all four applications:
|
||||
|
||||
- **Claude Code**
|
||||
- **Codex**
|
||||
- **Gemini CLI**
|
||||
- **OpenCode**
|
||||
|
||||
## Open the Skills Page
|
||||
|
||||
Click the **Skills** button in the top navigation bar.
|
||||
|
||||
> Note: The Skills button is visible in all app modes.
|
||||
|
||||
## Page Overview
|
||||
|
||||
|
||||
|
||||
## Discover Skills
|
||||
|
||||
### Pre-configured Repositories
|
||||
|
||||
CC Switch comes pre-configured with the following GitHub repositories:
|
||||
|
||||
| Repository | Description |
|
||||
|------------|-------------|
|
||||
| Anthropic Official | Official skills provided by Anthropic |
|
||||
| ComposioHQ | Community-maintained skill collection |
|
||||
| Community Picks | Curated high-quality skills |
|
||||
|
||||
|
||||
|
||||
### Search & Filter
|
||||
|
||||
CC Switch provides powerful search and filter features:
|
||||
|
||||
#### Search Box
|
||||
|
||||
- Search by skill name
|
||||
- Search by skill description
|
||||
- Search by directory name
|
||||
- Real-time filtering, results update as you type
|
||||
|
||||
#### Status Filter
|
||||
|
||||
Use the dropdown menu to filter by installation status:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| All | Show all skills |
|
||||
| Installed | Show only installed skills |
|
||||
| Not Installed | Show only uninstalled skills |
|
||||
|
||||
|
||||
|
||||
#### Combined Use
|
||||
|
||||
Search and filter can be combined:
|
||||
|
||||
- Select "Installed" filter first
|
||||
- Then enter keywords to search
|
||||
- Results show the match count
|
||||
|
||||
### Refresh List
|
||||
|
||||
Click the "Refresh" button to re-scan repositories for the latest skills.
|
||||
|
||||
## Install Skills
|
||||
|
||||
### Steps
|
||||
|
||||
1. Find the skill card you want to install
|
||||
2. Click the "Install" button
|
||||
3. Wait for installation to complete
|
||||
|
||||
### Installation Location
|
||||
|
||||
| Application | Install Directory |
|
||||
|-------------|-------------------|
|
||||
| Claude | `~/.claude/skills/` |
|
||||
| Codex | `~/.codex/skills/` |
|
||||
| Gemini | `~/.gemini/skills/` |
|
||||
| OpenCode | `~/.opencode/skills/` |
|
||||
|
||||
### Installation Contents
|
||||
|
||||
Installation copies the skill folder to your local machine:
|
||||
|
||||
```
|
||||
~/.claude/skills/
|
||||
└── skill-name/
|
||||
├── README.md
|
||||
├── prompt.md
|
||||
└── tools/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Uninstall Skills
|
||||
|
||||
### Steps
|
||||
|
||||
1. Find the installed skill card
|
||||
2. Click the "Uninstall" button
|
||||
3. Confirm uninstallation
|
||||
|
||||
### Uninstall Effect
|
||||
|
||||
- Deletes the local skill folder
|
||||
- Updates installation status
|
||||
|
||||
## Repository Management
|
||||
|
||||
### Open Repository Management
|
||||
|
||||
Click the "Repository Management" button at the top of the page.
|
||||
|
||||
### Add Custom Repository
|
||||
|
||||
1. Click "Add Repository"
|
||||
2. Fill in repository information:
|
||||
- Owner: GitHub username or organization name
|
||||
- Name: Repository name
|
||||
- Branch: Branch name (default: main)
|
||||
- Subdirectory: Subdirectory containing skills (optional)
|
||||
3. Click "Add"
|
||||
|
||||
### Repository Format
|
||||
|
||||
```
|
||||
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Owner: anthropics
|
||||
Name: claude-skills
|
||||
Branch: main
|
||||
Subdirectory: skills
|
||||
```
|
||||
|
||||
### Delete Repository
|
||||
|
||||
1. Find the repository in the repository list
|
||||
2. Click the "Delete" button
|
||||
3. Confirm deletion
|
||||
|
||||
After deleting a repository, its skills will not disappear from the list, but they can no longer be updated.
|
||||
|
||||
## Skill Card Information
|
||||
|
||||
Each skill card displays:
|
||||
|
||||
| Information | Description |
|
||||
|-------------|-------------|
|
||||
| Name | Skill name |
|
||||
| Description | Function description |
|
||||
| Source | Source repository |
|
||||
| Status | Installed / Not Installed |
|
||||
|
||||
## Skill Updates
|
||||
|
||||
Automatic updates are not currently supported. To update a skill:
|
||||
|
||||
1. Uninstall the existing skill
|
||||
2. Refresh the list
|
||||
3. Reinstall
|
||||
|
||||
### Empty Skill List
|
||||
|
||||
Possible causes:
|
||||
|
||||
- Network issues preventing GitHub access
|
||||
- Incorrect repository configuration
|
||||
|
||||
Solutions:
|
||||
|
||||
- Check network connection
|
||||
- Click "Refresh" to retry
|
||||
- Verify repository configuration
|
||||
|
||||
### Installation Failed
|
||||
|
||||
Possible causes:
|
||||
|
||||
- Network issues
|
||||
- Insufficient disk space
|
||||
- Permission issues
|
||||
|
||||
Solutions:
|
||||
|
||||
- Check network connection
|
||||
- Check disk space
|
||||
- Check directory permissions
|
||||
@@ -0,0 +1,222 @@
|
||||
# 4.1 Proxy Service
|
||||
|
||||
## Overview
|
||||
|
||||
The proxy service starts a local HTTP proxy through which all API requests are forwarded.
|
||||
|
||||
**Primary uses**:
|
||||
- Record request logs
|
||||
- Track API usage
|
||||
- Support failover
|
||||
- Centrally manage requests from multiple applications
|
||||
|
||||
## Start the Proxy
|
||||
|
||||
### Option 1: Main Interface Toggle
|
||||
|
||||
Click the **Proxy Toggle** button at the top of the main interface.
|
||||
|
||||
Toggle states:
|
||||
- White: Proxy not running
|
||||
- Green: Proxy running
|
||||
|
||||
|
||||
|
||||
### Option 2: Settings Page
|
||||
|
||||
1. Open "Settings > Advanced > Proxy Service"
|
||||
2. Click the toggle in the top-right corner
|
||||
|
||||
|
||||
|
||||
## Proxy Configuration
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
| Setting | Description | Default |
|
||||
|---------|-------------|---------|
|
||||
| Listen Address | IP address the proxy binds to | `127.0.0.1` |
|
||||
| Listen Port | Port the proxy listens on | `15721` |
|
||||
| Enable Logging | Whether to record request logs | Enabled |
|
||||
|
||||
### Modify Configuration
|
||||
|
||||
1. **Stop the proxy service** (must stop first)
|
||||
2. Modify the listen address or port
|
||||
3. Click "Save"
|
||||
4. Restart the proxy
|
||||
|
||||
> Modifying address/port requires stopping the proxy service first
|
||||
|
||||
### Listen Address Options
|
||||
|
||||
| Address | Description |
|
||||
|---------|-------------|
|
||||
| `127.0.0.1` | Only accessible from local machine (recommended) |
|
||||
| `0.0.0.0` | Allow LAN access |
|
||||
|
||||
## Running Status
|
||||
|
||||
When the proxy is running, the panel displays the following information:
|
||||
|
||||
### Service Address
|
||||
|
||||
```
|
||||
http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
Click the "Copy" button to copy the address.
|
||||
|
||||
### Current Providers
|
||||
|
||||
Displays the currently used provider for each app:
|
||||
|
||||
```
|
||||
Claude: PackyCode
|
||||
Codex: AIGoCode
|
||||
Gemini: Google Official
|
||||
```
|
||||
|
||||
### Statistics
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| Active Connections | Number of requests currently being processed |
|
||||
| Total Requests | Total number of requests since startup |
|
||||
| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
|
||||
| Uptime | How long the proxy has been running |
|
||||
|
||||
### Failover Queue
|
||||
|
||||
The proxy panel displays the failover queue by app type:
|
||||
|
||||
```
|
||||
Claude
|
||||
├── 1. PackyCode [Currently Using] ●
|
||||
├── 2. AIGoCode ●
|
||||
└── 3. Backup Provider ○
|
||||
|
||||
Codex
|
||||
├── 1. AIGoCode [Currently Using] ●
|
||||
└── 2. Backup Provider ●
|
||||
```
|
||||
|
||||
Queue details:
|
||||
- Numbers indicate priority order
|
||||
- "Currently Using" label indicates the active provider
|
||||
- Health badges show provider status:
|
||||
- Green: Healthy (0 consecutive failures)
|
||||
- Yellow: Degraded (1-2 consecutive failures)
|
||||
- Red: Unhealthy (3+ consecutive failures)
|
||||
|
||||
## How It Works
|
||||
|
||||
### Request Flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as CLI Tool (Claude)
|
||||
participant Proxy as Local Proxy (CC Switch)
|
||||
participant API as API Provider (Anthropic)
|
||||
participant DB as Data Store (Logger)
|
||||
|
||||
CLI->>Proxy: Send API request
|
||||
Proxy->>DB: Record request log / track usage
|
||||
Proxy->>API: Forward request
|
||||
API-->>Proxy: Return response
|
||||
Proxy-->>CLI: Return response
|
||||
```
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
|
||||
|
||||
**Claude**:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex**:
|
||||
```toml
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini**:
|
||||
```
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
## Stop the Proxy
|
||||
|
||||
### Option 1: Main Interface Toggle
|
||||
|
||||
Click the proxy toggle button to turn it off.
|
||||
|
||||
### Option 2: Settings Page
|
||||
|
||||
Turn off the toggle in the proxy service panel.
|
||||
|
||||
### Post-stop Processing
|
||||
|
||||
When stopping the proxy, CC Switch will:
|
||||
|
||||
1. Restore app configurations to their original state
|
||||
2. Save request logs
|
||||
3. Close all connections
|
||||
|
||||
## Log Recording
|
||||
|
||||
### Enable Logging
|
||||
|
||||
Enable the "Enable Logging" toggle in the proxy panel.
|
||||
|
||||
### Log Contents
|
||||
|
||||
Each request record includes:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Time | Request time |
|
||||
| App | Claude / Codex / Gemini |
|
||||
| Provider | Provider used |
|
||||
| Model | Requested model |
|
||||
| Tokens | Input/output token count |
|
||||
| Latency | Request duration |
|
||||
| Status | Success/failure |
|
||||
|
||||
### View Logs
|
||||
|
||||
View request logs in the "Settings > Usage" tab.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
Error message: `Address already in use`
|
||||
|
||||
Solution:
|
||||
1. Change the port (e.g., to 5001)
|
||||
2. Or close the program occupying the port
|
||||
|
||||
### Proxy Fails to Start
|
||||
|
||||
Check:
|
||||
- Is the port occupied
|
||||
- Are there sufficient permissions
|
||||
- Is the firewall blocking it
|
||||
|
||||
### Request Timeout
|
||||
|
||||
Possible causes:
|
||||
- Network issues
|
||||
- Provider server issues
|
||||
- Incorrect proxy configuration
|
||||
|
||||
Solutions:
|
||||
- Check network connection
|
||||
- Try accessing the provider API directly
|
||||
- Check provider configuration
|
||||
@@ -0,0 +1,195 @@
|
||||
# 4.2 App Takeover
|
||||
|
||||
## Overview
|
||||
|
||||
App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.
|
||||
|
||||
When takeover is enabled:
|
||||
- The app's API requests are forwarded through the local proxy
|
||||
- Request logs and usage statistics can be recorded
|
||||
- Failover functionality becomes available
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The proxy service must be started before using the app takeover feature.
|
||||
|
||||
## Enable Takeover
|
||||
|
||||
### Location
|
||||
|
||||
Settings > Advanced > Proxy Service > App Takeover area
|
||||
|
||||
### Steps
|
||||
|
||||
1. Ensure the proxy service is started
|
||||
2. Find the "App Takeover" area
|
||||
3. Enable the toggle for the desired apps
|
||||
|
||||
### Takeover Toggles
|
||||
|
||||
| Toggle | Effect |
|
||||
|--------|--------|
|
||||
| Claude Takeover | Intercept Claude Code requests |
|
||||
| Codex Takeover | Intercept Codex requests |
|
||||
| Gemini Takeover | Intercept Gemini CLI requests |
|
||||
|
||||
Multiple app takeovers can be enabled simultaneously.
|
||||
|
||||
## How Takeover Works
|
||||
|
||||
### Configuration Changes
|
||||
|
||||
When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.
|
||||
|
||||
**Claude configuration change**:
|
||||
|
||||
```json
|
||||
// Before takeover
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
}
|
||||
}
|
||||
|
||||
// After takeover
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Codex configuration change**:
|
||||
|
||||
```toml
|
||||
# Before takeover
|
||||
base_url = "https://api.openai.com/v1"
|
||||
|
||||
# After takeover
|
||||
base_url = "http://127.0.0.1:15721/v1"
|
||||
```
|
||||
|
||||
**Gemini configuration change**:
|
||||
|
||||
```bash
|
||||
# Before takeover
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
|
||||
# After takeover
|
||||
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
|
||||
```
|
||||
|
||||
### Request Forwarding
|
||||
|
||||
When the proxy receives a request:
|
||||
|
||||
1. Identifies the request source (Claude/Codex/Gemini)
|
||||
2. Looks up the currently enabled provider for that app
|
||||
3. Forwards the request to the provider's actual endpoint
|
||||
4. Records the request log
|
||||
5. Returns the response to the app
|
||||
|
||||
## Takeover Status Indicators
|
||||
|
||||
### Main Interface Indicators
|
||||
|
||||
When takeover is enabled, the main interface shows the following changes:
|
||||
|
||||
- **Proxy logo color**: Changes from colorless to green
|
||||
- **Provider cards**: The currently active provider shows a green border
|
||||
|
||||
### Provider Card States
|
||||
|
||||
| State | Border Color | Description |
|
||||
|-------|--------------|-------------|
|
||||
| Currently Active | Blue | Provider in the config file (non-proxy mode) |
|
||||
| Proxy Active | Green | Provider actually used by the proxy |
|
||||
| Normal | Default | Unused provider |
|
||||
|
||||
## Disable Takeover
|
||||
|
||||
### Steps
|
||||
|
||||
1. Turn off the corresponding app's takeover toggle in the proxy panel
|
||||
2. Or directly stop the proxy service
|
||||
|
||||
### Configuration Restoration
|
||||
|
||||
When disabling takeover, CC Switch will:
|
||||
|
||||
1. Restore the app configuration to its pre-takeover state
|
||||
2. Save current request logs
|
||||
|
||||
## Takeover and Provider Switching
|
||||
|
||||
### Switching Providers in Takeover Mode
|
||||
|
||||
When switching providers in takeover mode:
|
||||
|
||||
1. Click the "Enable" button on a provider in the main interface
|
||||
2. The proxy immediately uses the new provider to forward requests
|
||||
3. **No need to restart the CLI tool**
|
||||
|
||||
This is a major advantage of takeover mode: provider switching takes effect instantly.
|
||||
|
||||
### Switching Without Takeover
|
||||
|
||||
When switching providers without takeover:
|
||||
|
||||
1. Configuration file is modified
|
||||
2. CLI tool must be restarted for changes to take effect
|
||||
|
||||
## Multi-app Takeover
|
||||
|
||||
Multiple apps can be taken over simultaneously, each managed independently:
|
||||
|
||||
- Independent provider configurations
|
||||
- Independent failover queues
|
||||
- Independent request statistics
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Scenario 1: Usage Monitoring
|
||||
|
||||
Enable takeover + log recording to monitor API usage.
|
||||
|
||||
### Scenario 2: Quick Switching
|
||||
|
||||
With takeover enabled, switching providers does not require restarting CLI tools.
|
||||
|
||||
### Scenario 3: Failover
|
||||
|
||||
Enabling takeover is a prerequisite for using the failover feature.
|
||||
|
||||
## Notes
|
||||
|
||||
### Performance Impact
|
||||
|
||||
The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.
|
||||
|
||||
### Network Requirements
|
||||
|
||||
In takeover mode, CLI tools must be able to access the local proxy address.
|
||||
|
||||
### Configuration Backup
|
||||
|
||||
Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Requests Fail After Takeover
|
||||
|
||||
Check:
|
||||
- Is the proxy service running normally
|
||||
- Is the provider configuration correct
|
||||
- Is the network working properly
|
||||
|
||||
### Configuration Not Restored After Disabling Takeover
|
||||
|
||||
Possible causes:
|
||||
- Proxy exited abnormally
|
||||
- Configuration file was modified by another program
|
||||
|
||||
Solutions:
|
||||
- Manually edit the provider and re-save
|
||||
- Or re-enable and then disable takeover
|
||||
@@ -0,0 +1,232 @@
|
||||
# 4.3 Failover
|
||||
|
||||
## Overview
|
||||
|
||||
The failover feature automatically switches to a backup provider when the primary provider's request fails, ensuring uninterrupted service.
|
||||
|
||||
**Applicable scenarios**:
|
||||
- Unstable provider services
|
||||
- High availability requirements
|
||||
- Long-running tasks
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Using the failover feature requires:
|
||||
|
||||
1. Proxy service started
|
||||
2. App takeover enabled
|
||||
3. Failover queue configured
|
||||
4. Auto failover enabled
|
||||
|
||||
## Configure the Failover Queue
|
||||
|
||||
### Open Configuration Page
|
||||
|
||||
Settings > Advanced > Failover
|
||||
|
||||
### Select Application
|
||||
|
||||
Three tabs at the top of the page:
|
||||
- Claude
|
||||
- Codex
|
||||
- Gemini
|
||||
|
||||
Select the application to configure.
|
||||
|
||||
### Add Backup Providers
|
||||
|
||||
1. In the "Failover Queue" area
|
||||
2. Click "Add Provider"
|
||||
3. Select a provider from the dropdown list
|
||||
4. The provider is added to the end of the queue
|
||||
|
||||
### Adjust Priority
|
||||
|
||||
Drag providers to adjust their order:
|
||||
- Lower numbers mean higher priority
|
||||
- After the primary provider fails, backup providers are tried in order
|
||||
|
||||
### Remove Provider
|
||||
|
||||
Click the "Remove" button to the right of the provider.
|
||||
|
||||
## Main Interface Quick Actions
|
||||
|
||||
When both proxy and failover are enabled, provider cards display a failover toggle.
|
||||
|
||||
### Add to Queue
|
||||
|
||||
1. Find the provider card
|
||||
2. Enable the failover toggle
|
||||
3. The provider is automatically added to the queue
|
||||
|
||||
### Remove from Queue
|
||||
|
||||
1. Disable the failover toggle on the provider card
|
||||
2. The provider is removed from the queue
|
||||
|
||||
## Enable Auto Failover
|
||||
|
||||
### Steps
|
||||
|
||||
1. On the failover configuration page
|
||||
2. Enable the "Auto Failover" toggle
|
||||
|
||||
### Toggle Description
|
||||
|
||||
| State | Behavior |
|
||||
|-------|----------|
|
||||
| Off | Only records failures, no automatic switching |
|
||||
| On | Automatically switches to the next provider on failure |
|
||||
|
||||
## Failover Flow
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start[Request arrives at proxy] --> Send[Send to current provider]
|
||||
Send --> CheckSuccess{Success?}
|
||||
CheckSuccess -- Yes --> Return[Return response]
|
||||
CheckSuccess -- No --> LogFail[Record failure]
|
||||
LogFail --> CheckCircuit{Check circuit breaker}
|
||||
CheckCircuit -- Tripped --> Skip[Skip this provider]
|
||||
CheckCircuit -- Not tripped --> IncFail[Increment failure count]
|
||||
Skip --> Next{Next in queue?}
|
||||
IncFail --> Next
|
||||
Next -- Yes --> Switch[Switch provider]
|
||||
Switch --> Retry[Retry request]
|
||||
Retry --> Send
|
||||
Next -- No --> Error[Return error]
|
||||
```
|
||||
|
||||
## Circuit Breaker Configuration
|
||||
|
||||
The circuit breaker prevents frequent retries against failing providers.
|
||||
|
||||
### Configuration Items
|
||||
|
||||
Different apps have independent default configurations. Below are general defaults; Claude has its own relaxed configuration.
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Failure Threshold | Consecutive failures to trigger circuit breaker | 4 | 8 | 1-20 |
|
||||
| Recovery Success Threshold | Successes needed in half-open state to close breaker | 2 | 3 | 1-10 |
|
||||
| Recovery Wait Time | Time before attempting recovery after tripping (seconds) | 60 | 90 | 0-300 |
|
||||
| Error Rate Threshold | Error rate that opens the circuit breaker | 60% | 70% | 0-100% |
|
||||
| Minimum Requests | Minimum requests before calculating error rate | 10 | 15 | 5-100 |
|
||||
|
||||
> Claude has more relaxed default settings due to longer request times, tolerating more failures.
|
||||
|
||||
### Timeout Configuration
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Stream First Byte Timeout | Max wait time for first data chunk (seconds) | 60 | 90 | 1-120 |
|
||||
| Stream Idle Timeout | Max interval between data chunks (seconds) | 120 | 180 | 60-600 (0 to disable) |
|
||||
| Non-stream Timeout | Total timeout for non-streaming requests (seconds) | 600 | 600 | 60-1200 |
|
||||
|
||||
### Retry Configuration
|
||||
|
||||
| Setting | Description | General Default | Claude Default | Range |
|
||||
|---------|-------------|-----------------|----------------|-------|
|
||||
| Max Retries | Number of retries on request failure | 3 | 6 | 0-10 |
|
||||
|
||||
> Gemini's default max retries is 5.
|
||||
|
||||
### Circuit Breaker States
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| Closed | Normal state, requests allowed |
|
||||
| Open | Circuit broken, this provider is skipped |
|
||||
| Half-Open | Attempting recovery, sending probe requests |
|
||||
|
||||
### State Transitions
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Closed: Initialize
|
||||
Closed --> Open: Failures >= threshold
|
||||
Open --> HalfOpen: Recovery wait time expires
|
||||
HalfOpen --> Closed: Probe successes >= recovery threshold
|
||||
HalfOpen --> Open: Probe failed
|
||||
```
|
||||
|
||||
## Health Status Indicators
|
||||
|
||||
### Provider Cards
|
||||
|
||||
Cards display health status badges:
|
||||
|
||||
| Badge | Status | Description |
|
||||
|-------|--------|-------------|
|
||||
| Green | Healthy | 0 consecutive failures |
|
||||
| Yellow | Warning | Has failures but circuit not tripped |
|
||||
| Red | Circuit Broken | Circuit breaker tripped, temporarily skipped |
|
||||
|
||||
### Queue List
|
||||
|
||||
The failover queue also displays each provider's health status.
|
||||
|
||||
## Failover Logs
|
||||
|
||||
Each failover event records:
|
||||
|
||||
| Information | Description |
|
||||
|-------------|-------------|
|
||||
| Time | When it occurred |
|
||||
| Original Provider | The provider that failed |
|
||||
| New Provider | The provider switched to |
|
||||
| Failure Reason | Error message |
|
||||
|
||||
Viewable in the request logs within usage statistics.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Queue Configuration Recommendations
|
||||
|
||||
1. **Primary provider**: The most stable and fastest provider
|
||||
2. **First backup**: Second-best choice
|
||||
3. **Second backup**: Last resort
|
||||
|
||||
### Circuit Breaker Configuration Recommendations
|
||||
|
||||
| Scenario | Failure Threshold | Recovery Wait |
|
||||
|----------|-------------------|---------------|
|
||||
| High availability requirement | 2 | 30 seconds |
|
||||
| General scenario | 3 | 60 seconds |
|
||||
| Tolerant of occasional failures | 5 | 120 seconds |
|
||||
|
||||
### Monitoring Recommendations
|
||||
|
||||
Periodically check:
|
||||
- Health status of each provider
|
||||
- Failover frequency
|
||||
- Circuit breaker trigger frequency
|
||||
|
||||
## FAQ
|
||||
|
||||
### Failover Not Triggering
|
||||
|
||||
Check:
|
||||
1. Is the proxy service running
|
||||
2. Is app takeover enabled
|
||||
3. Is auto failover enabled
|
||||
4. Are there backup providers in the queue
|
||||
|
||||
### Failover Triggering Too Frequently
|
||||
|
||||
Possible causes:
|
||||
- Unstable primary provider
|
||||
- Network issues
|
||||
- Configuration errors
|
||||
|
||||
Solutions:
|
||||
- Check primary provider status
|
||||
- Adjust circuit breaker parameters
|
||||
- Consider changing the primary provider
|
||||
|
||||
### All Providers Circuit-Broken
|
||||
|
||||
Wait for the recovery wait time to expire for automatic recovery, or:
|
||||
1. Manually restart the proxy service
|
||||
2. Reset circuit breaker states
|
||||
@@ -0,0 +1,291 @@
|
||||
# 4.4 Usage Statistics
|
||||
|
||||
## Overview
|
||||
|
||||
The usage statistics feature records and analyzes API request data, helping you:
|
||||
|
||||
- Understand API usage patterns
|
||||
- Estimate cost expenditure
|
||||
- Analyze usage patterns
|
||||
- Troubleshoot issues
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Using the usage statistics feature requires:
|
||||
|
||||
1. Proxy service started
|
||||
2. App takeover enabled
|
||||
3. Log recording enabled
|
||||
|
||||
## Open Usage Statistics
|
||||
|
||||
Settings > Usage Tab
|
||||
|
||||
## Statistics Overview
|
||||
|
||||
### Summary Cards
|
||||
|
||||
Key metrics displayed at the top of the page:
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| Total Requests | Total number of requests in the time period |
|
||||
| Total Tokens | Total input + output tokens |
|
||||
| Estimated Cost | Cost calculated based on pricing configuration |
|
||||
| Success Rate | Percentage of successful requests |
|
||||
|
||||
### Time Range
|
||||
|
||||
Select the time range for statistics:
|
||||
|
||||
| Option | Range |
|
||||
|--------|-------|
|
||||
| Today | From 00:00 today to now |
|
||||
| Last 7 Days | Past 7 days |
|
||||
| Last 30 Days | Past 30 days |
|
||||
|
||||
|
||||
|
||||
## Trend Charts
|
||||
|
||||
### Request Trend
|
||||
|
||||
Line chart showing the trend of request counts:
|
||||
|
||||
- X-axis: Time
|
||||
- Y-axis: Request count
|
||||
- Viewable by hour/day
|
||||
- Supports zoom and drag
|
||||
|
||||
### Token Trend
|
||||
|
||||
Shows token usage trends:
|
||||
|
||||
- Input Tokens (blue) - Prompt content sent by the user
|
||||
- Output Tokens (green) - Response content generated by AI
|
||||
- Cache Creation Tokens (orange) - Tokens consumed when first creating cache
|
||||
- Cache Hit Tokens (purple) - Tokens saved by reusing cache
|
||||
- Cost (red dashed line, right Y-axis) - Estimated cost
|
||||
|
||||
> **Cache Token explanation**: Anthropic API supports Prompt Caching. Creating cache incurs a higher fee (typically 1.25x input price), but subsequent cache hits only charge 0.1x, significantly reducing costs for repeated requests.
|
||||
|
||||
### Time Granularity
|
||||
|
||||
- **Today**: Displayed by hour (24 data points)
|
||||
- **7 Days/30 Days**: Displayed by day
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Detailed Data
|
||||
|
||||
Three data tabs at the bottom of the page:
|
||||
|
||||
### Request Logs
|
||||
|
||||
Detailed record of each request:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Time | Request time |
|
||||
| Provider | Provider name used |
|
||||
| Model | Requested model (billing model) |
|
||||
| Input Tokens | Number of input tokens |
|
||||
| Output Tokens | Number of output tokens |
|
||||
| Cache Read | Cache hit token count |
|
||||
| Cache Creation | Cache creation token count |
|
||||
| Total Cost | Estimated cost (USD) |
|
||||
| Timing Info | Request duration, time to first token, streaming/non-streaming |
|
||||
| Status | HTTP status code |
|
||||
|
||||
#### Timing Information
|
||||
|
||||
The timing info column displays multiple badges:
|
||||
|
||||
| Badge | Description | Color Rules |
|
||||
|-------|-------------|-------------|
|
||||
| Total Duration | Total request time (seconds) | <=5s green, <=120s orange, >120s red |
|
||||
| First Token | Time to first token in streaming requests | <=5s green, <=120s orange, >120s red |
|
||||
| Stream/Non-stream | Request type | Streaming blue, non-streaming purple |
|
||||
|
||||
#### View Details
|
||||
|
||||
Click a request row to view detailed information:
|
||||
|
||||
- Complete request parameters
|
||||
- Response content summary
|
||||
- Error messages (if failed)
|
||||
|
||||
#### Filter Logs
|
||||
|
||||
Supports filtering by the following criteria:
|
||||
|
||||
| Filter | Options |
|
||||
|--------|---------|
|
||||
| App Type | All / Claude / Codex / Gemini |
|
||||
| Status Code | All / 200 / 400 / 401 / 429 / 500 |
|
||||
| Provider | Text search |
|
||||
| Model | Text search |
|
||||
| Time Range | Start time - End time (datetime picker) |
|
||||
|
||||
Action buttons:
|
||||
- **Search**: Apply filter criteria
|
||||
- **Reset**: Restore defaults (past 24 hours)
|
||||
- **Refresh**: Reload data
|
||||
|
||||
|
||||
|
||||
### Provider Statistics
|
||||
|
||||
Statistics grouped by provider:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Provider | Provider name |
|
||||
| Requests | Total requests for this provider |
|
||||
| Successes | Number of successful requests |
|
||||
| Failures | Number of failed requests |
|
||||
| Success Rate | Success percentage |
|
||||
| Total Tokens | Total token usage |
|
||||
| Estimated Cost | Cost for this provider |
|
||||
|
||||
|
||||
|
||||
### Model Statistics
|
||||
|
||||
Statistics grouped by model:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Model | Model name |
|
||||
| Requests | Total requests for this model |
|
||||
| Input Tokens | Total input tokens |
|
||||
| Output Tokens | Total output tokens |
|
||||
| Avg Latency | Average response time |
|
||||
| Estimated Cost | Cost for this model |
|
||||
|
||||
|
||||
|
||||
## Pricing Configuration
|
||||
|
||||
### Open Pricing Configuration
|
||||
|
||||
Settings > Advanced > Pricing Configuration
|
||||
|
||||
### Configure Model Prices
|
||||
|
||||
Set prices for each model (per million tokens):
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Model ID | Model identifier (e.g., claude-3-sonnet) |
|
||||
| Display Name | Custom display name |
|
||||
| Input Price | Price per million input tokens |
|
||||
| Output Price | Price per million output tokens |
|
||||
| Cache Read Price | Price per million cache hit tokens |
|
||||
| Cache Creation Price | Price per million cache creation tokens |
|
||||
|
||||
### Operations
|
||||
|
||||
- **Add**: Click the "Add" button to add model pricing
|
||||
- **Edit**: Click the edit icon at the end of the row to modify
|
||||
- **Delete**: Click the delete icon at the end of the row to remove
|
||||
|
||||
|
||||
|
||||
### Preset Prices
|
||||
|
||||
CC Switch includes preset official prices for common models (per million tokens):
|
||||
|
||||
**Claude Series (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read | Cache Creation |
|
||||
|-------|-------|--------|------------|----------------|
|
||||
| **Claude 4.5 Series** | | | | |
|
||||
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
|
||||
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
|
||||
| **Claude 4 Series** | | | | |
|
||||
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
|
||||
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
|
||||
| **Claude 3.5 Series** | | | | |
|
||||
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
|
||||
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
|
||||
|
||||
**OpenAI Series / Codex (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **GPT-5.2 Series** | | | |
|
||||
| gpt-5.2 | $1.75 | $14 | $0.175 |
|
||||
| **GPT-5.1 Series** | | | |
|
||||
| gpt-5.1 | $1.25 | $10 | $0.125 |
|
||||
| **GPT-5 Series** | | | |
|
||||
| gpt-5 | $1.25 | $10 | $0.125 |
|
||||
|
||||
> Note: Codex presets include low/medium/high variants with prices identical to the base model.
|
||||
|
||||
**Gemini Series (USD)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **Gemini 3 Series** | | | |
|
||||
| gemini-3-pro-preview | $2 | $12 | $0.20 |
|
||||
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
|
||||
| **Gemini 2.5 Series** | | | |
|
||||
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
|
||||
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
|
||||
|
||||
**Chinese Provider Models (CNY)**:
|
||||
|
||||
| Model | Input | Output | Cache Read |
|
||||
|-------|-------|--------|------------|
|
||||
| **DeepSeek** | | | |
|
||||
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
|
||||
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
|
||||
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| **Kimi (Moonshot)** | | | |
|
||||
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
|
||||
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
|
||||
| **MiniMax** | | | |
|
||||
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
|
||||
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
|
||||
| **Others** | | | |
|
||||
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
|
||||
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
|
||||
| mimo-v2-flash | Free | Free | - |
|
||||
|
||||
### Custom Prices
|
||||
|
||||
If using proxy services, prices may differ:
|
||||
|
||||
1. Click the "Edit" button
|
||||
2. Modify prices
|
||||
3. Save
|
||||
|
||||
## FAQ
|
||||
|
||||
### Statistics Data Is Empty
|
||||
|
||||
Check:
|
||||
- Is the proxy service running
|
||||
- Is app takeover enabled
|
||||
- Is log recording enabled
|
||||
- Have requests been going through the proxy
|
||||
|
||||
### Cost Estimates Are Inaccurate
|
||||
|
||||
Possible causes:
|
||||
- Pricing configuration doesn't match actual prices
|
||||
- Using a proxy service with special pricing
|
||||
|
||||
Solutions:
|
||||
- Update pricing configuration
|
||||
- Refer to the provider's actual invoices
|
||||
|
||||
### Token Count Differs from Provider
|
||||
|
||||
CC Switch uses its own method to estimate token counts, which may slightly differ from the provider's calculation. Refer to the provider's invoice for authoritative numbers.
|
||||
@@ -0,0 +1,156 @@
|
||||
# 4.5 Model Test
|
||||
|
||||
## Overview
|
||||
|
||||
The model test feature verifies whether a provider's configured model is available by sending actual API requests to test:
|
||||
|
||||
- Whether the model exists
|
||||
- Whether the API Key is valid
|
||||
- Whether the endpoint responds normally
|
||||
- Whether the response latency is acceptable
|
||||
|
||||
## Open Configuration
|
||||
|
||||
Settings > Advanced > Model Test Config
|
||||
|
||||
## Test Model Configuration
|
||||
|
||||
Configure the model used for testing per application:
|
||||
|
||||
| Application | Setting | Default | Notes |
|
||||
|-------------|---------|---------|-------|
|
||||
| Claude | Claude Model | System default | Recommend using Haiku series (low cost, fast) |
|
||||
| Codex | Codex Model | System default | Recommend using mini series |
|
||||
| Gemini | Gemini Model | System default | Recommend using Flash series |
|
||||
|
||||
### Model Selection Tips
|
||||
|
||||
When choosing a test model, consider:
|
||||
|
||||
1. **Cost**: Choose lower-priced models (e.g., Haiku, Mini, Flash)
|
||||
2. **Speed**: Choose fast-responding models
|
||||
3. **Availability**: Choose models supported by the provider
|
||||
|
||||
## Test Parameter Configuration
|
||||
|
||||
### Timeout
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Timeout | Single request timeout | 45 seconds | 10-120 seconds |
|
||||
|
||||
Setting it too short may cause false negatives; too long delays fault detection.
|
||||
|
||||
### Retries
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Max Retries | Retries after failure | 2 times | 0-5 times |
|
||||
|
||||
Increase retries when the network is unstable.
|
||||
|
||||
### Degradation Threshold
|
||||
|
||||
| Parameter | Description | Default | Range |
|
||||
|-----------|-------------|---------|-------|
|
||||
| Degradation Threshold | Responses exceeding this time are marked as degraded | 6000ms | 1000-30000ms |
|
||||
|
||||
Providers exceeding the threshold are marked as "degraded" but remain usable.
|
||||
|
||||
## Execute Model Test
|
||||
|
||||
### Manual Test
|
||||
|
||||
Click the "Test" button on the provider card:
|
||||
|
||||
1. Sends a test request to the configured endpoint
|
||||
2. Uses the configured test model
|
||||
3. Waits for response or timeout
|
||||
4. Displays the test result
|
||||
|
||||
### Test Content
|
||||
|
||||
The test request:
|
||||
- Sends a short prompt (e.g., "Hi")
|
||||
- Limits maximum output tokens (typically 10-50)
|
||||
- Uses streaming response to detect time to first byte
|
||||
|
||||
## Test Results
|
||||
|
||||
### Health Status
|
||||
|
||||
| Status | Icon | Description |
|
||||
|--------|------|-------------|
|
||||
| Healthy | Green | Normal response, latency within threshold |
|
||||
| Degraded | Yellow | Normal response, but latency exceeds threshold |
|
||||
| Unavailable | Red | Request failed or timed out |
|
||||
|
||||
### Result Information
|
||||
|
||||
After testing completes, displays:
|
||||
- Response latency (milliseconds)
|
||||
- Time to first byte (TTFB)
|
||||
- Error message (if failed)
|
||||
|
||||
## Integration with Failover
|
||||
|
||||
Model testing works in conjunction with the failover feature:
|
||||
|
||||
### Health Checks
|
||||
|
||||
After enabling the proxy service, the system periodically performs health checks on providers in the failover queue:
|
||||
|
||||
1. Sends a request using the configured test model
|
||||
2. Updates health status based on the response
|
||||
3. Unhealthy providers are temporarily skipped
|
||||
|
||||
### Circuit Breaker Recovery
|
||||
|
||||
When a provider recovers from a circuit-broken state:
|
||||
|
||||
1. Performs a model test to verify availability
|
||||
2. If the test passes, normal status is restored
|
||||
3. If the test fails, the circuit breaker remains active
|
||||
|
||||
## FAQ
|
||||
|
||||
### Test Fails But Actually Available
|
||||
|
||||
**Possible causes**:
|
||||
- The test model differs from the actually used model
|
||||
- The provider doesn't support the configured test model
|
||||
|
||||
**Solutions**:
|
||||
- Change the test model to one supported by the provider
|
||||
- Check the provider's model list
|
||||
|
||||
### High Latency
|
||||
|
||||
**Possible causes**:
|
||||
- Network latency
|
||||
- High server load on the provider
|
||||
- Slow model response
|
||||
|
||||
**Solutions**:
|
||||
- Use a faster test model
|
||||
- Adjust the degradation threshold
|
||||
- Consider using mirror endpoints
|
||||
|
||||
### Frequent Timeouts
|
||||
|
||||
**Possible causes**:
|
||||
- Timeout set too short
|
||||
- Unstable network
|
||||
- Unstable provider service
|
||||
|
||||
**Solutions**:
|
||||
- Increase the timeout
|
||||
- Increase retry count
|
||||
- Check network connection
|
||||
|
||||
## Notes
|
||||
|
||||
- Model testing consumes a small amount of API quota
|
||||
- Recommend using low-cost models for testing
|
||||
- Testing frequency should not be too high to avoid wasting quota
|
||||
- Different providers may support different models
|
||||
@@ -0,0 +1,340 @@
|
||||
# 5.1 Configuration Files
|
||||
|
||||
## CC Switch Data Storage
|
||||
|
||||
### Storage Directory
|
||||
|
||||
Default location: `~/.cc-switch/`
|
||||
|
||||
Customizable location in settings (for cloud sync).
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/.cc-switch/
|
||||
├── cc-switch.db # SQLite database
|
||||
├── settings.json # Device-level settings
|
||||
└── backups/ # Automatic backups
|
||||
├── backup-20251230-120000.json
|
||||
├── backup-20251229-180000.json
|
||||
└── ...
|
||||
```
|
||||
|
||||
### Database Contents
|
||||
|
||||
`cc-switch.db` is a SQLite database that stores:
|
||||
|
||||
| Table | Contents |
|
||||
|-------|----------|
|
||||
| providers | Provider configurations |
|
||||
| provider_endpoints | Provider endpoint candidate list |
|
||||
| mcp_servers | MCP server configurations |
|
||||
| prompts | Prompt presets |
|
||||
| skills | Skill installation status |
|
||||
| skill_repos | Skill repository configurations |
|
||||
| proxy_config | Proxy configuration |
|
||||
| proxy_request_logs | Proxy request logs |
|
||||
| provider_health | Provider health status |
|
||||
| model_pricing | Model pricing |
|
||||
| settings | App settings |
|
||||
|
||||
### Device Settings
|
||||
|
||||
`settings.json` stores device-level settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "zh",
|
||||
"theme": "system",
|
||||
"windowBehavior": "minimize",
|
||||
"autoStart": false,
|
||||
"claudeConfigDir": null,
|
||||
"codexConfigDir": null,
|
||||
"geminiConfigDir": null,
|
||||
"opencodeConfigDir": null,
|
||||
"openclawConfigDir": null
|
||||
}
|
||||
```
|
||||
|
||||
These settings are not synced across devices.
|
||||
|
||||
### Automatic Backups
|
||||
|
||||
The `backups/` directory stores automatic backups:
|
||||
|
||||
- Automatically created before each configuration import
|
||||
- Retains the most recent 10 backups
|
||||
- File names include timestamps
|
||||
|
||||
## Claude Code Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.claude/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── settings.json # Main configuration file
|
||||
├── CLAUDE.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ANTHROPIC_API_KEY": "sk-xxx",
|
||||
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
|
||||
},
|
||||
"permissions": {
|
||||
"allow_file_access": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `env.ANTHROPIC_API_KEY` | API key |
|
||||
| `env.ANTHROPIC_BASE_URL` | API endpoint (optional) |
|
||||
| `env.ANTHROPIC_AUTH_TOKEN` | Alternative authentication method |
|
||||
|
||||
### MCP Configuration
|
||||
|
||||
MCP server configuration is in `~/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codex Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.codex/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.codex/
|
||||
├── auth.json # Authentication configuration
|
||||
├── config.toml # Main configuration + MCP
|
||||
└── AGENTS.md # System prompt
|
||||
```
|
||||
|
||||
### auth.json
|
||||
|
||||
```json
|
||||
{
|
||||
"OPENAI_API_KEY": "sk-xxx"
|
||||
}
|
||||
```
|
||||
|
||||
### config.toml
|
||||
|
||||
```toml
|
||||
# Basic configuration
|
||||
base_url = "https://api.openai.com/v1"
|
||||
model = "gpt-4"
|
||||
|
||||
# MCP servers
|
||||
[mcp_servers.mcp-fetch]
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
```
|
||||
|
||||
## Gemini CLI Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.gemini/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.gemini/
|
||||
├── .env # Environment variables (API Key)
|
||||
├── settings.json # Main configuration + MCP
|
||||
└── GEMINI.md # System prompt
|
||||
```
|
||||
|
||||
### .env
|
||||
|
||||
```bash
|
||||
GEMINI_API_KEY=xxx
|
||||
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
|
||||
GEMINI_MODEL=gemini-pro
|
||||
```
|
||||
|
||||
### settings.json
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-fetch": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-server-fetch"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `mcpServers` | MCP server configuration |
|
||||
|
||||
## OpenCode Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.opencode/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.opencode/
|
||||
├── config.json # Main configuration file
|
||||
├── AGENTS.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
## OpenClaw Configuration
|
||||
|
||||
### Configuration Directory
|
||||
|
||||
Default: `~/.openclaw/`
|
||||
|
||||
### Key Files
|
||||
|
||||
```
|
||||
~/.openclaw/
|
||||
├── openclaw.json # Main configuration file (JSON5 format)
|
||||
├── AGENTS.md # System prompt
|
||||
└── skills/ # Skills directory
|
||||
└── ...
|
||||
```
|
||||
|
||||
### openclaw.json
|
||||
|
||||
OpenClaw uses a JSON5 format configuration file with the following main sections:
|
||||
|
||||
```json5
|
||||
{
|
||||
// Model provider configuration
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
"custom-provider": {
|
||||
baseUrl: "https://api.example.com/v1",
|
||||
apiKey: "your-api-key",
|
||||
api: "openai-completions",
|
||||
models: [{ id: "model-id", name: "Model Name" }]
|
||||
}
|
||||
}
|
||||
},
|
||||
// Environment variables
|
||||
env: {
|
||||
ANTHROPIC_API_KEY: "sk-..."
|
||||
},
|
||||
// Agent default model configuration
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "provider/model"
|
||||
}
|
||||
}
|
||||
},
|
||||
// Tool configuration
|
||||
tools: {},
|
||||
// Workspace file configuration
|
||||
workspace: {}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `models.providers` | Provider configuration (mapped to CC Switch's "providers") |
|
||||
| `env` | Environment variable configuration |
|
||||
| `agents.defaults` | Agent default model settings |
|
||||
| `tools` | Tool configuration |
|
||||
| `workspace` | Workspace file management |
|
||||
|
||||
## Configuration Priority
|
||||
|
||||
CC Switch's priority when modifying configurations:
|
||||
|
||||
1. **CC Switch Database** - Single source of truth (SSOT)
|
||||
2. **Live Configuration Files** - Written when switching providers
|
||||
3. **Backfill Mechanism** - Reads from live files when editing the current provider
|
||||
|
||||
## Manual Configuration Editing
|
||||
|
||||
### Safe to Edit Manually
|
||||
|
||||
- CLI tool configuration files (will be backfilled by CC Switch)
|
||||
- CC Switch's `settings.json`
|
||||
|
||||
### Not Recommended to Edit Manually
|
||||
|
||||
- `cc-switch.db` database file
|
||||
- Backup files
|
||||
|
||||
### Sync After Editing
|
||||
|
||||
If you manually edit CLI tool configurations:
|
||||
|
||||
1. Open CC Switch
|
||||
2. Edit the corresponding provider
|
||||
3. You will see the manual changes have been backfilled
|
||||
4. Save to sync to the database
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
### Migrating from Older Versions
|
||||
|
||||
CC Switch v3.7.0 migrated from JSON files to SQLite:
|
||||
|
||||
- Automatic migration on first launch
|
||||
- Displays a notification upon successful migration
|
||||
- Old configuration files are retained as backups
|
||||
|
||||
### Cross-device Migration
|
||||
|
||||
1. Export configuration on the source device
|
||||
2. Import configuration on the target device
|
||||
3. Or use the cloud sync feature
|
||||
|
||||
## Configuration Backup Recommendations
|
||||
|
||||
### Regular Backups
|
||||
|
||||
It is recommended to regularly export configurations:
|
||||
|
||||
1. Settings > Advanced > Data Management
|
||||
2. Click "Export"
|
||||
3. Save to a secure location
|
||||
|
||||
### Backup Contents
|
||||
|
||||
The export file includes:
|
||||
|
||||
- All provider configurations
|
||||
- MCP server configurations
|
||||
- Prompt presets
|
||||
- App settings
|
||||
|
||||
### Not Included
|
||||
|
||||
- Usage logs (large data volume)
|
||||
- Device-level settings (not suitable for cross-device)
|
||||
@@ -0,0 +1,220 @@
|
||||
# 5.2 Frequently Asked Questions
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### macOS Shows "Unidentified Developer"
|
||||
|
||||
**Problem**: First launch shows "Cannot open because it is from an unidentified developer"
|
||||
|
||||
**Solution 1**: Via System Settings
|
||||
1. Close the warning dialog
|
||||
2. Open "System Settings" > "Privacy & Security"
|
||||
3. Find the CC Switch prompt
|
||||
4. Click "Open Anyway"
|
||||
5. Reopen the app
|
||||
|
||||
**Solution 2**: Via Terminal command (recommended)
|
||||
```bash
|
||||
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
||||
```
|
||||
|
||||
The app can be opened normally after running this command.
|
||||
|
||||
### Windows: App Doesn't Launch After Installation
|
||||
|
||||
**Possible causes**:
|
||||
- Missing WebView2 runtime
|
||||
- Antivirus software blocking
|
||||
|
||||
**Solutions**:
|
||||
1. Install [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
||||
2. Add CC Switch to your antivirus software's whitelist
|
||||
|
||||
### Linux: Startup Error
|
||||
|
||||
**Problem**: AppImage won't start
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Add execute permission
|
||||
chmod +x CC-Switch-*.AppImage
|
||||
|
||||
# If it still fails, try
|
||||
./CC-Switch-*.AppImage --no-sandbox
|
||||
```
|
||||
|
||||
## Provider Issues
|
||||
|
||||
### Provider Switch Doesn't Take Effect
|
||||
|
||||
**Cause**: The CLI tool needs to reload its configuration
|
||||
|
||||
**Solutions**:
|
||||
- Claude Code: Close and reopen the terminal, or restart the IDE
|
||||
- Codex: Close and reopen the terminal
|
||||
- Gemini: Tray switching takes effect immediately, no restart needed
|
||||
|
||||
### API Key Invalid
|
||||
|
||||
**Troubleshooting steps**:
|
||||
1. Confirm the API Key is copied correctly (no extra spaces)
|
||||
2. Confirm the API Key hasn't expired
|
||||
3. Confirm the endpoint URL is correct
|
||||
4. Use the speed test to verify connectivity
|
||||
|
||||
### How to Restore Official Login
|
||||
|
||||
**Steps**:
|
||||
1. Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini)
|
||||
2. Click "Enable"
|
||||
3. Restart the corresponding CLI tool
|
||||
4. Follow the CLI tool's login flow
|
||||
|
||||
## Proxy Issues
|
||||
|
||||
### Proxy Service Fails to Start
|
||||
|
||||
**Possible cause**: Port is occupied
|
||||
|
||||
**Solution**:
|
||||
1. Check port usage:
|
||||
```bash
|
||||
# macOS/Linux
|
||||
lsof -i :49152
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr :49152
|
||||
```
|
||||
2. Close the program occupying the port
|
||||
3. Or try modifying the configuration to restore the default port:
|
||||
- Open "Settings > Proxy Service"
|
||||
- Click the "Reset to Default" button
|
||||
|
||||
### Request Timeout in Proxy Mode
|
||||
|
||||
**Possible causes**:
|
||||
- Network issues
|
||||
- Provider server issues
|
||||
- Incorrect proxy configuration
|
||||
|
||||
**Solutions**:
|
||||
1. Check network connection
|
||||
2. Try accessing the provider API directly (disable proxy)
|
||||
3. Check if provider configuration is correct
|
||||
|
||||
### Configuration Not Restored After Disabling Proxy
|
||||
|
||||
**Possible cause**: Proxy exited abnormally
|
||||
|
||||
**Solution**:
|
||||
1. Edit the current provider
|
||||
2. Check if the endpoint URL is correct
|
||||
3. Save to update the configuration
|
||||
|
||||
## Failover Issues
|
||||
|
||||
### Failover Not Triggering
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Is the proxy service running
|
||||
- [ ] Is app takeover enabled
|
||||
- [ ] Is auto failover enabled
|
||||
- [ ] Are there backup providers in the queue
|
||||
|
||||
### Failover Triggering Too Frequently
|
||||
|
||||
**Possible causes**:
|
||||
- Unstable primary provider
|
||||
- Circuit breaker threshold set too low
|
||||
|
||||
**Solutions**:
|
||||
1. Check primary provider status
|
||||
2. Increase the failure threshold (e.g., from 3 to 5)
|
||||
3. Consider changing the primary provider
|
||||
|
||||
### All Providers Are Circuit-Broken
|
||||
|
||||
**Solutions**:
|
||||
1. Wait for the recovery wait time to expire (default 60 seconds)
|
||||
2. Or restart the proxy service to reset states
|
||||
|
||||
## Data Issues
|
||||
|
||||
### Configuration Lost
|
||||
|
||||
**Possible causes**:
|
||||
- Configuration directory was deleted
|
||||
- Database corruption
|
||||
|
||||
**Solutions**:
|
||||
1. Check if the `~/.cc-switch/` directory exists
|
||||
2. Restore from backup: `~/.cc-switch/backups/`
|
||||
3. Or import from a previously exported configuration file
|
||||
|
||||
### Import Configuration Failed
|
||||
|
||||
**Possible causes**:
|
||||
- Incorrect file format
|
||||
- Version incompatibility
|
||||
|
||||
**Solutions**:
|
||||
1. Confirm the file was exported by CC Switch
|
||||
2. Check if the file content is complete
|
||||
3. Try opening with a text editor to check format
|
||||
|
||||
### Usage Statistics Data Is Empty
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Is the proxy service running
|
||||
- [ ] Is app takeover enabled
|
||||
- [ ] Is log recording enabled
|
||||
- [ ] Have requests been going through the proxy
|
||||
|
||||
## Other Issues
|
||||
|
||||
### Tray Icon Not Showing
|
||||
|
||||
**macOS**:
|
||||
- Check menu bar icon settings in System Settings
|
||||
|
||||
**Windows**:
|
||||
- Check taskbar settings to ensure the CC Switch icon is not hidden
|
||||
|
||||
**Linux**:
|
||||
- System tray support may need to be installed (e.g., `libappindicator`)
|
||||
|
||||
### UI Display Issues
|
||||
|
||||
**Solutions**:
|
||||
1. Try switching themes (light/dark)
|
||||
2. Restart the app
|
||||
3. Delete `~/.cc-switch/settings.json` to reset settings
|
||||
|
||||
### Update Failed
|
||||
|
||||
**Solutions**:
|
||||
1. Check network connection
|
||||
2. Manually download and install the latest version
|
||||
3. If using Homebrew: `brew upgrade --cask cc-switch`
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Submit an Issue
|
||||
|
||||
If none of the above solutions work:
|
||||
|
||||
1. Visit [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
2. Search for similar issues
|
||||
3. If none found, create a new Issue
|
||||
4. Provide the following information:
|
||||
- Operating system and version
|
||||
- CC Switch version
|
||||
- Problem description and reproduction steps
|
||||
- Error messages (if any)
|
||||
|
||||
### Log Files
|
||||
|
||||
Attach log files when submitting an Issue:
|
||||
|
||||
- macOS/Linux: `~/.cc-switch/logs/`
|
||||
- Windows: `%APPDATA%\cc-switch\logs\`
|
||||
@@ -0,0 +1,256 @@
|
||||
# 5.3 Deep Link Protocol
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch supports the `ccswitch://` deep link protocol, enabling one-click configuration import via links.
|
||||
|
||||
**Use cases**:
|
||||
- Team configuration sharing
|
||||
- One-click setup in tutorials
|
||||
- Quick sync across devices
|
||||
|
||||
## Online Generator Tool
|
||||
|
||||
CC Switch provides an online deep link generator tool:
|
||||
|
||||
**URL**: [https://farion1231.github.io/cc-switch/deplink.html](https://farion1231.github.io/cc-switch/deplink.html)
|
||||
|
||||
### How to Use
|
||||
|
||||
1. Open the above URL
|
||||
2. Select the import type (Provider/MCP/Prompt)
|
||||
3. Fill in the configuration information
|
||||
4. Click "Generate Link"
|
||||
5. Copy the generated deep link
|
||||
6. Share with others or use on other devices
|
||||
|
||||
## Protocol Format
|
||||
|
||||
### V1 Protocol
|
||||
|
||||
Uses URL parameter format, easy to read and generate:
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource={type}&app={app}&name={name}&...
|
||||
```
|
||||
|
||||
**Common parameters**:
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `resource` | Yes | Resource type: `provider` / `mcp` / `prompt` / `skill` |
|
||||
| `app` | Yes | App type: `claude` / `codex` / `gemini` / `opencode` / `openclaw` |
|
||||
| `name` | Yes | Name |
|
||||
|
||||
**Provider parameters** (resource=provider):
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `endpoint` | No | API endpoint URL (supports comma-separated multiple URLs) |
|
||||
| `apiKey` | No | API key |
|
||||
| `homepage` | No | Provider website |
|
||||
| `model` | No | Default model |
|
||||
| `haikuModel` | No | Haiku model (Claude only) |
|
||||
| `sonnetModel` | No | Sonnet model (Claude only) |
|
||||
| `opusModel` | No | Opus model (Claude only) |
|
||||
| `notes` | No | Notes |
|
||||
| `icon` | No | Icon |
|
||||
| `config` | No | Base64-encoded configuration content |
|
||||
| `configFormat` | No | Configuration format: `json` / `toml` |
|
||||
| `configUrl` | No | Remote configuration URL |
|
||||
| `enabled` | No | Whether to enable (boolean) |
|
||||
| `usageScript` | No | Usage query script |
|
||||
| `usageEnabled` | No | Whether to enable usage query (default true) |
|
||||
| `usageApiKey` | No | Usage query API Key |
|
||||
| `usageBaseUrl` | No | Usage query base URL |
|
||||
| `usageAccessToken` | No | Usage query access token |
|
||||
| `usageUserId` | No | Usage query user ID |
|
||||
| `usageAutoInterval` | No | Auto query interval (minutes) |
|
||||
|
||||
**Prompt parameters** (resource=prompt):
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `content` | Yes | Prompt content |
|
||||
| `description` | No | Description |
|
||||
| `enabled` | No | Whether to enable (boolean) |
|
||||
|
||||
**MCP parameters** (resource=mcp):
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `apps` | Yes | App list (comma-separated, e.g., `claude,codex,gemini,opencode`) |
|
||||
| `config` | Yes | MCP server configuration (JSON format) |
|
||||
| `enabled` | No | Whether to enable (boolean) |
|
||||
|
||||
**Skill parameters** (resource=skill):
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `repo` | Yes | Repository (format: `owner/name`) |
|
||||
| `directory` | No | Directory path |
|
||||
| `branch` | No | Git branch |
|
||||
|
||||
**Example**:
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
|
||||
```
|
||||
|
||||
## Import Type Examples
|
||||
|
||||
### Import Provider
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
|
||||
```
|
||||
|
||||
### Import MCP Server
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch
|
||||
```
|
||||
|
||||
### Import Prompt Preset
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6
|
||||
```
|
||||
|
||||
### Import Skill
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
|
||||
```
|
||||
|
||||
## Generate Deep Links
|
||||
|
||||
### Manual Generation
|
||||
|
||||
1. Prepare parameters
|
||||
2. Assemble the URL following V1 protocol format
|
||||
3. URL-encode special characters
|
||||
|
||||
**Example**:
|
||||
|
||||
```javascript
|
||||
const params = new URLSearchParams({
|
||||
resource: 'provider',
|
||||
app: 'claude',
|
||||
name: 'My Provider',
|
||||
endpoint: 'https://api.example.com',
|
||||
apiKey: 'sk-xxx'
|
||||
});
|
||||
|
||||
const url = `ccswitch://v1/import?${params.toString()}`;
|
||||
```
|
||||
|
||||
### Online Tool
|
||||
|
||||
Using CC Switch's official online deep link generator tool is more convenient.
|
||||
|
||||
## Using Deep Links
|
||||
|
||||
### Click the Link
|
||||
|
||||
Click a deep link in a browser or other application:
|
||||
|
||||
1. The system asks whether to open CC Switch
|
||||
2. After confirming, CC Switch opens
|
||||
3. An import confirmation dialog is displayed
|
||||
4. Confirm the import
|
||||
|
||||
### Import Confirmation
|
||||
|
||||
A confirmation dialog is shown before import, containing:
|
||||
|
||||
- Import type
|
||||
- Configuration preview
|
||||
- Confirm/Cancel buttons
|
||||
|
||||
**Security tip**: Only import configurations from trusted sources.
|
||||
|
||||
## Protocol Registration
|
||||
|
||||
### Automatic Registration
|
||||
|
||||
CC Switch automatically registers the `ccswitch://` protocol during installation.
|
||||
|
||||
### Manual Registration
|
||||
|
||||
If the protocol is not registered correctly:
|
||||
|
||||
**macOS**:
|
||||
Reinstall the app, or run:
|
||||
```bash
|
||||
/usr/bin/open -a "CC Switch" --args --register-protocol
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
Reinstall the app, or check the registry:
|
||||
```
|
||||
HKEY_CLASSES_ROOT\ccswitch
|
||||
```
|
||||
|
||||
**Linux**:
|
||||
Check the `MimeType` configuration in the `.desktop` file.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Sensitive Information
|
||||
|
||||
Deep links may contain sensitive information (e.g., API Keys):
|
||||
|
||||
- Do not share links containing API Keys in public
|
||||
- Remove or replace sensitive information before sharing
|
||||
- Use secure channels to transmit links
|
||||
|
||||
### Source Verification
|
||||
|
||||
Before import, CC Switch will:
|
||||
|
||||
1. Validate the data format
|
||||
2. Display a configuration preview
|
||||
3. Require user confirmation
|
||||
|
||||
### Malicious Link Protection
|
||||
|
||||
CC Switch checks:
|
||||
|
||||
- Whether the data format is valid
|
||||
- Whether required fields are complete
|
||||
- Whether configuration values are within reasonable ranges
|
||||
|
||||
## Example Links
|
||||
|
||||
### Example: Import Claude Provider
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com
|
||||
```
|
||||
|
||||
### Example: Import MCP Server
|
||||
|
||||
```
|
||||
ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Link Won't Open
|
||||
|
||||
**Check**:
|
||||
1. Is CC Switch installed
|
||||
2. Is the protocol registered correctly
|
||||
3. Is the link format correct
|
||||
|
||||
### Import Failed
|
||||
|
||||
**Possible causes**:
|
||||
- Base64 encoding error
|
||||
- JSON format error
|
||||
- Missing required fields
|
||||
|
||||
**Solutions**:
|
||||
1. Check the original JSON format
|
||||
2. Re-encode in Base64
|
||||
3. Ensure all required fields are present
|
||||
@@ -0,0 +1,108 @@
|
||||
# 5.4 Environment Variable Conflicts
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch automatically detects conflicts between system environment variables and app configurations, preventing configurations from being unexpectedly overridden.
|
||||
|
||||
**Detected environment variables**:
|
||||
- `ANTHROPIC_API_KEY` - Claude API key
|
||||
- `ANTHROPIC_BASE_URL` - Claude API endpoint
|
||||
- `OPENAI_API_KEY` - OpenAI API key
|
||||
- `GEMINI_API_KEY` - Gemini API key
|
||||
- Other related environment variables
|
||||
|
||||
## Conflict Warning
|
||||
|
||||
When a conflict is detected, a yellow warning banner appears at the top of the interface:
|
||||
|
||||
```
|
||||
Warning: Environment variable conflict detected
|
||||
Found X environment variables that may conflict with CC Switch configuration
|
||||
[Expand] [Dismiss]
|
||||
```
|
||||
|
||||
## View Conflict Details
|
||||
|
||||
Click the "Expand" button to view detailed information:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| Variable Name | Environment variable name |
|
||||
| Variable Value | Currently set value |
|
||||
| Source | Where the variable originates from |
|
||||
|
||||
### Source Types
|
||||
|
||||
| Source | Description |
|
||||
|--------|-------------|
|
||||
| User Registry | Windows user-level environment variable |
|
||||
| System Registry | Windows system-level environment variable |
|
||||
| Shell Configuration | macOS/Linux shell configuration file |
|
||||
| System Environment | System-level environment variable |
|
||||
|
||||
## Resolve Conflicts
|
||||
|
||||
### Select Variables to Remove
|
||||
|
||||
1. Check the environment variables you want to remove
|
||||
2. Or click "Select All" to select all conflicting variables
|
||||
|
||||
### Remove Variables
|
||||
|
||||
1. Click the "Remove Selected" button
|
||||
2. Confirm the removal operation
|
||||
3. CC Switch will automatically back up and remove the selected variables
|
||||
|
||||
### Automatic Backup
|
||||
|
||||
A backup is automatically created before removal:
|
||||
|
||||
- Backup location: `~/.cc-switch/env-backups/`
|
||||
- Backup format: JSON file
|
||||
- Includes variable name, value, source, and other information
|
||||
|
||||
## Dismiss Warning
|
||||
|
||||
If you confirm the conflict does not affect usage, you can:
|
||||
|
||||
1. Click the "Dismiss" button on the right side of the warning banner
|
||||
2. The warning will be temporarily hidden
|
||||
3. Detection will run again on next launch
|
||||
|
||||
## Manual Resolution
|
||||
|
||||
If you prefer not to use CC Switch to remove variables, you can handle them manually:
|
||||
|
||||
### Windows
|
||||
|
||||
1. Open "System Properties > Advanced > Environment Variables"
|
||||
2. Find the conflicting variable in User or System variables
|
||||
3. Delete or modify the variable
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
1. Edit the shell configuration file (e.g., `~/.zshrc`, `~/.bashrc`)
|
||||
2. Delete or comment out the relevant `export` statements
|
||||
3. Reload the configuration: `source ~/.zshrc`
|
||||
|
||||
## Why Do Conflicts Occur
|
||||
|
||||
Environment variables typically take priority over configuration files, which may cause:
|
||||
|
||||
- CC Switch provider configurations being overridden
|
||||
- API requests being sent to the wrong endpoint
|
||||
- Using the wrong API key
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use CC Switch to manage configurations**: Avoid setting API keys in system environment variables
|
||||
2. **Check regularly**: Pay attention to conflict warnings and address them promptly
|
||||
3. **Back up important variables**: Confirm backups exist before removal
|
||||
|
||||
## Restore Deleted Variables
|
||||
|
||||
If you accidentally deleted environment variables:
|
||||
|
||||
1. Find the backup file: `~/.cc-switch/env-backups/`
|
||||
2. Open the corresponding JSON file
|
||||
3. Manually restore the variable to the system environment
|
||||
@@ -0,0 +1,111 @@
|
||||
# CC Switch User Manual
|
||||
|
||||
> All-in-One Assistant for Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw
|
||||
|
||||
## Table of Contents
|
||||
|
||||
```
|
||||
CC Switch User Manual
|
||||
│
|
||||
├── 1. Getting Started
|
||||
│ ├── 1.1 Introduction
|
||||
│ ├── 1.2 Installation Guide
|
||||
│ ├── 1.3 Interface Overview
|
||||
│ ├── 1.4 Quick Start
|
||||
│ └── 1.5 Personalization
|
||||
│
|
||||
├── 2. Provider Management
|
||||
│ ├── 2.1 Add Provider
|
||||
│ ├── 2.2 Switch Provider
|
||||
│ ├── 2.3 Edit Provider
|
||||
│ ├── 2.4 Sort & Duplicate
|
||||
│ └── 2.5 Usage Query
|
||||
│
|
||||
├── 3. Extensions
|
||||
│ ├── 3.1 MCP Server Management
|
||||
│ ├── 3.2 Prompts Management
|
||||
│ └── 3.3 Skills Management
|
||||
│
|
||||
├── 4. Proxy & High Availability
|
||||
│ ├── 4.1 Proxy Service
|
||||
│ ├── 4.2 App Takeover
|
||||
│ ├── 4.3 Failover
|
||||
│ ├── 4.4 Usage Statistics
|
||||
│ └── 4.5 Model Test
|
||||
│
|
||||
└── 5. FAQ
|
||||
├── 5.1 Configuration Files
|
||||
├── 5.2 FAQ
|
||||
├── 5.3 Deep Link Protocol
|
||||
└── 5.4 Environment Variable Conflicts
|
||||
```
|
||||
|
||||
## File List
|
||||
|
||||
### 1. Getting Started
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [1.1-introduction.md](./1-getting-started/1.1-introduction.md) | Introduction, core features, supported platforms |
|
||||
| [1.2-installation.md](./1-getting-started/1.2-installation.md) | Windows/macOS/Linux installation guide |
|
||||
| [1.3-interface.md](./1-getting-started/1.3-interface.md) | Interface layout, navigation bar, provider cards |
|
||||
| [1.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5-minute quick start tutorial |
|
||||
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | Language, theme, directories, cloud sync settings |
|
||||
|
||||
### 2. Provider Management
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [2.1-add.md](./2-providers/2.1-add.md) | Using presets, custom configuration, universal providers |
|
||||
| [2.2-switch.md](./2-providers/2.2-switch.md) | Main UI switching, tray switching, activation methods |
|
||||
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, backfill mechanism |
|
||||
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | Drag-to-reorder, duplicate provider, delete |
|
||||
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | Usage query, remaining balance, multi-plan display |
|
||||
|
||||
### 3. Extensions
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP protocol, add servers, app binding |
|
||||
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | Create presets, activate/switch, smart backfill |
|
||||
| [3.3-skills.md](./3-extensions/3.3-skills.md) | Discover skills, install/uninstall, repository management |
|
||||
|
||||
### 4. Proxy & High Availability
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [4.1-service.md](./4-proxy/4.1-service.md) | Start proxy, configuration, running status |
|
||||
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | App takeover, configuration changes, status indicators |
|
||||
| [4.3-failover.md](./4-proxy/4.3-failover.md) | Failover queue, circuit breaker, health status |
|
||||
| [4.4-usage.md](./4-proxy/4.4-usage.md) | Usage statistics, trend charts, pricing configuration |
|
||||
| [4.5-model-test.md](./4-proxy/4.5-model-test.md) | Model test, health check, latency testing |
|
||||
|
||||
### 5. FAQ
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch storage, CLI configuration file formats |
|
||||
| [5.2-questions.md](./5-faq/5.2-questions.md) | Frequently asked questions |
|
||||
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | Deep link protocol, generation and usage |
|
||||
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | Environment variable conflict detection and resolution |
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **New users**: Start with [1.1 Introduction](./1-getting-started/1.1-introduction.md)
|
||||
- **Installation issues**: See [1.2 Installation Guide](./1-getting-started/1.2-installation.md)
|
||||
- **Configure providers**: See [2.1 Add Provider](./2-providers/2.1-add.md)
|
||||
- **Using proxy**: See [4.1 Proxy Service](./4-proxy/4.1-service.md)
|
||||
- **Having trouble**: See [5.2 FAQ](./5-faq/5.2-questions.md)
|
||||
|
||||
## Version Information
|
||||
|
||||
- Documentation version: v3.11.1
|
||||
- Last updated: 2026-03-02
|
||||
- Applicable to CC Switch v3.11.1+
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to submit Issues or PRs to improve the documentation:
|
||||
|
||||
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- [GitHub Repository](https://github.com/farion1231/cc-switch)
|
||||
Reference in New Issue
Block a user