admin/CC-Switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-08-04 19:45:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

- docs: update user manual for v3.15.0

Browse Source 
- Sync zh/en/ja manuals with Claude Desktop and Hermes support

- Update install requirements, official channels, and release asset guidance

- Document Usage Hero, Codex OAuth live models, Save Anyway, Hermes sessions, and Warp launch

- Correct tray and app-scope descriptions to match current implementation
This commit is contained in:
Jason
2026-05-16 20:58:51 +08:00
parent c9efec294b
commit ddde7f13b3
33 changed files with 222 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-manual/en/1-getting-started/1.1-introduction.md
+7 -4
View File
@@ -2,14 +2,14 @@
## 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**.
CC Switch is a cross-platform desktop application designed for developers who use AI coding tools. It helps you centrally manage configurations for **Claude Code**, **Claude Desktop**, **Codex**, **Gemini CLI**, **OpenCode**, **OpenClaw**, and **Hermes**.
## 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
- **Scattered configurations**: Claude Code, Claude Desktop, Codex, Gemini, OpenCode, OpenClaw, and Hermes 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
@@ -21,6 +21,7 @@ CC Switch solves these problems through a unified interface.
- One-click switching between multiple API provider configurations
- Preset templates for quickly adding common providers
- Universal provider feature for sharing configurations across apps
- Claude Desktop third-party providers, direct mode, and model mapping
- Usage query and balance display
- Endpoint speed testing
@@ -40,16 +41,18 @@ CC Switch solves these problems through a unified interface.
| Application | Description |
|-------------|-------------|
| **Claude Code** | Anthropic's official AI coding assistant |
| **Claude Desktop** | Claude desktop app with official sign-in and third-party 3P profiles |
| **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) |
| **Hermes** | Hermes Agent provider, MCP, Skills, and Memory management |
## Supported Platforms
- **Windows** 10 and above
- **macOS** 10.15 (Catalina) and above
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+
- **macOS** 12 (Monterey) and above
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+ (x64 / ARM64)
## Technical Architecture
docs/user-manual/en/1-getting-started/1.2-installation.md
+18 -8
View File
@@ -1,5 +1,15 @@
# 1.2 Installation Guide
## Official Channels and System Requirements
Only download CC Switch from **[ccswitch.io](https://ccswitch.io)**, **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**, or the project source repository. Any "CC Switch" site or client that asks for payment, top-ups, or login credentials is not official.
| System | Minimum Version | Architecture |
|--------|-----------------|--------------|
| Windows | Windows 10 or later | x64 |
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux | See distribution notes below | x64 / ARM64 |
## Prerequisites
### Install Node.js
@@ -127,8 +137,8 @@ brew upgrade --cask cc-switch
### Option 2: Manual Download
1. Download `CC-Switch-v{version}-macOS.zip`
2. Extract to get `CC Switch.app`
1. Download `CC-Switch-v{version}-macOS.dmg` (recommended) or `CC-Switch-v{version}-macOS.zip`
2. Open the DMG, or extract the zip to get `CC Switch.app`
3. Drag it to the Applications folder
### Signed and Notarized
@@ -151,11 +161,11 @@ yay -S cc-switch-bin
### Debian / Ubuntu
1. Download `CC-Switch-v{version}-Linux.deb`
1. Download `CC-Switch-v{version}-Linux-x86_64.deb` or `CC-Switch-v{version}-Linux-arm64.deb` for your architecture
2. Install:
```bash
sudo dpkg -i CC-Switch-v{version}-Linux.deb
sudo dpkg -i CC-Switch-v{version}-Linux-*.deb
# If there are dependency issues
sudo apt-get install -f
@@ -163,17 +173,17 @@ sudo apt-get install -f
### AppImage (Universal)
1. Download `CC-Switch-v{version}-Linux.AppImage`
1. Download `CC-Switch-v{version}-Linux-x86_64.AppImage` or `CC-Switch-v{version}-Linux-arm64.AppImage` for your architecture
2. Add execute permission:
```bash
chmod +x CC-Switch-v{version}-Linux.AppImage
chmod +x CC-Switch-v{version}-Linux-*.AppImage
```
3. Run:
```bash
./CC-Switch-v{version}-Linux.AppImage
./CC-Switch-v{version}-Linux-*.AppImage
```
## Verify Installation
@@ -182,7 +192,7 @@ 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
3. The app switcher shows enabled managed apps, and you can switch to the target app panel
## Auto Update
docs/user-manual/en/1-getting-started/1.3-interface.md
+7 -3
View File
@@ -11,7 +11,7 @@
| 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 |
| 4 | App Switcher | Switch between Claude / Claude Desktop / Codex / Gemini / OpenCode / OpenClaw / Hermes |
| 5 | Feature Area | Skills / Prompts / MCP entry points |
| 6 | Add Button | Add a new provider |
@@ -20,10 +20,12 @@
Click the dropdown menu to switch the currently managed application:
- **Claude** - Manage Claude Code configuration
- **Claude Desktop** - Manage Claude Desktop third-party providers and official mode
- **Codex** - Manage Codex configuration
- **Gemini** - Manage Gemini CLI configuration
- **OpenCode** - Manage OpenCode configuration
- **OpenClaw** - Manage OpenClaw configuration
- **Hermes** - Manage Hermes Agent providers and Memory
After switching, the provider list displays the configurations for the selected application.
@@ -56,6 +58,8 @@ Each provider is displayed as a card, containing the following elements from lef
> **Tip**: The action buttons area (5-10) appears on hover and is hidden by default to keep the interface clean.
Starting from v3.15.0, some Claude Code and Codex provider cards also show a **Local Routing support badge**, helping you quickly identify providers that can be served through local routing.
### Button Details
| Button | State Changes | Notes |
@@ -100,12 +104,12 @@ CC Switch displays an icon in the system tray, providing quick access to operati
| Menu Item | Function |
|-----------|----------|
| Open Main Window | Show and focus the main window |
| App Submenus | Collapsible submenus grouped by Claude/Codex/Gemini (e.g., "Claude · PackyCode") |
| App Submenus | Collapsible submenus grouped by Claude/Codex/Gemini (e.g., "Claude · PackyCode"), with current provider and cached usage summaries when available |
| Provider List | Inside each submenu, click to switch; currently active shows a checkmark |
| Lightweight Mode | Toggle checkbox to enter/exit tray-only mode |
| Quit | Fully exit the application |
> **Note**: Each app submenu title shows the current provider name (e.g., "Claude · PackyCode"). Apps with no configured providers show a disabled "(no providers)" entry. App visibility is controlled by the App Visibility setting.
> **Note**: Each tray submenu title shows the current provider name (e.g., "Claude · PackyCode"). Apps with no configured providers show a disabled "(no providers)" entry. The tray currently focuses on Claude / Codex / Gemini, the apps that support proxy routing and usage summaries; main-window app visibility is still controlled by the App Visibility setting.
### Multi-language Support
docs/user-manual/en/2-providers/2.1-add.md
+17 -5
View File
@@ -5,7 +5,7 @@
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)
- **App-specific Provider**: Only for the currently selected app (Claude Code / Claude Desktop / Codex / Gemini / OpenCode / OpenClaw / Hermes)
- **Universal Provider**: Shared configuration across apps
## Add Using Presets
@@ -56,6 +56,16 @@ Presets are pre-configured provider templates that only require an API Key to us
> The preset list may be updated with new versions. Refer to the actual list shown in the app.
#### Claude Desktop Presets
The Claude Desktop panel includes provider presets translated from the Claude Code preset catalog. When adding one, choose between:
- **Direct mode**: the provider exposes a native Anthropic Messages API that Claude Desktop can reach directly
- **Model mapping mode**: non-Claude models are mapped through the CC Switch local gateway into Sonnet / Opus / Haiku routes
- **Claude Desktop Official**: restores Claude Desktop's official sign-in mode
See [2.6 Claude Desktop](./2.6-claude-desktop.md) for the full workflow.
#### Codex Presets
| Preset Name | Description |
@@ -161,7 +171,7 @@ When adding or editing a provider, you can automatically discover available mode
3. CC Switch uses the configured API Key to call the OpenAI-compatible `/v1/models` endpoint
4. Select a model from the dropdown, grouped by category
This feature covers **all five apps** — **Claude / Codex / Gemini / OpenCode / OpenClaw** — and works for any provider that supports the `/v1/models` endpoint.
This feature is available in model-aware provider forms for **Claude Code / Claude Desktop / Codex / Gemini / OpenCode / OpenClaw / Hermes**, and works for providers that support the `/v1/models` endpoint. Codex OAuth providers fetch live model lists from the ChatGPT Codex backend on demand.
**Common errors:**
- **Authentication failed (401/403)**: Check your API Key
@@ -259,7 +269,7 @@ requires_openai_auth = true
## Universal Provider
Universal providers can share configurations across Claude/Codex/Gemini/OpenCode/OpenClaw, suitable for proxy services that support multiple API formats.
Universal providers can share configurations across Claude Code / Codex / Gemini, suitable for proxy services that support multiple API formats.
### Create a Universal Provider
@@ -269,7 +279,7 @@ Universal providers can share configurations across Claude/Codex/Gemini/OpenCode
- Name
- API Key
- Endpoint URL
4. Check the apps to sync to (Claude/Codex/Gemini/OpenCode/OpenClaw)
4. Check the apps to sync to (Claude Code / Codex / Gemini)
5. Save
### Sync Mechanism
@@ -403,6 +413,8 @@ The Codex OAuth preset's default model mapping:
| Opus role | `gpt-5.4` |
| Haiku role | `gpt-5.4-mini` |
Starting from v3.15.0, Codex OAuth model selection no longer relies only on a hardcoded list. When the model selector opens, CC Switch fetches available models from the ChatGPT Codex backend on demand; the default mapping can still be overridden.
You can override the `ANTHROPIC_MODEL` and related environment variables in the provider's JSON editor to customize.
### Multi-Account Management (OAuth Auth Center)
@@ -523,7 +535,7 @@ When adding a Codex provider, an **Enable 1M Context Window** toggle is availabl
- **When enabled**: Sets `model_context_window = 1000000` and auto-fills `model_auto_compact_token_limit = 900000` in config.toml
- **When disabled**: Removes both fields
The auto-compact limit can be customized in the text field that appears when the toggle is on.
The auto-compact limit can be customized in the text field that appears when the toggle is on. Starting from v3.15.0, this toggle only appears when adding a new Codex provider; when editing an existing provider, adjust the fields directly in advanced configuration if needed.
### Custom Icon
docs/user-manual/en/2-providers/2.2-switch.md
+2 -4
View File
@@ -39,14 +39,12 @@ Starting from v3.13.0, the tray menu is refactored from a flat list into **per-a
| Claude | All Claude providers (including Codex OAuth reverse proxy) |
| Codex | All Codex providers |
| Gemini | All Gemini providers |
| OpenCode | All OpenCode providers |
| OpenClaw | All OpenClaw providers |
**Benefits of the refactor**:
- **Prevents menu overflow**: With many providers, a flat list would exceed screen height; per-app submenus scale naturally
- **Submenu title shows the currently active provider**: You know at a glance which provider each app is using, without opening the submenu
- **Per-app isolation**: Switching Claude's provider doesn't disturb the Codex view
- **Submenu title shows the currently active provider and usage summary**: You know at a glance which provider Claude / Codex / Gemini is using, plus available cached usage information, without opening the submenu
- **Per-app isolation**: Switching Claude's provider doesn't disturb the Codex or Gemini view
> **Tip**: The combination of background residency + Lightweight Mode + per-app submenus is especially suited for heavy users who frequently switch among multiple apps. See [1.5 Personalization → Lightweight Mode](../1-getting-started/1.5-settings.md).
docs/user-manual/en/2-providers/2.3-edit.md
+3 -2
View File
@@ -151,8 +151,9 @@ Configuration uses JSON format, and the editor provides:
## 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
2. If the form detects a non-blocking issue, a "save anyway" prompt appears; confirming still saves the provider
3. If this is the currently active provider, the configuration is immediately written to the live file
4. Restart the CLI tool for changes to take effect
## Cancel Editing
docs/user-manual/en/2-providers/2.4-sort-duplicate.md
+2
View File
@@ -24,6 +24,8 @@ Quickly create a copy of a provider, useful for:
- Backing up current configurations
- Creating test configurations
Starting from v3.15.0, universal providers also have a duplicate action, so you can create a copy first and then adjust enabled apps and models.
### Steps
1. Hover over the provider card to reveal action buttons
docs/user-manual/en/3-extensions/3.4-sessions.md
+5 -3
View File
@@ -11,12 +11,13 @@ The Session Manager lets you browse, search, and manage conversation sessions fr
| OpenCode | `~/.local/share/opencode/` (JSON or SQLite) |
| OpenClaw | `~/.openclaw/agents/<agent>/sessions/*.jsonl` |
| Gemini CLI | `~/.cache/gemini/tmp/<project_hash>/chats/` |
| Hermes | `~/.hermes/state.db` or `~/.hermes/sessions/*.jsonl` |
## Opening the Session Manager
Click the **Sessions** button in the main navigation bar toolbar.
> **Note**: The Sessions button is visible for all five supported applications.
> **Note**: The Session Manager covers the six session sources listed above; the Claude Desktop entry reuses the Claude Code session view.
## Interface Layout
@@ -63,6 +64,7 @@ Click the provider filter dropdown (top-right of left panel) to filter by applic
- **OpenCode**
- **OpenClaw**
- **Gemini CLI**
- **Hermes**
The filter can be combined with search.
@@ -81,7 +83,7 @@ Click the **Resume** button (play icon) on a selected session to continue the co
- The terminal opens in the session's project directory
- If terminal launch fails, the command is copied to your clipboard instead
**Supported terminals (macOS):** Terminal.app, iTerm2, Ghostty, Kitty, WezTerm, Alacritty
**Supported terminals (macOS):** Terminal.app, iTerm2, Ghostty, Kitty, WezTerm, Alacritty, Warp
**On other platforms:**
- The resume command is copied to your clipboard
@@ -103,7 +105,7 @@ Starting from v3.13.0, **Claude sessions** show a **directory picker** before re
2. In the popup directory picker, confirm the default directory or choose a new one
3. CC Switch launches the Claude terminal session in the selected directory
> **Note**: Codex / Gemini / OpenCode / OpenClaw session resume flows do not yet include the directory picker and still use the session's original project directory.
> **Note**: Codex / Gemini / OpenCode / OpenClaw / Hermes session resume flows do not yet include the directory picker and still use the session's original project directory.
### Delete Session
docs/user-manual/en/4-proxy/4.4-usage.md
+6 -1
View File
@@ -50,10 +50,15 @@ 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 |
| Real Total Tokens | Cache-normalized total of input + output + cache creation + cache read tokens |
| Cache Hit Rate | Cache read tokens as a share of cacheable input |
| Estimated Cost | Cost calculated based on pricing configuration |
| Success Rate | Percentage of successful requests |
Starting from v3.15.0, the top of the Usage page uses a filter-driven Hero card. When you change the date range, app, provider, or model filters, the Hero's real total tokens, cache hit rate, request count, and cost update together and stay aligned with the logs and stats below.
> Note: v3.15.0 normalizes cache reads, cache creation, and OpenAI-style cache reporting. Historical token and cost numbers may differ from older estimates; the current numbers follow the normalized rules.
### Time Range
Select the time range for statistics:
docs/user-manual/en/4-proxy/4.5-model-test.md
+1 -1
View File
@@ -10,7 +10,7 @@ The model test feature (also known as **Stream Check**) verifies whether a provi
- Whether the response latency is acceptable
- Time to first token (TTFB) for streaming responses
Starting from v3.13.0, Stream Check coverage is extended to **all five apps** (Claude / Codex / Gemini / OpenCode / OpenClaw), including all OpenClaw protocol variants (such as `openai-completions`). OpenCode is auto-detected via npm package mapping; OpenClaw supports custom `auth-header` detection and handles edge cases like Bedrock error messages and `baseURL` fallback.
Starting from v3.13.0, Stream Check coverage is extended to **Claude / Codex / Gemini / OpenCode / OpenClaw**, including all OpenClaw protocol variants (such as `openai-completions`). OpenCode is auto-detected via npm package mapping; OpenClaw supports custom `auth-header` detection and handles edge cases like Bedrock error messages and `baseURL` fallback.
## Open Configuration
docs/user-manual/en/README.md
+6 -3
View File
@@ -1,6 +1,6 @@
# CC Switch User Manual
> All-in-One Assistant for Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw
> All-in-One Assistant for Claude Code / Claude Desktop / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes
## Table of Contents
@@ -115,13 +115,16 @@ CC Switch User Manual
- **First-class Claude Desktop panel**: supports third-party providers, direct / model mapping modes, Copilot / Codex OAuth reuse, and 3P profile writing. See [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **Role-based model mapping**: adapts Claude Desktop model validation with Sonnet / Opus / Haiku routes and `supports1m`
- **Claude Desktop local routing**: provides a local gateway at `127.0.0.1:15721/claude-desktop` for providers that need conversion
- **Routing support badges**: Claude Code / Codex provider cards indicate whether a provider can be served through Local Routing
- **Codex OAuth live model discovery**: ChatGPT Codex providers fetch available models from the ChatGPT backend on demand
- **Filter-driven Usage Hero**: shows cache-normalized real total tokens and cache hit rate, updating with date / provider / model filters — see [4.4 Usage Statistics](./4-proxy/4.4-usage.md)
- **Lightweight Mode**: Destroys the main window when minimizing to tray — near-zero idle footprint. See [1.5 Personalization](./1-getting-started/1.5-settings.md)
- **Quota & Balance Display**: Official subscriptions (Claude/Codex/Gemini/Copilot/Codex OAuth) auto-display quotas; Token Plan and third-party balances use built-in templates with one-click enable — see [2.5 Usage Query](./2-providers/2.5-usage-query.md)
- **Codex OAuth Reverse Proxy**: Reuse your ChatGPT account's Codex service inside Claude Code — see [2.1 Add Provider](./2-providers/2.1-add.md)
- **Per-App Tray Submenus**: Five independent app submenus to prevent tray overflow — see [2.2 Switch Provider](./2-providers/2.2-switch.md)
- **Per-App Tray Submenus**: Claude / Codex / Gemini submenus show the current provider and available usage summaries — see [2.2 Switch Provider](./2-providers/2.2-switch.md)
- **Skills Discovery & Batch Updates**: SHA-256 update detection, batch updates, skills.sh public registry search — see [3.3 Skills Management](./3-extensions/3.3-skills.md)
- **Full URL Endpoint Mode**: Advanced option to treat `base_url` as the full upstream endpoint — see [2.1 Add Provider](./2-providers/2.1-add.md)
- **OpenCode / OpenClaw Stream Check Coverage**: Stream Check panel extended to all five apps — see [4.5 Model Test](./4-proxy/4.5-model-test.md)
- **OpenCode / OpenClaw Stream Check Coverage**: Stream Check covers Claude / Codex / Gemini / OpenCode / OpenClaw — see [4.5 Model Test](./4-proxy/4.5-model-test.md)
## Contributing