docs(manual): update the user manual for v4.0

Bring the zh, en and ja user manuals up to the v4.0.4 interface: the
sidebar layout, the six Settings groups, the Direct / Routing /
Aggregation connection modes, Accounts, and the Apps page. Old
Settings paths (Advanced, Routing, Auth) and takeover wording are gone.

- Add 4.6 Aggregation Mode in all three languages and list it in the
  manual indexes.
- Rewrite 1.3 Interface Overview and 1.5 Settings around the new
  layout; refresh provider, extension, routing, usage and FAQ pages.
- Use the v4.0 release screenshots where they fit and leave
  TODO(v4 screenshot) markers elsewhere.
- Update the version section of each manual index to v4.0.4.
- Remove the 40 v3 screenshots that are no longer referenced.
This commit is contained in:
Jason
2026-10-07 20:42:08 +08:00
parent a40adef3f7
commit efd236a474
121 changed files with 3567 additions and 3864 deletions
Binary file not shown.

Before

Width:  |  Height:  |  Size: 85 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 69 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 29 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 82 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 69 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.2 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 395 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 237 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 190 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 52 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 286 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 425 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 148 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 135 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 164 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 152 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 160 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 176 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 611 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 166 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 415 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 290 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 140 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 192 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 159 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 157 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 218 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 65 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 42 KiB

@@ -30,8 +30,10 @@ CC Switch solves these problems through a unified interface.
- **Prompts**: Manage system prompt presets for quick scenario switching
- **Skills**: Install and manage skill extensions
- **Session Manager**: Browse and search each tool's session history, and copy the resume command to continue a conversation
- **Accounts**: Manage ChatGPT (Codex), GitHub Copilot, xAI, and other OAuth accounts in one place
### Local Routing & High Availability
### Connection Modes, Local Routing & High Availability
- Three connection modes: **Direct** (the client connects to the provider directly), **Routing** (requests go through CC Switch on this machine), and **Aggregation** (Claude Code and Codex only; models from several providers are listed together in `/model`)
- Local routing converts request formats between Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini Native
- Automatic failover that switches to a backup provider when the primary one fails
- Circuit breaker mechanism to prevent repeated retries against failing providers
@@ -55,7 +57,7 @@ CC Switch solves these problems through a unified interface.
- **Switch**: Only one provider is active at a time; switching rewrites the tool's configuration files.
- **Coexist**: Multiple providers are written into the tool's own configuration at the same time, and you choose which one to use inside the tool.
The features each tool supports (local routing, tray switching, MCP, Skills, prompts, sessions, usage statistics) vary; see [1.3 Interface Overview](./1.3-interface.md) and the individual feature chapters.
The features each tool supports (local routing, Aggregation, tray switching, MCP, Skills, prompts, sessions, usage statistics) vary; see [1.3 Interface Overview](./1.3-interface.md) and the individual feature chapters.
## Supported Platforms
@@ -18,7 +18,7 @@ CC Switch itself does not need Node.js or any other runtime. It manages tools yo
### Method 1: One-Click Install in CC Switch (Recommended)
Open "Settings → About". The tool list shows the current and latest version of each tool. Tools that are not installed have an install button next to them; installed tools can be updated individually or with "Update All". Supported tools: Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, and Pi. See [1.5 Personalization → About Page](./1.5-settings.md#about-page) for details.
Click "Apps" at the bottom of the sidebar. The list shows the current and latest version of each tool. Tools that are not installed have an install button next to them, and installed tools can be updated individually; you can also choose here which apps show in the sidebar. Supported tools: Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code. Claude Desktop is a desktop app and cannot be installed here. See [1.3 Interface Overview](./1.3-interface.md#apps-page) for details.
### Method 2: Install Each Tool the Official Way
@@ -33,7 +33,7 @@ Open "Settings → About". The tool list shows the current and latest version of
| Hermes | `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash` |
| Pi | `npm i -g @earendil-works/pi-coding-agent` |
For Claude Desktop, MiniMax Code, and installation on Windows, refer to each tool's official documentation.
For Claude Desktop, MiniMax Code (which Method 1 can install), and installation on Windows, refer to each tool's official documentation.
Installing with npm requires Node.js. Each tool requires a different version (for example, Claude Code needs 22 or later, and OpenClaw needs 24.x at 24.16 or later, or 26.1 or later). Installing the current LTS release is recommended; npm will tell you if your version is too old.
@@ -150,7 +150,7 @@ After installation, launch CC Switch:
1. The app window displays correctly
2. A CC Switch icon appears in the system tray
3. The app switcher shows enabled managed apps, and you can switch to the target app panel
3. The app list in the left sidebar shows the managed apps you chose to display; click one to open its provider page
## Auto Update
@@ -2,154 +2,156 @@
## Main Interface Layout
![image-20260108001629138](../../assets/image-20260108001629138.png)
![CC Switch main interface](../../../../assets/release-notes/v4.0.0/main-en.png)
## Top Navigation Bar
The main window is split into a left sidebar and a content area on the right:
| # | Element | Description |
|---|---------|-------------|
| ① | Logo | Click to visit the official website ccswitch.io |
| ② | Settings Button | Open the settings page (shortcut `Cmd/Ctrl + ,`) |
| ③ | Local Routing Toggle | Claude Code / Codex / Gemini CLI / Grok Build pages: turn local routing on/off for the current app (requires turning on "Show Routing Toggle on Main Page" in "Settings → Routing → Local Routing"); Claude Desktop page: always shown, starts/stops the local routing used by Claude Desktop |
| ④ | App Switcher | Switch between the 10 managed apps |
| ⑤ | Feature Area | App-specific feature entry points |
| ⑥ | Add Button | Add a new provider |
- **Left sidebar**: Choose the app to manage, or open a global feature page
- **Content area**: The page header (app name, the "Add Provider" button, and the ⋯ menu) at the top, with the content of the current page below it
A few more entry points appear under certain conditions:
## Left Sidebar
- **Project switcher**: Shown by default (except on the MiniMax Code page); you can turn off "Show project switcher" in "Settings → General → Homepage Display"
- **Failover toggle**: Shown after you turn on "Show Failover Toggle on Main Page" in "Settings → Routing → Auto Failover"
- **Usage Statistics button**: Shown when local routing is enabled for the current app
The sidebar has three sections from top to bottom:
### App Switcher
| Section | Contents |
|---------|----------|
| App list | The managed apps you chose to display (up to 10). Click an app to show its provider page on the right. A small marker next to an app's name shows that it is currently using Routing, Aggregation, or model mapping, and "Needs attention" appears when something is wrong |
| Global pages | MCP, Skills, Prompts, Sessions, Accounts, and Usage ("Today $xx" is shown next to it when there is spending today). These pages don't belong to a single app, and each has one entry |
| Bottom | "Apps" (install, upgrade, and choose which apps show in the sidebar) and "Settings" |
Click an app icon at the top to switch the currently managed application (when the window is narrow, apps that don't fit are collected into the "More apps" menu):
Click the collapse button at the top of the sidebar to shrink it to icons only; click it again to expand. A dot next to "Apps" or "Settings" means a command-line tool or CC Switch itself has a new version.
- **Claude** - Manage Claude Code configuration
> Shortcut `Cmd/Ctrl + ,` opens Settings at any time.
### Managed Apps
- **Claude Code** - Manage Claude Code configuration
- **Claude Desktop** - Manage Claude Desktop third-party providers and official mode
- **Codex** - Manage Codex configuration
- **Gemini** - Manage Gemini CLI configuration
- **Grok Build** - Manage Grok Build configuration
- **OpenCode** - Manage OpenCode configuration
- **OpenClaw** - Manage OpenClaw configuration
- **Hermes** - Manage Hermes Agent providers and Memory
- **Grok Build** - Manage Grok Build configuration
- **Pi** - Manage Pi providers and models
- **MiniMax Code** - Manage MiniMax Code custom providers
After switching, the provider list displays the configurations for the selected application. Apps you rarely use can be hidden in "Settings → General → Homepage Display".
Apps you rarely use can be hidden on the sidebar's "Apps" page. Once hidden, an app no longer appears in the sidebar, in the MCP / Skills app columns, or in the app pickers on Prompts and Sessions; its existing configuration is not affected.
### Feature Area Buttons
### Global Pages
Each app shows a different set of feature buttons:
| Entry | Purpose |
|-------|---------|
| MCP | Manage MCP servers and enable them per app; see [3.1 MCP](../3-extensions/3.1-mcp.md) |
| Skills | Install and manage skills; see [3.3 Skills](../3-extensions/3.3-skills.md) |
| Prompts | Manage system prompts; see [3.2 Prompts](../3-extensions/3.2-prompts.md) |
| Sessions | Browse and search each tool's session history |
| Accounts | Manage ChatGPT (Codex), GitHub Copilot, xAI, and other OAuth accounts in one place |
| Usage | Request statistics overview, trend charts, request logs, provider/model statistics, and cost pricing |
| App | Feature Area Buttons |
|-----|----------------------|
| Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, MiniMax Code | Skills, Prompts, Sessions, MCP |
| Pi | Skills, Prompts, Sessions (Pi has no MCP) |
| Claude Desktop | Same as Claude Code, operating on Claude Code's data |
| Hermes | Skills, Memory, Hermes Web UI, MCP |
| OpenClaw | Workspace, Environment Variables, Tools, Agents, Sessions |
Not every app supports every feature: Claude Desktop and OpenClaw are not part of MCP or Skills, and the MCP, Skills, Prompts, and Sessions actions on the Claude Desktop page operate on Claude Code's data.
For the MCP, Skills, and Prompts support of each app, see [3.1 MCP](../3-extensions/3.1-mcp.md), [3.2 Prompts](../3-extensions/3.2-prompts.md), and [3.3 Skills](../3-extensions/3.3-skills.md).
## App Pages
## Provider Cards
### App Page Header
The header shows the app name and the page name (for example "Claude Code Providers"). On the right are:
- **Add Provider**: Add a new provider
- **Project switcher**: Hidden by default; turn on "Show project switcher" in "Settings → General → Sidebar and header" (not available on the MiniMax Code page)
- **⋯ menu**: View sessions, config directory, install and upgrade, hide from sidebar, and view usage for this app
- The Hermes header also has a "Web UI" button
OpenClaw and Hermes show a row of tabs under the header for switching between the provider page and their own pages:
| App | Tabs |
|-----|------|
| OpenClaw | Providers, Workspace, Config |
| Hermes | Providers, Memory |
### Connection Modes
The provider pages of Claude Code, Codex, Gemini CLI, and Grok Build have three tabs at the top: **Direct / Routing / Aggregation** (Aggregation exists only for Claude Code and Codex; Claude Desktop has Direct / Model mapping instead). The dot on a tab marks the mode currently in effect, and the text next to it says which provider is connected right now.
Clicking a tab only shows the list for that mode and does not change any configuration. To actually switch, click the button below that spells out the consequences: "Start routing", "Switch to Aggregation", or "Back to direct". For Routing see [4.2 App Routing](../4-proxy/4.2-routing.md), and for Aggregation see [4.6 Aggregation Mode](../4-proxy/4.6-aggregation.md).
### Provider Cards
Each provider is displayed as a card, containing the following elements from left to right:
### Card Elements (Left to Right)
| Element | Description |
|---------|-------------|
| Drag handle | Drag to reorder providers (appears on hover) |
| Provider icon | The brand icon |
| Provider info | Name, notes or endpoint URL (click to open the website); badges such as "Official" or "Needs Routing" may appear next to the name |
| Usage info | Remaining quota or balance; shows several rows for multi-plan providers |
| Status / main action | The card currently in effect shows "In use" ("Routing" in Routing mode); other cards show a play button, which switches provider in Direct mode, means "Route here" in Routing mode, and sets the default or adds the provider in Aggregation mode |
| Edit button | Edit the provider configuration |
| ⋯ More | Duplicate, connectivity check, configure usage query, open terminal (Claude Code only), delete |
| # | Element | Icon | Description |
|---|---------|------|-------------|
| ① | Drag Handle | ≡ | Hold and drag up/down to reorder providers |
| ② | Provider Icon | 🔷 | Displays provider brand icon with customizable color |
| ③ | Provider Info | - | Name, notes/endpoint URL (clickable to open website) |
| ④ | Usage Info | - | Shows remaining balance; displays plan count for multi-plan |
| ⑤ | Enable Button | ▶ | Switch to this provider |
| ⑥ | Edit Button | ✏️ | Edit provider configuration |
| ⑦ | Duplicate Button | 📋 | Duplicate provider (create a copy) |
| ⑧ | Connectivity check | 🧪 | Check whether the provider address is reachable and show the latency |
| ⑨ | Usage Query | 📊 | Configure usage query script |
| ⑩ | Open Terminal | ⌨️ | After you choose a working directory, open a terminal with this provider's configuration (Claude Code only) |
| ⑪ | Delete Button | 🗑️ | Delete provider (disabled when currently active) |
The provider currently in use cannot be deleted; switch to another one first. "Connectivity check" only checks whether the address is reachable, without sending real model requests, and is unavailable on official providers and MiniMax Code providers. Providers whose quota is displayed automatically, such as Copilot, Codex OAuth, and xAI OAuth, have no "Configure usage query".
> 💡 **Tip**: The action buttons area (⑤-⑪) appears on hover and is hidden by default to keep the interface clean.
The **"Needs Routing"** badge means the provider can only be used through local routing (for example, its API format needs conversion); if you switch to it directly, the client cannot use it. **Official subscriptions do not go through routing** (Codex's OpenAI Official is the exception), so you cannot switch to them in Routing mode.
Some provider cards show a **"Needs Routing"** or **"No Routing Support"** badge: the former means the provider can only be used with local routing enabled (for example, when its API format needs conversion); the latter means the provider cannot be forwarded through local routing (such as Claude Official).
OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code are "coexist" apps: the card buttons are "Add / Remove" ("Enable / Remove" for Pi), and there are no Direct / Routing / Aggregation tabs.
### Button Details
### Failover Queue and Health Status
| Button | State Changes | Notes |
|--------|---------------|-------|
| **Enable** | Shows ✓ and disables when active | Changes to "Add/In queue" in failover mode |
| **Edit** | Always available | Opens edit panel to modify configuration |
| **Duplicate** | Always available | Creates a copy with `copy` suffix |
| **Connectivity check** | Shows loading animation while checking | Only checks whether the address is reachable, without sending real model requests; grayed out and unavailable on official providers and MiniMax Code providers |
| **Usage Query** | Available on most providers | Configure a usage query template or script; grayed out and unavailable on providers whose quota is displayed automatically, such as Copilot, Codex OAuth, and xAI OAuth |
| **Delete** | Semi-transparent/disabled when active | Must switch to another provider first |
In Routing mode, the provider page is split into "Queue · by priority" and "Not in queue". Providers in the queue take requests in order, and when the previous one fails repeatedly, the next one takes over automatically. You can reorder them with move up, move down, or drag; see [4.3 Failover](../4-proxy/4.3-failover.md) for setup.
### Card States
Providers in the queue show a health status:
| State | Border Color | Description |
|-------|--------------|-------------|
| **Currently Active** | 🔵 Blue border | Current provider in normal mode |
| **Routing Active** | 🟢 Green border | Provider actually forwarding requests when local routing is enabled |
| **Normal** | Default border | Inactive provider |
| **In Failover** | Shows priority badge | e.g., P1, P2 indicates failover priority |
| Status | Description |
|--------|-------------|
| Operational | 0 consecutive failures |
| Degraded | Has failures, but the circuit breaker has not tripped |
| Circuit Open | The circuit breaker has tripped; the provider is temporarily skipped (for thresholds, see [4.3 Failover](../4-proxy/4.3-failover.md#circuit-breaker-configuration)) |
### Health Status Badges
### Apps Page
With local routing enabled, providers in the failover queue display health status:
The "Apps" page at the bottom of the sidebar manages command-line tools:
| Badge | Color | Description |
|-------|-------|-------------|
| Operational | 🟢 Green | 0 consecutive failures |
| Degraded | 🟡 Yellow | Has failures, but the circuit breaker has not tripped |
| Circuit Open | 🔴 Red | The circuit breaker has tripped; the provider is temporarily skipped (for thresholds, see [4.3 Failover](../4-proxy/4.3-failover.md#circuit-breaker-configuration)) |
- See each tool's current and latest version, install missing tools, and upgrade installed ones
- Choose which apps show in the sidebar
- "Manual install commands" lets you copy each tool's install command
Claude Desktop is a desktop app and cannot be installed or upgraded here; the page only shows whether it is connected. Whether to check for new versions at launch is controlled by "Settings → General → New versions of your apps".
## System Tray
CC Switch displays an icon in the system tray, providing quick access to operations.
### Tray Menu Structure
<!-- TODO(v4 screenshot): Expanded tray menu showing the app submenus (Claude Code / Codex, etc.) -->
![image-20260108002153668](../../assets/image-20260108002153668.png)
### Menu Functions
### Tray Menu
| Menu Item | Function |
|-----------|----------|
| Open main window | Show and focus the main window |
| Open Official Website | Open ccswitch.io in the browser |
| Projects | Switch projects (a full set of provider, MCP, Skills, and prompt states) |
| App Submenus | Collapsible submenus grouped by Claude / Codex / Gemini / Grok Build (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 |
| Open CC Switch | Show and focus the main window, always on top |
| App submenus | One submenu each for the five switch-mode apps: Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build. The title shows the current provider and mode; click a provider in the submenu to switch, and the current one has a checkmark. You can also open the app page or add a provider there, and some apps show a quota summary |
| Projects | Switch projects (a full set of provider, MCP, Skills, and prompt states); appears only after "Show project switcher" is turned on |
| Lightweight mode | Checkbox to enter or exit tray-only mode |
| Open official website | Open ccswitch.io in the browser |
| Quit CC Switch | Fully exit the application. When an app is using Routing or Aggregation, the item reads "Quit CC Switch (stops the routing service)" |
> **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 includes only the four apps that support local routing: Claude Code, Codex, Gemini CLI, and Grok Build; switch other apps from the main window. Which apps appear in the main window is controlled by the "Homepage Display" setting.
Problems such as the routing service not running or a switch failing for an app are shown at the top of the menu, and a small dot also appears on the tray icon.
> **Note**: Coexist apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code) do not appear in the tray; use the main window for them. Apps with no configured providers show a corresponding hint in their submenu. Which apps appear in the tray is determined by the display toggles on the "Apps" page.
### Multi-language Support
The tray menu supports four languages, automatically switching based on settings:
| Language | Open Main Window | Quit |
|----------|-----------------|------|
| Simplified Chinese | 打开主界面 | 退出 |
| Traditional Chinese | 開啟主介面 | 退出 |
| English | Open main window | Quit |
| Japanese | メインウィンドウを開く | 終了 |
The tray menu follows the interface language and supports Simplified Chinese, Traditional Chinese, English, and Japanese; if no language has been set yet, it follows the system language.
### Lightweight Mode
The tray menu includes a **Lightweight Mode** toggle (checkbox). When enabled:
The tray menu includes a **Lightweight mode** checkbox. When enabled:
- The main window is closed to free up resources
- The app continues running in the system tray only
- You can still switch providers via the tray submenus
- On macOS, the Dock icon is also hidden
To exit Lightweight Mode, uncheck the toggle or click "Open main window" — the main window will be rebuilt and shown.
To exit Lightweight mode, uncheck the option or click "Open CC Switch" — the main window will be rebuilt and shown.
### Use Cases
@@ -158,66 +160,60 @@ Switching providers via the tray menu doesn't require opening the main window, s
- Frequently switching providers
- Quick operations when the main window is minimized
- Managing configurations while running in the background
- Running in Lightweight Mode for minimal resource usage
- Running in Lightweight mode for minimal resource usage
## Settings Page
## Settings
The settings page is divided into multiple tabs:
Click "Settings" at the bottom of the sidebar. The sidebar is replaced by the settings menu, and the current group is shown on the right; click "Back" or press `Esc` to return to the main interface. Settings has 6 groups:
### General Tab
### General
- Language settings (Simplified Chinese/Traditional Chinese/English/Japanese)
- Theme settings (System/Light/Dark)
- Homepage Display (app and project switcher entries)
- Skill storage location and sync method
- Codex App Enhancements (keep official login, unified session history)
- Window behavior (launch on startup, close behavior)
- Preferred terminal
- **Appearance**: Interface language (Simplified Chinese/Traditional Chinese/English/Japanese) and light/dark theme (System/Light/Dark)
- **Sidebar and header**: Which apps show in the sidebar (jumps to the "Apps" page) and the project switcher
- **New versions of your apps**: Check for new versions of your apps at launch
- **Window and terminal**: Launch on startup, close button behavior (hide to tray or quit), and preferred terminal
### Routing Tab
### App config
- Local Routing (Routing Master Switch, per-app enablement, listen address and port)
- Each app's configuration directory override (except Claude Desktop and MiniMax Code)
- Per-app options, such as Claude Code's "Apply to Claude Code extension" and "Skip Claude Code first-run confirmation", and Codex's keep-official-login option for direct switches
### Local routing
- Service: listen address and port, start/stop
- Apps using routing
- Auto Failover
- Rectifier
- Switch all back to direct
### Network
- Global Outbound Proxy
### Auth Tab
### Data
- OAuth Authentication Center (GitHub Copilot, ChatGPT, and xAI accounts)
### Advanced Tab
- Configuration Directory
- Data Management (import/export)
- Backup & Restore
- Location (the CC Switch configuration directory)
- Data Management (SQL import/export)
- Backup & Restore (including the "Other Backups" overview)
- Cloud Sync
- Connectivity Check Settings
- Application Diagnostic Logs
### Usage Statistics Tab
- Request statistics overview
- Trend charts
- Request logs
- Provider/model statistics
- Cost Pricing
### About Tab
### About
- Version information and update check
- Version detection, installation, and updates for CLI tools
- GitHub, official website, and release notes
## Keyboard Shortcuts
| Shortcut | Function |
|----------|----------|
| `Cmd/Ctrl + ,` | Open Settings |
| `Cmd/Ctrl + F` | Search providers |
| `Esc` | Close dialog/search |
| `Cmd/Ctrl + F` | Search providers (on a provider page) |
| `Esc` | Close search; on a settings page, go back to the main interface |
## Search
Press `Cmd/Ctrl + F` to open the search bar:
Press `Cmd/Ctrl + F` on a provider page to open the search bar:
- Search by name, notes, or URL
- Real-time provider list filtering
@@ -4,28 +4,28 @@ 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
1. Select the tool you want to manage in the left sidebar, then click the **+** (Add Provider) button in the top-right corner of the page
2. Select your provider under "Provider Preset"
- Common presets: Zhipu GLM, MiniMax, DeepSeek, Kimi, PackyCode
- Or select "Custom" for manual configuration
3. Enter your **API Key**
4. Click "Add"
![image-20260108002807657](../../assets/image-20260108002807657.png)
<!-- TODO(v4 screenshot): Add provider panel: search box, preset list, and API Key form -->
> 💡 **Tip**: Presets auto-fill the endpoint URL, so you only need to enter your API Key.
> 💡 **Tip**: The add panel supports searching by Chinese name and domain, and different plans and regions of the same provider are merged into one row. 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 1: Switch from the app page**
- Click the "Switch" button on the provider card, and its status changes to "In use"
- OpenCode, OpenClaw, Hermes, and MiniMax Code are coexist apps: the button is "Add" (for Pi, "Enable"), and you can add multiple providers at the same time
**Option 2: Quick switch via system tray**
- Right-click the CC Switch icon in the system tray
- Click the provider name directly (supported for Claude Code, Codex, Gemini CLI, and Grok Build)
- Each tool has one row showing "name · mode · provider · quota"; click a provider name directly in the submenu (supported for Claude Code, Claude Desktop, Codex, Gemini CLI, and Grok Build)
## Step 3: Activation
@@ -42,17 +42,27 @@ After switching providers, each CLI tool activates differently:
| OpenClaw | Requires closing and reopening the terminal |
| Hermes / Pi / MiniMax Code | Once added, the provider is written into the tool's configuration; for Pi and MiniMax Code, choose the model to use inside the tool; for Hermes, click "Enable" on the card to make it the current provider |
With local routing enabled, switching providers for Claude Code, Codex, Gemini CLI, and Grok Build takes effect immediately for subsequent requests; however, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
In Routing mode, switching providers for Claude Code, Codex, Gemini CLI, and Grok Build takes effect immediately for subsequent requests; however, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
## Direct, Routing, and Aggregation (Optional)
The pages of Claude Code, Codex, Gemini CLI, and Grok Build have "Direct / Routing" tabs at the top, and Claude Code and Codex also have "Aggregation". Clicking a tab only changes what you are viewing and does not change any configuration; to actually switch, click the button on the page that spells out the consequences: "Start routing" or "Switch to Aggregation", and "Back to direct" to return to Direct.
- **Direct** (default): The client connects to the provider directly; choose it for everyday use
- **Routing**: Requests go through CC Switch on this machine (default `127.0.0.1:15721`), which can convert API formats and do failover. Choose it if you want to use an OpenAI- or Gemini-format provider in Claude Code, or Claude in Codex
- **Aggregation**: Puts models from several providers into one model list, and a request goes to whichever provider owns the model you pick; no failover
Routing and Aggregation need CC Switch to keep running; quitting CC Switch automatically returns to Direct, and it reconnects the next time you start it. Official subscriptions do not go through routing (Codex's OpenAI Official is the exception). See [Enable local routing](../4-proxy/4.1-service.md) for details.
### 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"
1. Open CC Switch "Settings → App config" and find the Claude Code block
2. Enable the "Skip Claude Code first-run confirmation" toggle
3. Restart Claude Code
![image-20260108002626389](../../assets/image-20260108002626389.png)
<!-- TODO(v4 screenshot): The "Skip Claude Code first-run confirmation" toggle under Settings → App config → Claude Code -->
> ⚠️ **Note**: This option writes `hasCompletedOnboarding: true` to `~/.claude.json`, skipping the official first-run confirmation flow.
@@ -84,6 +94,8 @@ openclaw
If the AI responds normally, the configuration is successful.
> **Note**: On first launch, CC Switch automatically imports the existing configuration of Claude Code, Codex, Gemini CLI, and Grok Build as a provider named `default`, and adds an official provider for these tools and Claude Desktop. Your original configuration is not lost.
## Next Steps
Congratulations! You have completed the basic configuration. Next, you can:
@@ -92,6 +104,7 @@ Congratulations! You have completed the basic configuration. Next, you can:
- [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 local routing](../4-proxy/4.1-service.md) - Use providers that need format conversion, and enable automatic failover
- [Manage AI coding tools](./1.2-installation.md#optional-install-the-tools-to-manage) - Install and upgrade tools on the sidebar "Apps" page, and choose which apps show in the sidebar
- [View usage statistics](../4-proxy/4.4-usage.md) - Track request counts, tokens, and costs
## Common Issues
@@ -4,33 +4,36 @@ 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 + ,`
- Click **Settings** at the bottom of the left sidebar
- Or use the shortcut `Cmd/Ctrl + ,` (opens "General" directly)
## Language Settings
Settings takes a full screen: the left sidebar is replaced by the settings menu, which has 6 groups: **General, App config, Local routing, Network, Data, About**. Click "Back" above the menu (or press `Esc`) to return to the previous page. Settings only holds preferences; feature pages such as MCP, Skills, Prompts, and Sessions are in the left sidebar.
CC Switch supports four languages:
Toggle-type settings are saved immediately; path-type settings (configuration directories) need a click on that block's "Save" after you change them.
| Language | Description |
|----------|-------------|
| Simplified Chinese | Default language |
| Traditional Chinese | Traditional Chinese interface |
| English | English interface |
| Japanese | Japanese interface |
## General
Language changes take effect immediately without restarting.
### Appearance
## Theme Settings
| Setting | Description |
|---------|-------------|
| Language | Simplified Chinese, Traditional Chinese, English, Japanese; takes effect immediately without restarting |
| Light & dark | System / Light / Dark |
| Option | Description |
|--------|-------------|
| System | Automatically matches the system's dark/light mode |
| Light | Always use the light theme |
| Dark | Always use the dark theme |
### Sidebar and header
## Window Behavior
- **Which apps show in the sidebar**: Click "Open Apps" to jump to the sidebar's "Apps" page and choose there which apps are shown (Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code are available; at least one must stay visible)
- **Show project switcher**: When on, a project switcher appears at the top of the Claude Code, Claude Desktop, and Codex pages. Off by default
### Launch on Startup
> 💡 **Use case**: If you only use Claude Code and Codex, you can hide the other apps to keep the sidebar clean.
### New versions of your apps
**Check for new versions of your apps at launch**: When on, CC Switch checks once at every launch whether the installed command-line apps have new versions, and shows a dot on "Apps" in the sidebar if it finds any. It does not upgrade anything automatically. Upgrades are done on the "Apps" page; see [1.2 Installation Guide](./1.2-installation.md#optional-install-the-tools-to-manage).
### Window and terminal
#### Launch on Startup
When enabled, CC Switch automatically runs when the system starts.
@@ -38,7 +41,9 @@ When enabled, CC Switch automatically runs when the system starts.
- **macOS**: Implemented via LaunchAgent
- **Linux**: Implemented via XDG autostart
### Close Behavior
Once enabled, a **Silent Startup** toggle appears: the main window is not shown at launch, and the app runs in the system tray only.
#### Minimize to Tray on Close
| "Minimize to tray on close" | When you click the window's close button |
|--------|-------------|
@@ -47,13 +52,27 @@ When enabled, CC Switch automatically runs when the system starts.
Keeping it on is recommended, so you can switch providers quickly from the tray.
### Lightweight Mode
#### Application-level Window Buttons (Linux only)
When on, the app's own minimize, maximize/restore, and close buttons are used; when off, the system window mode is kept.
#### Preferred Terminal
Choose the terminal application used when you click "Open terminal" on a provider card. If the chosen terminal is unavailable, the system default terminal is used instead.
| Platform | Terminal Options |
|----------|-----------------|
| macOS | Terminal, iTerm2, Alacritty, Kitty, Ghostty, Otty, WezTerm, Kaku, Warp |
| Windows | CMD, PowerShell, Windows Terminal |
| Linux | GNOME Terminal, Konsole, Xfce4 Terminal, Alacritty, Kitty, Ghostty |
#### Lightweight Mode
Starting from v3.13.0, CC Switch adds **Lightweight Mode** — a **tray-only** running state that minimizes desktop footprint when idle.
**How to enter**: Right-click the tray icon → click **Lightweight Mode**. The main window is **destroyed** (not just hidden), freeing UI resources and memory.
**How to enter**: Right-click the tray icon → click **Lightweight mode**. The main window is **destroyed** (not just hidden), freeing UI resources and memory.
**How to exit**: Click **Open main window** from the tray menu, or trigger CC Switch via deep link / relaunch. The window is **rebuilt on demand**, with state preserved.
**How to exit**: Click **Open CC Switch** from the tray menu, or trigger CC Switch via deep link / relaunch. The window is **rebuilt on demand**, with state preserved.
| Aspect | Minimize to Tray | Lightweight Mode |
|--------|------------------|------------------|
@@ -63,51 +82,18 @@ Starting from v3.13.0, CC Switch adds **Lightweight Mode** — a **tray-only** r
| Tray switching | Available | Available |
| Deep link wake | Available | Available (on-demand rebuild) |
> 💡 **Use case**: If CC Switch runs in the background for long periods and you mainly switch providers via the tray menu, enabling Lightweight Mode significantly reduces memory usage.
> ⚠️ **Note**: Lightweight Mode state is not persistent — the next normal launch returns to normal mode. Combine with Launch on Startup for long-term use.
### Apply to Claude Code Extension
## App config
When enabled, the provider of the Claude Code extension in VS Code follows CC Switch when you switch (writes `primaryApiKey` to `~/.claude/config.json`).
One block per app, holding the toggles and configuration directory that belong only to it.
> 💡 **Use case**: If you use both Claude Code CLI and the VS Code extension, enable this option to keep both configurations in sync.
### Claude Code
### Skip Claude Code First-Run Confirmation
- **Apply to Claude Code extension**: When on, the provider of the Claude Code extension in VS Code follows CC Switch when you switch (writes `primaryApiKey` to `~/.claude/config.json`). If you use both the Claude Code CLI and the VS Code extension, turning it on keeps the two in sync
- **Skip Claude Code first-run confirmation**: When on, skips the first-run confirmation that Claude Code shows on its first launch.
When enabled, skips the first-run confirmation that Claude Code shows on its first launch, suitable for users already familiar with Claude Code.
> ⚠️ **Note**: This option writes `hasCompletedOnboarding: true` to `~/.claude.json`; turning it off removes the field.
### Homepage Display
Choose which applications to display in the app switcher on the main page. Each app can be toggled independently, but at least one must remain visible.
Configurable apps: Claude Code, Claude Desktop, Codex, Gemini, Grok Build, OpenCode, OpenClaw, Hermes, Pi, MiniMax Code.
The same group also has a **Show project switcher** toggle that controls whether the project switcher appears at the top of the main page.
> 💡 **Use case**: If you only use Claude Code and Codex CLI, you can hide the other apps to keep the interface clean.
### Skill Storage Location
Choose the directory where CC Switch stores the master copies of your Skills:
| Option | Description |
|--------|-------------|
| CC Switch (default) | Stored in `~/.cc-switch/skills/`, managed centrally by CC Switch and synced to each app |
| `~/.agents/skills` | Stored in `~/.agents/skills/`, following the Agent Skills open standard so compatible tools can read it directly |
### 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 Files | Copies skill files entirely to the target directory |
> 💡 **Recommended**: Symlink is the default method. Switch to Copy Files if you encounter permission issues.
> ⚠️ **Note**: "Skip Claude Code first-run confirmation" writes `hasCompletedOnboarding: true` to `~/.claude.json`; turning it off removes the field.
### Codex App Enhancements
@@ -122,50 +108,59 @@ A third-party provider's API key is always written only to `~/.codex/config.toml
**Unified Codex session history**: When enabled, the official subscription runs under a shared custom provider ID, so official and third-party sessions appear in the same history list; you can optionally migrate existing official sessions as well (they are backed up automatically before migration). When turned off, they can be restored from the backup. Note: when you continue an old session with a different provider, that provider's backend may be unable to decrypt the reasoning content in the session, and the continuation will fail. See the guide [Unified Codex Session History](../../../guides/codex-unified-session-history-guide-en.md).
### Preferred Terminal
### Configuration Directory
Choose the terminal application that CC Switch uses when opening a terminal.
Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, and Pi — these 8 apps each have a "Config directory" row that can point somewhere else; leave it empty to use the default. MCP, Skills, and prompt paths change accordingly.
Supported terminals (by platform):
| App | Default |
|-----|---------|
| Claude Code | `~/.claude/` |
| Codex | `~/.codex/` |
| Gemini CLI | `~/.gemini/` |
| Grok Build | `~/.grok/` |
| OpenCode | `~/.config/opencode/` |
| OpenClaw | `~/.openclaw/` |
| Hermes | `~/.hermes/` |
| Pi | `~/.pi/agent/` |
| Platform | Terminal Options |
|----------|-----------------|
| macOS | Terminal, iTerm2, Alacritty, Kitty, Ghostty, Otty, WezTerm, Kaku, Warp |
| Windows | CMD, PowerShell, Windows Terminal |
| Linux | GNOME Terminal, Konsole, Xfce4 Terminal, Alacritty, Kitty, Ghostty |
Claude Desktop and MiniMax Code do not support overriding the directory here (so they are not in App config). MiniMax Code's data directory defaults to `~/.minimax/` and can be set with the `MINIMAX_DATA_DIR` (or `MAVIS_DATA_DIR`) environment variable; Hermes also recognizes `HERMES_HOME`, and Pi also recognizes `PI_CODING_AGENT_DIR`.
## Directory Configuration
Settings → Advanced → Configuration Directory
### 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 |
| Grok Build Directory | `~/.grok/` | Grok Build configuration directory |
| OpenCode Directory | `~/.config/opencode/` | OpenCode configuration directory |
| OpenClaw Directory | `~/.openclaw/` | OpenClaw configuration directory |
| Hermes Directory | `~/.hermes/` | Hermes configuration directory |
| Pi Directory | `~/.pi/agent/` | Pi agent configuration directory |
Claude Desktop and MiniMax Code do not support overriding the directory here. MiniMax Code's data directory defaults to `~/.minimax/` and can be set with the `MINIMAX_DATA_DIR` (or `MAVIS_DATA_DIR`) environment variable; Hermes also recognizes `HERMES_HOME`, and Pi also recognizes `PI_CODING_AGENT_DIR`.
> 💡 **WSL**: CC Switch does not detect WSL automatically. On Windows, you can set a directory to a path inside WSL (e.g. `\\wsl.localhost\Ubuntu\home\<username>\.claude`); CC Switch then reads and writes the configuration inside WSL, and the "About" page also detects and updates that tool in the corresponding WSL distribution.
> 💡 **WSL**: CC Switch does not detect WSL automatically. On Windows, you can set a directory to a path inside WSL (e.g. `\\wsl.localhost\Ubuntu\home\<username>\.claude`); CC Switch then reads and writes the configuration inside WSL.
> ⚠️ **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
> 💡 **Skill storage location and sync method** are not in Settings: on the sidebar's "Skills" page, click "Storage and sync" to choose whether the master copies live in the "CC Switch directory" or the "Common directory" (`~/.agents/skills`), and whether syncing to each app uses symlinks or copies.
### Export Configuration
## Local routing
Settings → Local routing
This group centralizes the global parts of local routing:
- **Service**: Shows the routing service's running state (uptime, total requests, success rate, active connections) and lets you "Start" / "Stop" it. The "Listen address and port" defaults to `127.0.0.1`; click "Save and restart service" after changing it. When "Record request usage" is off, Usage has no per-request details for routed requests. The service cannot be stopped while apps are still using it; switch them back to direct first
- **Apps using routing**: Lists the apps currently in Routing or Aggregation mode; click "Open" to jump to that app's page. "Switch all back to direct" writes every app's direct configuration back and stops the routing service; route targets, queues, and aggregation lists are kept
- **Auto Failover**: Tune each app's timeouts, retries, and circuit breaker. Queues are managed on the "Routing" tab of each app page. See [4.3 Failover](../4-proxy/4.3-failover.md)
- **Rectifier**: Automatically fixes some requests that are incompatible with the upstream; for example, when a Thinking signature is incompatible, it removes the related content and retries
The entry to Routing or Aggregation is the "Direct / Routing / Aggregation" tabs at the top of each app page; see [4.1 Local Routing Service](../4-proxy/4.1-service.md).
## Network
Settings → Network
**Global Outbound Proxy**: Configure the HTTP/HTTPS proxy CC Switch uses when accessing external APIs, applicable for scenarios where external API access requires a proxy.
## Data
Settings → Data
### Location
**CC Switch configuration directory**: The storage location for CC Switch's own data, defaulting to `~/.cc-switch/`; it can be pointed at a cloud-synced folder. Click "Save" after changing it; the app must be restarted for it to take effect.
### Data Management
#### Export Configuration
Click the "Export SQL Backup" button to save a SQL backup file containing:
@@ -177,7 +172,7 @@ Click the "Export SQL Backup" button to save a SQL backup file containing:
The exported file name format is `cc-switch-export-{timestamp}.sql`.
### Import Configuration
#### Import Configuration
1. Click "Select SQL File"
2. Select a previously exported backup file
@@ -186,40 +181,6 @@ The exported file name format is `cc-switch-export-{timestamp}.sql`.
> ⚠️ **Note**: Importing will overwrite existing configuration. It is recommended to export your current configuration as a backup first.
## Routing Settings
Settings → Routing Tab
The Routing tab centralizes the features related to local routing:
### Local Routing
Start/stop local routing, enable routing per app, and configure the listen address and port. See [4.1 Local Routing Service](../4-proxy/4.1-service.md) for details.
### Auto Failover
Configure failover queues and automatic switching strategies by app (Claude / Codex / Gemini / Grok Build). See [4.3 Failover](../4-proxy/4.3-failover.md) for details.
### Rectifier
Automatically fixes some requests that are incompatible with the upstream; for example, when a Thinking signature is incompatible, it removes the related content and retries.
### 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 Directory
Customize configuration file directories for each app. See the "Directory Configuration" section above for details.
### Data Management
Import/export configuration backups. See the "Data Management" section above for details.
### Backup & Restore
The Backup Management panel provides full control over database backups.
@@ -251,6 +212,12 @@ The panel displays all existing backups with:
> ⚠️ **Important**: Restoring a backup overwrites the current database. A safety backup is always created before the restore operation, so you can recover if needed.
#### Other Backups
The "Other Backups" overview below the backup list lists the backups CC Switch has left in various places (Skill uninstall backups, first-write backups of configuration files, Codex session migration backups, Hermes / OpenClaw configuration backups, leftover files from older versions, and so on), showing each item's location and size, with the total size next to the heading. Each item can be shown in the file manager, or you can "Delete" it yourself (with confirmation; permanent). Database backups are managed in the list above.
> ⚠️ For some backups, deleting them means the matching content can no longer be recovered: for example, after deleting the "first-write backup of configuration files" you can no longer find the original files from before they were rewritten, and after deleting a "Skill uninstall backup" an uninstalled Skill can no longer be restored; the note under each item spells out the consequences.
### Cloud Sync
Sync configurations across multiple devices via **WebDAV** or **S3-compatible storage**; only one of the two can be enabled at a time. Uses **v2 protocol** with dual-layer versioning for improved reliability.
@@ -321,11 +288,9 @@ Log level descriptions:
- **debug** - Detailed debugging information
- **trace** - All verbose information
## OAuth Authentication Center (Beta)
## Accounts (Beta)
Settings → **Auth** Tab
Added in v3.13.0, the **OAuth Authentication Center** (Beta) provides unified management for third-party OAuth credentials. It currently supports three account types:
The sign-in entry is "Accounts" in the left sidebar, not in Settings. Added in v3.13.0, **Accounts** (formerly the OAuth Authentication Center) provides unified management for third-party OAuth credentials. It currently supports three account types:
| Account Type | Purpose |
| ------------------------- | ---------------------------------------------------------- |
@@ -358,35 +323,16 @@ The xAI integration does **not** use an OAuth application registered to CC Switc
## About Page
Settings → About Tab
Settings → About
### Version Information
Displays the current CC Switch version number, with support for:
- Viewing release notes
- Checking for updates
- Downloading and installing new versions
- Checking for updates; when a new version is available, click "Update to vX" to download and install it (the portable version must be downloaded manually)
- Viewing GitHub, the official website, and the release notes
- "Recent updates": view the update summaries of the last few versions again
### Local Environment Check
### Tool Installation and Upgrades
Automatically detects installed CLI tool versions:
| Tool | Detection Contents |
|------|-------------------|
| Claude Code | Current version, latest version |
| Codex | Current version, latest version |
| Gemini CLI | Current version, latest version |
| Grok Build | Current version, latest version |
| OpenCode | Current version, latest version |
| OpenClaw | Current version, latest version |
| Hermes | Current version, latest version |
| Pi | Current version, latest version |
Click the "Refresh" button to re-detect. When an update is available, you can update a single tool or use "Update All". Missing tools show an install button. Installs and updates run silently in the background—the button shows progress and versions refresh automatically when done. Tools that are installed but cannot run in the current environment (for example, because the Node.js version is too old) are marked "Installed · can't run".
On Windows, if you set a tool's directory to a WSL path in "Configuration Directory", the "About" page detects and updates that tool in the corresponding WSL distribution.
### Manual Install Commands
This section is collapsed by default; click the heading to expand it. It lets you copy the install commands for all tools in one click: Claude Code, OpenCode, and Hermes use their official install scripts (Claude Code and OpenCode fall back to npm if the script fails), and the other tools are installed with npm. On Windows, Hermes uses a PowerShell install script and the other tools use npm. For each tool's install command, you can also refer to [1.2 Installation Guide](./1.2-installation.md#optional-install-the-tools-to-manage).
Version detection, installation, upgrades, and "Update All" for the AI coding tools are not here but on the sidebar's "Apps" page; see [1.2 Installation Guide](./1.2-installation.md#optional-install-the-tools-to-manage). On Windows, if you set a tool's directory to a WSL path in "App config", the "Apps" page detects and updates that tool in the corresponding WSL distribution.
+91 -183
View File
@@ -1,61 +1,61 @@
# 2.1 Add Provider
## Open the Add Panel
## Open the Add Page
Click the **+** button in the top-right corner of the main interface to open the Add Provider panel.
First select the app you want to add to in the sidebar, then click the **Add Provider** button (with a + sign) on the right side of the page header. When the app page has the "Direct / Routing / Aggregation" tabs at the top, the add page opens for the tab you are currently viewing: if you add under the "Aggregation" tab, the page header is marked "(Aggregation mode)" and the form uses a simplified aggregation layout (available for Claude Code and Codex only).
The panel has two tabs:
- **App-specific Provider**: Only for the currently selected app
- **Universal Provider**: Shared configuration across apps
The add page is a full-page view laid over the content area, in two steps:
1. **Pick a preset**: choose a preset, or choose "Custom Configuration"
2. **Fill in the form**: only a single preset bar remains at the top of the form; click "Change" on its right to go back to step 1. The back button at the top reads "Back to presets" in step 2 and "Back to providers" in step 1
In step 2, once you have touched the form (typed text, flipped a switch, changed an option), leaving the page through the sidebar, the tray, or Settings first brings up an "Unsaved changes" confirmation: "Discard and leave" or "Keep editing". Clicking "Cancel" in the footer closes the add page directly.
## Add Using Presets
Presets are pre-configured provider templates that only require an API Key to use.
Presets are pre-configured provider templates that usually only require an API Key to use.
### Choosing a Preset
The layout of step 1:
- **Search box**: always at the top, ready to type as soon as the page opens. You can search by name, URL, or common alias (for example kimi, 智谱, openrouter); ⌘F / Ctrl+F returns you to the search box
- **Categories on the left**: "All", "Account sign-in", "Model vendors", "Third-party platforms", "Cloud providers", and, for OpenCode, "Plugin configs". Presets are sorted into categories automatically by their own attributes, and each entry shows its match count
- **Two-column list on the right**: all presets are sorted by display name (Chinese names are placed in alphabetical order by pinyin); there is no pinning and no starring. "Custom Configuration" always sits at the top of "All"
What each category roughly holds:
| Category | Contents |
|----------|----------|
| Account sign-in | No API Key needed; sign in with an existing account, such as Claude Official, ChatGPT (Codex), GitHub Copilot, xAI, Google Official. Everything except Claude goes through routing |
| Model vendors | Vendors' own APIs and coding plans. A vendor's domestic site, overseas site, and different plans are merged into one row; after selecting it, switch between them with "Plan", "Region", and "Version" in the next step |
| Third-party platforms | Platforms that aggregate many vendors' models, or relay services that resell official models |
| Cloud providers | Calling models with a cloud vendor's account, such as AWS Bedrock |
| Plugin configs | Model assignment configs for OpenCode plugins |
Some presets carry a "Needs Routing" badge, meaning the upstream protocol differs from the client's, so you must turn on [local routing](../4-proxy/4.1-service.md) to use them.
When you switch between versions of the same vendor after already filling in the form, you are told "The form will be refilled for the new version. The API key you entered and any other changes will be cleared." and the switch happens only after you confirm.
### Steps
1. Select a provider from the "Preset" dropdown
1. Find the provider in the search box or the categories on the left, and click it
2. Name and endpoint are auto-filled
3. Enter your **API Key**
4. (Optional) Add notes
5. Click "Add"
5. Click "Add" in the footer
### Common Presets
If you can't find the vendor you want, the empty-search message has an "Add with a custom config" button; just fill in the endpoint URL and API Key by hand.
> The preset list is updated with new versions; refer to what the app actually shows. Below are only the common traits of each app's presets and what to watch out for.
#### 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 |
| StepFun | StepFun model |
| ModelScope | ModelScope community |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| Volcengine Doubao | DouBao Seed model |
| BaiLing | BaiLing AI |
| AiHubMix | AiHubMix aggregation service |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow (English version) |
| DMXAPI | DMXAPI relay service |
| PackyCode | PackyCode relay 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 |
| Command Code | Command Code aggregator |
Claude Code has the fullest set of presets, covering vendors' official offerings, coding plans, and aggregation and relay platforms. Among them:
> Presets marked with ⭐ in the preset selector are partner presets. The preset list may be updated with new versions. Refer to the actual list shown in the app.
- **Claude Official**: log in with an Anthropic official account; in the "Account sign-in" category
- **GitHub Copilot / Codex (ChatGPT account) / xAI (Grok)**: also under "Account sign-in"; you must first sign in to the matching account in Accounts, see "Codex OAuth Reverse Proxy" below
- For the other presets, just enter an API Key; the upstream format and model mapping already written into the preset need no manual changes
#### Claude Desktop Presets
@@ -78,103 +78,15 @@ Different plans from the same vendor may use different protocols (for example, S
> **Existing cards are not upgraded automatically**: a provider stores a snapshot of the preset as it was when the card was created. Presets such as DeepSeek, GLM (v3.20.2), and Kimi (v3.20.3) have since moved to native Responses. To let an existing card connect directly, re-add the latest version of the preset. To migrate by hand, change "Upstream Format" to Responses and make sure the API endpoint and model mapping match the vendor's Responses endpoint. See the [v3.20.3 release notes](../../../release-notes/v3.20.3-en.md) for details.
Other common Codex presets include:
| Preset Name | Description |
|-------------|-------------|
| OpenAI Official | Log in with an OpenAI official account |
| Azure OpenAI | Azure OpenAI service |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI relay service |
| PackyCode | PackyCode relay service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
> 💡 The preset list is updated continuously — refer to the in-app list for the authoritative version. For upstream format, model mapping, and reasoning capability, see "Upstream Format and Model Mapping for Codex / Grok Build" below.
> 💡 The preset list is updated continuously; refer to the in-app list for the authoritative version. For upstream format, model mapping, and reasoning capability, see "Upstream Format and Model Mapping for Codex / Grok Build" below.
#### Gemini Presets
| Preset Name | Description |
|-------------|-------------|
| Google Official | Log in with Google OAuth |
| PackyCode | PackyCode relay service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
| Custom | Manually configure all parameters |
Gemini CLI presets include "Google Official" (sign in with a Google account, no API Key needed) and a number of relay and aggregation services. Choose "Custom Configuration" when you need to configure every parameter by hand.
#### OpenCode Presets
#### OpenCode / OpenClaw 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 |
| StepFun | StepFun model |
| ModelScope | ModelScope community |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| Volcengine Doubao | DouBao Seed model |
| BaiLing | BaiLing AI |
| Xiaomi MiMo | Xiaomi MiMo model |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI relay service |
| OpenRouter | Aggregation routing service |
| Nvidia | Nvidia AI service |
| PackyCode | PackyCode relay 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 |
| StepFun | StepFun model |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| Volcengine Doubao | DouBao Seed model |
| BaiLing | BaiLing AI |
| Xiaomi MiMo | Xiaomi MiMo model |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI relay service |
| OpenRouter | Aggregation routing service |
| ModelScope | ModelScope community |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow (English version) |
| Nvidia | Nvidia AI service |
| PackyCode | PackyCode relay 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 |
OpenCode and OpenClaw are coexist apps: clicking "Add" writes the provider into each one's own configuration file, and multiple providers can exist at the same time. The presets cover mainstream model vendors, aggregation platforms, and relay services, and there is also an "OpenAI Compatible" preset for any OpenAI-compatible interface; OpenCode also has an Oh My OpenCode "Plugin configs" category.
#### Grok Build Presets
@@ -190,7 +102,7 @@ Pi presets cover official platforms such as Kimi and Volcengine Ark, plus a numb
#### MiniMax Code Presets
MiniMax Code presets are derived from the Pi preset catalog (41 in v3.20.4), keeping only presets that use one of three interfaces — Anthropic Messages, OpenAI Chat Completions, or OpenAI Responses — and need no Pi-specific compatibility options. Clicking "Add" writes the provider into `custom_provider` in `~/.minimax/config.yaml`; then choose a model inside MiniMax Code. CC Switch manages only custom providers; the official MiniMax account is managed by MiniMax Code itself.
MiniMax Code presets are derived from the Pi preset catalog, keeping only presets that use one of three interfaces — Anthropic Messages, OpenAI Chat Completions, or OpenAI Responses — and need no Pi-specific compatibility options. Clicking "Add" writes the provider into `custom_provider` in `~/.minimax/config.yaml`; then choose a model inside MiniMax Code. CC Switch manages only custom providers; the official MiniMax account is managed by MiniMax Code itself.
## Auto-Fetch Models
@@ -211,7 +123,7 @@ This feature is available in model-aware provider forms for **Claude Code / Clau
## Custom Configuration
After selecting the "Custom" preset, you need to manually edit the JSON configuration.
After choosing the "Custom Configuration" preset, you need to manually edit the JSON configuration.
> 💡 **What takes effect when you switch**: When you add a provider for Claude Code, Codex, Gemini CLI, or Grok Build, the editor shows "what the config file will look like after switching to this provider": the chosen preset applied on top of the tool's current config file. The key fields (endpoint, key, model name, API protocol, etc.) and a few compatibility options are stored in this provider; everything else is a global setting, and if you change it here, it is written straight to the config file when you add the provider and applies to every provider. The rules are the same as when editing; see [2.3 Edit Provider → Config Editor](./2.3-edit.md#config-editor).
@@ -300,14 +212,17 @@ Universal providers can share configurations across Claude Code / Codex / Gemini
### Create a Universal Provider
1. Switch to the "Universal" tab
2. Click "Add Universal Provider"
3. Fill in the common configuration:
Universal providers appear only on the add page for Claude Code, Codex, and Gemini CLI. In step 1, look at the bottom of the categories on the left: "Universal Provider" under "Across apps":
1. Click the "Universal Provider" category and pick a preset type
2. Fill in the common configuration in the form that opens:
- Name
- API Key
- Endpoint URL
4. Check the apps to sync to (Claude Code / Codex / Gemini)
5. Save
3. Check the apps to sync to (Claude Code / Codex / Gemini)
4. Save
For existing universal providers, click "Manage existing universal providers ›" in this category to view, edit, duplicate, and delete them.
### Sync Mechanism
@@ -329,7 +244,7 @@ When editing a universal provider, you can choose:
If you need to manually trigger a sync:
1. Click the "Sync" button on the universal provider card
1. In "Manage existing universal providers", click the "Sync" button on the universal provider card
2. Confirm the sync operation
3. Configuration will overwrite the linked provider in each app
@@ -354,8 +269,8 @@ One-click import via `ccswitch://` protocol links:
Batch import from SQL backup files:
1. Open "Settings → Advanced → Data Management"
2. Click "Select File"
1. Open "Settings → Data" and find "SQL Import/Export" under "Data Management"
2. Click "Select SQL File"
3. Select a previously exported `.sql` backup file
4. Click "Import"
5. Confirm to overwrite existing configuration
@@ -370,7 +285,7 @@ Batch import from SQL backup files:
## Codex OAuth Reverse Proxy (Claude Provider)
Starting from v3.13.0, CC Switch adds a **Codex OAuth reverse proxy** path that lets you reuse your ChatGPT account's Codex service inside Claude Code.
CC Switch provides a **Codex OAuth reverse proxy** path that lets you use a **ChatGPT account** to reuse Codex service inside Claude Code.
> 💡 **Location hint**: This feature appears as a **new Claude provider card type**, not as a Codex-side preset. Once added, it sits alongside regular API-Key providers in the Claude provider list.
@@ -384,21 +299,21 @@ Starting from v3.13.0, CC Switch adds a **Codex OAuth reverse proxy** path that
You can start from either entry point:
#### Entry A: From the Add Provider panel (recommended for new users)
#### Entry A: From the Add Provider page (recommended for new users)
1. Switch to the **Claude** app
2. Click the **+** button in the top-right to open the Add Provider panel
3. Under the third-party category, select the **Codex** preset (use the name as shown in the UI)
4. If no ChatGPT account is logged in yet, the panel **automatically guides** you into the login flow (see "Login Flow" below)
5. After login succeeds, the provider form shows the logged-in account — click **Save** to finish
2. Click **Add Provider** in the page header
3. Under the "Account sign-in" category, select the **Codex** (sign in with a ChatGPT account) preset (use the name as shown in the app)
4. If no ChatGPT account is logged in yet, the form guides you into the login flow (see "Login Flow" below)
5. After login succeeds, the form shows the logged-in account; click "Add" to finish
#### Entry B: From the OAuth Authentication Center (better for multi-account management)
#### Entry B: From Accounts (better for multi-account management)
1. Open **Settings → Auth** (the OAuth Authentication Center, marked with a **Beta** label at the top)
2. In the **ChatGPT (Codex OAuth)** section, click **Sign in with ChatGPT**
1. Click **Accounts** in the sidebar
2. In the **ChatGPT** section, click **Add account**
3. Complete the login flow (see below)
4. Once logged in, return to the **Claude** app → **Add Provider** → select the same Codex preset
5. In the form's **Select account** dropdown, choose the account you just logged in and save
5. In the form's "Select account" dropdown, choose the account you just logged in and add it
### Login Flow (Device Code)
@@ -414,16 +329,16 @@ No matter which entry point you use, the login flow is the same:
- Enter the verification code you copied
- Confirm authorization
3. **Automatic polling**: CC Switch keeps polling the OpenAI server in the background and closes the waiting UI once authorization succeeds
4. **Account appears in the list**: The logged-in ChatGPT account (login email) shows up in **OAuth Authentication Center → Logged in accounts**
4. **Logged-in account shown**: The logged-in ChatGPT account appears in the ChatGPT section of **Accounts**, showing the account you signed in with
> ⏱️ **Verification codes are valid for about 15 minutes**. If it expires, the UI shows "Device Code has expired" — click **Retry** to get a new one.
> ⏱️ **Verification codes are valid for about 15 minutes**. If it expires, the UI says sign-in didn't finish; just start the login again to get a new code.
### Enable and Use
After adding and saving a Codex OAuth provider:
1. Make sure [local routing](../4-proxy/4.1-service.md) is on and routing is enabled for Claude (the card shows a "Needs Routing" badge)
2. Find it in the Claude provider list and click the **Enable** button on the card — same as any regular provider
1. The card shows a "Needs Routing" badge: first switch to the "Routing" tab at the top of the app page and click "Start routing" (see [local routing](../4-proxy/4.1-service.md))
2. Find it in the Claude provider list and click "Route here" on the card; everything else is the same as for any regular provider
3. Claude Code CLI can then use your ChatGPT subscription through the reverse proxy
4. The provider also appears in the tray menu's **Claude** submenu for quick switching
@@ -442,21 +357,22 @@ The Codex OAuth preset's default model mapping:
The preset also sets `CLAUDE_CODE_MAX_CONTEXT_TOKENS` and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to `372000`, matching the context window of the ChatGPT Codex backend.
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.
Codex OAuth model selection does not rely only on the built-in 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 Authentication Center)
### Multi-Account Management (Accounts)
The **OAuth Authentication Center** supports managing multiple ChatGPT accounts at the same time:
**Accounts** can manage multiple ChatGPT accounts at the same time (GitHub Copilot and xAI accounts are here too):
| Action | Description |
| ---------------------- | ----------------------------------------------------------------- |
| Add another account | Click **Add another account** to repeat the login flow |
| Set as default | Click **Set as default** on an account row — new providers use it |
| Choose for a provider | In the provider form, use the **Select account** dropdown |
| Remove account | Click the red × next to an account (the token is cleared) |
| Log out all accounts | The **Logout all accounts** button at the bottom clears all |
| Add another account | Click "Add account" to repeat the login flow |
| Set as default | Choose "Set as default" in the account row's more actions: providers with no account specified use the default account |
| Choose for a provider | In the provider form, use the "Select account" dropdown to pick a specific account |
| Sign in again | When an account shows "Re-login required", choose "Re-login" in its more actions |
| Remove account | Choose "Delete account" in the account row's more actions (the token is cleared) |
| Remove all accounts | Choose "Delete all accounts" in the section's more actions |
> 💡 **Use case**: If you share a dev machine with teammates, create one provider per member's ChatGPT account and switch between them via the tray menu.
@@ -468,26 +384,20 @@ The **OAuth Authentication Center** supports managing multiple ChatGPT accounts
### Quota Display
After login and enabling the provider, the **bottom of the provider card** automatically shows the account quota:
After login, the right side of the account row in **Accounts** shows that account's quota bar (drawn as "remaining") and an "x minutes ago" update time; click the refresh icon to query again manually.
| Display Element | Example | Color Rules |
| ------------------- | ---------------- | -------------------------------------------- |
| Usage percentage | `45%` | < 70% green, 70–89% orange, ≥ 90% red |
| Reset countdown | `7d12h until reset` | ChatGPT account's sliding window or daily limit |
| Refresh button | Circular arrow | Manually re-query quota |
> ⚠️ **Session expired**: If the token becomes completely invalid (and cannot be refreshed automatically), the bottom of the card shows a yellow "Session expired" warning. Go to **Settings → Auth**, remove the account, and log in again.
> ⚠️ **Re-login required**: If the token becomes completely invalid (and cannot be refreshed automatically), the account row shows "Re-login required". Choose "Re-login" for that account in **Accounts**, or delete it and add it again.
### Common Failures
| Scenario | Symptom | Resolution |
| --------------------------- | -------------------------------- | ------------------------------------------- |
| Verification code timeout | "Device Code has expired" shown | Click **Retry** to get a new code |
| Authorization denied | "User denied authorization" | Retry and click "Authorize" in the browser |
| Verification code timeout | "Sign-in didn't finish" | Start the login again to get a new code |
| Authorization denied | "Sign-in didn't finish" | Log in again and click "Authorize" in the browser |
| Network error | Specific error details shown | Check network, confirm access to OpenAI domains |
| Not logged in before adding | "Please sign in to ChatGPT first" | Complete login in Settings → Auth first |
| Token refresh failed | "Session expired" in quota box | Remove the account and log in again |
| Quota query failed | "Query failed" in quota box | Click the **Refresh** button to retry |
| Not logged in before adding | "Please sign in to ChatGPT first" | Complete login in Accounts first |
| Token refresh failed | Account row shows "Re-login required" | Log in to that account again |
| Quota query failed | Account row shows "Quota unavailable" | Click the refresh icon to retry |
### ⚠️ Risk Notice (Important)
@@ -520,7 +430,7 @@ The Advanced Options section auto-expands when a non-default API format is confi
### Full URL Endpoint Mode
Added in v3.13.0. By default, CC Switch treats the configured `base_url` as a **prefix** and appends fixed paths like `/v1/chat/completions`. For some vendors (such as third-party services with non-standard URL layouts), this path concatenation causes requests to fail.
By default, CC Switch treats the configured `base_url` as a **prefix** and appends fixed paths like `/v1/chat/completions`. For some vendors (such as third-party services with non-standard URL layouts), this path concatenation causes requests to fail.
**How to enable**:
@@ -578,8 +488,6 @@ When editing a Codex or Grok Build provider, the **Upstream Format** option in A
With either of the last two, [local routing](../4-proxy/4.1-service.md) must be running with routing enabled for the app in question, and must stay on while in use. When you pick a preset, the upstream format is already set — no manual adjustment needed.
> 💡 Before v3.16.5, this was a "Needs Local Routing" toggle; it has been replaced by "Upstream Format", and model mapping no longer depends on that toggle.
#### Model Mapping (Codex Only)
The form for every non-official Codex provider has a **Model Mapping** table that declares the models available for this provider:
@@ -618,7 +526,7 @@ When adding a Codex provider, a **1M Context Window** toggle is available:
- **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. 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.
The auto-compact limit can be customized in the text field that appears when the toggle is on. 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
@@ -631,7 +539,7 @@ Click the icon area to the left of the name to:
Enter the provider's website or console URL for quick access:
- Click the link icon on the provider card to open directly
- Open it directly from the provider card
- Useful for checking balance, obtaining API keys, etc.
### Notes
@@ -659,4 +567,4 @@ When adding or editing a provider, you can speed-test API endpoints:
- 🟠 Orange: Latency 500–800ms
- 🔴 Red: Latency ≥ 800ms
![image-20260108005327817](../../assets/image-20260108005327817.png)
<!-- TODO(v4 screenshot): The endpoint speed test panel opened by "Manage & Test" when editing a provider, with several endpoints and latency results -->
+59 -31
View File
@@ -1,25 +1,49 @@
# 2.2 Switch Provider
## Connection Modes
At the top of the app page for Claude Code, Codex, Gemini CLI, and Grok Build there are three tabs: "Direct / Routing / Aggregation" (only Claude Code and Codex have Aggregation):
| Mode | How requests travel | Switching providers |
|------|---------------------|---------------------|
| Direct | The client connects to the provider directly | Rewrites the key fields in the client's config file |
| Routing | Requests go through CC Switch on your machine first, which can convert formats and fail over | Changes only the routing target; the config file is no longer rewritten |
| Aggregation | Requests are split across several providers according to the model picked in `/model`; no failover | Switching changes the default provider |
**Clicking a tab only views that page; it does not change your configuration.** To actually change modes, click the button on the page that spells out the consequences: "Start routing", "Switch to Aggregation", or "Back to direct". The "active" marker next to a tab shows which mode is actually in effect. For details on Routing and Aggregation, see [4.2 App Routing](../4-proxy/4.2-routing.md).
The most common case, switching in Direct mode, comes first.
<!-- TODO(v4 screenshot): The Direct / Routing / Aggregation tabs at the top of an app page, with the active mode marked "active" -->
## Switch from Main Interface
In the provider list, click the "Enable" button on the target provider card.
On the Direct page, click the "Switch" button on the target provider card.
OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code are coexist apps that can have several providers added at the same time; see [Coexist Apps](#coexist-apps) below for how they work.
OpenCode, OpenClaw, Hermes, Pi, and MiniMax Code are coexist apps that can have several providers added at the same time; see [Coexist Apps](#coexist-apps) below for how they work. Claude Desktop has no mode tabs; see [2.6 Claude Desktop](./2.6-claude-desktop.md).
### Switching Flow
1. Click the "Enable" button
1. Click the "Switch" button
2. CC Switch updates the configuration file
3. The card status changes to "Currently Active"
3. The button on the card changes to the "In use" state
4. The change takes effect in the way each app supports (see "Activation Methods" below)
### Status Indicators
| Status | Display | Description |
|--------|---------|-------------|
| Currently Active | Blue border + label | Current provider in the configuration file |
| Routing Active | Green border | The provider actually forwarding requests while local routing is on |
| Normal | Default style | Inactive provider |
| In use | Direct-colored border + "In use" | In Direct mode, the provider currently in the config file |
| Routing | Routing-colored border + "Routing" | In Routing mode, the provider actually forwarding requests |
| Current default | Aggregation-colored border + "Current default" | The default provider in Aggregation mode |
| Normal | Default style | Other providers |
The buttons on the cards follow the mode:
- On the Direct page, when routing or aggregation is actually in effect, the other cards' button is "Back to direct and use".
- On the Routing page, the other cards' button is "Route here".
- A provider marked "Needs routing" (for example one that needs format conversion) cannot be used directly; switching to it shows a prompt, and you can choose "Start routing and use it".
- Official subscriptions do not go through routing (except Codex's OpenAI Official) and are greyed out on the Routing page.
## Quick Switch via System Tray
@@ -28,32 +52,34 @@ 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. Hover over the corresponding app submenu (e.g., "Claude · CurrentProvider")
2. Hover over the corresponding app submenu
3. Click the provider name you want to switch to
4. Switching completes with a brief tray notification
4. Switching completes with a brief tray notification (for example "Claude Code switched to xxx. Restart Claude Code to apply")
### Tray Menu Structure
Starting from v3.13.0, the tray menu is refactored from a flat list into **per-app submenus**, with a dedicated submenu for each app:
The tray has one submenu row for each switch-style app:
| Submenu | Description |
| ---------- | -------------------------------------------------------------- |
| Claude | All Claude providers (including Codex OAuth reverse proxy) |
| Codex | All Codex providers |
| Gemini | All Gemini providers |
| Grok Build | All Grok Build providers |
| Submenu | Description |
| ------- | ----------- |
| Claude Code | That app's providers |
| Claude Desktop | That app's providers; providers in model mapping mode carry " · Model mapping" |
| Codex | That app's providers |
| Gemini CLI | That app's providers |
| Grok Build | That app's providers |
The tray only includes these four apps that support local routing; for Claude Desktop and coexist apps, use the main interface.
The submenu title looks like "App name · [Routing / Aggregation ·] provider in use · quota summary", so you can see which provider is in use and which mode it is in without opening it. What the submenu does follows the current mode:
**Benefits of the refactor**:
- **Direct**: click a provider to switch. A provider that needs routing is marked " (needs routing)…"; clicking it opens the app page with a prompt.
- **Routing**: click a provider to change the routing target. Official subscriptions are marked " (official plans don't go through routing)" and cannot be clicked.
- **Routing + Failover on**: read-only; it lists the queue order. To adjust it, go to the app page.
- **Aggregation**: lists only the providers on the aggregation roster; clicking one makes it the default.
- **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 and usage summary**: You know at a glance which provider Claude / Codex / Gemini / Grok Build is using, plus available cached usage information, without opening the submenu
- **Per-app isolation**: Switching Claude's provider doesn't disturb the other apps' views
The tray holds only these five switch-style apps; use the main interface for coexist apps.
> 💡 **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).
> 💡 **Tip**: The combination of background residency + Lightweight Mode + tray 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).
![image-20260108004348993](../../assets/image-20260108004348993.png)
<!-- TODO(v4 screenshot): The tray menu with one app's submenu expanded, showing the mode title and the provider list -->
## Activation Methods
@@ -69,9 +95,7 @@ Restart Claude Desktop after switching. Providers in "Model Mapping" mode also n
### Codex
Requires restart after switching:
- Close the current terminal window
- Reopen the terminal
Requires a restart after switching: for the CLI, quit and run `codex` again; for the desktop app, quit completely (⌘Q on macOS) and reopen it.
### Gemini CLI
@@ -83,11 +107,15 @@ Gemini CLI reads `.env` and `settings.json` at startup, so a running session doe
Restart Grok Build after switching; a notification appears when the switch succeeds.
### With Local Routing On
### In Routing and Aggregation Modes
When local routing is on, requests from Claude Code, Codex, Gemini CLI, and Grok Build are all forwarded through CC Switch, so switching providers applies to subsequent requests immediately. However, if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
Requests are all forwarded through CC Switch. On the Routing page, switching providers changes only the routing target and applies to subsequent requests immediately; if the switch changes the model, Codex, Gemini CLI, and Grok Build may still need a restart.
While local routing is on, switching changes the provider that local routing uses; the provider you were using before you turned it on stays the same and is labeled "Direct" on its card, and the config file is written back to it when you turn local routing off. See [4.2 App Routing](../4-proxy/4.2-routing.md#routing-and-provider-switching) for details.
While routing is on, the provider you were using in Direct mode stays the same (labeled "Used when direct" on its card), and the config file is written back to it once you return to Direct.
In Aggregation mode, changes to the aggregated model list take effect immediately in Claude Code; Codex needs a full restart to see the new model list: for the CLI, click "Restart Codex daemon" in the page prompt (this interrupts running tasks); for the desktop app, quit completely with ⌘Q and reopen it; for editor plugins, reopen the window.
Routing and Aggregation need CC Switch to keep running. Quitting CC Switch automatically returns to Direct, and it reconnects on the next launch. See [4.2 App Routing](../4-proxy/4.2-routing.md) for details.
## Configuration File Changes
@@ -115,7 +143,7 @@ Modified content (only the key fields are shown; nothing else in the file is tou
~/.codex/config.toml
```
A third-party provider's API Key is written to that provider's `experimental_bearer_token` in `config.toml`, not to `~/.codex/auth.json`. `auth.json` is used only for the official OpenAI ChatGPT login: whether it is kept when you switch to a third-party provider is controlled by "Settings → General → Codex App Enhancements". Providers with a model mapping also generate `~/.codex/cc-switch-model-catalog.json`.
A third-party provider's API Key is written to that provider's `experimental_bearer_token` in `config.toml`, not to `~/.codex/auth.json`. `auth.json` is used only for the official OpenAI ChatGPT login: whether it is kept when you switch to a third-party provider is controlled by "Keep official login for direct switches" under "Settings → App config". Providers with a model mapping also generate `~/.codex/cc-switch-model-catalog.json`.
### Gemini
@@ -136,7 +164,7 @@ Only the default model (`default` under `[models]`) and the `[model."<name>"]` t
### Claude Desktop
Writes Claude Desktop's 3P profile configuration (on macOS under `~/Library/Application Support/Claude-3p/`); see [2.6 Claude Desktop](./2.6-claude-desktop.md) for details.
Writes Claude Desktop's 3P profile configuration (on macOS under `~/Library/Application Support/Claude-3p/`). Providers in Direct mode have their endpoint and key written straight in; providers in model mapping mode point at the local routing service. See [2.6 Claude Desktop](./2.6-claude-desktop.md) for details.
## Coexist Apps
+14 -14
View File
@@ -1,10 +1,10 @@
# 2.3 Edit Provider
## Open the Edit Panel
## Open the Edit Page
1. Find the provider card you want to edit
2. Hover over the card to reveal action buttons
3. Click the "Edit" button
2. Click the pencil icon ("Edit") on the right side of the card
3. This opens the full-page editor; click "Back to providers" to leave
## Editable Content
@@ -32,7 +32,7 @@ The icon library includes common AI service provider and technology icons, suppo
- Icon name tooltips
- Real-time preview of selected icon
![image-20260108004734882](../../assets/image-20260108004734882.png)
<!-- TODO(v4 screenshot): The icon picker opened on the edit page -->
### Configuration
@@ -46,7 +46,7 @@ For Claude Code, Codex, Gemini CLI, and Grok Build, the bottom of the edit panel
|-----|--------|
| Claude Code | `~/.claude/settings.json` |
| Codex | `~/.codex/config.toml` (the key is in the API Key field above and isn't repeated in the editor) |
| Gemini CLI | `~/.gemini/.env` and `~/.gemini/settings.json` |
| Gemini CLI | `~/.gemini/.env` and `~/.gemini/settings.json` (two editors) |
| Grok Build | `~/.grok/config.toml` |
The editor's content falls into two groups, and a line above the editor lists what the first group covers for this app:
@@ -54,14 +54,14 @@ The editor's content falls into two groups, and a line above the editor lists wh
- **Follows the provider**: key fields such as the endpoint, key, model name, and API protocol, plus a few compatibility options that belong to the provider (such as the context window). The editor shows this provider's own values, and they are stored in this provider on save.
- **Global settings**: everything else, such as plugins, hooks, permissions, MCP, and environment variables you added yourself. The editor shows what's in the tool's config file right now, and on save they are written straight to the config file and apply to every provider.
The rules are exactly the same whether you edit the current provider or another one: no matter which provider you edit, changes to global settings are written to the config file immediately. With local routing on, the key fields in the editor also show the provider's own real endpoint and key, not the local routing address.
The rules are exactly the same whether you edit the current provider or another one: no matter which provider you edit, changes to global settings are written to the config file immediately. In Routing mode, the key fields in the editor also show the provider's own real endpoint and key, not the local routing address.
### Settings Changed in the Tool
- **Global settings**: if you change them in the tool (for example, by installing a plugin), you'll see the change when you open the edit panel, and switching providers won't touch them.
- **Key fields**: a model you pick temporarily in the tool (for example, with `/model` in Claude Code) isn't saved back to the provider; after you switch away and back, it returns to the value saved in the provider. To change it for good, edit the provider here.
> 💡 Older versions read the whole config file back into the provider ("backfill") when you edited the current provider. The new version no longer backfills: shared settings already live in the config file and don't need to be stored in any one provider.
> 💡 **Common config snippets are frozen**: older versions had a "common config snippet" that was merged into the config file on switching, and when you edited the current provider they also read the whole config file back into the provider ("backfill"). The new version does neither: shared settings already live in the config file and don't need to be stored in any one provider, nor does a snippet. Snippets left in existing providers are read only by older versions and don't affect the new one.
### Config File Changed While Editing
@@ -144,15 +144,15 @@ When editing a provider, in the "Endpoint Management" area you can:
- Delete existing endpoints
- Set a default endpoint
## JSON Editor
## JSON / TOML Editor
Configuration uses JSON format, and the editor provides:
The config editors for Claude Code and Gemini CLI use JSON (Gemini's `.env` is environment-variable text), while Codex and Grok Build use TOML. The editor provides:
- Syntax highlighting
- Format validation
- Error messages
### Common Errors
### Common Errors (JSON as an example)
**Missing quotes**:
```json
@@ -183,12 +183,12 @@ Configuration uses JSON format, and the editor provides:
## Save and Activate
1. Click the "Save" button
2. If the form detects a non-blocking issue, a "save anyway" prompt appears; confirming still saves the provider
1. Click the "Save" button at the bottom of the page
2. If the form detects a non-blocking issue, a "Configuration has the following issues" prompt appears; click "Save anyway" to still save the provider
3. Changes to global settings are written to the config file immediately, whether or not you're editing the current provider
4. Changes to key fields are stored in the provider. Without local routing, if you're editing the current provider, they are also written to the config file; with local routing on, if you're editing the provider that routing is using and the change affects what local routing writes to the config file (such as the model name), the config file is updated as well
4. Changes to key fields are stored in the provider. In Direct mode, if you're editing the provider in use, they are also written to the config file; in Routing mode, if you're editing the provider that routing is using and the change affects what routing writes to the config file (such as the model name), the config file is updated as well
5. Whether you need to restart the tool is the same as for switching providers; see [2.2 Switch Provider](./2.2-switch.md)
## Cancel Editing
Click "Cancel" or press the `Esc` key to close the edit panel. All modifications will be discarded.
Click "Cancel" or "Back to providers" to leave the edit page; your changes are not saved. If there are unfinished edits you are prompted with "Unsaved changes", and they are discarded only if you choose "Discard and leave".
@@ -6,15 +6,16 @@ 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
1. Move the mouse over the provider card; a **⋮⋮** drag handle appears at the far left of the card (hidden otherwise)
2. Hold the left mouse button
3. Drag up or down to the target position
4. Release the mouse to complete reordering
4. Release the mouse to complete reordering; a "Sort order updated" notice appears
### 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
- **Failover order**: The order in the queue is the providers' sort order. In "Queue · by priority" on the "Routing" tab, you can also use the move up / move down buttons on the cards, or drag them, to adjust who gets requests first; see [4.3 Failover](../4-proxy/4.3-failover.md)
- The provider order in the tray menu follows as well
## Duplicate Provider
@@ -24,28 +25,28 @@ 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.
The universal provider list ("Manage existing universal providers" under the "Universal Provider" category on the add page) also has 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
2. Click the "Duplicate" button
1. Click the **⋯** (More) button on the right side of the provider card
2. Choose "Duplicate"
3. A copy is automatically created with a `copy` name suffix
4. Edit the copy to modify the configuration
4. Click the edit button on the card to modify the copy's configuration
### Duplicated Content
Duplication creates a complete copy, including:
Duplication creates a copy that carries over:
| Content | Duplicated |
|---------|------------|
| Name | Yes (with `copy` suffix) |
| Configuration | Fully duplicated |
| Notes | Yes |
| Notes | No; fill them in again in the copy if needed |
| Website Link | Yes |
| Icon | Yes |
| Endpoint List | Yes |
| Sort Position | Inserted below the original provider |
| Sort Position | Placed after the original provider |
### After Duplication
@@ -59,20 +60,18 @@ After duplication, you typically need to modify:
### Steps
1. Hover over the provider card to reveal action buttons
2. Click the "Delete" button
3. Confirm deletion
1. Click the **⋯** (More) button on the right side of the provider card
2. Choose "Delete" (in red, at the bottom of the menu)
3. Confirm deletion in the dialog
### Deletion Confirmation
A confirmation dialog appears before deletion, showing:
- Provider name
- Warning that deletion cannot be undone
- The "This action cannot be undone" warning
### Deletion Restrictions
- **Currently active provider**: Can be deleted, but it is recommended to switch to another provider first
- **Provider in use**: Cannot be deleted; "Delete" is greyed out, with the note "The provider in use can't be deleted. Switch to another one first." For switch-style apps this covers the one used in Direct mode and the one being routed to in Routing or Aggregation mode; switch to another provider first, then delete
- **Universal provider**: Deleting will also remove linked app configurations
![image-20260108004946288](../../assets/image-20260108004946288.png)
@@ -2,6 +2,8 @@
CC Switch's quota / balance display is split into two categories: **Auto Display** (OAuth account types, works out of the box) and **Manual Enable** (built-in templates + custom scripts, shown only after you configure them on the provider card).
> This page covers the **quota / balance** shown on provider cards. Statistics for requests, tokens, and spend are on the "Usage" page in the left sidebar; see [4.4 Usage Statistics](../4-proxy/4.4-usage.md).
| Category | Scope | User Enable Required |
| ------------------------------ | -------------------------------------------------------------------------- | -------------------- |
| **Auto Display** | GitHub Copilot, Codex OAuth reverse proxy, xAI OAuth | No |
@@ -20,10 +22,10 @@ The following account-type providers automatically display the quota at the bott
### Auto Display Interactions
- **Card footer display**: Usage percentage + reset countdown, colored by usage (< 70% green / 70–89% orange / ≥ 90% red)
- **Manual refresh**: Click the refresh icon on the card to re-query
- **Simplified card**: The quota for these provider types is displayed by built-in logic, so the card's "Usage Query" button is grayed out
- **Session expired notice**: If a token fails to refresh, the card shows a "Session expired" warning
- **Card footer display**: Quota is always written as what's left, such as "5h 62% left", next to the reset countdown. It is gray normally; when any tier has less than 10% left, the text turns darker and bold. When used up it shows "Used up", when the plan has expired "Plan expired", and when the query fails "Quota unavailable" (in red)
- **Manual refresh**: Click the quota text to re-query (hovering shows "Click to check again" and the update time)
- **Simplified card**: The quota for these provider types is displayed by built-in logic, so the card's "More" menu has no "Configure usage query"
- **Sign-in expired notice**: If a token fails to refresh, the card shows "Sign-in expired" or "Token refresh pending"; sign in again in **Accounts** in the left sidebar
---
@@ -33,13 +35,13 @@ Besides the auto-display account types above, **all other providers** (including
### Official Subscription Quota
Starting from v3.16.2, the subscription quota of the Claude / Codex / Gemini / Grok Build official providers is a built-in template that is **off by default**:
The subscription quota of the Claude / Codex / Gemini / Grok Build official providers is a built-in template that is **off by default**:
1. Click the **Usage Query** button on the official provider card
1. On the official provider card, click the "More" (⋯) button on the right and choose **Configure usage query**
2. Turn on "Enable usage query" and choose the **Official Subscription** template
3. After saving, the subscription quota shows at the bottom of the card (for Grok Build, the SuperGrok quota)
3. After saving, the subscription quota shows at the bottom of the card (for Grok Build, the SuperGrok quota). The official subscription quota reads the local CLI's OAuth credentials and calls the official API, and it only makes requests once enabled
Exception: an OpenAI Official provider bound to a ChatGPT account in the Auth Center has it on by default.
Exception: an OpenAI Official provider bound to a ChatGPT account in Accounts has it on by default.
### Why do these need manual enabling?
@@ -47,7 +49,7 @@ One important reason: **the same request URL (same vendor) may expose multiple q
### Built-in Template Coverage
v3.13.0 provides **ready-to-use built-in templates** for the following categories — no script writing required:
There are **ready-to-use built-in templates** for the following categories — no script writing required:
| Category | Covered Providers | Template Type |
| ------------------ | --------------------------------------------------------- | ------------------------------- |
@@ -59,15 +61,15 @@ v3.13.0 provides **ready-to-use built-in templates** for the following categorie
### Enable Steps
1. Hover over the provider card to reveal action buttons
2. Click the **Usage Query** button (📊 icon)
1. Hover over the provider card and click the "More" (⋯) button on the right
2. Choose **Configure usage query** (the first time, a confirmation appears; click "I understand, configure")
3. At the top of the configuration panel, toggle on **Enable usage query**
4. Select the right built-in template (e.g., Token Plan, third-party balance) or choose "Custom"
5. Fill in API Key / Base URL / Access Token as needed (most cases can be left blank, reusing the provider's own credentials)
6. Click **Test script** to verify the query returns successfully
7. Save — next time the provider is activated, the quota will show up at the bottom of the card
7. Save — the quota will show up at the bottom of the card
> ⚠️ **Note**: The auto-refresh interval after enabling is controlled by the "Auto Query Interval" field (set to `0` to disable auto-refresh). Background queries only trigger when the provider is in "Currently Active" state.
> ⚠️ **Note**: The auto-refresh interval after enabling is controlled by the "Auto Query Interval" field (set to `0` to disable auto-refresh). Background queries only trigger when the provider is in the "In use" state.
---
@@ -84,8 +86,8 @@ When a provider **is not covered by the built-in templates**, you can write a cu
## Open Configuration
1. Hover over the provider card to reveal action buttons
2. Click the "Usage Query" button (📊 icon)
1. Hover over the provider card and click the "More" (⋯) button on the right
2. Choose "Configure usage query"
3. Opens the usage query configuration panel
## Enable Usage Query
@@ -94,7 +96,7 @@ At the top of the configuration panel, enable the "Enable usage query" toggle.
## Preset Templates
CC Switch provides three preset templates:
The preset template dropdown offers: Custom, General, NewAPI, plus the built-in templates above such as Token Plan, Official, and Official Subscription. The three most commonly used for custom scripts:
### Custom Template
@@ -180,8 +182,8 @@ Request timeout in seconds, default 10 seconds.
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
- Range: 0-1440 minutes (up to 24 hours); 5-60 minutes is recommended
- Only effective when the provider is in "In use" status
## Extractor Return Format
@@ -211,7 +213,8 @@ After configuration, click the "Test script" button to verify:
After successful configuration, the provider card displays:
- **Single plan**: Directly shows remaining balance
- **Multi-plan**: Shows plan count, click to expand for details
- **Multi-plan**: Shows "N plans"; click "Expand" for details
- Plan-type quotas also lead with what's left; when the query fails it shows "Quota unavailable"
## Variable Placeholders
@@ -232,8 +235,8 @@ The following placeholders can be used in scripts and are automatically replaced
**Check**:
1. Official providers (Claude / Codex / Gemini / Grok Build): make sure "Enable usage query" is turned on under "Usage Query" and the **Official Subscription** template is selected (off by default)
2. The provider is in "Currently Active" state (inactive providers do not trigger queries)
3. For OAuth account types (Copilot / Codex OAuth / xAI OAuth), check whether the token is still valid; if the card shows "Session expired", log in again under **Settings → Auth**
2. The provider is in the "In use" state (providers not in use do not trigger background queries)
3. For OAuth account types (Copilot / Codex OAuth / xAI OAuth), check whether the token is still valid; if the card shows "Session expired", log in again under **Accounts** in the left sidebar
4. Network access to the official quota endpoint
### Manual Enable Still Not Showing Quota
@@ -244,7 +247,7 @@ The following placeholders can be used in scripts and are automatically replaced
3. Click **Test script** to see the specific error
4. Required fields such as API Key / Base URL are filled correctly
5. Network access to the provider's quota endpoint
6. Background auto-refresh only triggers when the provider is in "Currently Active" state
6. Background auto-refresh only triggers when the provider is in the "In use" state
### Query Failed
@@ -2,7 +2,7 @@
## Overview
The Claude Desktop panel lets you manage Claude Desktop provider configurations in CC Switch.
The Claude Desktop page lets you manage Claude Desktop provider configurations in CC Switch.
Once enabled, you can:
@@ -11,7 +11,7 @@ Once enabled, you can:
- Reuse Copilot / Codex OAuth / xAI OAuth account-based providers
- Switch between Claude Desktop official mode and third-party providers
Claude Desktop and Claude Code are separate app entry points. Claude Code uses `~/.claude/settings.json`, while Claude Desktop uses its own 3P profile configuration. In CC Switch they appear as separate apps: "Claude" and "Claude Desktop"; the icon badge in the bottom-right corner helps distinguish them.
Claude Desktop and Claude Code are separate app entry points. Claude Code uses `~/.claude/settings.json`, while Claude Desktop uses its own 3P profile configuration. In CC Switch they appear as separate apps: "Claude" and "Claude Desktop"; the Claude Desktop icon in the sidebar has a small badge in the bottom-right corner to help distinguish them.
## Support Scope
@@ -26,25 +26,23 @@ Claude Desktop and Claude Code are separate app entry points. Claude Code uses `
## Quick Start
### Step 1: Open the Claude Desktop Panel
### Step 1: Open the Claude Desktop Page
Select **Claude Desktop** in the app switcher on the left.
Select **Claude Desktop** in the app list in the left sidebar.
![Claude Desktop panel](../../assets/claude-desktop-panel-en.png)
<!-- TODO(v4 screenshot): The Claude Desktop provider page after selecting it in the sidebar, with the connection bar at the top showing "Current: xxx · Direct" -->
If you do not see this entry, go to:
If the sidebar has no such entry, go to the "Apps" page in the sidebar and check under "Apps shown in the sidebar" that Claude Desktop is not hidden.
Settings → General → Homepage Display
Make sure Claude Desktop is not hidden.
The Claude Desktop page has no "Direct / Routing / Aggregation" tabs: the connection is set per provider, and the connection bar at the top of the page shows whether the current provider is "Direct" or "Model mapping", along with the status of the routing service.
### Step 2: Import or Add Providers
#### Recommended: Import from Claude Code
Many users configure providers in Claude Code first, then want to bring the same provider set into Claude Desktop. On first launch, or when entering the Claude Desktop panel for the first time, if no providers exist here, click **Import existing providers from Claude Code**.
Many users configure providers in Claude Code first, then want to bring the same provider set into Claude Desktop. On first launch, or when entering the Claude Desktop page for the first time, if no providers exist here, click **Import existing providers from Claude Code**.
![Import providers from Claude Code](../../assets/claude-desktop-import-from-claude-en.png)
<!-- TODO(v4 screenshot): The "Import existing providers from Claude Code" button in the empty list -->
If you already have many providers configured in Claude Code, this one-click import saves you from re-entering endpoint URLs, API keys, and default models one by one.
@@ -61,9 +59,9 @@ After importing, review each provider's model mapping against your actual upstre
If you already configured providers in Claude Code, prefer **Import existing providers from Claude Code**. This is the easiest migration path to Claude Desktop.
If there is nothing to import, or if you want to add a provider only for Claude Desktop, click the **+** button in the top-right corner.
If there is nothing to import, or if you want to add a provider only for Claude Desktop, click the "Add Provider" button in the top-right corner of the page.
![Add Claude Desktop provider](../../assets/claude-desktop-add-provider-en.png)
<!-- TODO(v4 screenshot): The Add Provider page for Claude Desktop -->
You can choose:
@@ -81,18 +79,20 @@ For native Anthropic Messages API providers that already accept Claude Desktop's
### Step 3: Switch and Restart Claude Desktop
Click **Enable** on a provider card.
Click "Switch" on a provider card; the current one then shows "In use".
After switching:
- Direct providers: restart Claude Desktop for the change to take effect
- Providers that need routing: keep CC Switch running, turn on Claude Desktop local routing, then restart Claude Desktop
- Model mapping providers: CC Switch starts the routing service automatically and keeps it running; then restart Claude Desktop
> Note: Claude Desktop does not hot-reload configuration like Claude Code. After each provider switch, fully quit and reopen Claude Desktop.
## Two Modes
## Two Connection Modes
### Direct Mode
In "Connection Mode" on the provider edit page, choose "Direct" or "Model Mapping" (this corresponds to the "Needs model mapping" toggle); the card also marks it with a "Direct" or "Model mapping" badge.
### Direct
Direct mode is for providers that already expose the Anthropic Messages API and can be reached by Claude Desktop directly.
@@ -112,15 +112,15 @@ Use this when:
- The provider exposes native Anthropic Messages API
- Model IDs are Claude Desktop-recognized role names: `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` (or the same with the `anthropic/claude-` prefix)
- No format conversion is needed
- CC Switch local routing does not need to stay running while in use
- CC Switch does not need to keep the routing service running while in use
The "Manually specify Claude Desktop models" option in direct mode is advanced. Most native Claude model providers do not need it because Claude Desktop can fetch `/v1/models` automatically.
Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop. Manually entered model names must follow the `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` shape (legacy IDs like `claude-3-5-sonnet-…` are rejected).
### Model Mapping Mode
### Model Mapping
Model mapping mode is for providers whose models are not `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role IDs (including legacy Claude IDs and non-Claude models such as DeepSeek and Kimi), or when CC Switch needs to convert the API format.
Model mapping is for providers whose models are not `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` role IDs (including legacy Claude IDs and non-Claude models such as DeepSeek and Kimi), or when CC Switch needs to convert the API format.
After **Needs model mapping** is enabled, Claude Desktop connects to the CC Switch local gateway:
@@ -157,7 +157,7 @@ In model mapping mode, Claude Desktop only sees the three role routes: `claude-s
| Requested model | Real upstream model ID sent to the provider |
| 1M | Declares 1M context support to Claude Desktop |
![Claude Desktop model mapping](../../assets/claude-desktop-model-mapping-rows-en.png)
<!-- TODO(v4 screenshot): The model mapping rows on the edit page (model role, menu display name, requested model, 1M) -->
### Recommended Setup
@@ -185,37 +185,35 @@ You can configure Sonnet, Opus, and Haiku at the same time:
| Opus | Higher quality or complex tasks |
| Haiku | Fast, lower-cost model |
If the provider only has one model, filling in just one role's requested model is enough; blank roles automatically inherit the first filled model (Sonnet first), so the Haiku that sub-agents call is always available. Model mapping mode requires at least one requested model.
If the provider only has one model, filling in just one role's requested model is enough; blank roles automatically inherit the first filled model (Sonnet first), so the Haiku that sub-agents call is always available. Model mapping requires at least one requested model.
## Local Routing Toggle
## Routing Service
Model mapping mode needs CC Switch local routing to convert requests. The Claude Desktop local routing toggle is always shown in the top-right corner of the Claude Desktop panel, regardless of the "Show Routing Toggle on Main Page" setting (that setting only controls the toggle on the Claude Code, Codex, Gemini CLI, and Grok Build pages).
Model mapping needs CC Switch's routing service to forward requests; the service listens on `127.0.0.1:15721` by default. **No manual switch is needed**: when the current provider uses model mapping, the routing service starts automatically and keeps running; when the current provider is direct, the top of the page shows "Routing service: not needed by the current provider".
![Claude Desktop local routing toggle](../../assets/claude-desktop-route-toggle-context-en.png)
<!-- TODO(v4 screenshot): The connection bar showing "Routing service Running" while a model mapping provider is in use -->
Status reference:
Status on the connection bar:
| Status | Description |
|--------|-------------|
| On | Local gateway is running, usually at `127.0.0.1:15721` |
| Off | Direct providers still work; model mapping providers cannot work normally |
| Loading | Routing service is starting or stopping |
| Routing service Running | The local gateway is running |
| The routing service couldn't start | Click "Retry"; if the port is taken, click "Change port", which jumps to "Settings → Local routing" to change it |
| Routing service: not needed by the current provider | The current provider is direct, or in official mode |
Only providers with **Needs model mapping** depend on local routing. Direct providers do not need this toggle.
If another app is using local routing, stopping local routing may be blocked. First turn off routing for that app in "Settings → Routing → Local Routing", then stop local routing.
If other apps are using Routing or Aggregation, the routing service cannot be stopped. First go to "Settings → Local routing" and use "Switch all back to direct" to return those apps to Direct, then stop the service.
## Restore Official Claude Desktop
To return to Claude Desktop official sign-in:
1. Select **Claude Desktop Official**
2. Click **Enable**
2. Click "Switch"
3. Restart Claude Desktop
CC Switch restores Claude Desktop's official 1P mode and removes the 3P profile managed by CC Switch.
Official mode does not need an API key or local routing.
Official mode does not need an API key or the routing service.
When importing from Claude Code, CC Switch automatically adds **Claude Desktop Official**.
@@ -258,7 +256,7 @@ These files are maintained automatically by CC Switch. Manual edits are not reco
## Status Messages
The Claude Desktop panel may show "Claude Desktop configuration needs attention".
The top of the Claude Desktop page may show "Claude Desktop configuration needs attention".
| Message | How to handle |
|---------|---------------|
@@ -279,14 +277,14 @@ Fully quit and restart Claude Desktop. Claude Desktop usually reads the 3P profi
Check:
- CC Switch is still running
- Claude Desktop local routing is enabled
- The routing service on the connection bar shows "Running"
- Provider API key and endpoint URL are correct
- Requested model is filled in the model mapping
- Claude Desktop was restarted after switching providers
### Why does my branded model name not appear in the Claude Desktop model menu?
Edit the provider, fill in **Menu display name** in model mapping, then enable the provider again and restart Claude Desktop.
Edit the provider, fill in **Menu display name** in model mapping, then switch to the provider again and restart Claude Desktop.
### Why does direct mode fail?
@@ -296,12 +294,12 @@ Direct mode requires the provider to expose native Anthropic Messages API and ac
It depends on the mode:
- Direct mode: after Claude Desktop restarts and loads the profile, local routing does not need to keep running
- Model mapping mode: CC Switch must keep running, and Claude Desktop local routing must stay on
- Direct: after Claude Desktop restarts and loads the profile, you can quit CC Switch
- Model mapping: CC Switch must keep running, and the routing service must stay running (managed automatically)
### Are real upstream model names written into Claude Desktop?
Not in model mapping mode. The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway.
Not with model mapping. The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway.
## Next Steps
+58 -40
View File
@@ -11,48 +11,62 @@ MCP (Model Context Protocol) is a protocol that allows AI tools to access extern
## Open the MCP Panel
Click the **MCP** icon button in the top navigation bar (its hover tooltip reads "MCP Management"; it is visible on the Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, Hermes, and MiniMax Code pages).
Click **MCP** in the left sidebar. It is a global page that does not belong to any one app: whichever app is currently selected, you open the same panel (Claude Desktop has no MCP of its own, so it has no column here either).
## Panel Overview
![image-20260108005723522](../../assets/image-20260108005723522.png)
<!-- TODO(v4 screenshot): Full MCP page: one MCP per row, per-app switches in columns on the right, and a page header with "Import from apps", "Add MCP" and the ⋯ menu -->
The page is a matrix table: **one row per MCP server, one column per app**. The switch in each cell means "this MCP is enabled in this app".
- Page header: "Import from apps", "Add MCP", and a ⋯ menu ("Rewrite every app's config from these switches", "Copy all as mcpServers JSON")
- Search box: filters by name, command, or URL
- Only the columns for apps set to show on the sidebar's "Apps" page are displayed; hiding only affects the UI, and configuration already written to a hidden app is kept and still synced
- Each row has an "Edit" button on the right and a ⋯ menu (Copy as JSON, Open docs, Enable in all apps, Turn off everywhere, Delete)
- If writing to an app fails, the row marks the failed app and you can click "Retry"
## Add MCP Server
### Using Preset Templates
### Using a Template
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"
1. Click **Add MCP** in the page header; a drawer opens on the right
2. Under "Start from a template", pick a template, or leave it empty and fill things in yourself
3. Adjust as needed, and tick the apps to enable under "Write to"
4. Click Add
![image-20260108005739731](../../assets/image-20260108005739731.png)
<!-- TODO(v4 screenshot): Add MCP drawer: templates, paste a config, connection, write to -->
### Common Presets
### Paste a Config
| Preset | Package Name | Description |
|--------|-------------|-------------|
"Paste a config" in the drawer accepts a block of JSON or TOML directly. It recognizes `mcpServers`, Codex's `[mcp_servers.name]`, and OpenCode's local / remote format, and fills in the form below. If you paste several servers at once, the entries are listed as "New" or "Name already exists", and for same-name entries you can choose Skip or Replace.
### Common Templates
| Template | Package Name | Description |
|----------|-------------|-------------|
| fetch | mcp-server-fetch | HTTP request tool that enables AI to fetch web content |
| time | mcp-server-time | Time tool that provides current time information |
| time | mcp-server-time (run via `uvx`) | 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:
If you don't pick a template and fill things in yourself, you need:
| 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 |
| Name | Yes | The key written into each app's config file; no spaces allowed. It can't be changed after saving; to rename, create a new one and delete the old one |
| Transport | Yes | Local command (stdio) / HTTP / SSE |
| Command | Yes* | Required for local command type; enter only the program (such as `npx` or `uvx`), and put arguments in their own field |
| Arguments | No | Command-line arguments, one per line |
| Environment variables | No | Environment variables passed to the server |
| Working directory | No | Optional for local command type; if left empty, the app decides |
| URL | Yes* | Required for HTTP / SSE type; must start with `http://` or `https://` |
| Headers | No | Request headers for HTTP / SSE type |
| Display name, Description, Tags, Homepage, Docs | No | Grouped under "Description & links"; shown only in CC Switch and not written to app configs |
You can also click "Edit in JSON" to edit the whole configuration directly. It is the same data as the form and stays in sync when you switch; the values of environment variables and headers appear as `••••••••` in JSON, and the original values are kept when you save.
## Transport Types
@@ -84,7 +98,7 @@ Communicates with a remote server via HTTP protocol.
### sse (Server-Sent Events)
Communicates with a server via SSE protocol, supporting real-time push.
Communicates with a server via SSE protocol, supporting real-time push. Pi does not support the SSE type.
```json
{
@@ -94,23 +108,24 @@ Communicates with a server via SSE protocol, supporting real-time push.
## App Binding
Each MCP server can independently control which apps it is enabled for.
Each MCP server can independently control which apps it is enabled for: click the switch in that row and app column of the matrix.
### Toggle Description
### App Columns
| Toggle | Effect | Configuration File Path |
| App | Effect | Configuration File Path |
|--------|--------|------------------------|
| Claude | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
| Claude Code | 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` |
| Gemini CLI | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
| Grok Build | Sync to Grok Build | `~/.grok/config.toml`'s `[mcp_servers]` |
| OpenCode | Sync to OpenCode | `~/.config/opencode/opencode.json`'s `mcp` |
| Hermes | Sync to Hermes | `~/.hermes/config.yaml`'s `mcp_servers` |
| Pi | Sync to Pi (requires Pi 1.0 or later) | `~/.pi/agent/mcp.json` |
| MiniMax Code | Sync to MiniMax Code | `~/.minimax/mcp.json` |
> ⚠️ **Note**: OpenClaw, Pi, and Claude Desktop do not currently support CC Switch MCP sync. The MCP panel is a single unified panel shared by all apps; opening it from the Claude Desktop page shows the same panel, which has no Claude Desktop toggle. MCP functionality is supported for Claude, Codex, Gemini, Grok Build, OpenCode, Hermes, and MiniMax Code.
> ⚠️ **Note**: Claude Desktop and OpenClaw do not support CC Switch MCP sync, so the table has no columns for them. MCP is supported for the 8 apps above.
The MCP panel can enable or disable all servers for an app in one click.
Click a column header for bulk actions on that column: "Enable the other N", "Enable all", and "Turn all off". They apply only to the entries in the current list (or only to the results after a search or filter), and you can click "Undo" afterwards. Each row's ⋯ menu also has "Enable in all apps" and "Turn off everywhere".
### Toggle Implementation
@@ -126,18 +141,19 @@ When disabling an app's toggle, CC Switch will:
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
> 💡 CC Switch only manages servers that exist in its database; servers you added by hand in a tool's configuration and never imported into CC Switch are left untouched. **MiniMax Code is the exception**: during a bulk sync, servers that are not enabled for MiniMax Code are not deleted from `mcp.json`; they are removed only when you explicitly turn them off or delete them in CC Switch.
> 💡 CC Switch only manages servers that exist in its database; servers you added by hand in a tool's configuration and never imported into CC Switch are left untouched; however, if you edit an entry with the same name as one in CC Switch directly in an app's configuration, it is overwritten and CC Switch's version wins. **MiniMax Code and Pi are the exceptions**: during a bulk sync, servers that are not enabled for them are not deleted from `mcp.json`; they are removed only when you explicitly turn them off or delete them in CC Switch.
### Sync Conditions
MCP server sync only executes when the corresponding app is installed:
- **Claude**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Claude Code**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Codex**: Requires `~/.codex/` directory to exist
- **Gemini**: Requires `~/.gemini/` directory to exist
- **Gemini CLI**: Requires `~/.gemini/` directory to exist
- **Grok Build**: Requires `~/.grok/` directory to exist
- **OpenCode**: Requires `~/.config/opencode/` directory to exist
- **Hermes**: Requires `~/.hermes/` directory to exist
- **Pi**: Writes to `~/.pi/agent/mcp.json` (the Pi configuration directory can be set with `PI_CODING_AGENT_DIR`)
> 💡 **Tip**: If a CLI tool is not installed, enabling its toggle will not cause an error, but the configuration will not be written. MiniMax Code is the exception: CC Switch does not check whether it is installed and writes `~/.minimax/mcp.json` directly, creating the directory if it does not exist.
@@ -146,27 +162,29 @@ 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
2. Modify the configuration in the drawer (the name can't be changed)
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
1. Click "Delete" in the ⋯ menu on the right side of the server row
2. Confirm deletion
After deletion, the configuration is removed from all app configuration files.
Deletion cannot be undone. The configuration is removed from CC Switch and from the configuration files of every app it was enabled for.
## Import Existing Configurations
If you have already configured MCP servers in CLI tools, you can import them into CC Switch:
1. Click the "Import Existing" button at the top of the MCP page
2. CC Switch reads the existing configuration of every MCP-capable app (Claude / Codex / Gemini / Grok Build / OpenCode / Hermes / MiniMax Code) in one pass and imports it
3. When finished, it shows how many servers were imported; if no new servers are found, it tells you so
1. Click the "Import from apps" button at the top of the MCP page
2. CC Switch reads the existing configuration of every MCP-capable app (Claude Code / Codex / Gemini CLI / Grok Build / OpenCode / Hermes / Pi / MiniMax Code) in one pass and imports it
3. When finished, an "Import finished" dialog lists which MCP servers were added and which files were read; if no new servers are found, it tells you no new MCP servers were found
Imported servers are automatically enabled for the app they came from. When importing from MiniMax Code, the enabled status follows the `enabled` field in `mcp.json`; entries that conflict with an existing server's configuration or are invalid are not imported, in which case a message appears saying N servers were imported but import failed for some apps, along with the reasons.
Import reads only user-level configuration: MCP servers that `claude mcp add` adds to a project by default in Claude Code, and MCP servers bundled with plugins, are not imported.
Imported servers are automatically enabled for the app they came from; for servers with the same name as an existing one, only the switch for the corresponding app is turned on, and the configuration stays as it is in CC Switch. When importing from MiniMax Code, the enabled status follows the `enabled` field in `mcp.json`; entries that conflict with an existing server's configuration or are invalid are not imported, in which case a message "Some apps couldn't be read" appears along with the reasons.
## Configuration File Formats
+39 -67
View File
@@ -12,30 +12,28 @@ With CC Switch, you can:
## Open the Prompts Panel
Click the **Prompts** icon button in the top navigation bar (visible on the Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, Pi, and MiniMax Code pages; on the Claude Desktop page it works on Claude Code's prompts).
Click **Prompts** in the left sidebar. It is a global page, and the dropdown on the left of the page header selects the app: Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, Hermes, Pi, MiniMax Code (only apps set to show on the "Apps" page are listed).
Hermes and OpenClaw have no Prompts panel: Hermes uses "Memory" to edit MEMORY.md and USER.md, and OpenClaw uses the [workspace editor](./3.5-workspace.md).
- Claude Desktop has no prompts of its own; entering from its page works on Claude Code's prompts.
- OpenClaw is not on the Prompts page; its AGENTS.md and other files are managed with the [workspace editor](./3.5-workspace.md).
- For Hermes, this page manages the persona file `SOUL.md`; `MEMORY.md` and `USER.md` are edited on the "Memory" page of the Hermes page.
## Panel Overview
![image-20260108010110382](../../assets/image-20260108010110382.png)
<!-- TODO(v4 screenshot): Prompts page: app dropdown in the header, target file path, prompt list (the enabled one carries an "Enabled" badge) -->
The top of the page shows the current app's **Target file** (path and size), and below it is the prompt list. Each row has an Enable / Disable button, an "Edit" button, and a ⋯ menu (Copy to other apps, Copy text, Delete). When the list is not empty there is a search box that searches by name, description, or text.
## 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"
1. Click **Add Prompt** in the page header; a drawer opens on the right
2. Enter a name, and optionally a description (shown only in CC Switch)
3. Write the prompt in Markdown in the text box
4. Click "Add"
### Markdown Editor
The editor provides:
- Syntax highlighting
- Live preview
- Common format shortcuts
Content that is already in the file but not yet in CC Switch can be saved as an entry with "Import current xxx" in the page header's ⋯ menu; the file is not modified.
### Prompt Writing Tips
@@ -64,27 +62,28 @@ You are a professional code review expert.
- Maintain consistent code style
```
## Activate a Preset
## Enable a Preset
### How to Activate
### How to Enable
Click the toggle switch on the preset item to change its activation status.
Click the "Enable" button on the preset row; the enabled row shows "Enabled" and the button becomes "Disable".
### Single Activation
### One Enabled at a Time
Only one preset can be active at a time. Activating a new preset automatically deactivates the previous one.
Each app can have only one enabled prompt at a time. Enabling a new one automatically disables the previous one. Once enabled, its text overwrites the target file; after it is disabled, the file is emptied (Pi's `AGENTS.md` is deleted).
### Sync Target
After activation, the prompt is written to the corresponding app's file:
After enabling, the prompt is written to the corresponding app's file:
| Application | File Path |
|-------------|-----------|
| Claude | `~/.claude/CLAUDE.md` |
| Claude Code | `~/.claude/CLAUDE.md` |
| Codex | `~/.codex/AGENTS.md` |
| Gemini | `~/.gemini/GEMINI.md` |
| Gemini CLI | `~/.gemini/GEMINI.md` |
| Grok Build | `~/.grok/AGENTS.md` |
| OpenCode | `~/.config/opencode/AGENTS.md` |
| Hermes | `~/.hermes/SOUL.md` (Hermes's persona; takes effect in newly started sessions) |
| Pi | `~/.pi/agent/AGENTS.md` |
| MiniMax Code | `~/.minimax/AGENTS.md` (content must not exceed 32 KiB) |
@@ -92,73 +91,46 @@ If you override a configuration directory in Settings, the file path changes acc
### Extra Content for Pi
Pi's Prompts panel has three tabs:
Pi's Prompts page has three tabs:
| Tab | Description |
|-----|-------------|
| Global prompts | An AGENTS.md prompt library; pick one to write to Pi's global `AGENTS.md` |
| Global system prompt | Edit `APPEND_SYSTEM.md` (appended after Pi's built-in base prompt; recommended) or `SYSTEM.md` (replaces Pi's built-in base prompt) |
| Prompt templates | Manage Pi's prompt templates |
| Library | An AGENTS.md prompt library; only one can be enabled at a time, and it is written to Pi's global `AGENTS.md` |
| System prompt | Edit `APPEND_SYSTEM.md` (appended after Pi's built-in base prompt; recommended) or `SYSTEM.md` (replaces Pi's built-in base prompt); it takes effect whenever the file exists, no enabling needed |
| Templates | Manage Pi's prompt templates; after saving, type `/command-name` in Pi to invoke one, no enabling needed |
A Pi that is already open does not hot-reload automatically; run `/reload` when it is idle. A newly started Pi reads the files automatically.
## Edit a Preset
1. Click the "Edit" button on the preset item
2. Modify the name or content
1. Click the "Edit" button on the preset row (or click the row)
2. Modify the name, description, or text in the drawer
3. Click "Save"
If the currently active preset is edited, changes are immediately synced to the configuration file.
If the edited preset is the enabled one, the target file is overwritten immediately after saving.
## Delete a Preset
1. Click the "Delete" button on the preset item
1. Click "Delete" in the preset row's ⋯ menu
2. Confirm deletion
Active presets cannot be deleted. Deactivate the preset first before deleting.
An enabled preset cannot be deleted; disable it first. Deleting only affects that entry in CC Switch; the target file is not modified.
## Smart Backfill
## What Happens When You Edit the File by Hand
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
You can edit the target file directly in a CLI or an external editor, and CC Switch will not let those changes be lost:
| 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
| The file for the enabled entry was edited elsewhere | The next time you open this page, the changes are pulled into the enabled entry |
| The file contains content CC Switch doesn't have | Before another prompt is enabled, that content is saved as an "Original prompt" entry, then overwritten |
| The file already has content but the list is still empty | Use "Import current xxx" in the page header's ⋯ menu, or "Import existing content" on the empty-list page, to save it as an entry |
## Cross-app Usage
Prompts are managed separately per app:
Prompts are managed separately per app: switch the app in the header dropdown and the list changes to that app's presets.
- 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
- The same applies to the other apps
To use the same prompt across multiple apps, you need to create them separately.
To use the same prompt in several apps, you don't need to retype it: click "Copy to other apps" in the preset row's ⋯ menu and tick the target apps. Each gets its own independent copy that is not enabled automatically, and later edits do not affect each other (Hermes's SOUL.md is a persona, so it is unticked by default).
## Import & Export
+81 -124
View File
@@ -14,7 +14,7 @@ Skills exist as folders containing:
Skills are supported in the following applications:
- **Claude Code** (the Skills panel on the Claude Desktop page also works on Claude Code)
- **Claude Code** (the Skills page on the Claude Desktop page also works on Claude Code)
- **Codex**
- **Gemini CLI**
- **Grok Build**
@@ -27,83 +27,69 @@ OpenClaw does not support Skills management yet.
## Open the Skills Page
Click the **Skills** button in the top navigation bar when the selected app supports Skills.
Click **Skills** in the left sidebar. It is a global page that does not belong to any one app: whichever app is currently selected, you open the same page (Claude Desktop has no Skills of its own, so it has no column here either).
The top of the page has two views you can switch between: **Installed** and **Discover**.
## Page Overview
![image-20260108010253926](../../assets/image-20260108010253926.png)
<!-- TODO(v4 screenshot): Skills "Installed" view: one Skill per row, per-app switches in columns on the right, and a page header with the "Add Skill" button and the ⋯ menu -->
"Installed" is a matrix table: **one row per Skill, one column per app**. The switch in each cell means "this Skill is enabled in this app".
- Page header: the "Add Skill" button, and a ⋯ menu (Check Updates, Restore from backup, Manage repositories, Storage and sync)
- Search box: searches by name, directory, description, or repository
- Filters: All / Has updates / Not enabled anywhere / Enabled in a given app, and you can also filter by source repository
- Only the columns for apps set to show on the sidebar's "Apps" page are displayed; hiding only affects the UI, and Skills already enabled are kept
- After selecting several rows you can bulk "Enable in" an app, Disable, Update, or Uninstall them
- Click a column header to bulk-enable or turn off a whole column; it applies only to the entries in the current list
- Pi has no separate switch data; whether a Skill is enabled is determined by whether that directory exists in `~/.pi/agent/skills`
## Discover Skills
Switch to the "Discover" view to browse and search for installable Skills.
### Pre-configured Repositories
CC Switch comes pre-configured with the following GitHub repositories:
CC Switch comes pre-configured with several GitHub skill repositories, including Anthropic Official (`anthropics/skills`) and ComposioHQ (`ComposioHQ/awesome-claude-skills`). The "Repos" button in Discover lets you choose which repositories take part in discovery, and "Reload repositories" re-scans them to get the latest skills.
| Repository | Description |
|------------|-------------|
| Anthropic Official | Official skills provided by Anthropic |
| ComposioHQ | Community-maintained skill collection |
| Community Picks | Curated high-quality skills |
### Search
![image-20260108010308060](../../assets/image-20260108010308060.png)
- "Repos" source: search by Skill name or repository name, filtering as you type; you can switch between "Show all" and "Not installed only"
- "skills.sh" source: search the [skills.sh](https://skills.sh) public registry; enter at least 2 characters and press Enter to search, and results can be extended with "Load More"
### 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 |
![image-20260108010324583](../../assets/image-20260108010324583.png)
#### 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.
<!-- TODO(v4 screenshot): Skills "Discover" view: source switch (Repos / skills.sh), search box, "Install to" selector, and the installable list -->
## Install Skills
### Steps
1. Find the skill card you want to install
2. Click the "Install" button
3. Wait for installation to complete
1. Find the Skill you want to install in the "Discover" view
2. First choose under "Install to" which apps to enable it in (your last choice is remembered and used by default)
3. Click "Install" on that row and wait for it to finish
Once installed, it is enabled in the chosen apps right away, and you can adjust that at any time under "Installed". Besides installing from a repository, the page header's "Add Skill" menu offers:
- **Browse in Discover**: switch to the "Discover" view
- **Install from ZIP**: pick a ZIP containing `SKILL.md`; Skills whose directory name is already taken are skipped, and to use the version in the ZIP, uninstall the one with the same name first and then install
- **Import from this computer**: import Skills that already exist in the apps' directories on this computer but are not yet managed by CC Switch. Importing copies them into CC Switch's directory and leaves the originals untouched
When the page shows a notice such as "N Skills on this computer aren't managed by CC Switch", you can click "Review and import".
### Installation Location
| Application | Install Directory |
|-------------|-------------------|
| Claude | `~/.claude/skills/` |
| Claude Code | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| Gemini | `~/.gemini/skills/` |
| Gemini CLI | `~/.gemini/skills/` |
| Grok Build | `~/.grok/skills/` |
| OpenCode | `~/.config/opencode/skills/` |
| Hermes | `~/.hermes/skills/` |
| Pi | `~/.pi/agent/skills/` |
| MiniMax Code | `~/.minimax/skills/` |
If you override a configuration directory in Settings, the install directory changes accordingly (MiniMax Code's data directory can be set with the `MINIMAX_DATA_DIR` environment variable, and Pi additionally recognizes `PI_CODING_AGENT_DIR`). The master copy of each skill lives in the directory chosen under "Skill Storage Location" (default `~/.cc-switch/skills/`; see [Storage Location Switch](#storage-location-switch) below) and is synced to each app's directory by symlink or file copy.
If you override a configuration directory in Settings, the install directory changes accordingly (MiniMax Code's data directory can be set with the `MINIMAX_DATA_DIR` environment variable, and Pi additionally recognizes `PI_CODING_AGENT_DIR`). The master copy of each skill lives in the directory chosen under "Storage and sync" (default `~/.cc-switch/skills/`; see [Storage and Sync](#storage-and-sync) below) and is synced to each app's directory by symlink or file copy.
### Installation Contents
@@ -122,9 +108,8 @@ Installation copies the skill folder to your local machine:
### Steps
1. Find the installed skill card
2. Click the "Uninstall" button
3. Confirm uninstallation
1. Under "Installed", find the Skill and click "Uninstall" in that row's ⋯ menu (you can also select several and uninstall them in bulk)
2. Confirm uninstallation
### Uninstall Effect
@@ -138,9 +123,9 @@ Installation copies the skill folder to your local machine:
If you need to restore a previously uninstalled skill:
1. Open the Skills page
2. Click the **Restore from Backup** button
3. Select the backup you want to restore from the list (shows skill name and backup date)
4. The skill is restored and enabled for the current app
2. Click **Restore from backup** in the page header's ⋯ menu
3. Select the backup you want to restore from the list (shows skill name and backup date) and click "Restore"
4. The skill is restored and enabled in the apps chosen under "Install to" in Discover
### Delete Backups
@@ -154,105 +139,77 @@ To remove old skill backups:
### Open Repository Management
Click the "Repository Management" button at the top of the page.
Click "Manage repositories" in the page header's ⋯ menu (the "Repos" button in the Discover view also has an "Add or manage repositories" entry).
### 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"
1. In "Repository URL", enter `owner/name` or the full `https://github.com/owner/name`
2. Fill in the branch (default main)
3. The skills path is optional: the subdirectory containing skills; leave it empty to scan the root directory
4. Click "Add Repository"
### Repository Format
```
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
```
Example:
```
Owner: anthropics
Name: claude-skills
Branch: main
Subdirectory: skills
```
After it is added successfully, a message tells you how many skills were detected.
### Delete Repository
1. Find the repository in the repository list
2. Click the "Delete" button
3. Confirm deletion
In the "Added Repositories" list, click the delete button on the right of the repository.
After deleting a repository, its skills will not disappear from the list, but they can no longer be updated.
After deleting a repository, skills already installed will not disappear, but they can no longer be updated from that repository.
## Skill Card Information
## Skill Row Information
Each skill card displays:
Each row under "Installed" displays:
| Information | Description |
|-------------|-------------|
| Name | Skill name |
| Description | Function description |
| Source | Source repository |
| Status | Installed / Not Installed |
| Name, description | Skill name and function description |
| Source | The repository it belongs to; locally imported ones show "Local" |
| Per-app switches | Which apps it is enabled in; apps where writing failed are marked, and you can click "Change sync method" to adjust |
| New version | Shows "Update" when the remote has an update |
## Skill Updates
Starting from v3.13.0, Skills support **automatic update detection** and **batch updates** — no more uninstall-and-reinstall.
Skills support **update detection** and **batch updates** — no need to uninstall and reinstall.
### Update Detection Mechanism
CC Switch compares installed skills with the remote repository version using **SHA-256 content hashes**. Whenever the remote has any content changes, the corresponding local skill card automatically shows an "Update available" indicator.
CC Switch compares installed skills with the remote repository version using **SHA-256 content hashes**. Whenever the remote has any file content changes, the corresponding skill is marked as updatable.
### Single Update
### Check for Updates
For a skill with an available update:
Click "Check Updates" in the page header's ⋯ menu, or "Check Updates" next to the search box under "Installed", to re-scan the remote repositories. The page shows the "Last checked" time; if some repositories couldn't be read, a notice appears and the update results may be incomplete.
1. Find the skill card with the update indicator in the Skills panel
2. Click the **Update** button on the card
3. Wait for the download to finish — status refreshes automatically
### Single Update and Update All
### Update All
- For a Skill with a new version, click "Update" on that row
- When Skills have updates, the page header shows "N updates"; click it to show only those with updates. "Update all (N)" in the filter bar updates them in bulk, with a confirmation before updating
When multiple skills need updating:
> ⚠️ Updating replaces the local directory with the repository's content; local changes are kept only in the backup.
1. Click the **Update All** button at the top of the Skills panel (appears with a slide-in animation)
2. CC Switch batch-downloads all skills with pending updates
3. The panel refreshes automatically when done, and the update indicators disappear
## Storage and Sync
> 💡 **Tip**: Regularly click the **Refresh** button to trigger a remote scan so update detection stays current.
Click "Storage and sync" in the page header's ⋯ menu to set two things:
## Storage Location Switch
### Where Master Copies Are Kept
Starting from v3.13.0, the **source storage location** for skills can be switched between two locations:
| Location | Description |
|----------|-------------|
| **CC Switch folder** | Default location `~/.cc-switch/skills/`, managed by CC Switch |
| **Shared folder** (`~/.agents/skills`) | A shared directory conforming to community agent tool conventions, better for cross-tool collaboration |
| Location | Description |
| ------------------------ | --------------------------------------------------------------------- |
| **CC Switch built-in** | Default location `~/.cc-switch/skills/`, managed by CC Switch |
| **`~/.agents/skills`** | A shared directory conforming to community agent tool conventions, better for cross-tool collaboration |
When switching, click "Move and switch"; CC Switch moves the master copies one by one and then points the links in each app to the new location, so no skill state is lost. Do not quit CC Switch until the move finishes.
### How to Switch
> ⚠️ After choosing the "Shared folder", Codex, Gemini CLI, OpenCode and others read this folder directly, so the per-app switches no longer fully apply to them.
Select the target storage location in "Settings → General → Skill Storage Location". The switch **does not lose skill state** — CC Switch smoothly migrates existing skills to the new location.
### How Skills Reach Each App
> ⚠️ **Distinction**: The "Storage Location Switch" here manages the **source storage** of skills. In contrast, [1.5 Personalization → Skill Sync Method](../1-getting-started/1.5-settings.md) controls how skills are **distributed to each app's directory** (symlink vs. copy). The two settings work together.
| Method | Description |
|--------|-------------|
| Automatic (recommended) | Symlink first, copy if that fails |
| Symlink only | Requires Developer Mode on Windows |
| Copy only | Uses more disk space; copied again after each update |
## Public Registry Search (skills.sh)
v3.13.0 integrates **skills.sh** public registry search so you can discover community skills directly inside CC Switch.
### How to Use
1. Click the **Repository Management** button to open the dialog
2. Use the **skills.sh Search** input inside the dialog
3. Type keywords to filter results in real time
4. Click a target skill to quickly add it to your repository list
v3.13.0 also fixes broken link and empty description handling for skills.sh, so community skill metadata is displayed more reliably.
Changes only apply to Skills you enable or update afterwards; to make already-enabled Skills use the current method too, click "Resync now".
## Troubleshooting
@@ -266,7 +223,7 @@ Possible causes:
Solutions:
- Check network connection
- Click "Refresh" to retry
- Click "Reload repositories" to retry
- Verify repository configuration
### Installation Failed
@@ -292,5 +249,5 @@ Possible causes:
Solutions:
- Click **Refresh** to rescan
- Click "Check Updates" to rescan
- Confirm the repository configuration points to the right branch and path
@@ -20,77 +20,78 @@ If you override a configuration directory in Settings, the session directory cha
## Opening the Session Manager
Click the **Session Manager** icon button in the top navigation bar. It opens showing the current app's sessions by default; use the filter menu to switch to another app or to "All".
Click **Sessions** in the left sidebar. It is a global page: it opens showing the current app's sessions by default, and you can use the app dropdown at the top left of the page to switch to another app or to "All apps" (each item shows that app's session count).
> **Note**: The Claude Desktop entry reuses the Claude Code session view. The Hermes page has no sessions button; to view Hermes sessions, choose "All" in the filter menu.
> **Note**: Claude Desktop has no separate session records; entering from its page shows Claude Code's sessions. Hermes sessions are also chosen from the dropdown, and the page notes "Hermes shows only the latest 500 sessions".
![Session Manager](../../../../assets/release-notes/v4.0.0/session-en.png)
## Interface Layout
The Session Manager uses a **two-column layout**:
The Session Manager has two levels:
- **Left panel**: Session list with search and filter toolbar
- **Right panel**: Selected session details with conversation history
- **Session list**: At the top are the app dropdown, the search box, and the "By time / By project" grouping switch, with the session list below
- **Session details**: Click any row to enter; the whole page shows this session's conversation, and "Back to sessions" returns to the list. You can also use "Previous / Next" to move between sessions
### Session List (Left Panel)
The ⋯ menu on the right of the page header contains: Refresh list, Select multiple…, Preferred terminal… (jumps to Settings), and Where sessions are stored… (lists each app's session storage location).
### Session List
Each session entry displays:
- Provider icon
- App icon
- Session title
- Last active time (relative format, e.g., "5 min ago")
- Last active time and creation time
- A summary of the last message
- "Resume" and "Copy resume command" buttons on the right, and a ⋯ menu
### Session Details (Right Panel)
### Session Details
When a session is selected, the right panel shows:
- **Title**: Derived from session title, project directory name, or session ID
- **Last active date/time**: Full timestamp
- **Project directory**: Clickable to copy full path (shows basename with tooltip for full path)
- **Resume command**: Displayed in monospace style when available
- **Conversation history**: Full message transcript
Inside a session you can see:
- **Title and project directory**: The directory is clickable to copy the full path
- The **Resume** button and more ways to resume (such as copying the "enter directory and resume" command)
- **Conversation**: Shown in turns of question and reply; what the AI did (commands, file reads and writes, changes) is collected into one expandable "Steps" entry
- **View switch**: All / Chat / Changes, to see only the conversation or only file changes
- **Conversation outline**: Quickly jump to a particular question
- **Find**: Search within the current session
- **Copy / Export**: Copy the whole session as Markdown, or export it as a Markdown file
## Search & Filtering
### Full-Text Search
Use the search box at the top of the left panel to search across:
- Session ID
Use the search box at the top of the page to search across:
- Title
- Summary
- Project directory
- Source file path
- First and last messages
- Session ID
The search supports prefix matching and filters results in real-time. Press **Esc** to clear the search.
The search filters results in real-time. Press **Esc** to clear the search.
### Provider Filtering
### Filter by App
Click the provider filter dropdown (top-right of left panel) to filter by application:
- **All** — Show sessions from all apps (including Hermes)
- **Codex**
- **Grok Build**
- **Claude Code**
- **OpenCode**
- **OpenClaw**
- **Gemini CLI**
- **MiniMax Code**
- **Pi**
Click the app dropdown at the top left and choose:
- **All apps** — Show sessions from all apps (including Hermes)
- Claude Code, Codex, OpenCode, Hermes, Gemini CLI, Pi, Grok Build, OpenClaw, MiniMax Code
The session list can also switch between two views, "List" and "Grouped": the "Grouped" view groups sessions by app and project directory.
The session list can also switch between two groupings, "By time" (Today / Yesterday / This week / Earlier) and "By project", using the segmented control on the right.
The filter can be combined with search.
### Refresh
Click the refresh button (circular arrow icon) to re-scan all provider directories for new or deleted sessions.
Click "Refresh list" in the page header's ⋯ menu to re-scan each app's directory for new or deleted sessions.
## Session Actions
### Resume Session
Click the **Resume** button (play icon) on a selected session to continue the conversation.
Click the **Resume** button on the session row (or in the session details) to continue the conversation.
**On macOS:**
- CC Switch launches your preferred terminal with the resume command
- The terminal opens in the session's project directory
- If terminal launch fails, the command is copied to your clipboard instead
- You can change the preferred terminal under "Preferred terminal…" in the page header's ⋯ menu
**Supported terminals (macOS):** Terminal.app, iTerm2, Ghostty, Otty, Kitty, WezTerm, Kaku, Alacritty, Warp
@@ -98,24 +99,24 @@ Click the **Resume** button (play icon) on a selected session to continue the co
- The resume command is copied to your clipboard
- Paste it into your terminal to resume
> The Resume button is disabled if the session has no resume command available. Resuming OpenClaw and Hermes sessions is not supported yet.
> The Resume button is disabled if the session has no resume command available. OpenClaw sessions are managed by the gateway and Hermes sessions don't support command-line resume yet, so neither can be resumed here. Codex stores history separately per provider, so after you switch providers, old sessions may not be able to continue.
When resuming, the terminal opens in the session's original project directory. To open a terminal with a particular Claude provider in a different directory, use the "Open Terminal" button on the Claude provider card, which asks you to choose a working directory first.
### Delete Session
Click the **Delete** button (trash icon) to permanently remove a session file. A confirmation dialog is shown before deletion.
Click "Delete" in the session row's ⋯ menu to permanently remove the session file. It is deleted directly from disk, skipping the Trash, and cannot be undone; a confirmation dialog explaining exactly what will be deleted is shown first.
> Sessions without a local source path (e.g., immutable sessions) cannot be deleted.
> Sessions without a local source path cannot be deleted; delete MiniMax Code sessions in MiniMax Code.
### Batch Operations
For managing multiple sessions at once:
1. Click the **Batch Mode** button (checkbox icon) in the left panel toolbar
1. Click **Select multiple…** in the page header's ⋯ menu
2. Select sessions using the checkboxes that appear
3. Use **Select All** to select all filtered results, or **Clear** to deselect
4. Click **Batch Delete** (red trash icon) to delete all selected sessions
3. Use **Select all matches** to select all filtered results, **Clear** to deselect, and **Done selecting** to leave batch mode
4. Click "Delete N sessions" to delete all selected sessions
A confirmation dialog shows the count before deletion. Results report the number of successful deletions and any failures.
@@ -123,22 +124,18 @@ A confirmation dialog shows the count before deletion. Results report the number
### Message Display
Messages are color-coded by role:
- **User** messages: Green, left-aligned
- **AI** (Assistant) messages: Blue, right-aligned
- **System** messages: Amber
- **Tool** messages: Purple
The conversation is shown in "question and reply" turns:
- Your questions and the AI's final replies are shown normally
- What the AI did (running commands, reading or modifying files, calling MCP, sub-agents, and so on) is collected into one "Steps · N" entry that you can expand to see each step's arguments, output, and file changes; failed steps are marked
- Thinking content is marked separately (some tools' thinking content is not visible)
- Longer content is collapsed by default and can be shown with "Expand full content"; for content over 2 MB, copy the source file path and view it locally
### Table of Contents
For longer conversations, a Table of Contents is available:
- **Desktop (XL+ screens)**: Sidebar on the right showing user message previews
- **Smaller screens**: Floating button (list icon) at bottom-right that opens a dialog
Click any entry to scroll to that message, which is briefly highlighted.
"Conversation outline" lists every question in the session (with step count and whether any failed or were interrupted); click any entry to jump to that position.
## Tips
- Sessions are sorted by last activity time (newest first)
- The session count badge updates as you search and filter
- The session counts in the app dropdown update as you search
- OpenCode sessions may come from both JSON files and SQLite database — duplicates are automatically deduplicated
@@ -4,7 +4,7 @@
The Workspace panel provides file management and daily memory features for **OpenClaw**. It allows you to edit workspace configuration files and maintain a daily memory journal.
> This feature is specific to OpenClaw. The Workspace button appears in the navigation bar when OpenClaw is the selected application.
> This feature is specific to OpenClaw and lives inside the OpenClaw app page: select OpenClaw in the sidebar, and below the page header there are three tabs, "Providers / Workspace / Config"; click "Workspace".
## Workspace Files
@@ -12,7 +12,7 @@ The Workspace panel provides file management and daily memory features for **Ope
All workspace files are stored in `~/.openclaw/workspace/`.
Click the directory path at the top of the panel to open it in your file manager.
Click the directory path at the top of the panel to open it in your file manager (the hover tooltip reads "Open in file manager").
### Available Files
@@ -50,7 +50,7 @@ The Daily Memory feature provides a date-organized journal system stored in `~/.
### Accessing Daily Memory
Click the **Daily Memory** card in the Workspace Files grid to open the memory panel.
Click the **Daily Memory Files** card ("Browse & manage daily memories") in the Workspace Files grid to open the memory panel.
### File List
@@ -61,7 +61,7 @@ The panel displays all daily memory files sorted by date (newest first). Each en
### Create Today's Note
Click the **Create Today** button to:
Click the **Add Memory** button to:
- Open a new note with today's date (`YYYY-MM-DD.md`)
- If today's note already exists, it opens for editing
- The file is persisted only after you click Save
@@ -70,10 +70,10 @@ Click the **Create Today** button to:
Search across all daily memory files:
1. Press **Cmd/Ctrl+F** or click the search icon
1. Press **⌘/Ctrl+F** or click the search icon
2. Enter your search term
3. Results show matching files with:
- Match count per file
- Match count per file ("N match(es)")
- Snippet preview from the matching line
- File date and size
+50 -82
View File
@@ -2,7 +2,7 @@
## Overview
Local routing starts an HTTP service on your machine. Once routing is enabled for an app, that app's API requests go to CC Switch first, and CC Switch forwards them to the current provider.
Local routing starts an HTTP service on your machine. Once an app enters Routing mode, that app's API requests go to CC Switch first, and CC Switch forwards them to the current provider.
**Primary uses**:
- Format conversion: lets Claude Code use providers with OpenAI or Gemini formats, and lets Codex and Grok Build use providers with Chat Completions or Anthropic Messages formats
@@ -16,46 +16,39 @@ Apps that support local routing: **Claude Code**, **Codex**, **Gemini CLI**, **G
## Start Local Routing
### Option 1: Settings Page
Local routing normally doesn't need to be started by hand:
1. Open "Settings → Routing → Local Routing"
2. Turn on "Routing Master Switch" to start the local service
3. Under "Routing Enabled", turn on the apps you want to route (Claude / Codex / Gemini / Grok Build)
- On an app's page (pick an app in the sidebar), switch to the "Routing" tab at the top and click "Start routing". After you confirm, that app is forwarded through local routing, and the service starts automatically if it isn't running. In both Routing and Aggregation modes, requests go through the local routing service first
- When Claude Desktop uses a "Model mapping" provider, the service also starts automatically and keeps running; see [2.6 Claude Desktop](../2-providers/2.6-claude-desktop.md)
![image-20260108011338922](../../assets/image-20260108011338922.png)
Clicking the "Direct / Routing / Aggregation" tabs at the top is only for viewing and doesn't change any configuration. To actually switch, use the button under the tabs that spells out the consequence ("Start routing", "Switch to Aggregation", "Back to direct").
### Option 2: Main Interface Toggle
<!-- TODO(v4 screenshot): Top of an app page with the Direct / Routing / Aggregation tabs, "Routing" selected but not active, showing the "Start routing" button -->
After you turn on "Show Routing Toggle on Main Page" in "Settings → Routing → Local Routing", a local routing toggle appears at the top of the Claude, Codex, Gemini and Grok Build pages (the Claude Desktop page has its own routing toggle; see [2.6 Claude Desktop](../2-providers/2.6-claude-desktop.md)).
You can also click "Start" manually in the "Service" area under "Settings → Local routing". If the service isn't running while an app is in Routing or Aggregation mode, the app page shows "routing service isn't running, so requests will fail" with two buttons: "Start service" and "Back to direct".
This toggle only controls routing for the **current app**:
- Turning it on starts local routing automatically if it isn't running yet
- Turning it off only disables routing for the current app; when no other app still has routing on, local routing stops automatically
Toggle states:
- ⚪ White: routing is off for the current app
- 🟢 Green: the current app is being forwarded through local routing
![image-20260108011353927](../../assets/image-20260108011353927.png)
<!-- TODO(v4 screenshot): Settings → Local routing page, Service area (running status, statistics, listen address and port, record request usage) -->
## Routing Configuration
### Basic Configuration
In "Settings → Local routing → Service":
| Setting | Description | Default |
|---------|-------------|---------|
| Listen Address | IP address local routing binds to | `127.0.0.1` |
| Listen Address | IP address local routing binds to; IPv4, IPv6 and `localhost` are supported | `127.0.0.1` |
| Listen Port | Port local routing listens on (1024–65535) | `15721` |
| Record Request Usage | Writes the usage and status of routed requests to the local statistics database | Enabled |
| Record Request Usage | Writes the usage and status of routed requests to the local statistics database; when off, Usage has no per-request details for routed requests | Enabled |
The listen address and port are only shown while local routing is stopped; the "Record Request Usage" toggle is shown while local routing is running. Retry count and timeouts are configured per app in "Settings → Routing → Auto Failover"; see [4.3 Failover](./4.3-failover.md).
Retry count and timeouts are configured per app; see [4.3 Failover](./4.3-failover.md).
### Modify Configuration
1. **Turn off "Routing Master Switch"** (local routing must be stopped before the address and port settings appear)
2. Modify the listen address or port
3. Click "Save"
4. Turn "Routing Master Switch" back on
1. Change the address or port under "Listen address and port"
2. Click "Save and restart service" (only clickable when there are changes)
After saving, the service restarts automatically with the new address and port.
### Listen Address Options
@@ -66,57 +59,29 @@ The listen address and port are only shown while local routing is stopped; the "
## Running Status
When local routing 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
The top of "Settings → Local routing → Service" shows the service status: "Running · up X h Y min" when running, otherwise "Stopped". While the service is running, these statistics are shown on the right:
| 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 local routing has been running |
| Requests | Total number of requests since startup |
| Success rate | Percentage of successful requests |
| Active connections | Number of requests currently being processed |
### Apps using routing
"Apps using routing" lists every app in Routing or Aggregation mode, with its target, for example:
```
Claude Code · Routing Routed to PackyCode
Codex · Aggregation Default AIGoCode
Claude Desktop · Model mapping · kept running Current provider xxx
```
"Open" on the right of each row opens that app's page. When no app is using routing, this shows "No app is using routing".
### Failover Queue
The panel displays the failover queue for each app:
```
Claude
├── 1. PackyCode [In Use] ●
├── 2. AIGoCode ●
└── 3. Backup Provider ○
Codex
├── 1. AIGoCode [In Use] ●
└── 2. Backup Provider ●
```
Queue details:
- Numbers indicate priority order
- The "In Use" label indicates the provider currently in use
- Health badges show provider status:
- 🟢 Green: Operational (0 consecutive failures)
- 🟡 Yellow: Degraded (has failures but not circuit-broken)
- 🔴 Red: Circuit Open (circuit breaker tripped, temporarily skipped; see [4.3 Failover](./4.3-failover.md#circuit-breaker-configuration) for thresholds)
Queues are managed in the "Routing" tab of each app page, and their parameters are tuned under "Auto failover" in "Settings → Local routing". See [4.3 Failover](./4.3-failover.md).
## How It Works
@@ -138,7 +103,7 @@ sequenceDiagram
### Configuration Changes
After you start local routing and enable routing for an app, CC Switch points that app's request address at local routing:
Once an app enters Routing mode, CC Switch points that app's request address at local routing:
**Claude**:
```json
@@ -162,7 +127,7 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
**Grok Build**: the request address in `~/.grok/config.toml` points to `http://127.0.0.1:15721/grokbuild/v1`.
While routing is on, the API Key in the config file is replaced with a placeholder; the real Key is kept in CC Switch and injected by local routing when it forwards requests.
While routing, the API Key in the config file is replaced with a placeholder; the real Key is kept in CC Switch and injected by local routing when it forwards requests.
## Format Conversion
@@ -187,31 +152,34 @@ Local routing automatically converts requests and responses according to the pro
The upstream format is configured per provider in the advanced options when adding or editing a provider; see [2.1 Add Provider → Upstream Format (Claude)](../2-providers/2.1-add.md#upstream-format-claude) and [Upstream Format and Model Mapping for Codex / Grok Build](../2-providers/2.1-add.md#upstream-format-and-model-mapping-for-codex--grok-build).
> **Note**: Format conversion requires local routing to be running with routing enabled for the corresponding app.
> **Note**: Format conversion requires local routing to be running, with the corresponding app in Routing mode.
## Stop Local Routing
### Option 1: Settings Page
While an app is in Routing or Aggregation mode, the service can't be stopped: the "Stop" button under "Settings → Local routing → Service" is greyed out with the hint "Some apps still use the routing service. Switch them back to direct first."
Turn off "Routing Master Switch" in "Settings → Routing → Local Routing".
There are two ways to take apps out of routing:
### Option 2: Main Interface Toggle
- Click "Back to direct" on an app page; this takes one app out at a time
- Click "Switch all back to direct" in "Settings → Local routing"; after you confirm, all apps are written back to their direct configuration and then the routing service stops. Routing targets, failover queues and the aggregation list are all kept
Turn off the local routing toggle at the top of each app page (requires "Show Routing Toggle on Main Page" to be on). Once routing is off for every app, local routing stops automatically.
When no app is using routing, you can click "Stop" to shut the service down directly.
### Post-stop Processing
### After Leaving Routing
When local routing stops, CC Switch will:
When an app leaves routing, CC Switch will:
1. Write each app's config file back to the direct provider (the one in use before routing was enabled, labeled "Direct" on its card)
1. Write the app's config file back to the direct provider (the one in use before it entered routing, labeled "Direct" on its card)
2. Save request logs
3. Close all connections
3. Close connections
Quitting CC Switch also writes apps back to direct first, but each app's mode stays unchanged and is re-attached on the next launch; if re-attaching fails, the app goes back to direct and you get a notice.
## Request Logs
### Enable Recording
Turn on the "Record Request Usage" toggle in the local routing settings (on by default).
Turn on the "Record Request Usage" toggle in "Settings → Local routing → Service" (on by default).
### Log Contents
@@ -229,7 +197,7 @@ Each request record includes:
### View Logs
View request logs in the "Settings → Usage Statistics" tab.
View request logs in "Usage" in the sidebar.
## FAQ
+54 -52
View File
@@ -2,47 +2,50 @@
## Overview
App routing means letting CC Switch route a specific application's API requests through the local routing service.
App routing means letting CC Switch route a specific application's API requests through the local routing service. Each app has three connection modes, shown as the "Direct / Routing / Aggregation" tabs at the top of the app page:
When routing is enabled:
| Mode | Description |
|------|-------------|
| Direct | The client connects straight to the provider; switching only changes key fields in the config file |
| Routing | Requests go through CC Switch on your machine first, then on to the provider; format conversion and failover are available |
| Aggregation | Claude Code and Codex only. Requests are split across multiple providers by the model picked in `/model`, with no failover; an official account can only be the default provider and can't join Aggregation |
This page covers "Routing". Once an app is routing:
- The app's API requests are forwarded through local routing
- Request logs and usage statistics can be recorded
- Failover functionality becomes available
## Prerequisites
The routing service must be started before using the app routing feature.
Routing needs CC Switch to keep running. You don't need to start the routing service beforehand; it starts automatically when an app enters routing.
## Enable Routing
Apps that support routing: Claude Code, Codex, Gemini CLI, Grok Build.
## Start Routing
### Location
Settings → Routing → Local Routing → "Routing Enabled" area
The "Routing" tab at the top of the app page.
### Steps
1. Ensure the routing service is started ("Routing Master Switch" is on)
2. Find the "Routing Enabled" area
3. Enable the toggle for the desired apps
1. Select the app you want to route in the sidebar
2. Click the "Routing" tab at the top (viewing only; nothing is changed)
3. Click "Start routing", choose which provider to "Route to" in the confirmation dialog, then click "Start routing" to confirm
### Routing Toggles
The dialog spells out the consequences: the address and key in the client config are rewritten, the real key stays in CC Switch, and other settings are untouched; after that, changing providers in the "Routing" tab no longer rewrites the config file; CC Switch needs to keep running, writes the direct config back when it quits, and reconnects on the next start.
| Toggle | Effect |
|--------|--------|
| Claude Routing | Route Claude Code requests |
| Codex Routing | Route Codex requests |
| Gemini Routing | Route Gemini CLI requests |
| Grok Build Routing | Route Grok Build requests |
<!-- TODO(v4 screenshot): Confirmation dialog after clicking "Start routing" in an app page's "Routing" tab -->
Multiple app routings can be enabled simultaneously.
Multiple apps can be routing at the same time. "Apps using routing" under "Settings → Local routing" lists them.
> ⚠️ Official providers (such as Claude Official) cannot be forwarded through local routing, so you can't switch to them while routing is on. Codex's OpenAI Official is the exception.
> ⚠️ Official providers (such as Claude Official) cannot be forwarded through local routing, so you can't switch to them in routing mode; the card shows "Official subscriptions don't go through routing; available again in direct mode." Codex's OpenAI Official is the exception.
## How Routing Works
### Configuration Changes
When routing is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local routing service.
Once an app enters routing, CC Switch modifies the app's configuration file to point the API endpoint to the local routing service.
**Claude configuration change**:
@@ -84,54 +87,53 @@ GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
**Grok Build configuration change**: the request address in the routing provider's model table in `~/.grok/config.toml` changes to `http://127.0.0.1:15721/grokbuild/v1`. Grok Build's official account can't be used through local routing: enabling routing while the official provider is current reports an error, so switch to a third-party provider first.
**Grok Build configuration change**: the request address in the routing provider's model table in `~/.grok/config.toml` changes to `http://127.0.0.1:15721/grokbuild/v1`. Grok Build's official account can't be used through local routing: starting routing while the official provider is current reports an error, so switch to a third-party provider first.
While routing is on, the API Key in the config file is replaced with the placeholder `PROXY_MANAGED`; the real Key is injected by local routing when it forwards requests. As with switching providers, enabling routing changes only these key fields; nothing else in the config file is touched.
While routing, the API Key in the config file is replaced with the placeholder `PROXY_MANAGED`; the real Key is injected by local routing when it forwards requests. As with switching providers, entering routing changes only these key fields; nothing else in the config file is touched.
### Request Forwarding
When the routing service receives a request:
1. Identifies the request source (Claude/Codex/Gemini/Grok Build)
2. Looks up the currently enabled provider for that app
2. Looks up the app's current routing target (by the queue when failover is on)
3. Converts the request format if needed and forwards the request to the provider's actual endpoint
4. Records the request log
5. Returns the response to the app
## Routing Status Indicators
### Main Interface Indicators
### App Page Indicators
When routing is enabled, the main interface shows the following changes:
Once routing is active:
- **Routing logo color**: Changes from colorless to green
- **Provider cards**: The currently active provider shows a green border
- The "Routing" tab carries an active marker, and "Routing is active → provider name" appears to its right ("by queue" when failover is on)
- The provider card being routed shows the "Routing" state
- If the routing service isn't running, the app page shows a notice with "Start service" and "Back to direct" buttons
### Provider Card States
| State | Border Color | Description |
|-------|--------------|-------------|
| Currently Active | Blue | Provider in the config file (non-routing mode) |
| Routing Active | Green | Provider actually used by routing |
| Normal | Default | Unused provider |
| State | Description |
|-------|-------------|
| Routing | The provider actually used by routing |
| Direct | The direct provider, which is restored after leaving routing (the hover hint reads "Leaving routing mode switches back to this provider") |
| Route here | A button on other providers; click it to move the routing target to that provider |
In routing mode, the direct provider's card also carries a "Direct" label, meaning this is the provider the config file returns to when you disable routing.
## Disable Routing
## Leave Routing
### Steps
1. Turn off the corresponding app's routing toggle in the routing panel
2. Or directly stop the routing service
- Click "Back to direct" on the app page; this takes only that app out
- Or click "Switch all back to direct" in "Settings → Local routing"; all apps leave together and the routing service stops. See [4.1 Local Routing Service](./4.1-service.md#stop-local-routing)
### Configuration Restoration
When disabling routing, CC Switch will:
When leaving routing, CC Switch will:
1. Write the app's config file back to the direct provider (the one in use before routing was enabled, labeled "Direct" on its card), without relying on a backup taken when routing was enabled
1. Write the app's config file back to the direct provider (the one in use before it entered routing, labeled "Direct" on its card), without relying on a backup taken when it entered routing
2. Save current request logs
Quitting CC Switch also writes the config file back to the direct provider first, while the routing toggle stays as it is; local routing is reconnected the next time CC Switch starts.
Quitting CC Switch also writes the config file back to the direct provider first, while the app's mode stays as it is; local routing is reconnected the next time CC Switch starts.
## Routing and Provider Switching
@@ -139,17 +141,17 @@ Quitting CC Switch also writes the config file back to the direct provider first
When switching providers in routing mode:
1. Click the "Enable" button on a provider in the main interface
1. In the "Routing" tab, click "Route here" on a provider card (with failover on, adjust the queue instead; see [4.3 Failover](./4.3-failover.md))
2. The routing service immediately uses the new provider to forward requests
3. **No need to restart the CLI tool**
This is a major advantage of routing mode: provider switching takes effect instantly. After switching Codex, Gemini CLI, or Grok Build, the interface still prompts you to restart; with routing on, you can skip the restart as long as the switch doesn't change the model.
This is a major advantage of routing mode: provider switching takes effect instantly. After switching Codex, Gemini CLI, or Grok Build, the interface still prompts you to restart; while routing, you can skip the restart as long as the switch doesn't change the model.
In routing mode, switching changes only the provider that routing uses; the direct provider stays the same, is labeled "Direct" on its card, and is what you return to when you disable routing. If what the new provider writes to the config file (the local address, model name, etc.) is the same as before, switching doesn't touch the config file; if it differs (for example, a different model name), CC Switch updates the config file first, and Codex, Gemini CLI, and Grok Build then need a restart to use the new model.
In routing mode, switching changes only the provider that routing uses; the direct provider stays the same, is labeled "Direct" on its card, and is what you return to when you leave routing. If what the new provider writes to the config file (the local address, model name, etc.) is the same as before, switching doesn't touch the config file; if it differs (for example, a different model name), CC Switch updates the config file first, and Codex, Gemini CLI, and Grok Build then need a restart to use the new model.
### Switching Without Routing
### Switching in Direct Mode
When switching providers without routing:
When switching providers in direct mode:
1. Configuration file is modified
2. CLI tool must be restarted for changes to take effect
@@ -166,19 +168,19 @@ Multiple apps can be routed simultaneously, each managed independently:
### Scenario 1: Usage Monitoring
Enable routing + "Record Request Usage" to record every request that passes through local routing. With routing off, CC Switch also collects usage from each tool's local session logs; see [4.4 Usage Statistics](./4.4-usage.md).
Enter routing + "Record Request Usage" to record every request that passes through local routing. With routing off, CC Switch also collects usage from each tool's local session logs; see [4.4 Usage Statistics](./4.4-usage.md).
### Scenario 2: Quick Switching
With routing enabled, switching providers does not require restarting CLI tools.
Once routing, switching providers does not require restarting CLI tools.
### Scenario 3: Format Conversion
Using a provider with OpenAI or Gemini format with Claude Code, or a provider with Chat Completions / Anthropic Messages format with Codex or Grok Build, requires routing to be enabled.
Using a provider with OpenAI or Gemini format with Claude Code, or a provider with Chat Completions / Anthropic Messages format with Codex or Grok Build, requires entering routing.
### Scenario 4: Failover
Enabling routing is a prerequisite for using the failover feature.
Entering routing is a prerequisite for using the failover feature.
## Notes
@@ -192,18 +194,18 @@ In routing mode, CLI tools must be able to access the local routing address.
### Configuration Backup
Routing doesn't rely on a backup: when you disable routing, CC Switch writes the config file again from the direct provider. Separately, before CC Switch rewrites each config file for the first time, it backs up the original to `~/.cc-switch/backups/live-first-write/`.
Routing doesn't rely on a backup: when you leave routing, CC Switch writes the config file again from the direct provider. Separately, before CC Switch rewrites each config file for the first time, it backs up the original to `~/.cc-switch/backups/live-first-write/`.
## FAQ
### Requests Fail After Enabling Routing
### Requests Fail After Entering Routing
Check:
- Is the routing service running normally
- Is the routing service running normally (Settings → Local routing)
- Is the provider configuration correct
- Is the network working properly
### Configuration Not Restored After Disabling Routing
### Configuration Not Restored After Going Back to Direct
Possible causes:
- Routing service exited abnormally
@@ -211,4 +213,4 @@ Possible causes:
Solutions:
- Manually edit the provider and re-save
- Or re-enable and then disable routing
- Or enter routing again and then leave it
+51 -67
View File
@@ -13,74 +13,58 @@ The failover feature automatically switches to a backup provider when the primar
Using the failover feature requires:
1. ✅ Local routing started
2. ✅ Routing enabled for the corresponding app
3. ✅ Failover queue configured
4. ✅ Auto failover enabled
1. ✅ The app is in Routing mode (the "Routing" tab on the app page, click "Start routing")
2. ✅ The failover switch is on in the "Routing" tab
3. ✅ There are providers in the queue
## Configure the Failover Queue
Failover only supports Claude Code, Codex, Gemini CLI and Grok Build; Aggregation mode doesn't do failover (the queue and settings are kept and take effect again once you return to Routing mode); additive apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code) have no failover queue. Official accounts don't join the queue: they use the client's own login and can't rotate with other providers.
### Open Configuration Page
Settings → Routing → Auto Failover
### Select Application
Four tabs at the top of the page:
- Claude
- Codex
- Gemini
- Grok Build
Select the application to configure. Failover only supports these four apps; coexist apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code) have no failover queue.
### Add Backup Providers
1. In the "Failover Queue" area, select the provider to add from the dropdown list
2. Click the **+** button on the right to add the provider to the queue
When local routing isn't running, or routing isn't enabled for the app, the queue controls are grayed out and unavailable.
### Adjust Priority
The queue order follows the order of the provider list on the home page; drag provider cards on the home page to adjust it:
- Lower numbers mean higher priority (P1 first)
- After the primary provider fails, backup providers are tried in order
### Remove Provider
Click the delete button (trash icon) to the right of the provider.
## Main Interface Quick Actions
After you turn on "Show Failover Toggle on Main Page" in "Settings → Routing → Auto Failover", a failover toggle appears at the top of the main interface; it stays grayed out until routing is enabled for the app.
When routing is enabled for the app and auto failover is on, the "Enable" button on provider cards changes to "Add / In queue", which adds the provider to or removes it from the queue.
### Add to Queue
1. Find the provider card
2. Click "Add"
3. The provider is added to the queue
### Remove from Queue
1. Click "In queue" on the provider card again
2. The provider is removed from the queue
## Enable Auto Failover
## Enable Failover
### Steps
1. On the failover configuration page
2. Enable the "Auto Failover" toggle
1. On the app page, switch to the "Routing" tab and confirm the app is in Routing mode
2. Turn on the switch with the "Failover" hint at the right of the tab bar (its icon is two crossing arrows)
3. The first time, a confirmation dialog appears; click "I understand, enable"
### Toggle Description
<!-- TODO(v4 screenshot): The failover switch and the "Routing settings" button at the right of the tab bar in an app page's "Routing" tab -->
The switch only appears when the app is in Routing mode and you're viewing the "Routing" tab.
### Switch Description
| State | Behavior |
|-------|----------|
| Off | Only records failures, no automatic switching |
| On | Immediately switches to queue P1, and automatically switches to the next provider in the queue when a request fails |
| Off | Routes only to the selected provider, no automatic switching |
| On | Immediately switches to queue P1, and automatically switches to the next provider in the queue when a request fails; the status line shows "by queue" |
## Manage the Failover Queue
Once failover is on, the providers in the "Routing" tab are split into two groups:
- **Queue · by priority**: requests go to the first one (P1) first; when it fails repeatedly, routing moves on to the next
- **Not in queue**: providers that haven't been added to the queue yet
### Add Backup Providers
Under "Not in queue", click "Add to queue" on the provider card.
### Adjust Priority
Use the move up / move down buttons on the card, or drag the card to reorder. Lower numbers mean higher priority, and the queue order follows the order of the provider list on the home page.
### Remove Provider
Click "Remove from queue" on the provider card in the queue.
## Adjust Retry, Timeout and Circuit Breaker Parameters
Parameters are set per app, with two entry points:
- The "Routing settings" button at the right of the tab bar in the app page's "Routing" tab: opens a side panel for the current app's parameters; "More routing settings" at the bottom of the panel jumps to the settings page
- "Settings → Local routing → Auto failover": choose the app at the top, then adjust that app's parameters
The panel has two parts, "Retry & Timeout Settings" and "Circuit Breaker Settings"; their meanings are covered in the sections below.
## Failover Flow
@@ -158,7 +142,7 @@ stateDiagram-v2
### Provider Cards
Cards display health status badges:
In routing mode, provider cards display health status badges:
| Badge | Status | Description |
|-------|--------|-------------|
@@ -166,9 +150,9 @@ Cards display health status badges:
| 🟡 | Degraded | Has failures but circuit not tripped |
| 🔴 | Circuit Open | Circuit breaker tripped, temporarily skipped |
### Queue List
### Queue
The failover queue also displays each provider's health status.
Provider cards in the failover queue also display health status; the "Routing" marker shows the provider actually in use (it changes after a successful failover and isn't necessarily the head of the queue).
## Failover Logs
@@ -211,9 +195,9 @@ Periodically check:
### Failover Not Triggering
Check:
1. Is local routing running
2. Is routing enabled for the corresponding app
3. Is auto failover enabled
1. Is local routing running (Settings → Local routing)
2. Is the app in Routing mode (Aggregation mode doesn't do failover)
3. Is the failover switch in the "Routing" tab on
4. Are there backup providers in the queue
### Failover Triggering Too Frequently
@@ -231,5 +215,5 @@ Solutions:
### All Providers Circuit-Broken
Wait for the recovery wait time to expire for automatic recovery, or:
1. Manually restart local routing
2. Reset circuit breaker states
1. In "Settings → Local routing", switch the app back to direct, stop the service, then start routing again
2. Or adjust the circuit breaker parameters
+69 -112
View File
@@ -9,7 +9,7 @@ The usage statistics feature records and analyzes API request data, helping you:
- Analyze usage patterns
- Troubleshoot issues
Usage data comes from two sources:
Usage is a global page in the sidebar. Usage data comes from two sources:
| Data Source | Coverage | Local Routing Required? |
| ------------------------------- | ----------------------------------------- | ----------------------- |
@@ -18,7 +18,7 @@ Usage data comes from two sources:
- Works without local routing: by default, CC Switch periodically scans each tool's local session logs and tallies requests, tokens, cache hit rate and cost by provider and model
- **Codex sessions**: **Precisely parsed** from JSONL session logs; model names are normalized for consistent pricing lookup
- The usage panel supports **per-app filtering** so data from different apps does not mix
- The Usage page supports **per-app filtering** so data from different apps does not mix
- OpenClaw and Hermes don't support usage statistics yet; for Claude Desktop, only "Model Mapping" requests forwarded through local routing are counted, and they are included under the Claude Code filter
## Prerequisites
@@ -29,17 +29,27 @@ Depending on which data source you use, the prerequisites differ:
1. ✅ Local routing started
2. ✅ Routing enabled for the corresponding app
3. ✅ "Record Request Usage" turned on (on by default)
3. ✅ "Record request usage" turned on (on by default, under Settings → Local routing)
**CLI session log** (no local routing required):
1. ✅ The corresponding CLI has session history files
2. ✅ "Auto-Scan Session Logs" stays on (on by default). When it's off, scanning only happens on manual sync
3. ✅ CC Switch periodically scans session directories and imports usage data
2. ✅ "Scan session logs automatically" stays on (on by default). When it's off, scanning only happens when you click "Sync Now"
3. ✅ CC Switch scans once at startup and every 60 seconds after that, importing usage data
> Session logs can't tell which provider was used, so for these records the Provider column shows "{App} · Session logs".
## Open Usage Statistics
Settings → Usage Statistics Tab
Click **Usage** in the left sidebar. It's a global page: you don't need to pick an app first, or turn on local routing.
The top right of the page has:
- **Sync Now**: scans the session logs right away (the last sync time is shown next to it)
- **Auto refresh**: sets how often the page data refreshes automatically; can be turned off
- **Data sources**: opens a side panel to manage session log scanning, "Record request usage", and Codex usage maintenance (see below)
![Usage](../../../../assets/release-notes/v4.0.0/usage-en.png)
## Statistics Overview
@@ -49,155 +59,100 @@ Key metrics displayed at the top of the page:
| Metric | Description |
|--------|-------------|
| Total Cost | Cost estimated from the pricing configuration |
| Total Requests | Total number of requests in the time period |
| Tokens Processed | 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 |
| Tokens Processed | Fresh input + output + cache writes + cache hits |
| Cache Hit Rate | Cache hits ÷ (fresh input + cache writes + cache hits) |
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 Tokens Processed, cache hit rate, request count, and cost update together and stay aligned with the logs and stats below.
Click "More metrics" to expand the separate numbers for fresh input, output, cache writes and cache hits. Some protocols (such as OpenAI) don't report cache writes, so cache writes and tokens processed may read low.
> 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.
When you change the time range, app, provider or model filter, these numbers update together and stay aligned with the logs and stats below.
### Time Range
### Time Range and Filters
Select the time range for statistics:
| Option | Range |
|--------|-------|
| Time range | Description |
|------------|-------------|
| Today | From 00:00 today to now |
| 1d / 7d / 14d / 30d | Past 1 / 7 / 14 / 30 days |
| Last 24 hours / Last 7 days / Last 14 days / Last 30 days | The corresponding period up to now |
| All | All history |
| Calendar Filter | Custom start and end date and time |
At the top of the page you can also:
The filter row lets you:
- Filter by app: All / Claude Code / Codex / Gemini / OpenCode / Grok Build / Pi / MiniMax Code (Claude Desktop requests forwarded through local routing count toward Claude Code)
- Filter by provider ("All Sources") and model ("All Models") from the dropdowns
- Set the "Auto-refresh interval"
- Filter by provider and model from the dropdowns (the model list follows the selected provider)
![image-20260108011730105](../../assets/image-20260108011730105.png)
OpenClaw and Hermes don't support usage statistics yet.
## Trend Charts
## Heatmap and Trend Charts
### Request Trend
### Usage Heatmap
Line chart showing the trend of request counts:
Shows daily usage over the last 53 weeks; darker colors mean more usage.
- X-axis: Time
- Y-axis: Request count
- Viewable by hour/day
- Supports zoom and drag
### Usage Trends
### Token Trend
A line chart showing change over time; switch between three metrics: **Tokens / Requests / Cost**:
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
- Last 24 hours (and Today): shown by hour
- 7 days, 30 days and other longer ranges: shown by day
- Hover to see the exact numbers at that point in time
> 💡 **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
![image-20260108011742847](../../assets/image-20260108011742847.png)
## Detailed Data
Three data tabs at the bottom of the page:
Four tabs at the bottom of the page: **Request Logs**, **Providers**, **Models**, **Pricing** (pricing is covered in the next section).
### Request Logs
Detailed record of each request:
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 |
| App | The app it belongs to |
| Provider | Provider name used (records imported from session logs show "{App} · Session logs") |
| Model | Requested model |
| Fresh Input | Input tokens, excluding cache |
| Output | Output tokens |
| Cache Hit | Cache hit token count |
| Cost | Estimated cost (USD); models without pricing show "Unpriced" |
| Speed | Output tokens per second (see below) |
#### Timing Information
Hover to see details such as duration, time to first token and cache writes; click a request row to open the details panel, which shows the source (the routing service with its status code, or a session log), token usage, a cost breakdown and performance info. The status code filter at the top right of the table lets you view only requests with a certain kind of status code.
The timing info column displays multiple badges:
#### How Speed Is Calculated
| 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 |
Speed is output tokens per second, measured from the first token to the end. It's only counted for requests that went through local routing and output at least 100 tokens; for models that don't expose their thinking, it's an approximation.
#### View Details
With routing off, speed is estimated from session log timestamps and shown as "≈ xx tok/s": there's no first-token timing and the wait for the first token is included, so it reads low, and only requests with at least 200 output tokens are estimated.
Click a request row to view detailed information:
### Providers
- Complete request parameters
- Response content summary
- Error messages (if failed)
Statistics grouped by provider: requests, tokens, cost, success rate, speed.
#### Filter Logs
### Models
The request log table itself provides two filters:
Statistics grouped by model: requests, tokens, cost, average cost, success rate, speed.
| Filter | Options |
|--------|---------|
| Status Code | All / 200 OK / 400 / 401 / 429 / 500 |
| Date Range | Pick a date range |
## Data Sources Panel
App, provider, model and time range are controlled by the filters at the top of the page, and the request logs update accordingly.
Click "Data sources" at the top right of the page to open it:
![image-20260108011859974](../../assets/image-20260108011859974.png)
### 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 |
![image-20260108011907928](../../assets/image-20260108011907928.png)
### 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 |
![image-20260108011915381](../../assets/image-20260108011915381.png)
- **Scan session logs automatically**: a switch, plus "Sync Now". The panel lists the apps covered, and "Hermes and OpenClaw don't support usage stats yet"
- **Record request usage**: shows whether it's on; click "Change" to jump to Settings → Local routing to adjust it
- **Codex Usage Maintenance**: "Rebuild Codex Usage" clears the existing Codex session details and aggregates, then re-imports them from the local Codex logs. The database is backed up automatically before rebuilding; history belonging to logs that have already been deleted can't be re-imported
## Pricing Configuration
### Open Pricing Configuration
Settings → Usage Statistics → Cost Pricing
Usage page → **Pricing** tab
Besides entering prices manually, you can click "Import from models.dev" in the "Add Pricing" / "Edit Pricing" dialog to import public model pricing.
"Pricing Defaults" at the top of the page decides whether each app matches pricing by the "requested model" or the "returned model"; click "Change" to adjust it. It only applies to requests through local routing; usage imported from session logs is priced by the model recorded in the log.
Below it is the "Model Pricing" table. Besides entering prices manually, you can click "Import from models.dev" in the "Add Pricing" / "Edit Pricing" dialog to import public model pricing.
### Configure Model Prices
@@ -240,7 +195,9 @@ When adding pricing entries, enter the normalized Model ID rather than the full
- **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
![image-20260108011933565](../../assets/image-20260108011933565.png)
The Pricing tab also has "Automatic models.dev pricing sync": when on, CC Switch updates the prices of the models you choose from models.dev at startup (at most once every 6 hours). Both built-in and manually set prices for the same model ID are overwritten, so a confirmation appears before you turn it on. You can "Choose models", or let it include common models automatically.
<!-- TODO(v4 screenshot): Usage page "Pricing" tab (Pricing Defaults + Model Pricing table) -->
### Preset Prices
@@ -326,7 +283,7 @@ If using relay services, prices may differ:
### Statistics Data Is Empty
Check:
- Is "Auto-Scan Session Logs" on, and does the corresponding CLI have session history (the data source when local routing is off)
- Is "Scan session logs automatically" on, and does the corresponding CLI have session history (the data source when local routing is off)
- If you rely on routing request logs: is local routing running, is routing enabled for the corresponding app, and is "Record Request Usage" on
- Does the app support usage statistics (OpenClaw and Hermes don't yet)
+10 -11
View File
@@ -12,12 +12,12 @@ The connectivity check quickly tells you whether a provider's address can be rea
> 💡 Before v3.16.3, this feature was called "Model Test" (Stream Check) and sent a real streaming model request to the provider. Because many third-party gateways block such requests and cause false results, it has been replaced by the connectivity check, and you no longer need to configure a test model.
Non-official providers of every app can be checked, except MiniMax Code. Official providers (such as Claude Official and Claude Desktop Official) have no address to probe; on the cards of official providers and MiniMax Code providers, the check button is grayed out and can't be clicked.
Non-official providers of every app can be checked, except MiniMax Code. Official providers (such as Claude Official and Claude Desktop Official) have no address to probe, and MiniMax Code providers don't support the check either; the menu on those cards has no "Connectivity check".
## Run a Check
1. Hover over the provider card to show the action buttons
2. Click the **Connectivity check** button
1. Hover over the provider card and click the "More" (⋯) button on the right
2. Choose **Connectivity check** in the menu
3. Wait for the check to finish; the result appears as a toast message
| Result | Description |
@@ -28,13 +28,13 @@ Non-official providers of every app can be checked, except MiniMax Code. Officia
## Check Parameters
Settings → Advanced → Connectivity Check Settings
The check parameters currently have no settings in the UI; fixed defaults are used:
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| Timeout (seconds) | Maximum wait time for a single probe | 8 | 2-60 |
| Max Retries | Retries only on timeout-type failures; connection refused, DNS failure and the like return immediately | 1 | 0-5 |
| Slow-response threshold (ms) | When the address is reachable but latency exceeds this value, it is marked as "slow" | 6000 | 1000-30000 |
| Parameter | Description | Value |
|-----------|-------------|-------|
| Timeout | Maximum wait time for a single probe | 8 seconds |
| Max Retries | Retries only on timeout-type failures; connection refused, DNS failure and the like return immediately | 1 |
| Slow-response threshold | When the address is reachable but latency exceeds this value, it is marked as "slow" | 6000 ms |
## Relationship with Failover
@@ -53,7 +53,7 @@ The connectivity check doesn't verify auth or models. Check:
Possible causes:
- The request address is wrong
- The network is down, or access requires going through a proxy (configurable in "Settings → Routing → Global Outbound Proxy")
- The network is down, or access requires going through a proxy (configurable in "Settings → Network → Global Outbound Proxy")
- A firewall is blocking the connection
### High Latency
@@ -64,4 +64,3 @@ Possible causes:
Solutions:
- Use [Endpoint Speed Test](../2-providers/2.1-add.md#endpoint-speed-test) to pick a faster endpoint
- Adjust the slow-response threshold
@@ -0,0 +1,97 @@
# 4.6 Aggregation Mode
## Overview
Aggregation mode puts the models of several providers into one model list in Claude Code or Codex. Whichever model you pick in the client's `/model`, the request goes to that provider; you don't have to go back to CC Switch to switch providers.
Aggregation mode only supports **Claude Code** and **Codex**.
![Aggregation mode: one default provider, with several others added](../../../../assets/release-notes/v4.0.0/agg-en.png)
## How It Differs from Routing
| | Routing | Aggregation |
|------|------|------|
| Providers used at the same time | One (or rotating through the failover queue) | Several, dispatched by the selected model |
| Failover | Supported | Not supported |
| How you switch providers | Switch in CC Switch | Pick a model in the client's `/model` |
| Supported apps | Claude Code / Codex / Gemini CLI / Grok Build | Claude Code / Codex only |
Both go through the routing service on your machine, so both need CC Switch to keep running. An app can only be in one of three modes at a time: Direct, Routing or Aggregation.
## Enter Aggregation Mode
### Location
Select Claude Code or Codex in the sidebar → the "Aggregation" tab at the top of the page
### Steps
1. Click the "Aggregation" tab. Clicking the tab is only for viewing and doesn't change any configuration
2. Confirm the default provider in the "Default provider" area (see below)
3. Click "Switch to Aggregation"
4. In the confirmation dialog, review the default provider and the models that will appear in `/model`, then click "Switch to Aggregation" to confirm
After switching, the page shows "Aggregation is active · default", along with the default provider and how many models the other providers add. To go back to direct, click "Back to direct"; to use routing instead, click "Start routing" in the "Routing" tab.
## Add and Remove Providers
### Add
Under the "Aggregation" tab, the "Available" list holds the providers that haven't been added yet. Click "Add" on a card, and that provider's models appear in the client's model list.
### Remove
In the "Added" list, click "Remove" on the card. Added providers are written into the client's configuration as well.
> ⚠️ The default provider can't be removed; set another provider as the default first.
### Set Each Provider's Models
When editing a provider, the form has a "Models" list:
- These models appear in `/model`, and picking one sends requests straight to this provider
- The first one (★) is this provider's default model; when this provider is the default, Claude Code startup and background tasks and Codex's default model all use it
- A provider with no models configured adds nothing to `/model` after joining Aggregation
- Click "Add manually" to add more models
## Default Provider
The default provider takes all requests without a prefix. Click "Set as default" on a provider card to change it.
If you use an official subscription (a Claude official account, or Codex's OpenAI Official), set the official account as the default provider.
## The `ccs-` Prefix in `/model`
Other than the default provider, the models of the other added providers appear in `/model` with a `ccs-` prefix. Picking a model with the `ccs-` prefix sends the request to the corresponding provider; picking one without the prefix sends it to the default provider.
![Codex's model picker lists the models of several providers together](../../../../assets/release-notes/v4.0.0/agg-codex-en.png)
> After you change models within a session, the new model has to build its prompt cache again, so the first turn costs more. Claude Code needs version 2.1.243 or newer.
## When a Restart Is Needed
| App | After the aggregated model list changes |
|-----|------------------|
| Claude Code | Takes effect immediately |
| Codex | Needs a full restart |
Codex only reads its model list at startup. After entering or leaving Aggregation, adding or removing a provider, or changing a provider's models, the page shows "Codex is still using an old model list, so aggregated models won't show"; handle it according to your client:
- **CLI**: reopening codex isn't enough; click "Restart Codex daemon" in the notice. All codex sessions in your terminals share this daemon, and running tasks will be interrupted
- **Desktop app**: quit completely and reopen. On macOS press ⌘Q; just closing the window isn't enough
- **Editor extension**: reopen the editor window
Also, after CC Switch rewrites the client config, if the model currently selected in `/model` is an aggregated one, you need to select it again.
## Limits
- **No failover**: the queue and settings are kept in Aggregation mode and take effect again once you return to Routing mode
- **Official accounts can only be the default provider** and can't join Aggregation
- **The default provider can't be removed**
- **CC Switch must keep running**: quitting CC Switch automatically returns to direct, and it reconnects on the next start
- When you return to Routing mode, the aggregated models are withdrawn from `/model` (the list is kept), and an aggregated model that is currently selected needs to be changed back to a regular one
## Acknowledgements
Much of Aggregation mode's design draws on [opencodex](https://github.com/lidge-jun/opencodex); thanks to the author and contributors.
+40 -12
View File
@@ -6,7 +6,7 @@
Default location: `~/.cc-switch/`
Customizable location in settings (for cloud sync).
You can change the "CC Switch Configuration Directory" under "Settings → Data → Location" (for cloud sync). A restart is required after changing it; CC Switch doesn't move existing files for you, so copy them over manually first.
### Directory Structure
@@ -16,6 +16,9 @@ Customizable location in settings (for cloud sync).
├── settings.json # Device-level settings
├── live-state.json # Device state: whether each tool is direct or on local routing, and what was last written
├── codex-login-stash.json # Stashed official Codex login (restored when you switch back to an official provider)
├── copilot_auth.json # GitHub Copilot login credentials (Accounts)
├── codex_oauth_auth.json # ChatGPT / Codex OAuth login credentials (Accounts)
├── xai_oauth_auth.json # xAI OAuth login credentials (Accounts)
├── skills/ # Master copies of skills (when the storage location is "CC Switch")
├── skill-backups/ # Skill backups (created on uninstall)
├── backups/ # Database backups and environment variable backups
@@ -26,6 +29,8 @@ Customizable location in settings (for cloud sync).
`settings.json`, `live-state.json`, `codex-login-stash.json`, and `backups/live-first-write/` belong to this computer only: they always stay in `~/.cc-switch/`, don't move with the "CC Switch Configuration Directory" setting, and aren't included in cloud sync.
`live-state.json` records whether each switch-style app (Claude Code, Codex, Gemini CLI, Grok Build) is currently Direct, Routing or Aggregation, and what CC Switch last wrote into each tool's config file. After quitting CC Switch or restarting after a crash, it relies on this file to restore the config files to the right state, so please don't edit it by hand.
### Database Contents
`cc-switch.db` is a SQLite database that stores:
@@ -53,9 +58,9 @@ Customizable location in settings (for cloud sync).
```json
{
"language": "zh",
"theme": "system",
"windowBehavior": "minimize",
"autoStart": false,
"showInTray": true,
"minimizeToTrayOnClose": true,
"launchOnStartup": false,
"claudeConfigDir": null,
"codexConfigDir": null,
"geminiConfigDir": null,
@@ -67,17 +72,19 @@ Customizable location in settings (for cloud sync).
}
```
These settings are not synced across devices.
Besides these, each app's "current provider" is also recorded in this file (the direct pointer). These settings are not synced across devices. Each app's config directory is changed under "Settings → App config"; Claude Desktop and MiniMax Code don't support overriding the directory.
### Automatic Backups
The `backups/` directory stores database backups:
- Backed up automatically at the interval set in "Settings → Advanced → Backup & Restore" (24 hours by default)
- Backed up automatically at the interval set in "Settings → Data → Backup & Restore" (24 hours by default)
- Also created automatically before overwriting operations such as importing configuration, restoring a backup or downloading from the cloud
- Retains the most recent 10 backups by default
- File names include timestamps
Besides database backups, CC Switch leaves backups elsewhere too (environment variable cleanup backups, skill backups, original config files, and so on). "Other Backups" below "Backup & Restore" in "Settings → Data" lists these locations and their sizes, and you can clean them up by category.
## Claude Code Configuration
### Configuration Directory
@@ -131,6 +138,26 @@ MCP server configuration is in `~/.claude.json`:
}
```
## Claude Desktop Configuration
Claude Desktop is a switch-style app, but its config directory can't be overridden in CC Switch.
| System | Location |
|--------|----------|
| macOS | `~/Library/Application Support/Claude/` and `Claude-3p/` |
| Windows | The `Claude` and `Claude-3p` directories under `%LOCALAPPDATA%` |
| Linux | `~/.config/Claude/` and `Claude-3p/` |
```
Claude/claude_desktop_config.json # Claude Desktop's main config
Claude-3p/claude_desktop_config.json # Config for third-party inference (gateway) mode
Claude-3p/configLibrary/*.json # Gateway configs written by CC Switch
```
In the default "Direct" mode, CC Switch writes the provider address and Key straight into the gateway config; in "Model mapping" mode, the gateway config points to the `/claude-desktop` prefix of local routing, and the real address and Key are kept only in CC Switch, so CC Switch must keep running. After switching, quit Claude Desktop completely and reopen it.
Claude Desktop has no MCP, Skills, prompt or session data of its own: those pages operate on Claude Code's data.
## Codex Configuration
### Configuration Directory
@@ -149,7 +176,7 @@ Default: `~/.codex/`
### auth.json
`auth.json` only holds the OpenAI official ChatGPT login credentials, written by Codex's `codex login`. When you switch to a third-party provider, CC Switch does **not** write the third-party API Key into this file. When local routing is off, whether a direct switch keeps the official login is controlled by "Settings → General → Codex App Enhancements → Keep official login for direct switches" (off by default, meaning `auth.json` is deleted); while local routing is on, the official login is always kept. Before deleting it, CC Switch stashes this login in `~/.cc-switch/codex-login-stash.json` and puts it back unchanged when you switch back to the official provider, so you don't need to log in again.
`auth.json` only holds the OpenAI official ChatGPT login credentials, written by Codex's `codex login`. When you switch to a third-party provider, CC Switch does **not** write the third-party API Key into this file. When local routing is off, whether a direct switch keeps the official login is controlled by "Keep official login for direct switches" in "Settings → App config" (off by default, meaning `auth.json` is deleted); while routing, the official login is always kept. Before deleting it, CC Switch stashes this login in `~/.cc-switch/codex-login-stash.json` and puts it back unchanged when you switch back to the official provider, so you don't need to log in again.
### config.toml
@@ -170,7 +197,7 @@ command = "uvx"
args = ["mcp-server-fetch"]
```
Every third-party provider is written as the `[model_providers.custom]` table, with the API Key in that table's `experimental_bearer_token`. While local routing is on, it is replaced with the placeholder `PROXY_MANAGED`. For providers with model mapping configured, a `model_catalog_json` entry pointing to `cc-switch-model-catalog.json` is also written.
Every third-party provider is written as the `[model_providers.custom]` table, with the API Key in that table's `experimental_bearer_token`. In Routing or Aggregation mode, this holds the local routing address and the Key is replaced with the placeholder `PROXY_MANAGED`. For providers with model mapping configured, a `model_catalog_json` entry pointing to `cc-switch-model-catalog.json` is also written.
When switching providers, CC Switch changes only the key fields in `config.toml`: top-level keys such as `model_provider`, `model`, and the reasoning effort, the `[model_providers.custom]` table, and a few compatibility options (such as `model_context_window` and `web_search`). `[mcp_servers]`, `[projects]`, your own other provider tables, comments, and formatting are left alone.
@@ -228,7 +255,7 @@ Default: `~/.config/opencode/`
```
~/.config/opencode/
├── opencode.json # Main configuration file
├── opencode.json # Main configuration file; MCP is under the mcp key
├── AGENTS.md # System prompt
└── skills/ # Skills directory
└── ...
@@ -258,7 +285,7 @@ When switching away, CC Switch deletes the table it wrote last time (the table n
### Configuration Directory
Default: `~/.hermes/`
Default: `~/.hermes/` (on Windows the default is `%LOCALAPPDATA%\hermes\`; can also be set with the `HERMES_HOME` environment variable)
### Key Files
@@ -349,6 +376,7 @@ Default: `~/.pi/agent/` (can be overridden with the `PI_CODING_AGENT_DIR` enviro
```
~/.pi/agent/
├── models.json # Custom providers and models (written by CC Switch)
├── mcp.json # MCP servers (written by CC Switch)
├── settings.json # Pi global settings, including the current defaultProvider / defaultModel (read-only for CC Switch)
├── auth.json # Pi login credentials (CC Switch neither reads nor writes it)
├── AGENTS.md # Global prompt
@@ -378,7 +406,7 @@ CC Switch only manages nodes in `custom_provider` whose `kind` is omitted or set
## Who Manages What
The config files of Claude Code, Codex, Gemini CLI, and Grok Build are managed in two parts:
The config files of switch-style apps (Claude Code, Codex, Gemini CLI, and Grok Build) are managed in two parts (additive apps OpenCode, OpenClaw, Hermes, Pi and MiniMax Code write each provider into the config file as a whole entry, with several coexisting and nothing replaced on switching):
| Part | Includes | Stored in | Changed by |
|------|----------|-----------|------------|
@@ -434,7 +462,7 @@ CC Switch v3.7.0 migrated from JSON files to SQLite:
It is recommended to regularly export configurations:
1. Settings → Advanced → Data Management
1. Settings → Data → Data Management
2. Click "Export SQL Backup"
3. Save to a secure location
+57 -30
View File
@@ -53,13 +53,36 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
**Cause**: The CLI tool needs to reload its configuration
**Solutions**:
- Claude Code: Close and reopen the terminal, or restart the IDE
- Codex, Grok Build: Close and reopen the terminal
- Gemini CLI: Quit and run `gemini` again
- Claude Desktop: Restart Claude Desktop
- Coexist apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code): Make sure you clicked "Add" ("Enable" for Pi) and selected the corresponding model in the tool
- Claude Code: Supports hot switching, so a restart is usually unnecessary; if it didn't take effect, close and reopen the terminal, or restart the IDE
- Codex, Gemini CLI, Grok Build: Close and reopen the terminal or the CLI tool (a notice appears after a successful switch)
- Claude Desktop: Quit Claude Desktop completely and reopen it; with "Model mapping", also keep CC Switch running
- Additive apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code): Make sure you clicked "Add" ("Enable" for Pi) and selected the corresponding model in the tool
With local routing on, a switch takes effect immediately for subsequent requests; see [4.2 App Routing](../4-proxy/4.2-routing.md).
In Routing mode, requests are forwarded to the new provider immediately; but if the switch changes the model, Codex, Gemini CLI and Grok Build may still need a restart. In Aggregation mode, Claude Code takes effect immediately; Codex needs a full restart after entering or leaving Aggregation or changing the aggregated model list; see the next entry. See [4.2 App Routing](../4-proxy/4.2-routing.md) for details.
### Codex Doesn't Show the Aggregated Models in /model
Codex only reads its model list at startup. After entering or leaving Aggregation mode, adding or removing an aggregated provider, or changing a provider's aggregated models, you need to restart Codex completely:
- **Codex CLI**: just closing the terminal and reopening `codex` isn't enough; all `codex` sessions in your terminals share one background daemon. When CC Switch detects that Codex is still using the old list, it shows a notice at the top of the Codex page; click "Restart Codex daemon" in the notice (this interrupts tasks running in the daemon).
- **Codex desktop app**: quit completely and reopen (on macOS press ⌘Q; just closing the window isn't enough).
- **Editor extension**: reopen the editor window.
### Does Switching Providers Change My Plugins, Hooks and Other Settings
No. When switching providers in Claude Code, Codex, Gemini CLI and Grok Build, CC Switch only replaces the key fields in the config file (request address, Key, model name, API protocol and so on); plugins, hooks, permissions, MCP, environment variables you added yourself, comments and formatting are all kept as they are. For exactly which keys are changed, see [5.1 Configuration Files](./5.1-config-files.md).
### I Changed the Model in the Tool, but It Reverted After Switching Away and Back
The model is a key field and belongs to the provider. A model you change inside the tool (such as Claude Code's `/model`) stays in effect until the next switch; on switching it's replaced with the one saved on the target provider, and CC Switch doesn't save the model you changed in the tool back to the original provider. To use a model long term, edit that provider in CC Switch.
### Why Can't I Delete the Provider in Use
Claude Code, Claude Desktop, Codex, Gemini CLI and Grok Build enable only one provider at a time and always keep one in use, otherwise the app couldn't work properly. To delete it, switch to another provider first. In Aggregation mode, the default provider can't be removed either; set another provider as the default first. Additive apps don't have this limit.
### Using an OpenAI-Compatible Endpoint, Gemini or a Local Model in Claude Code
This needs routing. When editing the provider, under "Advanced Options" → "Upstream Format", choose the format that matches the provider: "OpenAI Chat Completions" for services that only offer a Chat Completions endpoint, "OpenAI Responses API" for those that offer a Responses endpoint, and "Gemini Native generateContent" for Gemini. Then click "Start routing" in the "Routing" tab on the Claude Code page. A wrong format, or not having started routing, usually produces a 404 or 405 error.
### API Key Invalid
@@ -73,11 +96,11 @@ With local routing on, a switch takes effect immediately for subsequent requests
**Steps**:
1. Find the built-in official provider in the provider list (such as Claude Official, OpenAI Official, Google Official, Grok Official; if you deleted it, add it again from the presets)
2. Click "Enable"
2. Click "Enable" (you can't switch to an official provider in Routing mode; click "Back to direct" first; Codex's OpenAI Official card is the exception)
3. Restart the corresponding CLI tool
4. Follow the CLI tool's login flow
## Local Routing Issues
## Routing and Aggregation Issues
### Local Routing Fails to Start
@@ -93,7 +116,11 @@ With local routing on, a switch takes effect immediately for subsequent requests
netstat -ano | findstr :15721
```
2. Close the program occupying the port
3. Or, in "Settings → Routing → Local Routing", turn off "Routing Master Switch" first, switch to another port (1024–65535), click "Save", then turn it back on
3. Or, in "Settings → Local routing → Service", stop the routing service first (if apps are still using routing, switch them back to direct first), change the "Listen port" to another port (1024–65535), and click "Save and restart service"
### Why Did the Address in the Config File Become 127.0.0.1 After Starting Routing
In Routing and Aggregation modes, the tool's requests go to CC Switch's local routing first (by default `http://127.0.0.1:15721`) and are then forwarded to the provider you selected, so the tool's config file only holds the local address and the placeholder key `PROXY_MANAGED`; Claude Code's model names are also written as fixed aliases such as `claude-sonnet-5` (the `/model` menu still shows the real model names). The real provider address, Key and models are all kept in CC Switch. Routing and Aggregation need CC Switch to keep running; quitting CC Switch automatically writes back to direct, and it reconnects on the next start.
### Request Timeout with Local Routing On
@@ -107,23 +134,23 @@ With local routing on, a switch takes effect immediately for subsequent requests
2. Try accessing the provider API directly (disable local routing)
3. Check if provider configuration is correct
### Configuration Not Restored After Disabling Local Routing
### Configuration Not Restored After Going Back to Direct
**Possible cause**: Local routing exited abnormally
**Possible cause**: CC Switch exited abnormally
**Solution**:
1. Edit the current provider
2. Check if the endpoint URL is correct
3. Save to update the configuration
1. Reopen CC Switch; on startup it restores each tool's config according to the state on this device
2. Or click "Back to direct" on the corresponding app page; "Switch all back to direct" in "Settings → Local routing" handles all apps at once
3. If it's still wrong, check that the current provider's endpoint URL is correct; you can also find the original config files from before CC Switch first rewrote them in `~/.cc-switch/backups/live-first-write/`
## Failover Issues
### Failover Not Triggering
**Checklist**:
- [ ] Is local routing running
- [ ] Is routing enabled for the corresponding app
- [ ] Is auto failover enabled
- [ ] Is the corresponding app in Routing mode (Aggregation mode doesn't do failover)
- [ ] Is the local routing service running
- [ ] Is auto failover on in the "Routing" tab on that app's page
- [ ] Are there backup providers in the queue
### Failover Triggering Too Frequently
@@ -141,7 +168,7 @@ With local routing on, a switch takes effect immediately for subsequent requests
**Solutions**:
1. Wait for the recovery wait time to expire (default 60 seconds)
2. Or restart local routing to reset states
2. Or, in "Settings → Local routing → Service", stop and restart the routing service to reset states
## Data Issues
@@ -152,8 +179,8 @@ With local routing on, a switch takes effect immediately for subsequent requests
- Database corruption
**Solutions**:
1. Check if the `~/.cc-switch/` directory exists
2. Restore from backup: `~/.cc-switch/backups/`
1. Check if the `~/.cc-switch/` directory exists (if you changed the configuration directory under "Settings → Data → Location", use the changed directory)
2. Restore from backup: "Settings → Data → Backup & Restore" (backup files are in `~/.cc-switch/backups/`)
3. Or import from a previously exported configuration file
### Import Configuration Failed
@@ -170,8 +197,8 @@ With local routing on, a switch takes effect immediately for subsequent requests
### Usage Statistics Data Is Empty
**Checklist**:
- [ ] Is "Auto-Scan Session Logs" on, and does the corresponding CLI have session history (the data source when local routing is off)
- [ ] If you rely on routing request logs: is local routing running, is routing enabled for the corresponding app, and is "Record Request Usage" on
- [ ] Is "Scan session logs automatically" on, and does the corresponding CLI have session history (the data source when local routing is off)
- [ ] If you rely on routing request logs: is local routing running, is the corresponding app in Routing or Aggregation mode, and is "Record request usage" in "Settings → Local routing → Service" on
- [ ] Does the app support usage statistics (OpenClaw and Hermes don't yet)
## Quota & Balance
@@ -183,8 +210,8 @@ Only **OAuth account** providers (GitHub Copilot, Codex OAuth reverse proxy, xAI
### Official subscription provider shows no quota
**Check**:
1. Confirm the provider is in "Currently Active" state (inactive providers do not trigger queries)
2. For Copilot / Codex OAuth, check whether the OAuth token is still valid; if the card shows "Session expired", log in again in **Settings → Auth**
1. Confirm the provider is in "In use" state (providers not in use do not trigger queries)
2. For Copilot / Codex OAuth, check whether the OAuth token is still valid; if the card shows "Session expired", log in again in **Accounts** in the sidebar
3. Check network connectivity
4. Click the refresh icon on the card to manually re-query
@@ -194,7 +221,7 @@ Only **OAuth account** providers (GitHub Copilot, Codex OAuth reverse proxy, xAI
1. Confirm the "Enable usage query" toggle is on in the "Usage Query" panel
2. A suitable built-in template is selected and saved
3. Click "Test script" to see the specific error
4. The provider must be in "Currently Active" state for background auto-refresh
4. The provider must be in "In use" state for background auto-refresh
### Codex usage does not match the direct-connection numbers
@@ -210,14 +237,14 @@ See the full disclaimer in the [v3.13.0 Release Notes → Risk Notice](../../../
### How do I log in to Codex OAuth?
See the complete Device Code login flow (verification code + browser authorization), both entry points (Add Provider panel / OAuth Authentication Center), multi-account management, and common failure scenarios in [2.1 Add Provider → Codex OAuth Reverse Proxy (Claude Provider)](../2-providers/2.1-add.md#codex-oauth-reverse-proxy-claude-provider).
See the complete Device Code login flow (verification code + browser authorization), both entry points (Add Provider panel / Accounts), multi-account management, and common failure scenarios in [2.1 Add Provider → Codex OAuth Reverse Proxy (Claude Provider)](../2-providers/2.1-add.md#codex-oauth-reverse-proxy-claude-provider).
### Codex OAuth logged in but no quota shown
**Solutions**:
1. Confirm the OAuth login flow is completed in **OAuth Authentication Center** (Settings → Auth, with the Beta label)
1. Confirm the OAuth login flow is completed in **Accounts** in the sidebar
2. Check whether the token is still valid — if the card shows "Session expired", the token cannot be refreshed
3. If expired, remove the account in the OAuth Authentication Center and log in again
3. If expired, remove the account in Accounts and log in again
## Other Issues
@@ -237,7 +264,7 @@ See the complete Device Code login flow (verification code + browser authorizati
**Solutions**:
1. Try switching themes (light/dark)
2. Restart the app
3. Delete `~/.cc-switch/settings.json` to reset settings
3. Delete `~/.cc-switch/settings.json` to reset settings (each app's current-provider pointer is also recorded in this file, so you'll need to confirm them again after the reset)
### Update Failed
@@ -277,7 +304,7 @@ If none of the above solutions work:
### Log Files
CC Switch stores logs under its application configuration directory. By default this is `.cc-switch` in your home directory; if you changed the configuration directory in Advanced Settings, use that custom location instead.
CC Switch stores logs under its application configuration directory. By default this is `.cc-switch` in your home directory; if you changed the configuration directory under "Settings → Data → Location", use that custom location instead.
When submitting an Issue, attach the files relevant to the problem:
+7 -8
View File
@@ -39,7 +39,7 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&...
| Parameter | Required | Description |
|-----------|----------|-------------|
| `resource` | Yes | Resource type: `provider` / `mcp` / `prompt` / `skill` |
| `app` | Yes | App type (needed for provider and prompt): `claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `openclaw` / `hermes`; prompt also supports `pi` |
| `app` | Yes | App type (needed for provider and prompt): `claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `openclaw` / `hermes`; prompt also supports `pi`. Provider deep-link import is not yet supported for Claude Desktop, Pi, or MiniMax Code |
| `name` | Required for provider and prompt | Name (for MCP, the server ID comes from the key under `mcpServers` in `config`; not needed for Skill) |
**Provider parameters** (resource=provider):
@@ -79,11 +79,11 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&...
| Parameter | Required | Description |
|-----------|----------|-------------|
| `apps` | Yes | App list (comma-separated, e.g., `claude,codex,gemini,grokbuild`). Available values: `claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `hermes`; MiniMax Code is not supported yet |
| `apps` | Yes | App list (comma-separated, e.g., `claude,codex,gemini,grokbuild`). Available values: `claude` / `codex` / `gemini` / `grokbuild` (`grok` also works) / `opencode` / `hermes`; `openclaw` does not support MCP and is ignored; Pi and MiniMax Code are not supported yet |
| `config` | Yes | MCP configuration JSON in the form `{"mcpServers": {"<server ID>": {...}}}`, Base64-encoded (then URL-escaped) |
| `enabled` | No | Whether to enable (boolean) |
**Skill parameters** (resource=skill):
**Skill parameters** (resource=skill): a deep link adds a Skill repository and does not install a Skill directly; after adding it, go to the "Skills" page and choose which Skill to install.
| Parameter | Required | Description |
|-----------|----------|-------------|
@@ -123,7 +123,7 @@ Here `content` is the Base64 encoding of a sample Chinese prompt: a heading mean
### Import Skill
```
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
ccswitch://v1/import?resource=skill&repo=owner/repo&directory=skills/my-skill&branch=main
```
## Generate Deep Links
@@ -171,6 +171,8 @@ A confirmation dialog is shown before import, containing:
- Configuration preview
- Confirm/Cancel buttons
What confirming does depends on the type: a provider appears in the provider list of the matching app and is not switched to automatically; an MCP server is written immediately to the configuration files of all specified apps; a prompt is enabled immediately after import, and other prompts in the same app are disabled. If the configuration contains suspicious content (addresses pointing to this machine or an internal network, environment variables that can change how a process loads, running an entire command through a shell, usage-query scripts, and so on), the dialog shows a risk warning, so check each item carefully.
**Security tip**: Only import configurations from trusted sources.
## Protocol Registration
@@ -184,10 +186,7 @@ CC Switch automatically registers the `ccswitch://` protocol during installation
If the protocol is not registered correctly:
**macOS**:
Reinstall the app, or run:
```bash
/usr/bin/open -a "CC Switch" --args --register-protocol
```
Reinstall the app (put CC Switch in the Applications folder and open it at least once).
**Windows**:
Reinstall the app, or check the registry:
@@ -37,10 +37,10 @@ Click the "View Details" button to see the details:
| 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 |
| User Environment Variable (Registry) | Windows user-level environment variable |
| System Environment Variable (Registry) | Windows system-level environment variable |
| System Environment Variable | macOS/Linux variable in the current process environment |
| Shell configuration file | macOS/Linux shell configuration file (such as `~/.zshrc`), shown as a file path in the UI |
## Resolve Conflicts
@@ -52,8 +52,8 @@ Click the "View Details" button to see the details:
### Remove Variables
1. Click the "Delete Selected" button
2. Confirm the removal operation
3. CC Switch will automatically back up and remove the selected variables
2. Click "Confirm Delete" in the "Confirm Delete Environment Variables" dialog
3. CC Switch will automatically back up and remove the selected variables; after removal, restart the app or terminal for it to take effect
### Automatic Backup
@@ -62,13 +62,14 @@ A backup is automatically created before removal:
- Backup location: `~/.cc-switch/backups/env-backup-<timestamp>.json`
- Backup format: JSON file
- Includes variable name, value, source, and other information
- You can view these backups (named "Environment variable cleanup backups") under "Other Backups" below **Settings → Data → Backup & Restore**, and clean them up there too; after cleaning up, the original values of the removed variables can no longer be looked up
## Dismiss Warning
If you confirm the conflict does not affect usage, you can:
1. Click the close button (×) on the right side of the warning banner
2. The warning will be temporarily hidden
2. The warning will be hidden for the current run
3. Detection will run again on next launch
## Manual Resolution
+18 -16
View File
@@ -34,7 +34,8 @@
│ ├── 4.2 App Routing
│ ├── 4.3 Failover
│ ├── 4.4 Usage Statistics
│ └── 4.5 Connectivity Check
│ ├── 4.5 Connectivity Check
│ └── 4.6 Aggregation Mode
│
└── 5. FAQ
├── 5.1 Configuration Files
@@ -51,16 +52,16 @@
|------|-------------|
| [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.3-interface.md](./1-getting-started/1.3-interface.md) | Sidebar layout, connection mode tabs, 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 |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | The six Settings groups: General, App config, Local routing, Network, Data, About |
### 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.2-switch.md](./2-providers/2.2-switch.md) | Direct / Routing / Aggregation, tray switching, activation methods |
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, global settings and edit conflicts |
| [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 |
@@ -71,7 +72,7 @@
| 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.2-prompts.md](./3-extensions/3.2-prompts.md) | Create prompts, enable/switch, target files |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | Discover skills, install/uninstall, repository management |
| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | Session Manager: browse, search, resume, delete sessions |
| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | Workspace files and daily memory (OpenClaw) |
@@ -85,6 +86,7 @@
| [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) | Connectivity check, check parameters |
| [4.6-aggregation.md](./4-proxy/4.6-aggregation.md) | Aggregation mode, default provider, `ccs-` prefix, Codex restart |
### 5. FAQ
@@ -106,19 +108,19 @@
## Version Information
- Documentation version: v3.20.4
- Last updated: 2026-09-26
- Applicable to CC Switch v3.20.4+
- Documentation version: v4.0.4
- Last updated: 2026-10-07
- Applicable to CC Switch v4.0.4+
### Recent Major Changes
### Recent Major Changes (v4.0)
- **New managed apps**: Grok Build (v3.18.0), Pi (v3.20.0), and MiniMax Code (v3.20.4), bringing the total to 10 managed apps — see [1.1 Introduction](./1-getting-started/1.1-introduction.md)
- **Official Codex presets now connect directly via native Responses**: DeepSeek, Zhipu GLM (v3.20.2), Kimi (v3.20.3), and others no longer need local routing for protocol conversion — see [2.1 Add Provider](./2-providers/2.1-add.md)
- **Codex switching writes only config.toml**: third-party API keys are no longer written to `auth.json` (v3.20.1) — see [1.5 Personalization → Codex App Enhancements](./1-getting-started/1.5-settings.md#codex-app-enhancements)
- **"Upstream Format" replaces the "Needs Local Routing" toggle** (v3.16.5) — see [2.1 Add Provider](./2-providers/2.1-add.md#upstream-format-and-model-mapping-for-codex--grok-build)
- **Connectivity check replaces model test**: it only checks whether the address is reachable and no longer sends real model requests (v3.16.3) — see [4.5 Connectivity Check](./4-proxy/4.5-model-test.md)
- **Usage statistics without local routing**: usage is imported from each tool's local session logs — see [4.4 Usage Statistics](./4-proxy/4.4-usage.md)
- **Cloud sync supports S3-compatible storage** — see [1.5 Personalization](./1-getting-started/1.5-settings.md)
- **Redesigned interface**: the top navigation is replaced by a left sidebar, with separate pages for Usage, Accounts, MCP, Skills, Prompts, Sessions, and Apps; Settings is split into six groups: General, App config, Local routing, Network, Data, About — see [1.3 Interface Overview](./1-getting-started/1.3-interface.md) and [1.5 Personalization](./1-getting-started/1.5-settings.md)
- **Three connection modes: Direct / Routing / Aggregation**: chosen at the top of each app page; going back to direct is one step — see [2.2 Switch Provider](./2-providers/2.2-switch.md)
- **New Aggregation mode**: Claude Code and Codex can mix models from several providers in one session — see [4.6 Aggregation Mode](./4-proxy/4.6-aggregation.md)
- **Switching only changes key fields**: everything other than the address, key, model, and other key fields is left as is; common config snippets are no longer used — see [2.3 Edit Provider](./2-providers/2.3-edit.md)
- **Accounts**: ChatGPT, GitHub Copilot, xAI, and other sign-ins are managed in one place under **Accounts** in the sidebar — see [1.5 Personalization](./1-getting-started/1.5-settings.md)
- **Apps page**: install and upgrade each CLI tool, and choose which apps show in the sidebar — see [1.2 Installation Guide](./1-getting-started/1.2-installation.md)
- For the full list of changes, see the [v4.0 release notes](../../release-notes/v4.0.4-en.md)
## Contributing
@@ -30,8 +30,10 @@ CC Switch は統一されたインターフェースでこれらの問題を解
- **Prompts**:システムプロンプトのプリセットを管理し、さまざまなシーンで素早く切り替え
- **Skills**:スキル拡張のインストールと管理
- **セッションマネージャー**:各ツールのセッション履歴を閲覧・検索し、再開コマンドをコピーして会話を続行
- **アカウント**:ChatGPT(Codex)、GitHub Copilot、xAI などの OAuth アカウントを一元管理
### ローカルルーティングと高可用性
### 接続モード、ローカルルーティング、高可用性
- 3 つの接続モード:**直接接続**(クライアントがプロバイダーに直接接続)、**ルーティング**(リクエストをこのマシン上の CC Switch 経由で転送)、**集約**(Claude Code と Codex 専用。複数プロバイダーのモデルを `/model` に並べて表示)
- ローカルルーティングが Anthropic Messages、OpenAI Chat Completions、OpenAI Responses、Gemini Native の間でリクエスト形式を変換
- 自動フェイルオーバー、メインプロバイダーの障害時にバックアップへ自動切り替え
- サーキットブレーカー機能で、障害プロバイダーへの頻繁なリトライを防止
@@ -55,7 +57,7 @@ CC Switch は統一されたインターフェースでこれらの問題を解
- **切り替え**:同時に有効にできるプロバイダーは 1 つだけで、切り替え時にそのツールの設定ファイルを書き換えます。
- **共存**:複数のプロバイダーをツール自身の設定に同時に書き込み、どれを使うかはツール側で選択します。
どの機能(ローカルルーティング、トレイでの切り替え、MCP、Skills、プロンプト、セッション、使用量統計)に対応しているかはツールによって異なります。詳細は [1.3 インターフェース概要](./1.3-interface.md) と各機能の章を参照してください。
どの機能(ローカルルーティング、集約、トレイでの切り替え、MCP、Skills、プロンプト、セッション、使用量統計)に対応しているかはツールによって異なります。詳細は [1.3 インターフェース概要](./1.3-interface.md) と各機能の章を参照してください。
## 対応プラットフォーム
@@ -18,7 +18,7 @@ CC Switch 自体には Node.js などのランタイムは不要です。CC Swit
### 方法 1:CC Switch からワンクリックでインストール(推奨)
「設定 → バージョン情報」を開くと、ツール一覧に各ツールの現在のバージョンと最新バージョンが表示されます。未インストールのツールにはインストールボタンがあり、インストール済みのツールは個別に更新するか「すべて更新」で一括更新できます。対応ツールは Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi です。詳細は [1.5 個人設定 → バージョン情報ページ](./1.5-settings.md#バージョン情報ページ) を参照してください。
サイドバー下部の「アプリ」をクリックすると、リストに各ツールの現在のバージョンと最新バージョンが表示されます。未インストールのツールにはインストールボタンがあり、インストール済みのツールは個別に更新できます。ここでサイドバーに表示するアプリを選ぶこともできます。対応ツールは Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code です。Claude Desktop はデスクトップアプリのため、ここではインストールできません。詳細は [1.3 インターフェース概要](./1.3-interface.md#アプリ管理ページ) を参照してください。
### 方法 2:各ツールの公式手順でインストール
@@ -33,7 +33,7 @@ CC Switch 自体には Node.js などのランタイムは不要です。CC Swit
| Hermes | `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash` |
| Pi | `npm i -g @earendil-works/pi-coding-agent` |
Claude Desktop、MiniMax Code、および Windows でのインストール方法は、各ツールの公式ドキュメントを参照してください。
Claude Desktop、MiniMax Code(方法 1 でインストール可能)、および Windows でのインストール方法は、各ツールの公式ドキュメントを参照してください。
npm でインストールするには、先に Node.js が必要です。必要なバージョンはツールによって異なります(例:Claude Code は 22 以上、OpenClaw は 24.16 以上の 24.x または 26.1 以上)。現行の LTS 版をインストールすることをおすすめします。バージョンが足りない場合は npm が知らせてくれます。
@@ -150,7 +150,7 @@ chmod +x CC-Switch-v{バージョン}-Linux-*.AppImage
1. アプリウィンドウが正常に表示される
2. システムトレイに CC Switch のアイコンが表示される
3. アプリ切り替えに有効化された管理対象アプリが表示され、目的のアプリパネルへ切り替えられる
3. 左サイドバーのアプリリストに表示設定済みの管理対象アプリが並び、クリックすると該当アプリのプロバイダーページに入れる
## 自動更新
@@ -2,154 +2,156 @@
## メイン画面のレイアウト
![image-20260108001629138](../../assets/image-20260108001629138.png)
![CC Switch メイン画面](../../../../assets/release-notes/v4.0.0/main-en.png)
## 上部ナビゲーションバー
メインウィンドウは左のサイドバーと右のコンテンツエリアに分かれています:
| 番号 | 要素 | 機能説明 |
|------|------|----------|
| ① | Logo | クリックで公式サイト ccswitch.io にアクセス |
| ② | 設定ボタン | 設定ページを開く(ショートカット `Cmd/Ctrl + ,`) |
| ③ | ローカルルーティングスイッチ | Claude Code / Codex / Gemini CLI / Grok Build のページ:現在のアプリのローカルルーティングをオン/オフ(「設定 → ルーティング → ローカルルーティング」で「メインページにルーティング切り替えを表示」をオンにする必要があります)。Claude Desktop のページ:常に表示され、Claude Desktop が使用するローカルルーティングを起動/停止 |
| ④ | アプリ切り替え | 10 個の管理対象アプリを切り替え |
| ⑤ | 機能エリア | 現在のアプリで利用できる機能入口 |
| ⑥ | 追加ボタン | 新しいプロバイダーを追加 |
- **左サイドバー**:管理するアプリを選ぶ、またはグローバル機能ページを開く
- **コンテンツエリア**:上部はページヘッダー(アプリ名、「プロバイダーを追加」ボタン、⋯ メニュー)、その下に現在のページの内容
このほか、条件に応じて表示される入口がいくつかあります:
## 左サイドバー
- **プロジェクト切り替え**:デフォルトで表示されます(MiniMax Code のページを除く)。「設定 → 一般 → ホームページ表示」で「プロジェクト切り替えを表示」をオフにできます
- **フェイルオーバースイッチ**:「設定 → ルーティング → 自動フェイルオーバー」で「メインページにフェイルオーバー切り替えを表示」をオンにすると表示されます
- **利用統計ボタン**:現在のアプリでローカルルーティングが有効なときに表示されます
左サイドバーは上から順に 3 つのブロックに分かれています:
### アプリ切り替え
| 領域 | 内容 |
|------|------|
| アプリリスト | 表示することにした管理対象アプリ(最大 10 個)。アプリをクリックすると、右側にそのプロバイダーページが表示されます。アプリ名の横の小さなマークは、現在ルーティング・集約・モデルマッピングのどれを使っているかを示し、問題があると「対応が必要」と表示されます |
| グローバルページ | MCP、Skills、プロンプト、セッション、アカウント、使用量(今日の費用があるときは横に「今日 $xx」と表示)。これらのページは特定のアプリに属さず、入口はそれぞれ 1 つだけです |
| 下部 | 「アプリ」(インストール、アップグレード、サイドバーに表示するアプリの選択)と「設定」 |
上部のアプリアイコンをクリックして、現在管理するアプリを切り替えます(ウィンドウが狭い場合、収まりきらないアプリは「その他のアプリ」メニューにまとめられます):
サイドバー上部の折りたたみボタンをクリックするとアイコンだけに縮み、もう一度クリックすると展開します。「アプリ」や「設定」の横に点が出ているときは、コマンドラインツールまたは CC Switch 本体に新しいバージョンがあります。
- **Claude** - Claude Code の設定を管理
> ショートカット `Cmd/Ctrl + ,` でいつでも設定を開けます。
### 管理対象アプリ
- **Claude Code** - Claude Code の設定を管理
- **Claude Desktop** - Claude Desktop のサードパーティプロバイダーと公式モードを管理
- **Codex** - Codex の設定を管理
- **Gemini** - Gemini CLI の設定を管理
- **Grok Build** - Grok Build の設定を管理
- **OpenCode** - OpenCode の設定を管理
- **OpenClaw** - OpenClaw の設定を管理
- **Hermes** - Hermes Agent のプロバイダーと Memory を管理
- **Grok Build** - Grok Build の設定を管理
- **Pi** - Pi のプロバイダーとモデルを管理
- **MiniMax Code** - MiniMax Code のカスタムプロバイダーを管理
切り替え後、プロバイダーリストに対応アプリの設定が表示されます。あまり使わないアプリは「設定 → 一般 → ホームページ表示」で非表示にできます。
あまり使わないアプリは、サイドバーの「アプリ」ページで表示をオフにできます。オフにするとサイドバーに表示されなくなり、MCP / Skills のアプリ列や、プロンプト・セッションのアプリ選択にも出なくなりますが、既存の設定には影響しません。
### 機能エリアボタン
### グローバルページ
表示される機能ボタンはアプリによって異なります:
| 入口 | 用途 |
|------|------|
| MCP | MCP サーバーを管理し、アプリごとに有効化します。[3.1 MCP](../3-extensions/3.1-mcp.md) を参照 |
| Skills | スキルのインストールと管理。[3.3 Skills](../3-extensions/3.3-skills.md) を参照 |
| プロンプト | システムプロンプトの管理。[3.2 Prompts](../3-extensions/3.2-prompts.md) を参照 |
| セッション | 各ツールのセッション履歴を閲覧・検索 |
| アカウント | ChatGPT(Codex)、GitHub Copilot、xAI などの OAuth アカウントを一元管理 |
| 使用量 | リクエスト統計の概要、トレンドグラフ、リクエストログ、プロバイダー/モデル統計、コストの料金設定 |
| アプリ | 機能エリアのボタン |
|------|------------|
| Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、MiniMax Code | Skills、Prompts、セッション、MCP |
| Pi | Skills、Prompts、セッション(Pi には MCP がありません) |
| Claude Desktop | Claude Code と同じ。操作対象は Claude Code のデータです |
| Hermes | Skills、メモリ、Hermes Web UI、MCP |
| OpenClaw | ワークスペース、環境変数、ツール、Agents、セッション |
すべてのアプリがすべての機能に対応しているわけではありません。Claude Desktop と OpenClaw は MCP、Skills の対象外です。Claude Desktop のページでの MCP、Skills、プロンプト、セッションの操作は、Claude Code のデータが対象です。
各アプリの MCP、Skills、Prompts の対応範囲は [3.1 MCP](../3-extensions/3.1-mcp.md)、[3.2 Prompts](../3-extensions/3.2-prompts.md)、[3.3 Skills](../3-extensions/3.3-skills.md) を参照してください。
## アプリページ
## プロバイダーカード
### アプリページのヘッダー
各プロバイダーはカード形式で表示されます。左から右へ以下の要素が含まれています:
ヘッダーにはアプリ名とページ名(例:「Claude Code プロバイダー」)が表示され、右側には次のものがあります:
### カード要素(左から右)
- **プロバイダーを追加**:新しいプロバイダーを追加
- **プロジェクト切り替え**:デフォルトでは非表示です。「設定 → 一般 → サイドバーとヘッダー」で「プロジェクト切り替えを表示」をオンにすると表示されます(MiniMax Code のページにはありません)
- **⋯ メニュー**:セッションを見る、設定ディレクトリ、インストールとアップグレード、サイドバーから隠す、このアプリの使用量を見る
- Hermes のヘッダーには「Web UI」ボタンもあります
| 番号 | 要素 | アイコン | 機能説明 |
|------|------|------|----------|
| ① | ドラッグハンドル | ≡ | 長押しして上下にドラッグしてプロバイダーの順序を調整 |
| ② | プロバイダーアイコン | 🔷 | プロバイダーのブランドアイコンを表示、カラーのカスタマイズ可能 |
| ③ | プロバイダー情報 | - | 名前、メモ/エンドポイントアドレス(クリックで公式サイトを開く) |
| ④ | 使用量情報 | - | 残額を表示、複数プランの場合はプラン数を表示 |
| ⑤ | 有効化ボタン | ▶ | 現在使用中のプロバイダーに切り替え |
| ⑥ | 編集ボタン | ✏️ | プロバイダー設定を編集 |
| ⑦ | 複製ボタン | 📋 | プロバイダーを複製(コピーを作成) |
| ⑧ | 接続チェック | 🧪 | プロバイダーのアドレスに到達できるかを確認し、レイテンシを表示 |
| ⑨ | 使用量クエリ | 📊 | 使用量クエリスクリプトを設定 |
| ⑩ | ターミナルを開く | ⌨️ | 作業ディレクトリを選択し、そのプロバイダーの設定でターミナルを開く(Claude Code のみ) |
| ⑪ | 削除ボタン | 🗑️ | プロバイダーを削除(現在有効な場合は無効) |
OpenClaw と Hermes では、ヘッダーの下にタブが並び、プロバイダーページと専用ページを切り替えられます:
> 💡 **ヒント**:操作ボタンエリア(⑤-⑪)はマウスホバー時に表示され、通常は非表示で画面をすっきり保ちます。
| アプリ | タブ |
|------|------|
| OpenClaw | プロバイダー、ワークスペース、設定 |
| Hermes | プロバイダー、メモリ |
一部のプロバイダーカードには **「ルーティングが必要」** または **「ルーティング非対応」** バッジが表示されます。前者は、そのプロバイダーを使うにはローカルルーティングを有効にする必要があること(例:API フォーマットの変換が必要な場合)を、後者は、そのプロバイダーをローカルルーティング経由で転送できないこと(例:Claude Official)を示します。
### 接続モード
### ボタンの詳細説明
Claude Code、Codex、Gemini CLI、Grok Build のプロバイダーページ上部には **直接接続 / ルーティング / 集約** の 3 つのタブがあります(集約は Claude Code と Codex のみ。Claude Desktop は直接接続 / モデルマッピング)。タブ上の点は現在有効なモードを示し、横の文字は今どのプロバイダーに接続しているかを示します。
| ボタン | 状態変化 | 説明 |
|------|----------|------|
| **有効化** | 有効化済みの場合は ✓ を表示して無効化 | フェイルオーバーモードでは「追加/キュー内」に変化 |
| **編集** | 常に使用可能 | 編集パネルを開いて設定を変更 |
| **複製** | 常に使用可能 | プロバイダーのコピーを作成、名前に `copy` が付加 |
| **接続チェック** | チェック中はローディングアニメーション | アドレスに到達できるかだけを確認し、実際のモデルリクエストは送信しません。公式プロバイダーと MiniMax Code のプロバイダーではグレーアウトして使用できません |
| **使用量クエリ** | ほとんどのプロバイダーで使用可能 | 使用量クエリのテンプレートまたはスクリプトを設定。Copilot、Codex OAuth、xAI OAuth などクォータが自動表示されるプロバイダーではグレーアウトして使用できません |
| **削除** | 現在有効な場合は半透明で無効 | 先に他のプロバイダーに切り替える必要あり |
タブをクリックしても、そのモードでのリストを見るだけで設定は変わりません。実際に切り替えるには、下に表示される結果が明記されたボタン「ルーティングを開始」「集約に切り替え」「直接接続に戻す」を押します。ルーティングは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md)、集約は [4.6 集約モード](../4-proxy/4.6-aggregation.md) を参照してください。
### カードの状態
### プロバイダーカード
| 状態 | 枠の色 | 説明 |
|------|----------|------|
| **現在有効** | 🔵 青い枠 | 通常モードで現在使用中のプロバイダー |
| **ルーティングアクティブ** | 🟢 緑の枠 | ローカルルーティング有効時に実際にリクエストを転送しているプロバイダー |
| **通常状態** | デフォルトの枠 | 有効化されていないプロバイダー |
| **フェイルオーバー中** | 優先度バッジを表示 | P1、P2 などのフェイルオーバー優先度を表示 |
各プロバイダーは 1 枚のカードで、左から順に次の要素があります:
### ヘルスステータスバッジ
| 要素 | 機能説明 |
|------|----------|
| ドラッグハンドル | ドラッグしてプロバイダーの順序を調整(ホバー時に表示) |
| プロバイダーアイコン | ブランドアイコン |
| プロバイダー情報 | 名前、メモ/エンドポイントアドレス(クリックで公式サイトを開く)。名前の横に「公式」「ルーティングが必要」などのバッジが付くことがあります |
| 使用量情報 | 残りクォータまたは残額。複数プランの場合は複数行で表示 |
| 状態 / 主な操作 | 現在有効なカードには「使用中」(ルーティングモードでは「転送中」)と表示されます。それ以外のカードは再生ボタンで、直接接続では切り替え、ルーティングでは「ここへ転送」、集約ではデフォルトに設定または追加に使います |
| 編集ボタン | プロバイダー設定を編集 |
| ⋯ その他 | 複製、接続チェック、使用量クエリの設定、ターミナルを開く(Claude Code のみ)、削除 |
ローカルルーティングを有効にすると、フェイルオーバーキューに参加しているプロバイダーにヘルスステータスが表示されます:
使用中のプロバイダーは削除できないため、先に他のプロバイダーへ切り替えてください。「接続チェック」はアドレスに到達できるかだけを確認し、実際のモデルリクエストは送信しません。公式プロバイダーと MiniMax Code のプロバイダーでは使用できません。Copilot、Codex OAuth、xAI OAuth などクォータが自動表示されるプロバイダーには「利用状況を設定」がありません。
| バッジ | 色 | 説明 |
|------|------|------|
| 正常 | 🟢 緑 | 連続失敗回数 0 |
| 低下 | 🟡 黄 | 失敗はあるが、サーキットブレーカーは発動していない |
| サーキットオープン | 🔴 赤 | サーキットブレーカーが発動し、一時的にスキップ中(しきい値は [4.3 フェイルオーバー](../4-proxy/4.3-failover.md#サーキットブレーカーの設定) を参照) |
**「ルーティングが必要」** バッジは、そのプロバイダーがローカルルーティング経由でしか使えない(例:API フォーマットの変換が必要)ことを示します。直接接続のまま切り替えても、クライアントはそのプロバイダーを使えません。**公式サブスクリプションはルーティングを経由せず**(Codex の OpenAI Official は例外)、ルーティングモードでは切り替えられません。
OpenCode、OpenClaw、Hermes、Pi、MiniMax Code は「共存」型アプリで、カードのボタンは「追加 / 削除」(Pi は「有効化 / 削除」)です。直接接続 / ルーティング / 集約のタブはありません。
### フェイルオーバーキューとヘルスステータス
ルーティングモードでは、プロバイダーページが「キュー · 優先順」と「キュー外」の 2 つに分かれます。キュー内のプロバイダーは順番にリクエストを受け、前のものが連続して失敗すると自動的に次へ切り替わります。上へ移動、下へ移動、またはドラッグで順序を調整できます。設定方法は [4.3 フェイルオーバー](../4-proxy/4.3-failover.md) を参照してください。
キュー内のプロバイダーにはヘルスステータスが表示されます:
| ステータス | 説明 |
|------|------|
| 正常 | 連続失敗回数 0 |
| 低下 | 失敗はあるが、サーキットブレーカーは発動していない |
| サーキットオープン | サーキットブレーカーが発動し、一時的にスキップ中(しきい値は [4.3 フェイルオーバー](../4-proxy/4.3-failover.md#サーキットブレーカーの設定) を参照) |
### アプリ管理ページ
サイドバー下部の「アプリ」ページでは、コマンドラインツールを管理します:
- 各ツールの現在のバージョンと最新バージョンを確認し、未インストールのものをインストール、インストール済みのものをアップグレード
- サイドバーに表示するアプリを選択
- 「手動インストールコマンド」で各ツールのインストールコマンドをコピー
Claude Desktop はデスクトップアプリのため、ここではインストールやアップグレードはできず、ページには接続済みかどうかだけが表示されます。起動時に新しいバージョンを確認するかどうかは、「設定 → 一般 → 各アプリの新しいバージョン」で制御します。
## システムトレイ
CC Switch はシステムトレイにアイコンを表示し、クイック操作の入口を提供します。
### トレイメニュー構造
<!-- TODO(v4 screenshot): Expanded tray menu (with app submenus such as Claude Code / Codex) -->
![image-20260108002153668](../../assets/image-20260108002153668.png)
### メニュー機能
### トレイメニュー
| メニュー項目 | 機能 |
|--------|------|
| メインウィンドウを開く | メインウィンドウを表示してフォーカス |
| 公式サイトを開く | ブラウザで ccswitch.io を開く |
| プロジェクト | プロジェクト(プロバイダー、MCP、Skills、プロンプトの状態一式)を切り替え |
| アプリサブメニュー | Claude / Codex / Gemini / Grok Build ごとの折りたたみサブメニュー(例:「Claude · PackyCode」)。現在のプロバイダーとキャッシュ済み使用量サマリーを表示可能 |
| プロバイダーリスト | 各サブメニュー内でクリックして切り替え、現在有効なものにはチェックマークを表示 |
| CC Switch を開く | メインウィンドウを表示してフォーカスし、常に最前面に出す |
| アプリサブメニュー | Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build の 5 つの切り替え型アプリにそれぞれサブメニューがあり、タイトルに現在のプロバイダーとモードを表示します。サブメニュー内でプロバイダーをクリックすると切り替わり、現在のものにはチェックマークが付きます。アプリのページを開く、プロバイダーを追加することもでき、アプリによってはクォータの概要も表示されます |
| プロジェクト | プロジェクト(プロバイダー、MCP、Skills、プロンプトの状態一式)を切り替え。「プロジェクト切り替えを表示」をオンにしたときのみ表示 |
| 軽量モード | チェックボックスで切り替え、トレイ専用モードの開始/終了 |
| 終了 | アプリを完全に終了 |
| 公式サイトを開く | ブラウザで ccswitch.io を開く |
| CC Switch を終了 | アプリを完全に終了。ルーティングまたは集約を使っているアプリがあるときは、メニュー項目に「ルーティングサービスが停止します」と表示されます |
> **注意**:各トレイサブメニューのタイトルには現在のプロバイダー名が表示されます(例:「Claude · PackyCode」)。プロバイダーが設定されていないアプリでは、無効化された「(プロバイダーなし)」エントリが表示されます。トレイに含まれるのは現在、ローカルルーティングに対応する Claude Code、Codex、Gemini CLI、Grok Build の 4 つのアプリだけです。その他のアプリはメイン画面で切り替えてください。メイン画面にどのアプリを表示するかは、設定の「ホームページ表示」で制御します。
ルーティングサービスが起動していない、あるアプリの切り替えに失敗したなどの問題はメニューの一番上に表示され、トレイアイコンにも小さな点が付きます。
> **注意**:共存型(累加式)アプリ(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code)はトレイに含まれないため、メイン画面で操作してください。プロバイダーが設定されていないアプリは、サブメニューに該当する案内が表示されます。トレイにどのアプリを表示するかは、「アプリ」ページの表示スイッチで決まります。
### 多言語対応
トレイメニューは 4 つの言語に対応し、設定に応じて自動的に切り替わります:
| 言語 | メインウィンドウを開く | 終了 |
|------|-----------|------|
| 簡体中文 | 打开主界面 | 退出 |
| 繁體中文 | 開啟主介面 | 退出 |
| English | Open main window | Quit |
| 日本語 | メインウィンドウを開く | 終了 |
トレイメニューはインターフェース言語に従い、簡体中文、繁體中文、English、日本語に対応しています。言語を設定していない場合はシステム言語が使われます。
### 軽量モード
トレイメニューには **軽量モード** のトグル(チェックボックス)があります。有効にすると:
トレイメニューには **軽量モード** のチェックボックスがあります。有効にすると:
- メインウィンドウが閉じられ、リソースが解放される
- アプリはシステムトレイのみで動作を継続
- トレイのサブメニューからプロバイダーの切り替えが可能
- macOS では Dock アイコンも非表示になる
軽量モードを終了するには、トグルのチェックを外すか「メインウィンドウを開く」をクリックします。メインウィンドウが再構築されて表示されます。
軽量モードを終了するには、チェックを外すか「CC Switch を開く」をクリックします。メインウィンドウが再構築されて表示されます。
### 使用シーン
@@ -160,64 +162,58 @@ CC Switch はシステムトレイにアイコンを表示し、クイック操
- バックグラウンド実行中の設定管理
- 軽量モードでリソース使用量を最小化
## 設定ページ
## 設定
設定ページは複数のタブに分かれています:
サイドバー下部の「設定」をクリックすると、サイドバーが設定の目次に切り替わり、右側に現在のグループが表示されます。「戻る」をクリックするか `Esc` を押すとメイン画面に戻ります。設定は 6 つのグループに分かれています:
### 一般タブ
### 一般
- 言語設定(簡体中文/繁體中文/English/日本語)
- テーマ設定(システムに合わせる/ライト/ダーク)
- ホームページ表示(アプリとプロジェクト切り替えの入口)
- スキル保存場所と同期方法
- Codex アプリ拡張(公式ログインの保持、セッション履歴の統一)
- ウィンドウ動作(起動時に自動実行、閉じる動作)
- 優先ターミナル
- **外観**:表示言語(簡体中文/繁體中文/English/日本語)、ライト/ダークテーマ(システムに合わせる/ライト/ダーク)
- **サイドバーとヘッダー**:サイドバーに表示するアプリ(「アプリ」ページへ移動)、プロジェクト切り替えを表示
- **各アプリの新しいバージョン**:起動時に各アプリの新しいバージョンを確認
- **ウィンドウとターミナル**:起動時に自動実行、閉じるボタンの動作(トレイへ隠す/終了)、優先ターミナル
### ルーティングタブ
### アプリ設定
- ローカルルーティング(ルーティング総スイッチ、アプリごとの有効化、リッスンアドレスとポート)
- 各アプリの設定ディレクトリの上書き(Claude Desktop と MiniMax Code を除く)
- 各アプリ固有のオプション。例:Claude Code の「Claude Code 拡張に適用」「Claude Code の初回確認をスキップ」、Codex の直接切替時に公式ログインを保持
### ローカルルーティング
- サービス:待ち受けアドレスとポート、起動/停止
- ルーティングを使用中のアプリ
- 自動フェイルオーバー
- 整流器
- すべて直接接続に戻す
### ネットワーク
- グローバル送信プロキシ
### 認証タブ
### データ
- OAuth 認証センター(GitHub Copilot、ChatGPT、xAI アカウント)
### 詳細タブ
- 設定ディレクトリ
- データ管理(インポート/エクスポート)
- バックアップと復元
- 保存場所(CC Switch 設定ディレクトリ)
- データ管理(SQL のインポート/エクスポート)
- バックアップと復元(「その他のバックアップ」の一覧を含む)
- クラウド同期
- 接続チェック設定
- アプリ診断ログ
### 利用統計タブ
### 情報
- リクエスト統計の概要
- トレンドグラフ
- リクエストログ
- プロバイダー/モデル統計
- コスト計算
### バージョン情報タブ
- バージョン情報と更新の確認
- CLI ツールのバージョン検出、インストール、更新
- バージョン情報、更新の確認
- GitHub、公式サイト、リリースノート
## ショートカットキー
| ショートカット | 機能 |
|--------|------|
| `Cmd/Ctrl + ,` | 設定を開く |
| `Cmd/Ctrl + F` | プロバイダーを検索 |
| `Esc` | ダイアログ/検索を閉じる |
| `Cmd/Ctrl + F` | プロバイダーを検索(プロバイダーページで) |
| `Esc` | 検索を閉じる。設定ページではメイン画面に戻る |
## 検索機能
`Cmd/Ctrl + F` で検索ボックスを開きます:
プロバイダーページで `Cmd/Ctrl + F` を押すと検索ボックスが開きます:
- 名前、メモ、URL で検索可能
- プロバイダーリストをリアルタイムでフィルタリング
@@ -4,28 +4,28 @@
## ステップ 1:プロバイダーの追加
1. メイン画面右上の **+** ボタンをクリック
1. 左サイドバーで管理したいツールを選び、ページ右上の **+**(プロバイダーを追加)をクリック
2. 「プロバイダータイプ」からプロバイダーを選択
- よく使われるプリセット:Zhipu GLM、MiniMax、DeepSeek、Kimi、PackyCode
- または「カスタム」を選択して手動設定
3. **API Key** を入力
4. 「追加」をクリック
![image-20260108002807657](../../assets/image-20260108002807657.png)
<!-- TODO(v4 screenshot): Add provider panel: search box, preset list and API Key form -->
> 💡 **ヒント**:プリセットではエンドポイントアドレスが自動入力されるため、API Key のみ入力すれば使用できます。
> 💡 **ヒント**:追加パネルは中国語名とドメインでの検索に対応しており、同じ提供元のプランやリージョンは 1 行にまとめられます。プリセットではエンドポイントアドレスが自動入力されるため、API Key のみ入力すれば使用できます。
## ステップ 2:プロバイダーの切り替え
追加が完了すると、プロバイダーがリストに表示されます。
**方法 1:メイン画面で切り替え**
- プロバイダーカードの「有効化」ボタンをクリック
**方法 1:アプリページで切り替え**
- プロバイダーカードの「切り替え」ボタンをクリックすると、状態が「使用中」になります
- OpenCode、OpenClaw、Hermes、MiniMax Code は共存型アプリで、ボタンは「追加」(Pi は「有効化」)です。複数のプロバイダーを同時に追加できます
**方法 2:トレイで素早く切り替え**
- システムトレイアイコンを右クリック
- プロバイダー名を直接クリック(Claude Code、Codex、Gemini CLI、Grok Build に対応)
- ツールごとに 1 行、「名前 · モード · プロバイダー · クォータ」と表示されます。サブメニューでプロバイダー名を直接クリックします(Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build に対応)
## ステップ 3:反映方法
@@ -42,17 +42,27 @@
| OpenClaw | ターミナルの再起動が必要 |
| Hermes / Pi / MiniMax Code | プロバイダーを追加するとツールの設定に書き込まれます。Pi と MiniMax Code ではツール側で使用するモデルを選択し、Hermes ではカードの「有効化」をクリックして現在のプロバイダーに設定できます |
ローカルルーティングを有効にしている場合、Claude Code、Codex、Gemini CLI、Grok Build でのプロバイダー切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
ルーティングモードの場合、Claude Code、Codex、Gemini CLI、Grok Build でのプロバイダー切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
## 直接接続、ルーティング、集約(任意)
Claude Code、Codex、Gemini CLI、Grok Build のページ上部には「直接接続 / ルーティング」のタブがあり、Claude Code と Codex には「集約」もあります。タブをクリックしても表示が切り替わるだけで設定は変更されません。実際に切り替えるには、ページ上の結果が明記されたボタン「ルーティングを開始」「集約に切り替え」を押します。直接接続に戻すときは「直接接続に戻す」を押します。
- **直接接続**(デフォルト):クライアントがプロバイダーに直接接続します。日常の利用ではこれを選びます
- **ルーティング**:リクエストをこのマシン上の CC Switch 経由で転送し(デフォルトは `127.0.0.1:15721`)、API フォーマットの変換やフェイルオーバーができます。Claude Code で OpenAI や Gemini 形式のプロバイダーを使いたい場合や、Codex で Claude を使いたい場合に選びます
- **集約**:複数プロバイダーのモデルを 1 つのモデルリストにまとめ、選んだモデルのプロバイダーへリクエストを送ります。フェイルオーバーは行いません
ルーティングと集約は CC Switch が起動し続けている必要があります。CC Switch を終了すると自動的に直接接続に戻り、次回起動時に再び接続されます。公式サブスクリプションはルーティングを経由しません(Codex の OpenAI Official は例外)。詳細は [ローカルルーティングの有効化](../4-proxy/4.1-service.md) を参照してください。
### Claude Code の初回インストール時の注意
Claude Code を初めて起動するときに**ログイン**の要求や初期化ガイドが表示される場合は、CC Switch で「Claude Code の初回確認をスキップ」オプションを有効にしてください:
1. CC Switch の「設定 → 一般」を開く
1. CC Switch の「設定 → アプリ設定」を開き、Claude Code のブロックを探す
2. 「Claude Code の初回確認をスキップ」スイッチをオンにする
3. Claude Code を再起動
![image-20260108002626389](../../assets/image-20260108002626389.png)
<!-- TODO(v4 screenshot): Settings → App config → Claude Code: the "Skip Claude Code first-run confirmation" switch -->
> ⚠️ **注意**:このオプションは `~/.claude.json` に `hasCompletedOnboarding: true` を書き込み、公式の初回インストール確認フローをスキップします。
@@ -84,6 +94,8 @@ openclaw
AI が正常に回答すれば、設定は成功です。
> **注意**:初回起動時、CC Switch は Claude Code、Codex、Gemini CLI、Grok Build の既存設定を `default` という名前のプロバイダーとして自動的にインポートし、これらのツールと Claude Desktop に公式プロバイダーを追加します。既存の設定は失われません。
## 次のステップ
基本設定が完了しました。次に以下のことができます:
@@ -92,6 +104,7 @@ AI が正常に回答すれば、設定は成功です。
- [MCP サーバーの設定](../3-extensions/3.1-mcp.md) - AI ツールの機能を拡張
- [システムプロンプトの設定](../3-extensions/3.2-prompts.md) - AI の動作をカスタマイズ
- [ローカルルーティングの有効化](../4-proxy/4.1-service.md) - フォーマット変換が必要なプロバイダーの利用、自動フェイルオーバー
- [AI プログラミングツールの管理](./1.2-installation.md#任意管理するツールのインストール) - サイドバーの「アプリ」ページでツールのインストール・更新を行い、サイドバーに表示するアプリを選択
- [使用量統計の確認](../4-proxy/4.4-usage.md) - リクエスト数、Token、費用を集計
## よくある質問
@@ -4,33 +4,36 @@
## 設定を開く
- 左上の **⚙️** ボタンをクリック
- またはショートカット `Cmd/Ctrl + ,`
- 左サイドバー下部の **設定** をクリック
- またはショートカット `Cmd/Ctrl + ,`(「一般」が直接開きます)
## 言語設定
設定は 1 画面を使い、左サイドバーが設定の目次に切り替わります。グループは 6 つあります:**一般、アプリ設定、ローカルルーティング、ネットワーク、データ、情報**。目次の上の「戻る」をクリックする(または `Esc` を押す)と、元のページに戻ります。設定には好みに関する項目だけが入っており、MCP、Skills、プロンプト、セッションなどの機能ページは左サイドバーにあります。
CC Switch は 4 つの言語に対応しています:
スイッチ類の設定は即時に保存されます。パス類の設定(設定ディレクトリ)は、変更後にそのブロックの「保存」をクリックする必要があります。
| 言語 | 説明 |
| -------- | -------- |
| 簡体中文 | デフォルト言語 |
| 繁體中文 | 繁体字中国語インターフェース |
| English | 英語インターフェース |
| 日本語 | 日本語インターフェース |
## 一般
言語を切り替えると即座に反映され、再起動は不要です。
### 外観
## テーマ設定
| 設定 | 説明 |
| ---- | ---- |
| 表示言語 | 簡体中文、繁體中文、English、日本語。切り替えると即座に反映され、再起動は不要です |
| テーマ | システムに合わせる / ライト / ダーク |
| オプション | 説明 |
| -------- | --------------------------- |
| システムに合わせる | システムのダーク/ライトモードに自動的に合わせる |
| ライト | 常にライトテーマを使用 |
| ダーク | 常にダークテーマを使用 |
### サイドバーとヘッダー
## ウィンドウ動作
- **サイドバーに表示するアプリ**:「「アプリ」を開く」をクリックするとサイドバーの「アプリ」ページに移動し、そこで表示するアプリを選べます(Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code から選択。少なくとも 1 つは残す必要があります)
- **プロジェクト切り替えを表示**:オンにすると、Claude Code、Claude Desktop、Codex のページ上部にプロジェクト切り替えが表示されます。デフォルトはオフです
### 起動時に自動実行
> 💡 **使用シーン**:Claude Code と Codex のみを使用する場合、他のアプリを非表示にしてサイドバーをシンプルに保てます。
### 各アプリの新しいバージョン
**起動時に各アプリの新しいバージョンを確認**:オンにすると、CC Switch の起動ごとに 1 回、インストール済みのコマンドラインアプリに新しいバージョンがないかを確認し、見つかればサイドバーの「アプリ」に点を表示します。自動ではアップグレードしません。アップグレードは「アプリ」ページで行います。[1.2 インストールガイド](./1.2-installation.md#任意管理するツールのインストール) を参照してください。
### ウィンドウとターミナル
#### 起動時に自動実行
有効にすると、システム起動時に CC Switch が自動的に起動します。
@@ -38,7 +41,9 @@ CC Switch は 4 つの言語に対応しています:
- **macOS**:LaunchAgent を使用
- **Linux**:XDG autostart を使用
### 閉じる動作
有効にすると **サイレント起動** スイッチが追加されます。起動時にメインウィンドウを表示せず、システムトレイでのみ動作します。
#### 閉じるときトレイへ最小化
| 「閉じるときトレイへ最小化」 | ウィンドウの閉じるボタンをクリックしたとき |
| ------------ | ---------------------------- |
@@ -47,13 +52,27 @@ CC Switch は 4 つの言語に対応しています:
トレイからプロバイダーを素早く切り替えられるため、オンのままにしておくことを推奨します。
### 軽量モード
#### アプリ内ウィンドウボタンを有効化(Linux のみ)
v3.13.0 より、CC Switch に **軽量モード** が追加されました — アイドル時のデスクトップ占有を最小限に抑える **トレイのみ実行状態** です。
オンにすると、アプリ独自の最小化、最大化/元に戻す、閉じるボタンを使用します。オフにすると、システムのウィンドウモードのままになります。
**開始方法**:トレイアイコンを右クリック → **軽量モード** をクリック。メインウィンドウは **破棄**(単に非表示ではなく)され、UI リソースとメモリが解放されます。
#### 優先ターミナル
**終了方法**:トレイメニューから **メインウィンドウを開く** をクリック、またはディープリンク / 再起動で CC Switch を呼び出します。ウィンドウは **必要に応じて再構築** され、状態は保持されます。
プロバイダーカードの「ターミナルを開く」をクリックしたときに使うターミナルアプリを選択します。選んだターミナルが使えない場合は、システムの既定のターミナルを使います。
| プラットフォーム | ターミナル選択肢 |
| ------- | ------------------------------------------------------------------ |
| macOS | Terminal、iTerm2、Alacritty、Kitty、Ghostty、Otty、WezTerm、Kaku、Warp |
| Windows | CMD、PowerShell、Windows Terminal |
| Linux | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |
#### 軽量モード
軽量モードは **トレイのみで実行** する状態で、アイドル時のデスクトップ占有を最小限に抑えます。
**開始方法**:トレイアイコンを右クリック → 「軽量モード」をクリック。メインウィンドウは **破棄**(単に非表示ではなく)され、UI リソースとメモリが解放されます。
**終了方法**:トレイメニューから「CC Switch を開く」をクリック、またはディープリンク / CC Switch の再起動で呼び出します。ウィンドウは **必要に応じて再構築** され、状態は保持されます。
| 項目 | トレイへ最小化 | 軽量モード |
| -------------------- | ---------------- | ---------------------- |
@@ -63,51 +82,18 @@ v3.13.0 より、CC Switch に **軽量モード** が追加されました —
| トレイ切り替え | 利用可能 | 利用可能 |
| ディープリンク起動 | 利用可能 | 利用可能(必要時再構築)|
> 💡 **使用シーン**:CC Switch を長時間バックグラウンドに常駐させ、主にトレイメニューからプロバイダーを切り替える場合、軽量モードを有効にするとメモリ使用量を大幅に削減できます。
> ⚠️ **注意**:軽量モードの状態は永続化されません — 次回の通常起動では通常モードに戻ります。長期的に使用する場合は「起動時に自動実行」と組み合わせてください。
### Claude Code 拡張に適用
## アプリ設定
有効にすると、VS Code の Claude Code 拡張のプロバイダーも CC Switch での切り替えに追従します(`~/.claude/config.json` の `primaryApiKey` に書き込み)。
アプリごとに 1 ブロックあり、そのアプリ専用のスイッチと設定ディレクトリがあります。
> 💡 **使用シーン**:Claude Code CLI と VS Code 拡張を同時に使用する場合、このオプションを有効にすると両方の設定を一致させることができます。
### Claude Code
### Claude Code の初回確認をスキップ
- **Claude Code 拡張に適用**:オンにすると、VS Code の Claude Code 拡張のプロバイダーも CC Switch での切り替えに追従します(`~/.claude/config.json` の `primaryApiKey` に書き込み)。Claude Code CLI と VS Code 拡張を同時に使用する場合、オンにすると両方を一致させられます
- **Claude Code の初回確認をスキップ**:オンにすると、Claude Code の初回起動時に表示される初回インストール確認をスキップします。
有効にすると、Claude Code の初回起動時に表示される初回インストール確認をスキップします。Claude Code に慣れているユーザー向けです。
> ⚠️ **注意**:このオプションは `~/.claude.json` に `hasCompletedOnboarding: true` を書き込みます。オフにするとこのフィールドを削除します。
### ホームページ表示
メインページのアプリ切り替えに表示するアプリを選択します。各アプリを個別にオン/オフできますが、少なくとも 1 つは有効にする必要があります。
設定可能なアプリ:Claude Code、Claude Desktop、Codex、Gemini、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code。
同じグループには **プロジェクト切り替えを表示** スイッチもあり、メインページ上部にプロジェクト切り替えの入口を表示するかどうかを制御します。
> 💡 **使用シーン**:Claude Code と Codex CLI のみを使用する場合、他のアプリを非表示にしてインターフェースをシンプルに保てます。
### スキル保存場所
CC Switch が Skills のマスターコピーを保存するディレクトリを選択します:
| オプション | 説明 |
| ----------------- | -------------------------------------------------------------------- |
| CC Switch(デフォルト) | `~/.cc-switch/skills/` に保存し、CC Switch が一元管理して各アプリに同期します |
| `~/.agents/skills` | `~/.agents/skills/` に保存します。Agent Skills オープン標準に準拠しており、対応ツールから直接読み込めます |
### スキル同期方式
スキルを各アプリディレクトリにインストールする際の同期方式を設定します:
| 方式 | 説明 |
| ----------------- | ---------------------------------------------------- |
| シンボリックリンク | スキルのソースファイルへのシンボリックリンクを作成、容量が少なく、リアルタイム同期 |
| ファイルコピー | スキルファイルをターゲットディレクトリに完全コピー |
> 💡 **推奨**:デフォルトではシンボリックリンク方式を使用します。権限の問題が発生する場合は、コピー方式に切り替えてください。
> ⚠️ **注意**:「Claude Code の初回確認をスキップ」は `~/.claude.json` に `hasCompletedOnboarding: true` を書き込みます。オフにするとこのフィールドを削除します。
### Codex アプリ拡張
@@ -122,50 +108,59 @@ CC Switch が Skills のマスターコピーを保存するディレクトリ
**Codex セッション履歴を統一**:有効にすると、公式サブスクリプションが共有の custom プロバイダー ID で動作し、公式とサードパーティのセッションが同じ履歴一覧に表示されます。既存の公式セッションもまとめて移行するかを選べます(移行前に自動バックアップ)。オフにする際はバックアップから復元できます。注意:プロバイダーをまたいで古いセッションを続けると、相手側のバックエンドがセッション内の推論内容を復号できず、続行に失敗することがあります。詳しくはガイド [Codex セッション履歴の統一](../../../guides/codex-unified-session-history-guide-ja.md) を参照してください。
### 優先ターミナル
### 設定ディレクトリ
CC Switch がターミナルを開く際に使用するターミナルアプリケーションを選択します。
Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi の 8 つのアプリには、それぞれ「設定ディレクトリ」の行があり、別の場所を指定できます。空欄の場合はデフォルト値が使われます。MCP、Skills、プロンプトのパスもそれに応じて変わります。
対応ターミナル(プラットフォーム別):
| アプリ | デフォルト値 |
| ----------------------- | --------------------- |
| Claude Code | `~/.claude/` |
| Codex | `~/.codex/` |
| Gemini CLI | `~/.gemini/` |
| Grok Build | `~/.grok/` |
| OpenCode | `~/.config/opencode/` |
| OpenClaw | `~/.openclaw/` |
| Hermes | `~/.hermes/` |
| Pi | `~/.pi/agent/` |
| プラットフォーム | ターミナル選択肢 |
| ------- | ------------------------------------------------------------------ |
| macOS | Terminal、iTerm2、Alacritty、Kitty、Ghostty、Otty、WezTerm、Kaku、Warp |
| Windows | CMD、PowerShell、Windows Terminal |
| Linux | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |
Claude Desktop と MiniMax Code は、ここでのディレクトリ上書きに対応していません(そのためアプリ設定にはこの 2 つはありません)。MiniMax Code のデータディレクトリはデフォルトで `~/.minimax/` で、環境変数 `MINIMAX_DATA_DIR`(または `MAVIS_DATA_DIR`)で指定できます。Hermes は `HERMES_HOME`、Pi は `PI_CODING_AGENT_DIR` も認識します。
## ディレクトリ設定
設定 → 詳細 → 設定ディレクトリ
### アプリ設定ディレクトリ
CC Switch 自体のデータの保存場所で、デフォルトは `~/.cc-switch/` です。
### CLI ツールディレクトリ
各 CLI ツールの設定ディレクトリをカスタマイズできます:
| 設定 | デフォルト値 | 説明 |
| --------------------- | --------------------- | ---------------------------- |
| Claude ディレクトリ | `~/.claude/` | Claude Code 設定ディレクトリ |
| Codex ディレクトリ | `~/.codex/` | Codex 設定ディレクトリ |
| Gemini ディレクトリ | `~/.gemini/` | Gemini CLI 設定ディレクトリ |
| Grok Build ディレクトリ | `~/.grok/` | Grok Build 設定ディレクトリ |
| OpenCode ディレクトリ | `~/.config/opencode/` | OpenCode 設定ディレクトリ |
| OpenClaw ディレクトリ | `~/.openclaw/` | OpenClaw 設定ディレクトリ |
| Hermes ディレクトリ | `~/.hermes/` | Hermes 設定ディレクトリ |
| Pi ディレクトリ | `~/.pi/agent/` | Pi の agent 設定ディレクトリ |
Claude Desktop と MiniMax Code は、ここでのディレクトリ上書きに対応していません。MiniMax Code のデータディレクトリはデフォルトで `~/.minimax/` で、環境変数 `MINIMAX_DATA_DIR`(または `MAVIS_DATA_DIR`)で指定できます。Hermes は `HERMES_HOME`、Pi は `PI_CODING_AGENT_DIR` も認識します。
> 💡 **WSL**:CC Switch は WSL を自動認識しません。Windows ではディレクトリを WSL 内のパス(例:`\\wsl.localhost\Ubuntu\home\<ユーザー名>\.claude`)に変更すると、CC Switch が WSL 内の設定を読み書きし、「バージョン情報」ページも対応する WSL ディストリビューション内でそのツールを検出・更新します。
> 💡 **WSL**:CC Switch は WSL を自動認識しません。Windows ではディレクトリを WSL 内のパス(例:`\\wsl.localhost\Ubuntu\home\<ユーザー名>\.claude`)に変更すると、CC Switch が WSL 内の設定を読み書きします。
> ⚠️ **注意**:ディレクトリを変更した後はアプリの再起動が必要で、対応する CLI ツールも同じディレクトリを設定する必要があります。
## データ管理
> 💡 **Skills の保存場所と同期方式**は設定にはありません。サイドバーの「Skills」ページで「保存と同期」をクリックすると、マスターコピーを「CC Switch フォルダ」と「共通フォルダ」(`~/.agents/skills`)のどちらに置くか、各アプリへの同期にシンボリックリンクとコピーのどちらを使うかを選べます。
### 設定のエクスポート
## ローカルルーティング
設定 → ローカルルーティング
このグループでは、ローカルルーティングの全体に関わる部分をまとめて管理します:
- **サービス**:ルーティングサービスの稼働状況(稼働時間、リクエスト数、成功率、アクティブ接続)を表示し、「起動」/「停止」ができます。「待ち受けアドレスとポート」のデフォルトは `127.0.0.1` で、変更後は「保存してサービスを再起動」をクリックします。「リクエストの使用量を記録」をオフにすると、使用量にルーティング経由のリクエストの明細が残りません。また、ルーティングサービスを使っているアプリがあるときは停止できないため、先にそれらを直接接続に戻してください
- **ルーティングを使用中のアプリ**:現在ルーティングまたは集約モードのアプリを一覧表示し、「開く」でそのアプリのページに移動できます。「すべて直接接続に戻す」を押すと、すべてのアプリに直接接続の設定を書き戻してルーティングサービスを停止します。転送先、キュー、集約のリストは保持されます
- **自動フェイルオーバー**:各アプリのタイムアウト、再試行、サーキットブレーカーを調整します。キューは各アプリページの「ルーティング」タブで管理します。詳しくは [4.3 フェイルオーバー](../4-proxy/4.3-failover.md) をご覧ください
- **整流器**:一部の上流で互換性のないリクエストを自動的に修正します。たとえば Thinking 署名に互換性がない場合は、該当する内容を取り除いてから再試行します
ルーティングや集約を開始する入口は、各アプリページ上部の「直接接続 / ルーティング / 集約」タブです。詳しくは [4.1 ローカルルーティングサービス](../4-proxy/4.1-service.md) をご覧ください。
## ネットワーク
設定 → ネットワーク
**グローバル送信プロキシ**:CC Switch が外部 API にアクセスする際に使う HTTP/HTTPS プロキシを設定します。外部 API にプロキシ経由でアクセスする必要がある場合に使用します。
## データ
設定 → データ
### 保存場所
**CC Switch 設定ディレクトリ**:CC Switch 自体のデータの保存場所で、デフォルトは `~/.cc-switch/` です。クラウド同期フォルダを指定することもできます。変更後は「保存」をクリックし、反映にはアプリの再起動が必要です。
### データ管理
#### 設定のエクスポート
「SQL バックアップをエクスポート」ボタンをクリックして、以下の内容を含む SQL バックアップファイルを保存します:
@@ -177,49 +172,15 @@ Claude Desktop と MiniMax Code は、ここでのディレクトリ上書きに
エクスポートされるファイル名の形式は `cc-switch-export-{timestamp}.sql` です。
### 設定のインポート
#### 設定のインポート
1. 「SQL ファイルを選択」をクリック
1. 「SQL ファイルを選択」をクリック(CC Switch でエクスポートしたバックアップのみインポートできます)
2. 以前にエクスポートしたバックアップファイルを選択
3. ボタンが「インポート」に変わったら、クリックしてインポートを開始
4. インポートが成功すると、インポート前に自動作成されたバックアップの ID が表示されます
> ⚠️ **注意**:インポートは既存の設定を上書きするため、事前に現在の設定をエクスポートしてバックアップすることをお勧めします。
## ルーティング設定
設定 → ルーティング タブ
ルーティング タブではローカルルーティング関連の機能を集中管理します:
### ローカルルーティング
ローカルルーティングの起動/停止、アプリごとのルーティングの有効化、リスニングアドレスとポートの設定を行います。詳しくは [4.1 ローカルルーティングサービス](../4-proxy/4.1-service.md) をご覧ください。
### 自動フェイルオーバー
アプリ(Claude / Codex / Gemini / Grok Build)ごとにフェイルオーバーキューと自動切り替え戦略を設定。詳しくは [4.3 フェイルオーバー](../4-proxy/4.3-failover.md) をご覧ください。
### 整流器
一部の上流で互換性のないリクエストを自動的に修正します。たとえば Thinking 署名に互換性がない場合は、該当する内容を取り除いてから再試行します。
### グローバル送信プロキシ
CC Switch の送信 HTTP/HTTPS プロキシを設定します。外部 API にプロキシ経由でアクセスする必要がある場合に使用します。
## 詳細設定
設定 → 詳細 タブ
### 設定ディレクトリ
各アプリの設定ファイルディレクトリをカスタマイズ。上記の「ディレクトリ設定」セクションを参照してください。
### データ管理
設定バックアップのインポート/エクスポート。上記の「データ管理」セクションを参照してください。
### バックアップと復元
バックアップ管理パネルでは、データベースバックアップを完全に管理できます。
@@ -251,6 +212,12 @@ CC Switch の送信 HTTP/HTTPS プロキシを設定します。外部 API に
> ⚠️ **重要**:バックアップの復元は現在のデータベースを上書きします。復元前に安全バックアップが自動作成されるため、必要に応じて元に戻すことができます。
#### その他のバックアップ
バックアップリストの下にある「その他のバックアップ」の一覧には、CC Switch がさまざまな場所に残したバックアップ(Skill アンインストール時のバックアップ、設定ファイル初回書き込みバックアップ、Codex セッション移行バックアップ、Hermes / OpenClaw 設定のバックアップ、旧バージョンの残存ファイルなど)が表示され、各項目の場所と使用サイズが分かります。合計サイズは見出しの横に表示されます。各項目は「ファイルマネージャーで表示」でき、自分で「削除」することもできます(確認あり、完全に削除されます)。データベースのバックアップは上のリストで管理します。
> ⚠️ 削除すると対応する内容を復元できなくなるバックアップがあります。たとえば「設定ファイル初回書き込みバックアップ」を削除すると書き換え前の元ファイルが見つからなくなり、「Skill アンインストール時のバックアップ」を削除するとアンインストール済みの Skill を復元できなくなります。各項目の下の説明に結果が書かれています。
### クラウド同期
**WebDAV** または **S3 互換ストレージ** を使って複数のデバイス間で設定を同期します。同時に有効にできるのはどちらか一方だけです。信頼性の向上のため、デュアルレイヤーバージョニングを備えた **v2 プロトコル** を使用しています。
@@ -321,11 +288,9 @@ CC Switch の送信 HTTP/HTTPS プロキシを設定します。外部 API に
- **debug** - デバッグ情報を記録
- **trace** - すべての詳細情報を記録
## OAuth 認証センター(Beta)
## アカウント(Beta)
設定 → **認証** タブ
v3.13.0 で追加された **OAuth 認証センター**(Beta)は、サードパーティの OAuth 認証情報を一元管理します。現在、以下の 3 種類のアカウントタイプをサポートしています:
ログインの入口は左サイドバーの「アカウント」にあり、設定の中にはありません。アカウントではサードパーティの OAuth 認証情報を一元管理します。現在、以下の 3 種類のアカウントタイプをサポートしています:
| アカウントタイプ | 用途 |
| ----------------------------- | --------------------------------------------------------------- |
@@ -356,37 +321,18 @@ xAI 連携は CC Switch 用に登録された OAuth アプリケーションを*
> ⚠️ **警告**:これらのアカウント型リバースプロキシは、リバースエンジニアリングされた OAuth 連携を使用しており、アカウントおよび利用規約上のリスクがあります。上流製品の OAuth クライアント再利用は公式にサポートされない可能性があり、サービス提供者によるアカウントの制限・停止につながるおそれがあります。各プロバイダーの規約を確認し、自己責任で使用してください。既存の Codex フローについては [2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ](../2-providers/2.1-add.md#codex-oauth-リバースプロキシclaude-プロバイダー) の完全なリスクに関する注意事項も参照してください。
## バージョン情報ページ
## 情報
設定 → バージョン情報 タブ
設定 → 情報
### バージョン情報
現在の CC Switch バージョン番号を表示し、以下をサポートします:
- リリースノートの表示
- 更新の確認
- 新バージョンのダウンロードとインストール
- 更新の確認。新しいバージョンがあるときは「v{{version}} に更新」をクリックしてダウンロードとインストール(ポータブル版は手動ダウンロード)
- GitHub、公式サイト、リリースノートの表示
- 「最近の更新」:直近数バージョンの更新概要をもう一度見る
### ローカル環境チェック
### ツールのインストールとアップグレード
インストール済みの CLI ツールのバージョンを自動検出:
| ツール | 検出内容 |
| ----------- | -------------------------------- |
| Claude Code | 現在のバージョン、最新バージョン |
| Codex | 現在のバージョン、最新バージョン |
| Gemini CLI | 現在のバージョン、最新バージョン |
| Grok Build | 現在のバージョン、最新バージョン |
| OpenCode | 現在のバージョン、最新バージョン |
| OpenClaw | 現在のバージョン、最新バージョン |
| Hermes | 現在のバージョン、最新バージョン |
| Pi | 現在のバージョン、最新バージョン |
「更新」ボタンで再検出できます。更新がある場合は個別更新または「すべて更新」を利用でき、未検出のツールにはインストールボタンが表示されます。インストールと更新はバックグラウンドで静かに実行され、ボタンに進捗が表示され、完了後にバージョンが自動更新されます。インストール済みでも現在の環境では実行できない(例:Node.js のバージョンが足りない)ツールには「インストール済み・実行不可」と表示されます。
Windows で、「設定ディレクトリ」でいずれかのツールのディレクトリを WSL のパスに設定している場合、「バージョン情報」ページは対応する WSL ディストリビューション内でそのツールを検出・更新します。
### 手動インストールコマンド
このエリアはデフォルトで折りたたまれており、見出しをクリックすると展開されます。すべてのツールのインストールコマンドをワンクリックでコピーできます。Claude Code、OpenCode、Hermes は公式インストールスクリプトを使用し(Claude Code と OpenCode は失敗時に npm にフォールバック)、その他のツールは npm でインストールします。Windows では Hermes は PowerShell インストールスクリプトを使用し、その他のツールは npm を使用します。各ツールのインストールコマンドは [1.2 インストールガイド](./1.2-installation.md#任意管理するツールのインストール) も参照してください。
各 AI プログラミングツールのバージョン検出、インストール、アップグレード、「すべて更新」はここではなく、左サイドバーの「アプリ」ページにあります。詳しくは [1.2 インストールガイド](./1.2-installation.md#任意管理するツールのインストール) を参照してください。Windows で「アプリ設定」の中のあるツールのディレクトリを WSL のパスに設定している場合、「アプリ」ページは対応する WSL ディストリビューション内でそのツールを検出・アップグレードします。
+89 -181
View File
@@ -1,61 +1,61 @@
# 2.1 プロバイダーの追加
## 追加パネルを開く
## 追加ページを開く
メイン画面右上の **+** ボタンをクリックして、プロバイダー追加パネルを開きます。
まずサイドバーで追加したいアプリを選び、ページヘッダー右側の **プロバイダーを追加** ボタン(+ 付き)をクリックします。アプリページの上部に「直接接続 / ルーティング / 集約」のタブがある場合、追加ページは現在見ているタブに合わせて開きます。「集約」タブで追加するとヘッダーに「(集約モード)」と表示され、フォームは簡略化された集約用のレイアウトになります(Claude Code と Codex のみ)。
パネルは 2 つのタブに分かれています:
- **アプリ専用プロバイダー**:現在選択中のアプリ専用
- **統一プロバイダー**:アプリ間で共有する設定
追加ページはコンテンツ領域の上に重なるフルページ画面で、2 つのステップに分かれています:
1. **プリセットを選ぶ**:プリセットを選ぶか、「カスタム設定」を選択
2. **入力する**:フォームの最上部にはプリセットバーだけが残り、右側の「変更」をクリックするとステップ 1 に戻れます。上部の戻るボタンは、ステップ 2 では「プリセットの選択に戻る」、ステップ 1 では「プロバイダー一覧に戻る」と表示されます
ステップ 2 でフォームを操作した(文字入力、スイッチのオン/オフ、選択肢の変更)後に、サイドバー、トレイ、設定から現在のページを離れようとすると、先に「未保存の変更があります」の確認が表示されます。「破棄して移動」または「編集を続ける」を選べます。フッターの「キャンセル」をクリックした場合は、そのまま追加ページを閉じます。
## プリセットで追加
プリセットは事前に設定されたプロバイダーテンプレートで、API Key を入力するだけで使用できます。
プリセットは事前に設定されたプロバイダーテンプレートで、通常は API Key を入力するだけで使用できます。
### プリセットの選択
ステップ 1 のレイアウト:
- **検索ボックス**:上部に常に表示され、開いてすぐ入力できます。名前、URL、よく使われる呼び名(例:kimi、智谱、openrouter)で検索できます。⌘F / Ctrl+F で検索ボックスに戻れます
- **左側のカテゴリ**:「すべて」「アカウントでログイン」「モデルベンダー」「サードパーティ」「クラウド事業者」。OpenCode にはさらに「プラグイン設定」があります。カテゴリはプリセット自身の属性から自動で振り分けられ、各項目の後ろに該当件数が付きます
- **右側の 2 列リスト**:すべてのプリセットは表示名順に並びます(中国語名はピンインでアルファベット順に組み込まれます)。固定表示もスター付きもありません。「カスタム設定」は「すべて」の一番上に固定されています
各カテゴリの内容は次のとおりです:
| カテゴリ | 内容 |
|------|------|
| アカウントでログイン | API Key 不要で、既存のアカウントでログインするもの。Claude 公式、ChatGPT(Codex)、GitHub Copilot、xAI、Google 公式など。Claude 以外はルーティングを経由する必要があります |
| モデルベンダー | ベンダー自身の API とコーディングプラン。同じベンダーの国内サイト、海外サイト、異なるプランは 1 行にまとめられ、選択後に次のステップで「プラン」「地域」「バージョン」を切り替えます |
| サードパーティ | 複数のモデルを集約するプラットフォーム、または公式モデルを再販する中継サービス |
| クラウド事業者 | クラウドベンダーのアカウントでモデルを呼び出すもの(AWS Bedrock など) |
| プラグイン設定 | OpenCode プラグインのモデル割り当て設定 |
一部のプリセットには「ルーティングが必要」バッジが付いています。これは上流のプロトコルがクライアントと一致しないため、[ローカルルーティング](../4-proxy/4.1-service.md)を有効にしないと使えないことを示します。
同じベンダーの複数のバージョンを切り替える際、すでに入力済みの内容がある場合は「フォームは新しいバージョンの内容で入力し直され、入力済みの API Key やその他の変更は消去されます」と確認が表示され、承認すると切り替わります。
### 操作手順
1. 「プリセット」ドロップダウンからプロバイダーを選択
1. 検索ボックスまたは左側のカテゴリでプロバイダーを探し、クリック
2. 名前とエンドポイントが自動入力される
3. **API Key** を入力
4. (任意)メモを入力
5. 「追加」をクリック
5. フッターの「追加」をクリック
### 主なプリセット
目的のベンダーが見つからない場合、検索結果が空のときの案内に「カスタム設定で追加」ボタンがあります。リクエスト先アドレスと API Key を手動で入力してください。
> プリセット一覧はバージョンの更新に伴い変更されます。アプリ内の実際の表示を基準にしてください。以下では、各アプリのプリセットに共通する特徴と注意点だけを説明します。
#### Claude プリセット
| プリセット名 | 説明 |
|----------|------|
| Claude 公式 | Anthropic 公式アカウントでログイン |
| DeepSeek | DeepSeek モデル |
| 智谱 GLM | 智谱 AI の GLM モデル |
| 智谱 GLM en | 智谱 AI(英語版) |
| 百炼 | アリクラウド百炼(通义千問) |
| Kimi | Moonshot Kimi モデル |
| Kimi For Coding | Kimi プログラミング専用モデル |
| StepFun | StepFun モデル |
| ModelScope | 魔搭コミュニティ |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax(英語版) |
| Volcengine Doubao | 豆包 Seed モデル |
| BaiLing | 百灵 AI |
| AiHubMix | AiHubMix 統合サービス |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow(英語版) |
| DMXAPI | DMXAPI 中継サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
| Nvidia | Nvidia AI サービス |
| Xiaomi MiMo | Xiaomi MiMo モデル |
| Command Code | Command Code 統合サービス |
Claude Code のプリセットは最も充実しており、ベンダー公式、コーディングプラン、集約プラットフォーム、中継プラットフォームをカバーしています。そのうち:
> プリセット選択画面で ⭐ が付いているのはパートナーのプリセットです。プリセットリストはバージョンの更新に伴い変更される場合があります。アプリ内の実際の表示を基準にしてください。
- **Claude 公式**:Anthropic 公式アカウントでログインします。「アカウントでログイン」カテゴリにあります
- **GitHub Copilot / Codex(ChatGPT アカウント)/ xAI (Grok)**:同じく「アカウントでログイン」にあり、先にアカウントページで該当アカウントにログインする必要があります。下記の「Codex OAuth リバースプロキシ」を参照してください
- その他のプリセットは API Key を入力するだけです。プリセットに設定済みの上流フォーマットやモデルマッピングを手動で変更する必要はありません
#### Claude Desktop プリセット
@@ -78,103 +78,15 @@ Codex プロバイダーは、**選択したエンドポイントのプロトコ
> **既存のカードは自動で更新されません**:プロバイダーには作成時のプリセットのスナップショットが保存されます。DeepSeek、GLM(v3.20.2)、Kimi(v3.20.3)などのプリセットは順次ネイティブ Responses に切り替わっています。既存のカードを直接接続にしたい場合は、最新版のプリセットで追加し直すことをお勧めします。手動で移行する場合は、「上流フォーマット」を Responses に変更し、API エンドポイントとモデルマッピングがベンダーの Responses エンドポイントに合っているか確認してください。詳しくは [v3.20.3 リリースノート](../../../release-notes/v3.20.3-ja.md) を参照してください。
その他のよく使われる Codex プリセット:
| プリセット名 | 説明 |
|----------|------|
| OpenAI 公式 | OpenAI 公式アカウントでログイン |
| Azure OpenAI | Azure OpenAI サービス |
| AiHubMix | AiHubMix 統合サービス |
| DMXAPI | DMXAPI 中継サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
> 💡 プリセット一覧は継続的に更新されます。アプリ内の表示を正としてください。上流フォーマット、モデルマッピング、思考能力については、下記の「Codex / Grok Build の上流フォーマットとモデルマッピング」を参照してください。
#### Gemini プリセット
| プリセット名 | 説明 |
|----------|------|
| Google 公式 | Google OAuth でログイン |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
| カスタム | すべてのパラメータを手動設定 |
Gemini CLI のプリセットには、「Google 公式」(Google アカウントでログイン。API Key は不要)と複数の中継・集約サービスが含まれます。すべてのパラメータを手動で設定する場合は「カスタム設定」を選択してください。
#### OpenCode プリセット
#### OpenCode / OpenClaw プリセット
| プリセット名 | 説明 |
|----------|------|
| DeepSeek | DeepSeek モデル |
| 智谱 GLM | 智谱 AI の GLM モデル |
| 智谱 GLM en | 智谱 AI(英語版) |
| 百炼 | アリクラウド百炼 |
| Kimi k2.5 | Moonshot Kimi-k2.5 モデル |
| Kimi For Coding | Kimi プログラミング専用モデル |
| StepFun | StepFun モデル |
| ModelScope | 魔搭コミュニティ |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax(英語版) |
| Volcengine Doubao | 豆包 Seed モデル |
| BaiLing | 百灵 AI |
| Xiaomi MiMo | Xiaomi MiMo モデル |
| AiHubMix | AiHubMix 統合サービス |
| DMXAPI | DMXAPI 中継サービス |
| OpenRouter | 統合ルーティングサービス |
| Nvidia | Nvidia AI サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenAI Compatible | OpenAI 互換インターフェース |
| Oh My OpenCode | Oh My OpenCode サービス |
> プリセットリストは継続的に更新されています。アプリ内の実際の表示を基準にしてください。
#### OpenClaw プリセット
| プリセット名 | 説明 |
|----------|------|
| DeepSeek | DeepSeek モデル |
| 智谱 GLM | 智谱 AI の GLM モデル |
| 智谱 GLM en | 智谱 AI(英語版) |
| Qwen Coder | 通义千問コーディングモデル |
| Kimi k2.5 | Moonshot Kimi-k2.5 モデル |
| Kimi For Coding | Kimi プログラミング専用モデル |
| StepFun | StepFun モデル |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax(英語版) |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| Volcengine Doubao | 豆包 Seed モデル |
| BaiLing | 百灵 AI |
| Xiaomi MiMo | Xiaomi MiMo モデル |
| AiHubMix | AiHubMix 統合サービス |
| DMXAPI | DMXAPI 中継サービス |
| OpenRouter | 統合ルーティングサービス |
| ModelScope | 魔搭コミュニティ |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow(英語版) |
| Nvidia | Nvidia AI サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| AICoding | AICoding サービス |
| CrazyRouter | CrazyRouter サービス |
| SSSAiCode | SSSAiCode サービス |
| AWS Bedrock | AWS Bedrock サービス |
| OpenAI Compatible | OpenAI 互換インターフェース |
OpenCode と OpenClaw は累積型アプリです。「追加」をクリックするとプロバイダーがそれぞれの設定ファイルに書き込まれ、複数のプロバイダーを同時に置けます。プリセットは主要なモデルベンダー、集約プラットフォーム、中継サービスをカバーしており、任意の OpenAI 互換インターフェース向けの「OpenAI Compatible」プリセットもあります。OpenCode には Oh My OpenCode の「プラグイン設定」カテゴリもあります。
#### Grok Build プリセット
@@ -190,7 +102,7 @@ Pi のプリセットは、Kimi、火山方舟(Volcengine Ark)などの公
#### MiniMax Code プリセット
MiniMax Code のプリセットは Pi のプリセットカタログから派生したもので(v3.20.4 時点で 41 個)、Anthropic Messages、OpenAI Chat Completions、OpenAI Responses の 3 種類のインターフェースを使い、かつ Pi 専用の互換オプションを必要としないプリセットのみが含まれます。「追加」をクリックするとプロバイダーが `~/.minimax/config.yaml` の `custom_provider` に書き込まれ、その後 MiniMax Code 側でモデルを選択します。CC Switch が管理するのはカスタムプロバイダーのみで、MiniMax 公式アカウントは MiniMax Code 自身が管理します。
MiniMax Code のプリセットは Pi のプリセットカタログから派生したもので、Anthropic Messages、OpenAI Chat Completions、OpenAI Responses の 3 種類のインターフェースを使い、かつ Pi 専用の互換オプションを必要としないプリセットのみが含まれます。「追加」をクリックするとプロバイダーが `~/.minimax/config.yaml` の `custom_provider` に書き込まれ、その後 MiniMax Code 側でモデルを選択します。CC Switch が管理するのはカスタムプロバイダーのみで、MiniMax 公式アカウントは MiniMax Code 自身が管理します。
## モデル自動取得
@@ -300,14 +212,17 @@ requires_openai_auth = true
### 統一プロバイダーの作成
1. 「統一プロバイダー」タブに切り替え
2. 「統合プロバイダーを追加」をクリック
3. 共通設定を入力:
統一プロバイダーは、Claude Code、Codex、Gemini CLI の追加ページにのみ表示されます。プリセット選択の手順で、左側カテゴリの一番下、「アプリ横断」の下にある「統合プロバイダー」です:
1. 「統合プロバイダー」カテゴリをクリックし、プリセットの種類を選択
2. 表示されたフォームに共通設定を入力:
- 名前
- API Key
- エンドポイントアドレス
4. 同期するアプリにチェック(Claude Code / Codex / Gemini)
5. 保存
- API エンドポイントアドレス
3. 同期するアプリにチェック(Claude Code / Codex / Gemini)
4. 保存
既存の統一プロバイダーは、このカテゴリの「既存の統合プロバイダーを管理 ›」から表示・編集・複製・削除できます。
### 同期の仕組み
@@ -329,7 +244,7 @@ requires_openai_auth = true
手動で同期をトリガーする場合:
1. 統一プロバイダーカードの「同期」ボタンをクリック
1. 「既存の統合プロバイダーを管理」で、統一プロバイダーカードの「同期」ボタンをクリック
2. 同期操作を確認
3. 各アプリの関連プロバイダーの設定が上書きされる
@@ -354,8 +269,8 @@ CC Switch は 2 つの方法でプロバイダー設定をインポートでき
SQL バックアップファイルから一括インポート:
1. 「設定 → 詳細 → データ管理」を開く
2. 「ファイルを選択」をクリック
1. 「設定 → データ」を開き、「データ管理」の「SQL インポート/エクスポート」を探す
2. 「SQL ファイルを選択」をクリック
3. 以前にエクスポートした `.sql` バックアップファイルを選択
4. 「インポート」をクリック
5. 既存の設定の上書きを確認
@@ -370,7 +285,7 @@ SQL バックアップファイルから一括インポート:
## Codex OAuth リバースプロキシ(Claude プロバイダー)
v3.13.0 より、CC Switch は **Codex OAuth リバースプロキシ** 経路を追加しました。**ChatGPT アカウント** を使って Claude Code 内から Codex サービスを再利用できます。
CC Switch には **Codex OAuth リバースプロキシ** 経路があり、**ChatGPT アカウント** を使って Claude Code 内から Codex サービスを再利用できます。
> **位置ヒント**:この機能は **新しい Claude プロバイダーカードタイプ** として表示され、Codex 側のプリセットではありません。追加後は通常の API Key プロバイダーと並んで Claude のプロバイダーリストに表示されます。
@@ -384,21 +299,21 @@ v3.13.0 より、CC Switch は **Codex OAuth リバースプロキシ** 経路
以下のどちらの入口からでも開始できます:
#### 入口 A:プロバイダー追加パネルから(新規ユーザー推奨)
#### 入口 A:プロバイダー追加ページから(新規ユーザー推奨)
1. **Claude** アプリに切り替える
2. 右上の **+** ボタンをクリックしてプロバイダー追加パネルを開く
3. プリセットリストの第三者カテゴリから **Codex** プリセットを選択(UI に表示される名称を優先)
4. まだ ChatGPT アカウントにログインしていない場合、パネルが **自動的に** ログインフローへ誘導します(下記「ログインフロー」を参照)
5. ログイン成功後、プロバイダーフォームにログイン済みアカウントが表示されるので「保存」をクリックして完了
2. ページヘッダーの **プロバイダーを追加** をクリック
3. 「アカウントでログイン」カテゴリから **Codex**(ChatGPT アカウントでログイン)プリセットを選択(UI に表示される名称を優先)
4. まだ ChatGPT アカウントにログインしていない場合、フォームがログインフローへ誘導します(下記「ログインフロー」を参照)
5. ログイン成功後、フォームにログイン済みアカウントが表示されるので「追加」をクリックして完了
#### 入口 B:OAuth 認証センターから(マルチアカウント管理に適する)
#### 入口 B:アカウントページから(マルチアカウント管理に適する)
1. **設定 → 認証** を開く(OAuth 認証センター。上部に **Beta** マーク)
2. **ChatGPT (Codex OAuth)** セクションで **ChatGPT でログイン** ボタンをクリック
1. サイドバーの **アカウント** をクリック
2. **ChatGPT** セクションで **アカウントを追加** をクリック
3. ログインフローを完了(下記参照)
4. ログイン完了後、**Claude** アプリに戻る → **プロバイダーを追加** → 同じ Codex プリセットを選択
5. フォーム内の「アカウントを選択」ドロップダウンから、先ほどログインしたアカウントを選択して保存
5. フォーム内の「アカウントを選択」ドロップダウンから、先ほどログインしたアカウントを選択して追加
### ログインフロー(Device Code)
@@ -414,16 +329,16 @@ v3.13.0 より、CC Switch は **Codex OAuth リバースプロキシ** 経路
- 先ほどコピーした認証コードを入力
- 認証を確認
3. **自動ポーリング完了**:CC Switch はバックグラウンドで OpenAI サーバーをポーリングし、認証成功を検知すると待機画面を自動的に閉じます
4. **ログイン済みアカウントを表示**:ログインした ChatGPT アカウント(ログインメール)が **OAuth 認証センター → ログイン済みアカウント** リストに表示されます
4. **ログイン済みアカウントを表示**:ログインした ChatGPT アカウントが **アカウント**ページの ChatGPT セクションに表示されます
> ⏱️ **認証コードの有効期限は約 15 分** です。タイムアウトすると「Device Code の有効期限切れ」が表示されるので、**再試行** をクリックして新しい認証コードを取得してください。
> ⏱️ **認証コードの有効期限は約 15 分** です。タイムアウトすると、認証が完了しなかった旨が表示されます。ログインをやり直して新しい認証コードを取得してください。
### 有効化と使用
Codex OAuth プロバイダーを追加・保存した後:
1. [ローカルルーティング](../4-proxy/4.1-service.md)が有効で、Claude のルーティングが有効になっていることを確認(カードには「ルーティングが必要」バッジが表示されます)
2. Claude のプロバイダーリストから探し、カードの **有効化** ボタンをクリック —— 通常のプロバイダーと同じ
1. カードに「ルーティングが必要」バッジが表示されます。まずアプリページ上部で「ルーティング」タブに切り替え、「ルーティングを開始」をクリックします(詳しくは[ローカルルーティング](../4-proxy/4.1-service.md))
2. Claude のプロバイダーリストから探し、カードの「ここへ転送」をクリック —— その他の操作は通常のプロバイダーと同じ
3. Claude Code CLI がリバースプロキシ経由で ChatGPT のサブスクリプションを使用できるようになります
4. トレイメニューの **Claude** サブメニューにもこのプロバイダーが表示され、素早く切り替え可能
@@ -442,21 +357,22 @@ Codex OAuth プリセットのデフォルトモデルマッピング:
プリセットは `CLAUDE_CODE_MAX_CONTEXT_TOKENS` と `CLAUDE_CODE_AUTO_COMPACT_WINDOW` も `372000` に設定し、ChatGPT Codex バックエンドのコンテキストウィンドウに合わせます。
v3.15.0 以降、Codex OAuth のモデル選択は固定リストだけに依存しません。モデルセレクターを開くと、CC Switch は必要に応じて ChatGPT Codex バックエンドから利用可能モデルを取得します。デフォルトマッピングは引き続き上書きできます。
Codex OAuth のモデル選択は固定リストだけに依存しません。モデルセレクターを開くと、CC Switch は必要に応じて ChatGPT Codex バックエンドから利用可能モデルを取得します。デフォルトマッピングは引き続き上書きできます。
プロバイダーの JSON エディタで `ANTHROPIC_MODEL` などの環境変数を上書きしてカスタマイズできます。
### マルチアカウント管理(OAuth 認証センター)
### マルチアカウント管理(アカウント)
**OAuth 認証センター** は複数の ChatGPT アカウントの同時管理をサポートします:
**アカウント**ページでは、複数の ChatGPT アカウントを同時に管理できます(GitHub Copilot、xAI のアカウントもここにあります):
| 操作 | 説明 |
| -------------------------- | ---------------------------------------------------------------------- |
| 別のアカウントを追加 | 「別のアカウントを追加」をクリックしてログインフローを繰り返す |
| デフォルトに設定 | アカウント行の「デフォルトに設定」をクリック —— 新規プロバイダーに適用 |
| 別のアカウントを追加 | 「アカウントを追加」をクリックしてログインフローを繰り返す |
| デフォルトに設定 | アカウント行のその他の操作から「デフォルトに設定」を選ぶ —— アカウントを指定していないプロバイダーはデフォルトのアカウントを使う |
| プロバイダー用に選択 | プロバイダーフォームの「アカウントを選択」ドロップダウンで特定アカウントを指定 |
| アカウントを削除 | アカウント右側の赤い × をクリックして削除(Token がクリアされる) |
| すべてのアカウントをログアウト | 下部の「すべてのアカウントをログアウト」ボタンで一括クリア |
| 再ログイン | アカウントに「再ログインが必要」と表示されたら、その他の操作から「再ログイン」を選ぶ |
| アカウントを削除 | アカウント行のその他の操作から「アカウントを削除」を選ぶ(Token がクリアされる) |
| すべてのアカウントを削除 | セクションのその他の操作から「すべてのアカウントを削除」を選ぶ |
> **使用シーン**:チームで開発マシンを共有する場合、各メンバーの ChatGPT アカウントごとに 1 つのプロバイダーを作成し、トレイメニューから素早く切り替えできます。
@@ -468,26 +384,20 @@ v3.15.0 以降、Codex OAuth のモデル選択は固定リストだけに依存
### クォータ表示
ログインしてプロバイダーを有効化すると、**プロバイダーカード下部** に自動的にアカウントクォータが表示されます:
ログインすると、**アカウント**ページのアカウント行の右側に、そのアカウントのクォータバー(「残り」で表示)と「x 分前」の更新時刻が表示されます。更新アイコンをクリックすると手動で再取得できます。
| 表示要素 | 例 | カラールール |
| ---------------- | ------------------- | --------------------------------------------- |
| 使用率 | `45%` | < 70% 緑、70–89% オレンジ、≥ 90% 赤 |
| リセットまでの時間 | `7d12h 後にリセット` | ChatGPT アカウントのスライディングウィンドウまたは日次制限 |
| 更新ボタン | 円形の矢印 | 手動でクォータを再取得 |
> ⚠️ **セッション期限切れ**:Token が完全に無効になった(自動更新できない)場合、カード下部に黄色い警告枠「セッション期限切れ」が表示されます。**設定 → 認証** からこのアカウントを削除し、再ログインしてください。
> ⚠️ **再ログインが必要**:Token が完全に無効になった(自動更新できない)場合、アカウント行に「再ログインが必要」と表示されます。**アカウント**ページでそのアカウントの「再ログイン」を選ぶか、削除して追加し直してください。
### よくある失敗
| シナリオ | 表示 | 解決方法 |
| --------------------------- | --------------------------------- | --------------------------------------------- |
| 認証コードタイムアウト | 「Device Code の有効期限切れ」 | 「再試行」をクリックして新しい認証コードを取得 |
| ブラウザで認証拒否 | 「ユーザーが認証を拒否」 | 再ログインしブラウザで「認証」をクリック |
| 認証コードのタイムアウト | ログインが完了しなかった旨のメッセージ | ログインをやり直し、新しい認証コードを取得 |
| ブラウザで認証拒否 | ログインが完了しなかった旨のメッセージ | 再ログインし、ブラウザで「認証」をクリック |
| ネットワークエラー | 具体的なエラー情報を表示 | ネットワーク接続を確認、OpenAI ドメインへのアクセス可否を確認 |
| ログイン前にプロバイダー作成 | 「先に ChatGPT にログインしてください」 | 先に 設定 → 認証 でログインを完了 |
| Token 更新失敗 | クォータ欄に「セッション期限切れ」 | アカウントを削除して再ログイン |
| クォータ取得失敗 | クォータ欄に「クエリに失敗しました」 | 「更新」ボタンをクリックして再試行 |
| ログイン前にプロバイダー追加 | 「先に ChatGPT にログインしてください」 | 先にアカウントページでログインを完了 |
| Token 更新失敗 | アカウント行に「再ログインが必要」 | そのアカウントで再ログイン |
| クォータ取得失敗 | アカウント行に「残量を取得できません」 | 更新アイコンをクリックして再試行 |
### ⚠️ リスク通知(重要)
@@ -520,7 +430,7 @@ Codex OAuth リバースプロキシは **リバースエンジニアリング
### 完全URLエンドポイントモード
v3.13.0 で追加された高度なオプション。デフォルトでは、CC Switch は設定された `base_url` を **プレフィックス** として扱い、`/v1/chat/completions` などの固定パスを後ろに連結します。一部のベンダー(非標準の URL レイアウトを必要とする第三者サービスなど)では、この連結方式ではリクエストが失敗します。
デフォルトでは、CC Switch は設定された `base_url` を **プレフィックス** として扱い、`/v1/chat/completions` などの固定パスを後ろに連結します。一部のベンダー(非標準の URL レイアウトを必要とする第三者サービスなど)では、この連結方式ではリクエストが失敗します。
**有効化方法**:
@@ -578,8 +488,6 @@ Codex または Grok Build のプロバイダーを編集する際、高度な
後の 2 つを選択した場合は、[ローカルルーティングサービス](../4-proxy/4.1-service.md)を有効にし、該当アプリのルーティングを有効にする必要があります。使用中はローカルルーティングを起動したままにしてください。プリセットを選択した場合、上流フォーマットは自動的に設定されるため、手動で調整する必要はありません。
> 💡 v3.16.5 より前は、ここは「ローカルルーティングが必要」トグルでしたが、現在は「上流フォーマット」に置き換えられています。モデルマッピングもこのトグルに依存しなくなりました。
#### モデルマッピング(Codex のみ)
Codex の非公式プロバイダーのフォームには、すべて **モデルマッピング** 表があり、このプロバイダーで利用可能なモデルを宣言できます:
@@ -618,7 +526,7 @@ Codex プロバイダーの追加時、**1M コンテキストウィンドウ**
- **有効時**:config.toml に `model_context_window = 1000000` を設定し、`model_auto_compact_token_limit = 900000` を自動入力
- **無効時**:両方のフィールドを削除
トグルがオンの場合に表示されるテキストフィールドで、自動コンパクト制限をカスタマイズできます。v3.15.0 以降、このトグルは Codex プロバイダーの新規追加時のみ表示されます。既存プロバイダーの編集時は、必要に応じて高度な設定で該当フィールドを直接調整してください。
トグルがオンの場合に表示されるテキストフィールドで、自動コンパクト制限をカスタマイズできます。このトグルは Codex プロバイダーの新規追加時のみ表示されます。既存プロバイダーの編集時は、必要に応じて高度な設定で該当フィールドを直接調整してください。
### カスタムアイコン
@@ -648,7 +556,7 @@ Codex プロバイダーの追加時、**1M コンテキストウィンドウ**
プロバイダーの追加や編集時に、API エンドポイントの速度テストができます:
1. プロバイダーを編集し、API エンドポイント欄の横にある「管理・テスト」をクリック
1. プロバイダーを編集し、リクエスト先アドレスの横にある「管理・テスト」をクリック
2. テストパネルで複数のエンドポイント URL を追加
3. 「テスト」をクリックして実行
4. レイテンシが最も低いエンドポイントを選択
@@ -659,4 +567,4 @@ Codex プロバイダーの追加時、**1M コンテキストウィンドウ**
- 🟠 オレンジ:レイテンシ 500–800ms
- 🔴 赤:レイテンシ ≥ 800ms
![image-20260108005327817](../../assets/image-20260108005327817.png)
<!-- TODO(v4 screenshot): Endpoint speed test panel after clicking "Manage & test" in the provider editor (with several endpoints and latency results) -->
+59 -31
View File
@@ -1,25 +1,49 @@
# 2.2 プロバイダーの切り替え
## 接続モード
Claude Code、Codex、Gemini CLI、Grok Build のアプリページの上部には、「直接接続 / ルーティング / 集約」の 3 つのタブがあります(集約があるのは Claude Code と Codex のみ):
| モード | リクエストの流れ | プロバイダーの切り替え |
|------|-----------|-----------|
| 直接接続 | クライアントがプロバイダーに直接接続 | クライアント設定ファイルの主要フィールドを書き換える |
| ルーティング | リクエストはまずこのマシン上の CC Switch を通り、フォーマット変換やフェイルオーバーができる | ルーティング先だけを変更し、設定ファイルはもう書き換えない |
| 集約 | `/model` で選んだモデルに応じてリクエストを複数のプロバイダーに振り分ける。フェイルオーバーはしない | 切り替わるのはデフォルトのプロバイダー |
**タブをクリックしても、そのページを見るだけで設定は変わりません。** 実際にモードを切り替えるには、ページ上で結果が明記されたボタン「ルーティングを開始」「集約に切り替え」「直接接続に戻す」をクリックします。タブの横の「有効」マークが、現在実際にどのモードかを示します。ルーティングと集約の詳細は [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md) を参照してください。
まず最も一般的な、直接接続での切り替えを説明します。
<!-- TODO(v4 screenshot): Top of an app page showing the Direct / Routing / Aggregation tabs, with the active mode marked "Active" -->
## メイン画面での切り替え
プロバイダーリストで、対象のプロバイダーカードの「有効化」ボタンをクリックします。
直接接続のページで、対象のプロバイダーカードの「切り替え」ボタンをクリックします。
OpenCode、OpenClaw、Hermes、Pi、MiniMax Code は共存型アプリで、複数のプロバイダーを同時に追加できます。操作方法は下記の [共存型アプリ](#共存型アプリ) を参照してください。
OpenCode、OpenClaw、Hermes、Pi、MiniMax Code は共存型アプリで、複数のプロバイダーを同時に追加できます。操作方法は下記の [共存型アプリ](#共存型アプリ) を参照してください。Claude Desktop にはモードのタブがありません。[2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。
### 切り替えフロー
1. 「有効化」ボタンをクリック
1. 「切り替え」ボタンをクリック
2. CC Switch が設定ファイルを更新
3. カードのステータスが「現在有効」に変更
3. カードのボタンが「使用中」の状態に変わる
4. アプリごとの方法で反映(下記「反映方法」を参照)
### ステータス表示
| ステータス | 表示 | 説明 |
|------|------|------|
| 現在有効 | 青い枠 + ラベル | 設定ファイル内の現在のプロバイダー |
| ルーティングアクティブ | 緑の枠 | ローカルルーティング有効時に実際にリクエストを転送しているプロバイダー |
| 通常 | デフォルトのスタイル | 有効化されていないプロバイダー |
| 使用中 | 直接接続の色の枠 + 「使用中」 | 直接接続モードで、設定ファイル内で現在使われているプロバイダー |
| 転送中 | ルーティングの色の枠 + 「転送中」 | ルーティングモードで、実際にリクエストを転送しているプロバイダー |
| 現在の既定 | 集約の色の枠 + 「現在の既定」 | 集約モードでのデフォルトのプロバイダー |
| 通常 | デフォルトのスタイル | その他のプロバイダー |
モードとカード上のボタンは次のように対応します:
- 直接接続のページで、実際にはルーティングまたは集約になっている場合、他のカードのボタンは「直接接続に戻して使う」です。
- ルーティングのページでは、他のカードのボタンは「ここへ転送」です。
- 「ルーティングが必要」と表示されたプロバイダー(フォーマット変換が必要なものなど)は直接接続できません。そのまま切り替えようとすると案内が表示され、「ルーティングを開始して使う」を選べます。
- 公式サブスクリプションはルーティングを通りません(Codex の OpenAI Official は例外)。ルーティングのページではグレー表示になります。
## トレイでの素早い切り替え
@@ -28,32 +52,34 @@ OpenCode、OpenClaw、Hermes、Pi、MiniMax Code は共存型アプリで、複
### 操作手順
1. システムトレイの CC Switch アイコンを右クリック
2. 対応するアプリのサブメニュー(例:「Claude · 現在のプロバイダー」)にマウスを合わせる
2. 対応するアプリのサブメニューにマウスを合わせる
3. 切り替えたいプロバイダー名をクリック
4. 切り替え完了、トレイに短い通知が表示
4. 切り替え完了、トレイに短い通知が表示(例:「Claude Code を xxx に切り替えました。反映するには Claude Code を再起動してください」)
### トレイメニュー構造
v3.13.0 より、トレイメニューがフラットなリストから **アプリ別サブメニュー** にリファクタリングされ、各アプリに独立したサブメニューが用意されました:
トレイには、切り替え式のアプリごとにサブメニューが 1 行ずつあります:
| サブメニュー | 説明 |
| ------------ | -------------------------------------------------------------------- |
| Claude | Claude のすべてのプロバイダー(Codex OAuth リバースプロキシを含む) |
| Codex | Codex のすべてのプロバイダー |
| Gemini | Gemini のすべてのプロバイダー |
| Grok Build | Grok Build のすべてのプロバイダー |
| サブメニュー | 説明 |
| ------ | ---- |
| Claude Code | このアプリのプロバイダー |
| Claude Desktop | このアプリのプロバイダー。モデルマッピングのプロバイダーには「 · モデルマッピング」が付く |
| Codex | このアプリのプロバイダー |
| Gemini CLI | このアプリのプロバイダー |
| Grok Build | このアプリのプロバイダー |
トレイに含まれるのは、ローカルルーティングに対応したこの 4 つのアプリだけです。Claude Desktop と共存型アプリはメイン画面で操作してください。
サブメニューのタイトルは「アプリ名 · [ルーティング / 集約 ·] 使用中のプロバイダー · クォータの概要」の形で、開かなくても、今どのプロバイダーを使っていて、どのモードかが分かります。サブメニュー内の動作は現在のモードに従います:
**リファクタリングの利点**:
- **直接接続**:プロバイダーをクリックすると切り替わります。ルーティングが必要なプロバイダーの後ろには「(ルーティングが必要)…」と表示され、クリックするとアプリページが開いて案内が表示されます。
- **ルーティング**:プロバイダーをクリックするとルーティング先が変わります。公式サブスクリプションには「(公式サブスクリプションはルーティングを通りません)」と表示され、クリックできません。
- **ルーティング + フェイルオーバー有効**:読み取り専用で、キューの順序が一覧表示されます。調整するにはアプリページで行ってください。
- **集約**:集約リストにあるプロバイダーだけが表示され、クリックするとそのプロバイダーがデフォルトになります。
- **メニューのオーバーフロー防止**:プロバイダーが多数ある場合、フラットなリストでは画面の高さを超えますが、アプリ別サブメニューは自然にスケールします
- **サブメニューのタイトルに現在有効なプロバイダーと使用量サマリーを表示**:サブメニューを開かなくても、Claude / Codex / Gemini / Grok Build がどのプロバイダーを使用中か、利用可能なキャッシュ済み使用量情報とあわせて確認できます
- **アプリ別の分離**:Claude のプロバイダーを切り替えても他のアプリのビューには影響しません
トレイに並ぶのはこの 5 つの切り替え式アプリだけです。共存型アプリはメイン画面で操作してください。
> **ヒント**:バックグラウンド常駐 + 軽量モード + アプリ別サブメニューの組み合わせは、複数のアプリを頻繁に切り替えるヘビーユーザーに特に適しています。[1.5 個人設定 → 軽量モード](../1-getting-started/1.5-settings.md) を参照してください。
> **ヒント**:バックグラウンド常駐 + 軽量モード + トレイのサブメニューの組み合わせは、複数のアプリを頻繁に切り替えるヘビーユーザーに特に適しています。[1.5 個人設定 → 軽量モード](../1-getting-started/1.5-settings.md) を参照してください。
![image-20260108004348993](../../assets/image-20260108004348993.png)
<!-- TODO(v4 screenshot): Tray menu with one app's submenu expanded, showing the mode title and the provider list -->
## 反映方法
@@ -69,9 +95,7 @@ Claude Code はホットリロードに対応しており、設定ファイル
### Codex
切り替え後は再起動が必要:
- 現在のターミナルウィンドウを閉じる
- ターミナルを再度開く
切り替え後は Codex の再起動が必要です。CLI は終了してから `codex` を再実行し、デスクトップ版は完全に終了(macOS では ⌘Q)してから開き直します。
### Gemini CLI
@@ -83,11 +107,15 @@ Gemini CLI は起動時に `.env` と `settings.json` を読み込むため、
切り替え後に Grok Build の再起動が必要です。切り替えに成功すると通知が表示されます。
### ローカルルーティング有効時
### ルーティングと集約モードのとき
ローカルルーティングを有効にすると、Claude Code、Codex、Gemini CLI、Grok Build のリクエストはすべて CC Switch 経由で転送されるため、プロバイダーの切り替えは以降のリクエストに即座に反映されます。ただし、切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
リクエストはすべて CC Switch 経由で転送されます。ルーティングのページでプロバイダーを切り替えると、変わるのはルーティング先だけで、以降のリクエストに即座に反映されます。切り替えによってモデルが変わる場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。
ローカルルーティングが有効な間に切り替わるのは、ローカルルーティングが使うプロバイダーです。有効にする前に使っていたプロバイダーはそのまま残り、カードに「直接接続」と表示されます。ローカルルーティングを無効にすると、設定ファイルはそのプロバイダーに書き戻されます。詳しくは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md#ルーティングとプロバイダーの切り替え) を参照してください。
ルーティング中も、直接接続のときに使っていたプロバイダーはそのまま残ります(カードに「直接接続時に使用」と表示)。直接接続に戻すと、設定ファイルはそのプロバイダーに書き戻されます。
集約モードでは、Claude Code の集約モデルリストの変更は即座に反映されます。Codex は完全に再起動しないと新しいモデルリストが見えません。CLI ではページの案内にある「Codex デーモンを再起動」をクリックし(実行中のタスクが中断されます)、デスクトップ版は ⌘Q で完全に終了してから開き直し、エディタ拡張はウィンドウを開き直します。
ルーティングと集約は CC Switch を起動したままにしておく必要があります。CC Switch を終了すると自動的に直接接続に戻り、次回起動時に再び接続されます。詳しくは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md) を参照してください。
## 設定ファイルの変更
@@ -115,7 +143,7 @@ Gemini CLI は起動時に `.env` と `settings.json` を読み込むため、
~/.codex/config.toml
```
サードパーティのプロバイダーの API Key は `config.toml` 内の該当プロバイダーの `experimental_bearer_token` に書き込まれ、`~/.codex/auth.json` には書き込まれません。`auth.json` は OpenAI 公式の ChatGPT ログイン専用です。サードパーティのプロバイダーに切り替えたときにこれを保持するかどうかは、「設定 → 一般 → Codex アプリ拡張」で決まります。モデルマッピングを設定したプロバイダーでは、`~/.codex/cc-switch-model-catalog.json` も生成されます。
サードパーティのプロバイダーの API Key は `config.toml` 内の該当プロバイダーの `experimental_bearer_token` に書き込まれ、`~/.codex/auth.json` には書き込まれません。`auth.json` は OpenAI 公式の ChatGPT ログイン専用です。サードパーティのプロバイダーに切り替えたときにこれを保持するかどうかは、「設定 → アプリ設定」の「直接切替時に公式ログインを保持」で決まります。モデルマッピングを設定したプロバイダーでは、`~/.codex/cc-switch-model-catalog.json` も生成されます。
### Gemini
@@ -136,7 +164,7 @@ Gemini CLI は起動時に `.env` と `settings.json` を読み込むため、
### Claude Desktop
Claude Desktop の 3P プロファイル設定に書き込みます(macOS では `~/Library/Application Support/Claude-3p/` 配下)。詳しくは [2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。
Claude Desktop の 3P プロファイル設定に書き込みます(macOS では `~/Library/Application Support/Claude-3p/` 配下)。直接接続のプロバイダーはアドレスと Key をそのまま書き込み、モデルマッピングのプロバイダーはローカルのルーティングサービスを指します。詳しくは [2.6 Claude Desktop](./2.6-claude-desktop.md) を参照してください。
## 共存型アプリ
+13 -13
View File
@@ -3,8 +3,8 @@
## 編集パネルを開く
1. 編集したいプロバイダーカードを見つける
2. カードにマウスをホバーして操作ボタンを表示
3. 「編集」ボタンをクリック
2. カード右側の鉛筆アイコン(「編集」)をクリック
3. フルページのエディタが開きます。「プロバイダー一覧に戻る」で離れます
## 編集可能な内容
@@ -32,7 +32,7 @@ CC Switch は豊富なアイコンカスタマイズ機能を提供していま
- アイコン名のツールチップ表示
- 選択結果のリアルタイムプレビュー
![image-20260108004734882](../../assets/image-20260108004734882.png)
<!-- TODO(v4 screenshot): The icon picker opened from the edit page -->
### 設定情報
@@ -46,7 +46,7 @@ Claude Code、Codex、Gemini CLI、Grok Build の編集パネル下部には、*
|------|--------|
| Claude Code | `~/.claude/settings.json` |
| Codex | `~/.codex/config.toml`(Key は上の API Key 入力ボックスにあり、エディタには重複して表示されません) |
| Gemini CLI | `~/.gemini/.env` と `~/.gemini/settings.json` |
| Gemini CLI | `~/.gemini/.env` と `~/.gemini/settings.json`(2 つのエディタ) |
| Grok Build | `~/.grok/config.toml` |
エディタの内容は 2 種類に分かれます。エディタの上にある 1 行の説明に、このアプリで 1 種類目に含まれるものが列挙されています:
@@ -54,14 +54,14 @@ Claude Code、Codex、Gemini CLI、Grok Build の編集パネル下部には、*
- **プロバイダーに合わせて切り替わるもの**:リクエスト先アドレス、Key、モデル名、API プロトコルなどの主要フィールドと、プロバイダーに付随する一部の互換オプション(コンテキストウィンドウなど)。このプロバイダー自身の値が表示され、保存するとこのプロバイダーに保存されます。
- **グローバル設定**:それ以外のすべての内容(プラグイン、Hook、権限、MCP、自分で追加した環境変数など)。ツールの設定ファイルの現在の内容が表示され、保存するとそのまま設定ファイルに書き込まれ、すべてのプロバイダーに適用されます。
現在のプロバイダーを編集する場合も、他のプロバイダーを編集する場合も、ルールはまったく同じです。どのプロバイダーを編集していても、グローバル設定を変更するとすぐに設定ファイルに書き込まれます。ローカルルーティングが有効な場合も、エディタの主要フィールドにはプロバイダー自身の実際のアドレスと Key が表示され、ローカルルーティングのアドレスは表示されません。
現在のプロバイダーを編集する場合も、他のプロバイダーを編集する場合も、ルールはまったく同じです。どのプロバイダーを編集していても、グローバル設定を変更するとすぐに設定ファイルに書き込まれます。ルーティングモードのときも、エディタの主要フィールドにはプロバイダー自身の実際のアドレスと Key が表示され、ローカルルーティングのアドレスは表示されません。
### ツール側で変更した設定
- **グローバル設定**:ツール側で変更した内容(プラグインのインストールなど)は、編集パネルを開けばそのまま表示され、プロバイダーを切り替えても変更されません。
- **主要フィールド**:ツール側で一時的に変えたモデル(Claude Code の `/model` など)はプロバイダーに保存されず、別のプロバイダーに切り替えてから戻すと、プロバイダーに保存された値に戻ります。恒久的に変更したい場合は、ここでプロバイダーを編集してください。
> 💡 旧バージョンでは、現在のプロバイダーを編集するときに設定ファイル全体をプロバイダーに読み戻していました(「バックフィル」)。新バージョンではバックフィルを行いません。共有設定はもともと設定ファイルに残っているため、特定のプロバイダーに保存する必要がないからです。
> 💡 **共通設定スニペットは凍結されました**:旧バージョンには「共通設定スニペット」があり、切り替え時に設定ファイルへマージされていました。また、現在のプロバイダーを編集するときに設定ファイル全体をプロバイダーに読み戻していました(「バックフィル」)。新バージョンではどちらも行いません。共有設定はもともと設定ファイルに残っているため、特定のプロバイダーに保存する必要も、スニペットも必要ないからです。既存のプロバイダーに残っているスニペットは旧バージョンが読むためだけのもので、新バージョンには影響しません。
### 編集中に設定ファイルが変更された場合
@@ -144,15 +144,15 @@ Claude プロバイダーの編集時、JSON エディタの上部にツール
- 既存のエンドポイントの削除
- デフォルトエンドポイントの設定
## JSON エディタ
## JSON / TOML エディタ
設定は JSON 形式を使用し、エディタは以下を提供します:
Claude Code と Gemini CLI の設定エディタは JSON(Gemini の `.env` は環境変数のテキスト)、Codex と Grok Build は TOML を使います。エディタは以下を提供します:
- シンタックスハイライト
- フォーマット検証
- エラー通知
### よくあるエラー
### よくあるエラー(JSON の例)
**引用符の欠落**:
```json
@@ -183,12 +183,12 @@ Claude プロバイダーの編集時、JSON エディタの上部にツール
## 保存と反映
1. 「保存」ボタンをクリック
2. フォームが非ブロッキングな問題を検出した場合、「それでも保存」の確認が表示されます。確認すると保存できます
1. ページ下部の「保存」ボタンをクリック
2. フォームが非ブロッキングな問題を検出した場合、「設定に以下の問題があります」の確認が表示されます。「それでも保存」をクリックすると保存できます
3. グローバル設定の変更は、編集しているのが現在のプロバイダーかどうかに関係なく、すぐに設定ファイルに書き込まれます
4. 主要フィールドの変更はプロバイダーに保存されます。ローカルルーティングが無効な場合、現在のプロバイダーを編集していれば、設定ファイルにも同時に書き込まれます。ローカルルーティングが有効な場合、ルーティングが使用中のプロバイダーを編集していて、かつその変更がローカルルーティングの設定ファイルへの書き込み内容に影響するとき(モデル名など)は、設定ファイルも合わせて更新されます
4. 主要フィールドの変更はプロバイダーに保存されます。直接接続モードでは、使用中のプロバイダーを編集していれば、設定ファイルにも同時に書き込まれます。ルーティングモードでは、ルーティングが使用中のプロバイダーを編集していて、かつその変更がルーティングの設定ファイルへの書き込み内容に影響するとき(モデル名など)は、設定ファイルも合わせて更新されます
5. ツールの再起動が必要かどうかは、プロバイダーの切り替えと同じです。[2.2 プロバイダーの切り替え](./2.2-switch.md) を参照してください
## 編集のキャンセル
「キャンセル」ボタンをクリックするか `Esc` キーを押して編集パネルを閉じると、すべての変更は保存されません。
「キャンセル」または「プロバイダー一覧に戻る」をクリックして編集ページを離れると、変更は保存されません。編集途中の内容がある場合は「未保存の変更があります」と表示され、「破棄して移動」を選んだときだけ破棄されます。
@@ -6,15 +6,16 @@
### 操作手順
1. プロバイダーカード左側の **≡** ドラッグハンドルにマウスを合わせる
1. マウスをプロバイダーカードの上に移動すると、カードの左端に **⋮⋮** ドラッグハンドルが表示される(普段は非表示)
2. マウスの左ボタンを押し続ける
3. 目的の位置まで上下にドラッグ
4. マウスを離して並べ替え完了
4. マウスを離して並べ替え完了。「並び順を更新しました」と通知される
### 並べ替えの用途
- **よく使うものを優先**:よく使うプロバイダーをリストの上部に配置
- **フェイルオーバーの順序**:並び順はフェイルオーバーキューのデフォルト順序に影響
- **フェイルオーバーの順序**:キュー内の順序がそのままプロバイダーの並び順です。「ルーティング」タブの「キュー · 優先順」では、カード上の上へ・下へボタンや直接のドラッグでも、どれから先に送るかを調整できます。詳しくは [4.3 フェイルオーバー](../4-proxy/4.3-failover.md) を参照してください
- トレイメニューのプロバイダーの順序も連動して変わる
## プロバイダーの複製
@@ -24,28 +25,28 @@
- 現在の設定をバックアップ
- テスト用の設定を作成
v3.15.0 以降、統一プロバイダー一覧にも複製アクションがあります。既存の統一プロバイダーをコピーしてから、有効化するアプリやモデルを調整できます。
統一プロバイダー一覧(追加ページの「統合プロバイダー」カテゴリにある「既存の統合プロバイダーを管理」)にも複製ボタンがあります。既存の統一プロバイダーをコピーしてから、有効化するアプリやモデルを調整できます。
### 操作手順
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「複製」ボタンをクリック
1. プロバイダーカード右側の **⋯**(その他)ボタンをクリック
2. 「複製」を選択
3. 名前に `copy` が付加されたコピーが自動作成
4. コピーを編集して設定を変更
4. カードの編集ボタンをクリックして、コピーの設定を変更
### コピーされる内容
コピーは完全な複製が作成され、以下を含みます:
コピーでは次のものを引き継いだ複製が作成されます:
| 内容 | コピーされるか |
|------|----------|
| 名前 | コピーされる(`copy` が付加) |
| 設定 | 完全にコピー |
| メモ | コピーされる |
| メモ | コピーされない。必要ならコピー側で入力し直す |
| Web サイトリンク | コピーされる |
| アイコン | コピーされる |
| エンドポイントリスト | コピーされる |
| 並び順の位置 | 元のプロバイダーの下に挿入 |
| 並び順の位置 | 元のプロバイダーの直後に並ぶ |
### コピー後の編集
@@ -59,20 +60,18 @@ v3.15.0 以降、統一プロバイダー一覧にも複製アクションがあ
### 操作手順
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「削除」ボタンをクリック
3. 削除を確認
1. プロバイダーカード右側の **⋯**(その他)ボタンをクリック
2. 「削除」を選択(赤色、メニューの一番下)
3. 確認ダイアログで削除を確認
### 削除の確認
削除前に確認ダイアログが表示され、以下が表示されます:
- プロバイダー名
- 削除後は元に戻せないという注意
- 「この操作は元に戻せません」という注意
### 削除の制限
- **現在有効なプロバイダー**:削除可能ですが、先に他のプロバイダーに切り替えることをお勧めします
- **使用中のプロバイダー**:削除できません。「削除」はグレー表示で、「使用中のプロバイダーは削除できません。先にほかへ切り替えてください。」と説明が表示されます。切り替え式のアプリでは、直接接続で使っているもののほか、ルーティングまたは集約モードで転送先になっているものも該当します。先に別のプロバイダーへ切り替えてから削除してください
- **統一プロバイダー**:削除すると、関連するアプリの設定も削除されます
![image-20260108004946288](../../assets/image-20260108004946288.png)
@@ -2,6 +2,8 @@
CC Switch のクォータ・残高表示は 2 つのカテゴリに分かれます:**自動表示**(OAuth アカウント系、すぐに使える)と **手動有効化**(内蔵テンプレート + カスタムスクリプト、プロバイダーカードで設定した後に表示)。
> このページで説明するのは、プロバイダーカード上の **クォータ / 残高** です。リクエスト数、Token、コストの統計は左サイドバーの「使用量」ページにあります。[4.4 使用量統計](../4-proxy/4.4-usage.md) を参照してください。
| カテゴリ | 範囲 | ユーザー操作必要 |
| ---------------------------------- | --------------------------------------------------------------------------------- | ---------------- |
| **自動表示** | GitHub Copilot、Codex OAuth リバースプロキシ、xAI OAuth | 不要 |
@@ -20,10 +22,10 @@ CC Switch のクォータ・残高表示は 2 つのカテゴリに分かれま
### 自動表示の操作
- **カード下部表示**:使用率 + リセットまでのカウントダウン、使用率に応じて色が変化(< 70% 緑 / 70–89% オレンジ / ≥ 90% 赤)
- **手動更新**:カード上の更新アイコンをクリックして再取得
- **カードの簡略化**:これらのプロバイダーのクォータは内蔵ロジックで表示されるため、カード上の「使用量クエリ」ボタンはグレーアウトされ使用できません
- **セッション期限切れ通知**:Token の更新に失敗した場合、カードに「セッション期限切れ」警告が表示されます
- **カード下部表示**:クォータは常に「残り」で表示されます(例:「5時間 残り 62%」)。横にリセットまでのカウントダウンが付きます。普段はグレーで、いずれかの枠の残りが 10% を切ると文字が濃く太くなります。使い切ると「使い切り」、プランの期限が切れると「プラン期限切れ」、取得に失敗すると「残量を取得できません」(赤)と表示されます
- **手動更新**:クォータの文字をクリックして再取得します(ホバーすると「クリックで再取得」と更新時刻が表示されます)
- **カードの簡略化**:これらのプロバイダーのクォータは内蔵ロジックで表示されるため、カードの「その他」メニューに「利用状況を設定」はありません
- **ログイン期限切れ通知**:Token の更新に失敗した場合、カードに「ログインの期限切れ」または「トークンの更新待ち」と表示されます。左サイドバーの **アカウント** で再ログインしてください
---
@@ -35,11 +37,11 @@ CC Switch のクォータ・残高表示は 2 つのカテゴリに分かれま
v3.16.2 以降、Claude / Codex / Gemini / Grok Build の公式プロバイダーのサブスクリプションクォータは、**デフォルトで無効** の内蔵テンプレートに変わりました:
1. 公式プロバイダーのカードで **使用量クエリ** ボタンをクリック
1. 公式プロバイダーのカード右側の「その他」(⋯)ボタンをクリックし、**利用状況を設定** を選択
2. 「利用状況照会を有効にする」をオンにし、テンプレートで **公式サブスクリプション** を選択
3. 保存すると、カード下部にサブスクリプションクォータが表示されます(Grok Build の場合は SuperGrok のクォータ)
3. 保存すると、カード下部にサブスクリプションクォータが表示されます(Grok Build の場合は SuperGrok のクォータ)。公式サブスクリプションのクォータは、このマシン上の CLI の OAuth 認証情報を読み取って公式 API を呼び出すもので、有効にしたときだけリクエストされます
例外:認証センターの ChatGPT アカウントに紐付けられた OpenAI Official プロバイダーは、デフォルトで有効です。
例外:アカウントページの ChatGPT アカウントに紐付けられた OpenAI Official プロバイダーは、デフォルトで有効です。
### なぜ手動有効化が必要なのか?
@@ -59,15 +61,15 @@ v3.13.0 では以下のカテゴリに **すぐに使える内蔵テンプレー
### 有効化手順
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. **使用量クエリ** ボタン(📊 アイコン)をクリック
1. プロバイダーカードにマウスをホバーし、右側の「その他」(⋯)ボタンをクリック
2. **利用状況を設定** を選択(初回は確認が表示されるので「理解しました、設定する」をクリック)
3. 設定パネル上部の **利用状況照会を有効にする** スイッチをオンにする
4. 適切な内蔵テンプレート(Token Plan、第三者残高など)または「カスタム」を選択
5. 必要に応じて API Key / Base URL / Access Token などのパラメータを入力(多くの場合は空欄のままプロバイダー自身の認証情報を使用可能)
6. 「スクリプトをテスト」をクリックして正常に応答するか確認
7. 設定を保存 —— 次回プロバイダーを有効化すると、カード下部にクォータが表示されます
7. 設定を保存 —— カード下部にクォータが表示されます
> ⚠️ **注意**:有効化後の自動更新間隔は「自動照会間隔」フィールドで制御します(`0` に設定すると自動更新を無効化)。プロバイダーが「現在有効」状態のときのみバックグラウンドクエリがトリガーされます。
> ⚠️ **注意**:有効化後の自動更新間隔は「自動照会間隔」フィールドで制御します(`0` に設定すると自動更新を無効化)。プロバイダーが「使用中」状態のときのみバックグラウンドクエリがトリガーされます。
---
@@ -84,8 +86,8 @@ v3.13.0 では以下のカテゴリに **すぐに使える内蔵テンプレー
## 設定を開く
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「使用量クエリ」ボタン(📊 アイコン)をクリック
1. プロバイダーカードにマウスをホバーし、右側の「その他」(⋯)ボタンをクリック
2. 「利用状況を設定」を選択
3. 使用量クエリ設定パネルが開く
## 使用量クエリの有効化
@@ -94,7 +96,7 @@ v3.13.0 では以下のカテゴリに **すぐに使える内蔵テンプレー
## プリセットテンプレート
CC Switch は 3 種類のプリセットテンプレートを提供しています:
プリセットテンプレートのドロップダウンには、カスタム、General、NewAPI のほか、上で説明した Token Plan、公式、公式サブスクリプションなどの内蔵テンプレートがあります。カスタムスクリプトでよく使う 3 種類は次のとおりです:
### カスタムテンプレート
@@ -180,8 +182,8 @@ New API タイプの中継サービス専用に設計されています:
使用量データの自動更新間隔(分):
- `0` に設定すると自動クエリを無効化
- 範囲:0-1440 分(最長 24 時間)
- プロバイダーが「現在有効」のときのみ動作
- 範囲:0-1440 分(最長 24 時間)。5〜60 分を推奨
- プロバイダーが「使用中」のときのみ動作
## エクストラクターの戻り値形式
@@ -211,7 +213,8 @@ New API タイプの中継サービス専用に設計されています:
設定が成功すると、プロバイダーカードに以下が表示されます:
- **単一プラン**:残額を直接表示
- **複数プラン**:プラン数を表示、クリックで詳細を展開
- **複数プラン**:「N プラン」と表示し、「展開」をクリックすると詳細を確認できます
- プラン系のクォータも同様に「残り」が中心です。取得に失敗すると「残量を取得できません」と表示されます
## 変数プレースホルダー
@@ -232,8 +235,8 @@ New API タイプの中継サービス専用に設計されています:
**確認事項**:
1. 公式プロバイダー(Claude / Codex / Gemini / Grok Build):「使用量クエリ」で「利用状況照会を有効にする」をオンにし、**公式サブスクリプション** テンプレートを選択しているか(デフォルトは無効)
2. プロバイダーが「現在有効」状態か(非アクティブ時はクエリがトリガーされません)
3. OAuth アカウント系(Copilot / Codex OAuth / xAI OAuth)の場合、Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は **設定 → 認証** で再ログインしてください
2. プロバイダーが「使用中」状態か(使用中でないときはバックグラウンドクエリがトリガーされません)
3. OAuth アカウント系(Copilot / Codex OAuth / xAI OAuth)の場合、Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は、左サイドバーの **アカウント** で再ログインしてください
4. 公式クォータエンドポイントへのネットワークアクセス可否
### 手動有効化後もクォータが表示されない
@@ -244,7 +247,7 @@ New API タイプの中継サービス専用に設計されています:
3. 「スクリプトをテスト」をクリックして具体的なエラー情報を確認
4. API Key / Base URL などの必須フィールドが正しく入力されているか
5. プロバイダーのクォータエンドポイントへのネットワークアクセス可否
6. プロバイダーが「現在有効」状態のときのみ、バックグラウンドの自動更新がトリガーされます
6. プロバイダーが「使用中」状態のときのみ、バックグラウンドの自動更新がトリガーされます
### クエリ失敗
@@ -2,7 +2,7 @@
## 機能概要
Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイダー設定を管理できます。
Claude Desktop ページでは、CC Switch 上で Claude Desktop のプロバイダー設定を管理できます。
有効にすると、次のことができます。
@@ -11,7 +11,7 @@ Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイ
- Copilot / Codex OAuth / xAI OAuth のアカウント型プロバイダーを再利用する
- Claude Desktop 公式モードとサードパーティプロバイダーを切り替える
Claude Desktop と Claude Code は別々のアプリ入口です。Claude Code は `~/.claude/settings.json` を使い、Claude Desktop は専用の 3P profile 設定を使います。CC Switch 上でも「Claude」と「Claude Desktop」として別々に表示され、アイコン右下の小さなバッジで区別できます。
Claude Desktop と Claude Code は別々のアプリ入口です。Claude Code は `~/.claude/settings.json` を使い、Claude Desktop は専用の 3P profile 設定を使います。CC Switch 上でも「Claude」と「Claude Desktop」として別々に表示され、サイドバーの Claude Desktop アイコンの右下にある小さなバッジで区別できます。
## 対応範囲
@@ -26,27 +26,25 @@ Claude Desktop と Claude Code は別々のアプリ入口です。Claude Code
## クイックスタート
### ステップ 1:Claude Desktop パネルへ切り替える
### ステップ 1:Claude Desktop ページを開く
左側のアプリ切り替えから **Claude Desktop** を選択します。
左サイドバーのアプリ一覧から **Claude Desktop** を選択します。
![Claude Desktop パネル](../../assets/claude-desktop-panel-ja.png)
<!-- TODO(v4 screenshot): Provider page with Claude Desktop selected in the sidebar, the access bar at the top showing "Current: xxx · Direct" -->
この入口が見つからない場合は、次を確認してください。
サイドバーにこの入口が見つからない場合は、サイドバーの「アプリ」ページで「サイドバーに表示するアプリ」を開き、Claude Desktop が非表示になっていないことを確認してください。
設定 → 一般 → ホームページ表示
Claude Desktop が非表示になっていないことを確認します。
Claude Desktop ページには「直接接続 / ルーティング / 集約」のタブがありません。接続方法はプロバイダーごとに設定し、ページ上部の接続バーに、現在のプロバイダーが「直結」か「モデルマッピング」か、およびルーティングサービスの状態が表示されます。
### ステップ 2:プロバイダーをインポートまたは追加する
#### 推奨:Claude Code から一括インポート
多くのユーザーはまず Claude Code 側でプロバイダーを設定し、その同じプロバイダー群を Claude Desktop に持ち込みたいはずです。CC Switch の初回起動時、または Claude Desktop パネルを初めて開いたときにプロバイダーがまだない場合は、**Claude Code の既存プロバイダーをインポート** をクリックします。
多くのユーザーはまず Claude Code 側でプロバイダーを設定し、その同じプロバイダー群を Claude Desktop に持ち込みたいはずです。CC Switch の初回起動時、または Claude Desktop ページを初めて開いたときにプロバイダーがまだない場合は、**Claude Code の既存プロバイダーをインポート** をクリックします。
![Claude Code からプロバイダーをインポート](../../assets/claude-desktop-import-from-claude-ja.png)
<!-- TODO(v4 screenshot): The "Import existing providers from Claude Code" button in the empty list -->
Claude Code 側に多くのプロバイダーがすでにある場合、この機能で Claude Desktop パネルへ一括インポートできます。エンドポイント URL、API Key、デフォルトモデルを一つずつ入力し直す必要がありません。
Claude Code 側に多くのプロバイダーがすでにある場合、この機能で Claude Desktop ページへ一括インポートできます。エンドポイント URL、API Key、デフォルトモデルを一つずつ入力し直す必要がありません。
インポートルール:
@@ -61,9 +59,9 @@ Claude Code 側に多くのプロバイダーがすでにある場合、この
すでに Claude Code でプロバイダーを設定している場合は、まず **Claude Code の既存プロバイダーをインポート** を使ってください。Claude Desktop へ移行する最も簡単な方法です。
インポートできる設定がない場合、または Claude Desktop 専用にプロバイダーを追加したい場合は、右上の **+** ボタンをクリックします。
インポートできる設定がない場合、または Claude Desktop 専用にプロバイダーを追加したい場合は、ページ右上の「プロバイダーを追加」ボタンをクリックします。
![Claude Desktop プロバイダーを追加](../../assets/claude-desktop-add-provider-ja.png)
<!-- TODO(v4 screenshot): The Add provider page for Claude Desktop -->
選べる方法:
@@ -81,18 +79,20 @@ Claude Desktop の三つの役割 ID(`claude-sonnet-*` / `claude-opus-*` / `cl
### ステップ 3:切り替えて Claude Desktop を再起動する
プロバイダーカードで **有効化** をクリックします。
プロバイダーカードで「切り替え」をクリックすると、現在のカードに「使用中」と表示されます。
切り替え後:
- 直結プロバイダー:Claude Desktop を再起動すると反映されます
- ルーティングが必要なプロバイダー:CC Switch を起動したまま、Claude Desktop ローカルルーティングをオンにし、Claude Desktop を再起動します
- モデルマッピングのプロバイダー:CC Switch がルーティングサービスを自動で起動して動かし続けるので、そのうえで Claude Desktop を再起動します
> 注意:Claude Desktop は Claude Code のように設定をホットリロードしません。プロバイダーを切り替えるたびに、Claude Desktop を完全に終了して再度開く必要があります。
## 2 つの動作モード
## 2 つの接続方式
### 直結モード
プロバイダーの編集ページの「接続方式」で「直接接続」または「モデルマッピング」を選びます(「モデルマッピングが必要」スイッチに対応)。カードにも「直結」「モデルマッピング」のバッジで表示されます。
### 直結
直結モードは、プロバイダー自身が Anthropic Messages API を提供しており、Claude Desktop から直接アクセスできる場合に適しています。
@@ -112,15 +112,15 @@ Claude Desktop の三つの役割 ID(`claude-sonnet-*` / `claude-opus-*` / `cl
- プロバイダーがネイティブの Anthropic Messages API を公開している
- モデル ID が Claude Desktop の認識できる役割名:`claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*`(または `anthropic/claude-` 接頭辞の同種名)
- 形式変換が不要
- 使用中に CC Switch のローカルルーティングを起動し続ける必要がない
- 使用中に CC Switch のルーティングサービスを動かし続ける必要がない
直結モードの「Claude Desktop モデルを手動指定」は高度な任意設定です。多くのネイティブ Claude モデルプロバイダーでは不要で、Claude Desktop が `/v1/models` を自動取得します。
プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。手動で入力するモデル名は `claude-sonnet-*`、`claude-opus-*`、`claude-haiku-*` の形式である必要があります(`claude-3-5-sonnet-…` のような旧式 ID は拒否されます)。
### モデルマッピングモード
### モデルマッピング
モデルマッピングモードは、プロバイダーのモデルが `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID でない場合(旧式 Claude ID や DeepSeek、Kimi などの非 Claude モデルを含む)、または CC Switch による API 形式変換が必要な場合に適しています。
モデルマッピングは、プロバイダーのモデルが `claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*` の三つの役割 ID でない場合(旧式 Claude ID や DeepSeek、Kimi などの非 Claude モデルを含む)、または CC Switch による API 形式変換が必要な場合に適しています。
**モデルマッピングが必要** をオンにすると、Claude Desktop は CC Switch のローカルゲートウェイへ接続します。
@@ -157,7 +157,7 @@ CC Switch は次を担当します。
| リクエストモデル | プロバイダーへ送信する実際のアップストリームモデル ID |
| 1M | Claude Desktop に 1M コンテキスト対応を宣言 |
![Claude Desktop モデルマッピング](../../assets/claude-desktop-model-mapping-rows-ja.png)
<!-- TODO(v4 screenshot): A few model mapping rows in the edit page (model role, menu display name, request model, 1M) -->
### 推奨設定
@@ -187,35 +187,33 @@ Sonnet、Opus、Haiku の 3 つを同時に設定できます。
プロバイダーにモデルが 1 つしかない場合は、1 つの役割のリクエストモデルだけ入力すれば十分です。空欄の役割は最初に入力したモデル(Sonnet 優先)を自動的に引き継ぐため、サブ agent が呼び出す Haiku なども常に利用できます。モデルマッピングモードでは少なくとも 1 つのリクエストモデルが必要です。
## ローカルルーティング切り替え
## ルーティングサービス
モデルマッピングモードでは、リクエスト変換のために CC Switch ローカルルーティングが必要です。Claude Desktop パネルの右上には Claude Desktop ローカルルーティング切り替えが常に表示され、「メインページにルーティング切り替えを表示」設定の影響を受けません(この設定が制御するのは Claude Code、Codex、Gemini CLI、Grok Build ページの切り替えだけです)。
モデルマッピングでは、CC Switch のルーティングサービスがリクエストを転送します。サービスはデフォルトで `127.0.0.1:15721` をリッスンします。**手動で切り替える必要はありません**。現在のプロバイダーがモデルマッピングのときはルーティングサービスが自動で起動して動き続け、現在のプロバイダーが直結のときは、ページ上部に「ルーティングサービス:現在のプロバイダーには不要」と表示されます。
![Claude Desktop ローカルルーティング切り替え](../../assets/claude-desktop-route-toggle-context-ja.png)
<!-- TODO(v4 screenshot): "Routing service: running" on the access bar while a model mapping provider is in use -->
状態説明:
接続バーの状態:
| 状態 | 説明 |
|------|------|
| オン | ローカルゲートウェイが起動中。通常は `127.0.0.1:15721` |
| オフ | 直結プロバイダーは利用可能。モデルマッピングプロバイダーは正常に動作しません |
| 読み込み中 | ルーティングサービスの起動または停止中 |
| ---- | ---- |
| ルーティングサービス 実行中 | ローカルゲートウェイが起動中 |
| ルーティングサービスを起動できませんでした | 「再試行」をクリック。ポートが使用中の場合は「ポートを変更」をクリックすると「設定 → ローカルルーティング」に移動して変更できます |
| ルーティングサービス:現在のプロバイダーには不要 | 現在のプロバイダーが直結、または公式モード |
**モデルマッピングが必要** なプロバイダーだけがローカルルーティングに依存します。直結プロバイダーではこの切り替えは不要です。
他のアプリがローカルルーティングを使用している場合、ローカルルーティングの停止がブロックされることがあります。先に「設定 → ルーティング → ローカルルーティング」で該当アプリのルーティングをオフにしてから、ローカルルーティングを停止してください。
他のアプリがルーティングまたは集約を使用している場合、ルーティングサービスは停止できません。先に「設定 → ローカルルーティング」で「すべて直接接続に戻す」を使ってそれらのアプリを直接接続に戻してから、サービスを停止してください。
## 公式 Claude Desktop に戻す
Claude Desktop の公式サインインへ戻す場合:
1. **Claude Desktop Official** を選択する
2. **有効化** をクリックする
2. 「切り替え」をクリックする
3. Claude Desktop を再起動する
CC Switch は Claude Desktop の公式 1P モードを復元し、CC Switch が管理する 3P profile を削除します。
公式モードでは API Key もローカルルーティングも不要です。
公式モードでは API Key もルーティングも不要です。
Claude Code からプロバイダーをインポートするとき、CC Switch は自動的に **Claude Desktop Official** も追加します。
@@ -254,11 +252,11 @@ CC Switch は Claude Desktop の 3P 設定ディレクトリに書き込みま
CC Switch 自体を Flatpak でインストールした場合も、Flatpak 固有の `XDG_CONFIG_HOME` ではなく、上記のホスト側 `~/.config` を使用します。これは意図的な設計上の境界です。Flatpak はサンドボックス内でこの変数を置き換えるため、元のホスト値を確実に取得できません。そのため CC Switch は設定ディレクトリの上書き項目を提供せず、ホスト側で独自設定された `XDG_CONFIG_HOME` を追従しません。Claude Desktop が独自の XDG 設定ディレクトリを使用する場合は、ネイティブ版 CC Switch を使用してください。同梱 Flatpak は現在 Home ディレクトリへのアクセスを許可しています。より厳格な独自 Flatpak ビルドでは、`xdg-config/Claude` と `xdg-config/Claude-3p` への読み書き権限が必要です。
これらのファイルは CC Switch が自動管理します。手動編集はおすすめしません。設定の不整合が起きた場合は、現在のプロバイダーを再度有効化すると通常は修復できます。
これらのファイルは CC Switch が自動管理します。手動編集はおすすめしません。設定の不整合が起きた場合は、現在のプロバイダーへ再度切り替えると通常は修復できます。
## ステータス表示と対処
Claude Desktop パネル上部に「Claude Desktop 設定の確認が必要です」と表示されることがあります。
Claude Desktop ページ上部に「Claude Desktop 設定の確認が必要です」と表示されることがあります。
| 表示 | 対処方法 |
|------|----------|
@@ -279,14 +277,14 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk
次を確認してください。
- CC Switch が起動したままになっている
- Claude Desktop ローカルルーティングがオンになっている
- 接続バーのルーティングサービスが「実行中」と表示されている
- プロバイダーの API Key とエンドポイント URL が正しい
- モデルマッピングにリクエストモデルが入力されている
- プロバイダー切り替え後に Claude Desktop を再起動した
### Claude Desktop のモデルメニューにブランド名が表示されない?
プロバイダーを編集し、モデルマッピングの **メニュー表示名** を入力してください。その後、プロバイダーを再度有効化し、Claude Desktop を再起動します。
プロバイダーを編集し、モデルマッピングの **メニュー表示名** を入力してください。その後、そのプロバイダーへ再度切り替え、Claude Desktop を再起動します。
### 直結モードでエラーになるのはなぜ?
@@ -296,12 +294,12 @@ Claude Desktop を完全に終了して再起動してください。Claude Desk
モードによります。
- 直結モード:Claude Desktop が再起動して設定を読み込んだ後は、ローカルルーティングを起動し続ける必要はありません
- モデルマッピングモード:CC Switch を起動したままにし、Claude Desktop ローカルルーティングもオンにしておく必要があります
- 直結:Claude Desktop が再起動して設定を読み込んだ後は、CC Switch を終了してもかまいません
- モデルマッピング:CC Switch を起動したままにし、ルーティングサービスを動かし続ける必要があります(自動で管理されます)
### 実際のアップストリームモデル名は Claude Desktop に書き込まれる?
モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な Sonnet / Opus / Haiku 役割ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。
モデルマッピングでは書き込まれません。Claude Desktop profile には安全な Sonnet / Opus / Haiku 役割ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。
## 次のステップ
+54 -36
View File
@@ -11,48 +11,62 @@ MCP (Model Context Protocol) は、AI ツールが外部データソースやツ
## MCP パネルを開く
上部ナビゲーションバーの **MCP** アイコンボタンをクリックします(マウスを合わせると「MCP 管理」と表示されます。Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、Hermes、MiniMax Code のページで表示されます)。
左サイドバーの **MCP** をクリックします。これはグローバルなページで、特定のアプリに属しません。どのアプリを選択していても同じパネルが開きます(Claude Desktop には独自の MCP がなく、ここにも列はありません)。
## パネル概要
![image-20260108005723522](../../assets/image-20260108005723522.png)
<!-- TODO(v4 screenshot): MCP page overview: one row per MCP, per-app toggle columns on the right, header with "Import from apps", "Add MCP" and the ⋯ menu -->
ページはマトリクス表です。**1 行が 1 つの MCP サーバー、1 列が 1 つのアプリ**で、セルのスイッチが「この MCP をこのアプリで有効にする」を表します。
- ヘッダー:「アプリから取り込む」「MCP を追加」と、⋯ メニュー(「ここのスイッチで各アプリの設定を書き直す」「すべてを mcpServers JSON としてコピー」)
- 検索ボックス:名前・コマンド・URL で絞り込み
- サイドバーの「アプリ」ページで表示にしたアプリの列だけを表示します。非表示は画面にだけ影響し、非表示のアプリに書き込み済みの設定はそのまま残り、同期も続きます
- 各行の右側に「編集」ボタンと ⋯ メニュー(JSON としてコピー、ドキュメントを開く、すべてのアプリで有効化、すべてオフ、削除)があります
- あるアプリへの書き込みに失敗した場合、その行に失敗したアプリが表示され、「再試行」を押せます
## MCP サーバーの追加
### プリセットテンプレートを使用
### テンプレートを使用
1. 右上の **+** ボタンをクリック
2. 「プリセット」ドロップダウンからテンプレートを選択
3. 必要に応じて設定を変更
4. 「保存」をクリック
1. ヘッダーの **MCP を追加** をクリックすると、右側にドロワーが開きます
2. 「テンプレートから始める」でテンプレートを選びます。空のまま自分で入力することもできます
3. 必要に応じて内容を変更し、「書き込み先」で有効にするアプリをチェックします
4. 「追加」をクリックします
![image-20260108005739731](../../assets/image-20260108005739731.png)
<!-- TODO(v4 screenshot): Add MCP drawer: templates, paste config, connection settings, write-to -->
### 主なプリセット
### 設定を貼り付け
| プリセット | パッケージ名 | 機能説明 |
ドロワーの「設定を貼り付け」に JSON または TOML をそのまま貼り付けると、`mcpServers`、Codex の `[mcp_servers.名前]`、OpenCode の local / remote 形式を自動認識し、下のフォームに入力します。複数のサーバーをまとめて貼り付けた場合は、「新規」と「同名あり」のエントリーが一覧表示され、同名のものはスキップか上書きを選べます。
### 主なテンプレート
| テンプレート | パッケージ名 | 機能説明 |
|------|------|----------|
| fetch | mcp-server-fetch | HTTP リクエストツール、AI が Web コンテンツを取得可能に |
| time | mcp-server-time | 時間ツール、現在の時刻情報を提供 |
| time | mcp-server-time(`uvx` で実行) | 時間ツール、現在の時刻情報を提供 |
| memory | @modelcontextprotocol/server-memory | メモリツール、AI が情報を保存・検索可能に |
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | 思考連鎖ツール、AI の推論能力を強化 |
| context7 | @upstash/context7-mcp | ドキュメント検索ツール、技術ドキュメントをクエリ |
### カスタム設定
「カスタム」を選択した場合、以下を入力する必要があります:
テンプレートを選ばずに自分で入力する場合は、以下を入力します:
| フィールド | 必須 | 説明 |
|------|------|------|
| サーバー ID | はい | 一意な識別子 |
| 名前 | いいえ | 表示名 |
| 説明 | いいえ | 機能の説明 |
| 転送タイプ | はい | stdio / http / sse |
| コマンド | はい* | stdio タイプの場合は必須 |
| 引数 | いいえ | コマンドライン引数 |
| URL | はい* | http/sse タイプの場合は必須 |
| Headers | いいえ | http/sse タイプのリクエストヘッダー |
| 名前 | はい | 各アプリの設定ファイルに書き込まれるキー名。空白は使えません。保存後は変更できないため、変えたい場合は新規作成して古いものを削除します |
| 接続方式 | はい | ローカルコマンド(stdio)/ HTTP / SSE |
| コマンド | はい* | ローカルコマンドの場合は必須。プログラムだけ(例:`npx`、`uvx`)を書き、引数は別に入力します |
| 引数 | いいえ | コマンドライン引数。1 項目ずつ入力します |
| 環境変数 | いいえ | サーバーに渡す環境変数 |
| 作業ディレクトリ | いいえ | ローカルコマンドの場合は任意。空欄ならアプリが決めます |
| URL | はい* | HTTP / SSE の場合は必須。`http://` または `https://` で始めます |
| ヘッダー | いいえ | HTTP / SSE のリクエストヘッダー |
| 表示名、説明、タグ、ホームページ、ドキュメント | いいえ | 「説明とリンク」にまとまっており、CC Switch 内でだけ表示され、アプリの設定には書き込まれません |
「JSON で編集」をクリックして設定全体を直接編集することもできます。フォームと同じデータで、切り替え時に自動で同期されます。環境変数とヘッダーの値は JSON 内では `••••••••` と表示され、保存時は元の値が保持されます。
## 転送タイプ
@@ -84,7 +98,7 @@ HTTP プロトコルでリモートサーバーと通信します。
### sse(Server-Sent Events)
SSE プロトコルでサーバーと通信し、リアルタイムプッシュをサポートします。
SSE プロトコルでサーバーと通信し、リアルタイムプッシュをサポートします。Pi は SSE タイプに対応していません。
```json
{
@@ -94,23 +108,24 @@ SSE プロトコルでサーバーと通信し、リアルタイムプッシュ
## アプリバインド
各 MCP サーバーは、有効にするアプリを個別に制御できます。
各 MCP サーバーは、有効にするアプリを個別に制御できます。マトリクス内のその行・そのアプリ列のスイッチをクリックします。
### スイッチの説明
### アプリ列の説明
| スイッチ | 作用 | 設定ファイルパス |
| アプリ | 作用 | 設定ファイルパス |
|------|------|--------------|
| Claude | Claude Code に同期 | `~/.claude.json` の `mcpServers` |
| Claude Code | Claude Code に同期 | `~/.claude.json` の `mcpServers` |
| Codex | Codex に同期 | `~/.codex/config.toml` の `[mcp_servers]` |
| Gemini | Gemini CLI に同期 | `~/.gemini/settings.json` の `mcpServers` |
| Gemini CLI | Gemini CLI に同期 | `~/.gemini/settings.json` の `mcpServers` |
| Grok Build | Grok Build に同期 | `~/.grok/config.toml` の `[mcp_servers]` |
| OpenCode | OpenCode に同期 | `~/.config/opencode/opencode.json` の `mcp` |
| Hermes | Hermes に同期 | `~/.hermes/config.yaml` の `mcp_servers` |
| Pi | Pi に同期(Pi 1.0 以降が必要) | `~/.pi/agent/mcp.json` |
| MiniMax Code | MiniMax Code に同期 | `~/.minimax/mcp.json` |
> ⚠️ **注意**:OpenClaw、Pi、Claude Desktop は現在 CC Switch MCP 同期に対応していません。MCP パネルはすべてのアプリで共通の統合パネルで、Claude Desktop のページで開いても同じパネルが表示され、Claude Desktop 用のスイッチはありません。MCP 機能は Claude、Codex、Gemini、Grok Build、OpenCode、Hermes、MiniMax Code に対応しています。
> ⚠️ **注意**:Claude Desktop と OpenClaw は CC Switch の MCP 同期に対応していないため、表にはこの 2 列がありません。MCP は上記の 8 アプリに対応しています。
MCP パネルでは、アプリごとにすべてのサーバーをワンクリックで一括有効化・無効化できます。
列ヘッダーをクリックすると、その列を一括操作できます:「残り N 件を有効化」「すべて有効化」「すべてオフ」。対象は現在の一覧(検索や絞り込み後は結果)のエントリーだけで、操作後に「元に戻す」を押せます。各行の ⋯ メニューにも「すべてのアプリで有効化」と「すべてオフ」があります。
### スイッチの動作
@@ -126,7 +141,7 @@ MCP パネルでは、アプリごとにすべてのサーバーをワンクリ
2. **Live 設定から削除**:アプリの設定ファイルからそのサーバーを削除
3. **即時反映**:次回 CLI ツール起動時にその MCP サーバーはロードされない
> 💡 CC Switch が管理するのはデータベースに存在するサーバーだけです。各ツールの設定に手動で追加し、CC Switch にインポートしていないサーバーは変更されません。**MiniMax Code は例外**:一括同期の際、MiniMax Code で有効になっていないサーバーは `mcp.json` から削除されません。CC Switch で明示的にオフにするか削除した場合にのみ削除されます。
> 💡 CC Switch が管理するのはデータベースに存在するサーバーだけです。各ツールの設定に手動で追加し、CC Switch にインポートしていないサーバーは変更されません。ただし、アプリの設定内で CC Switch と同名のエントリーを直接編集した場合は上書きされ、CC Switch 側の内容が優先されます。**MiniMax Code と Pi は例外**:一括同期の際、これらで有効になっていないサーバーは `mcp.json` から削除されません。CC Switch で明示的にオフにするか削除した場合にのみ削除されます。
### 同期条件
@@ -138,6 +153,7 @@ MCP サーバーの同期は、対応アプリがインストールされてい
- **Grok Build**:`~/.grok/` ディレクトリが存在する必要あり
- **OpenCode**:`~/.config/opencode/` ディレクトリが存在する必要あり
- **Hermes**:`~/.hermes/` ディレクトリが存在する必要あり
- **Pi**:`~/.pi/agent/mcp.json` に書き込みます(Pi の設定ディレクトリは `PI_CODING_AGENT_DIR` で指定できます)
> **ヒント**:CLI ツールがインストールされていない場合、対応するスイッチをオンにしてもエラーにはなりませんが、設定は書き込まれません。MiniMax Code は例外で、CC Switch はインストールの有無を確認せず `~/.minimax/mcp.json` に直接書き込み、ディレクトリがなければ自動的に作成します。
@@ -146,27 +162,29 @@ MCP サーバーの同期は、対応アプリがインストールされてい
## サーバーの編集
1. サーバー行の右側にある「編集」ボタンをクリック
2. 設定を変更
2. ドロワーで設定を変更(名前は変更できません)
3. 「保存」をクリック
変更は有効になっているアプリの設定ファイルに即座に同期されます。
## サーバーの削除
1. サーバー行の右側にある「削除」ボタンをクリック
1. サーバー行の右側にある ⋯ メニューの「削除」をクリック
2. 削除を確認
削除後、設定はすべてのアプリの設定ファイルから削除されます。
削除は元に戻せません。設定は CC Switch と、そのサーバーを有効にしているすべてのアプリの設定ファイルから削除されます。
## 既存の設定のインポート
CLI ツールで既に MCP サーバーを設定している場合、CC Switch にインポートできます:
1. MCP ページ上部の「既存をインポート」ボタンをクリック
2. CC Switch が MCP 対応のすべてのアプリ(Claude / Codex / Gemini / Grok Build / OpenCode / Hermes / MiniMax Code)の既存設定を一度に読み取ってインポート
3. 完了するとインポート件数が表示されます。新しいサーバーが見つからなかった場合は、その旨が表示されます
1. MCP ページ上部の「アプリから取り込む」ボタンをクリック
2. CC Switch が MCP 対応のすべてのアプリ(Claude Code / Codex / Gemini CLI / Grok Build / OpenCode / Hermes / Pi / MiniMax Code)の既存設定を一度に読み取ってインポート
3. 完了すると「取り込み完了」が表示され、追加された MCP と読み込んだファイルが一覧されます。新しいサーバーが見つからなかった場合は、新しい MCP は見つかりませんでした、と表示されます
インポートしたサーバーは、インポート元のアプリで自動的に有効になります。MiniMax Code からインポートする場合、有効状態には `mcp.json` の `enabled` フィールドの値がそのまま使われます。既存のサーバー設定と競合するエントリーや無効な設定のエントリーはインポートされず、その場合は、N 個をインポートしたものの一部のアプリでインポートに失敗したことを知らせる通知が、理由とともに表示されます。
インポートで読むのはユーザー単位の設定だけです。Claude Code で `claude mcp add` を使って既定でプロジェクトに追加した MCP や、プラグイン同梱の MCP はインポートされません。
インポートしたサーバーは、インポート元のアプリで自動的に有効になります。既存のサーバーと同名のものは該当アプリのスイッチがオンになるだけで、設定は引き続き CC Switch のものが優先されます。MiniMax Code からインポートする場合、有効状態には `mcp.json` の `enabled` フィールドの値がそのまま使われます。既存のサーバー設定と競合するエントリーや無効な設定のエントリーはインポートされず、その場合は「読み込めなかったアプリがあります」と表示され、理由が一覧されます。
## 設定ファイル形式
+34 -62
View File
@@ -12,30 +12,28 @@ CC Switch を使用すると:
## Prompts パネルを開く
上部ナビゲーションバーの **プロンプト** アイコンボタンをクリックします(Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、Pi、MiniMax Code のページで表示されます。Claude Desktop のページで操作するのは Claude Code のプロンプトです)。
左サイドバーの **プロンプト** をクリックします。これはグローバルなページで、ヘッダー左側のドロップダウンでアプリを選びます:Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、Hermes、Pi、MiniMax Code(サイドバーの「アプリ」ページで表示にしたアプリだけが並びます)。
Hermes と OpenClaw には Prompts パネルがありません。Hermes は「メモリ」で MEMORY.md と USER.md を編集し、OpenClaw は [ワークスペースエディター](./3.5-workspace.md) を使用します。
- Claude Desktop には独自のプロンプトがなく、そのページから開いた場合に操作するのは Claude Code のプロンプトです。
- OpenClaw はプロンプトページにはありません。AGENTS.md などのファイルは [ワークスペースエディター](./3.5-workspace.md) で管理します。
- Hermes でここから管理するのはペルソナファイル `SOUL.md` です。`MEMORY.md` と `USER.md` は Hermes ページの「メモリ」ページで編集します。
## パネル概要
![image-20260108010110382](../../assets/image-20260108010110382.png)
<!-- TODO(v4 screenshot): Prompts page: app dropdown in the header, target file path, prompt list (the enabled one carries an "Enabled" badge) -->
ページ上部に現在のアプリの**対象ファイル**(パスとサイズ)が表示され、その下にプロンプトの一覧があります。各行に「有効にする / 無効にする」ボタン、「編集」ボタン、⋯ メニュー(ほかのアプリにコピー、本文をコピー、削除)があります。一覧が空でないときは検索ボックスが表示され、名前・説明・本文で検索できます。
## プリセットの作成
### 操作手順
1. 右上の **+** ボタンをクリック
2. プリセット名を入力
3. Markdown エディタでプロンプトを作成
4. 「保存」をクリック
1. ヘッダーの **プロンプトを追加** をクリックすると、右側にドロワーが開きます
2. 名前を入力します。説明は任意です(CC Switch 内でのみ表示)
3. 本文欄に Markdown でプロンプトを書きます
4. 「追加」をクリックします
### Markdown エディタ
エディタは以下を提供します:
- シンタックスハイライト
- リアルタイムプレビュー
- よく使うフォーマットのショートカットキー
ファイルにすでにあって CC Switch にはまだない内容は、ヘッダーの ⋯ メニューにある「現在の xxx を取り込む」で 1 件として保存できます。ファイルは変更されません。
### プロンプトの書き方のヒント
@@ -68,11 +66,11 @@ Hermes と OpenClaw には Prompts パネルがありません。Hermes は「
### 操作方法
プリセット項目のスイッチボタンをクリックして、有効/無効を切り替えます。
プリセット行の「有効にする」ボタンをクリックします。有効なものは「有効」と表示され、ボタンは「無効にする」に変わります。
### 単一有効化
同時に有効にできるプリセットは 1 つだけです。新しいプリセットを有効にすると、以前のプリセットは自動的に無効になります。
各アプリで同時に有効にできるプリセットは 1 つだけです。新しいものを有効にすると、以前のものは自動的に無効になります。有効にすると、そのプリセットの本文が対象ファイルを上書きします。無効にするとファイルは空になります(Pi の `AGENTS.md` は削除されます)。
### 同期先
@@ -80,11 +78,12 @@ Hermes と OpenClaw には Prompts パネルがありません。Hermes は「
| アプリ | ファイルパス |
|------|----------|
| Claude | `~/.claude/CLAUDE.md` |
| Claude Code | `~/.claude/CLAUDE.md` |
| Codex | `~/.codex/AGENTS.md` |
| Gemini | `~/.gemini/GEMINI.md` |
| Gemini CLI | `~/.gemini/GEMINI.md` |
| Grok Build | `~/.grok/AGENTS.md` |
| OpenCode | `~/.config/opencode/AGENTS.md` |
| Hermes | `~/.hermes/SOUL.md`(Hermes のペルソナ。新しく開いたセッションから反映) |
| Pi | `~/.pi/agent/AGENTS.md` |
| MiniMax Code | `~/.minimax/AGENTS.md`(内容は 32 KiB 以内) |
@@ -96,69 +95,42 @@ Pi の Prompts パネルは 3 つのタブに分かれています:
| タブ | 説明 |
|------|------|
| グローバルプロンプト | AGENTS.md のプロンプトライブラリ。1 つを選んで Pi のグローバル `AGENTS.md` に書き込む |
| グローバルシステムプロンプト | `APPEND_SYSTEM.md`(Pi 内蔵の基本プロンプトの後ろに追記、推奨)または `SYSTEM.md`(Pi 内蔵の基本プロンプトを置き換え)を編集 |
| プロンプトテンプレート | Pi のプロンプトテンプレートを管理 |
| ライブラリ | AGENTS.md のプロンプトライブラリ。同時に有効にできるのは 1 件で、Pi のグローバル `AGENTS.md` に書き込まれます |
| システムプロンプト | `APPEND_SYSTEM.md`(Pi 内蔵の基本プロンプトの後ろに追記、推奨)または `SYSTEM.md`(Pi 内蔵の基本プロンプトを置き換え)を編集します。ファイルが存在すれば反映されるため、有効化は不要です |
| テンプレート | Pi のプロンプトテンプレートを管理します。保存後は Pi で `/コマンド名` と入力して呼び出します。有効化は不要です |
すでに開いている Pi は自動では更新されません。アイドル時に `/reload` を実行してください。新しく起動した Pi は自動で読み込みます。
## プリセットの編集
1. プリセット項目の「編集」ボタンをクリック
2. 名前や内容を変更
1. プリセット行の「編集」ボタンをクリック(または行をクリック)
2. ドロワーで名前・説明・本文を変更
3. 「保存」をクリック
現在有効なプリセットを編集した場合、保存後に設定ファイルに即座に同期されます。
現在有効なプリセットを編集した場合、保存後に対象ファイルが即座に上書きされます。
## プリセットの削除
1. プリセット項目の「削除」ボタンをクリック
1. プリセット行の ⋯ メニューの「削除」をクリック
2. 削除を確認
有効になっているプリセットは削除できません。先に無効にしてから削除してください。
有効になっているプリセットは削除できません。先に無効にしてください。削除は CC Switch 内のその 1 件にだけ影響し、対象ファイルは変更されません。
## スマートバックフィル
## 手動でファイルを変更した場合
CC Switch は、手動での変更を失わないようにスマートバックフィル保護機能を提供しています。
### 動作原理
1. プリセットを切り替える前に、現在の設定ファイルの内容を自動的に読み取る
2. ファイルの内容とデータベース内のプリセットを比較
3. 内容が異なる場合、ユーザーが手動で変更したことを示す
4. 手動変更の内容を現在のプリセットに保存
5. その後、新しいプリセットに切り替え
### 保護シーン
CLI や外部エディタで対象ファイルを直接編集しても、CC Switch はその変更を失いません:
| シーン | 処理方法 |
|------|----------|
| CLI 内で `CLAUDE.md` を直接編集 | 変更が自動的に現在のプリセットに保存 |
| 外部エディタで設定ファイルを変更 | 変更が自動的に現在のプリセットに保存 |
| 別のプリセットに切り替え | 現在の変更を保存してから切り替え |
### 技術的な詳細
バックフィル機能は以下のタイミングでトリガーされます:
- **プリセットの切り替え時**:現在の live ファイルの内容を現在のプリセットに保存
- **現在のプリセットの編集時**:live ファイルから最新の内容を読み取り
- **初回起動時**:既存の live ファイルの内容を自動インポート
### 注意事項
- バックフィルは異なるプリセットに切り替えるときにのみトリガーされる
- 現在有効なプリセットがない場合、バックフィルはトリガーされない
- バックフィルの失敗は切り替えフローに影響しない
| 有効なプリセットに対応するファイルを別の場所で編集した | 次にこのページを開いたとき、変更が有効なプリセットに取り込まれる |
| ファイルに CC Switch にない内容がある | 別のプロンプトを有効にする前に、その内容を「元のプロンプト」として 1 件保存してから上書きする |
| ファイルに内容があるのに一覧が空 | ヘッダー ⋯ メニューの「現在の xxx を取り込む」、または空の一覧ページの「既存の内容を取り込む」で 1 件として保存する |
## アプリ間での使用
Prompts はアプリごとに個別に管理されます:
Prompts はアプリごとに個別に管理されます。ヘッダーのドロップダウンでアプリを切り替えると、一覧がそのアプリのプリセットに変わります。
- Claude に切り替えると、Claude のプリセットが表示
- Codex に切り替えると、Codex のプリセットが表示
- Gemini に切り替えると、Gemini のプリセットが表示
- 他のアプリも同様
複数のアプリで同じプロンプトを使用する場合は、それぞれで作成する必要があります。
複数のアプリで同じプロンプトを使いたいときは、入力し直す必要はありません。プリセット行の ⋯ メニューの「ほかのアプリにコピー」でコピー先のアプリをチェックすると、それぞれに独立した 1 件としてコピーされます。自動では有効にならず、以後の編集は互いに影響しません(Hermes の SOUL.md はペルソナなので、既定ではチェックされません)。
## インポート・エクスポート
+80 -123
View File
@@ -27,83 +27,69 @@ OpenClaw は現在 Skills 管理に対応していません。
## Skills ページを開く
選択中のアプリが Skills に対応している場合、上部ナビゲーションバーの **Skills** ボタンをクリックします。
左サイドバーの **Skills** をクリックします。これはグローバルなページで、特定のアプリに属しません。どのアプリを選択していても同じページが開きます(Claude Desktop には独自の Skills がなく、ここにも列はありません)。
ページ上部で 2 つのビューを切り替えられます:**インストール済み** と **見つける**。
## ページ概要
![image-20260108010253926](../../assets/image-20260108010253926.png)
<!-- TODO(v4 screenshot): Skills "Installed" view: one row per Skill, per-app toggle columns on the right, header with the "Add Skill" button and the ⋯ menu -->
「インストール済み」はマトリクス表です。**1 行が 1 つの Skill、1 列が 1 つのアプリ**で、セルのスイッチが「この Skill をこのアプリで有効にする」を表します。
- ヘッダー:「Skill を追加」ボタンと、⋯ メニュー(更新を確認、バックアップから復元、リポジトリの管理、保存と同期)
- 検索ボックス:名前・フォルダー・説明・リポジトリで検索
- 絞り込み:すべて / 更新あり / どのアプリでも無効 / いずれかのアプリで有効。取得元リポジトリでも絞り込めます
- サイドバーの「アプリ」ページで表示にしたアプリの列だけを表示します。非表示は画面にだけ影響し、すでに有効なものはそのまま残ります
- 複数行をチェックすると、あるアプリへの「有効にする先」、「オフにする」、「更新」、「アンインストール」を一括で実行できます
- 列ヘッダーをクリックすると、その列全体を一括で有効化・オフにできます。対象は現在の一覧にあるエントリーだけです
- Pi には独立したスイッチのデータがなく、`~/.pi/agent/skills` にそのフォルダーがあるかどうかで有効かどうかを判断します
## スキルの発見
「見つける」ビューに切り替えて、インストールできる Skill を閲覧・検索します。
### プリセットリポジトリ
CC Switch は以下の GitHub リポジトリをプリセットとして設定しています:
CC Switch には、Anthropic 公式(`anthropics/skills`)や ComposioHQ(`ComposioHQ/awesome-claude-skills`)など、いくつかの GitHub スキルリポジトリがあらかじめ設定されています。「見つける」の「リポジトリ」ボタンで探索に使うリポジトリを選べ、「リポジトリを読み直す」で再スキャンして最新のスキルを取得します。
| リポジトリ | 説明 |
| -------------- | ------------------------ |
| Anthropic 公式 | Anthropic 提供の公式スキル |
| ComposioHQ | コミュニティが管理するスキルコレクション |
| コミュニティ精選 | 厳選された高品質スキル |
### 検索
![image-20260108010308060](../../assets/image-20260108010308060.png)
- 「リポジトリ」ソース:Skill 名やリポジトリ名で検索でき、入力に合わせて絞り込まれます。状態で絞り込むこともでき、「すべて表示」と「未インストールのみ」を切り替えられます
- 「skills.sh」ソース:[skills.sh](https://skills.sh) の公開レジストリを検索します。2 文字以上入力して Enter で検索し、結果は「さらに読み込む」で続きを表示できます
### 検索とフィルタリング
CC Switch は強力な検索とフィルタリング機能を提供しています:
#### 検索ボックス
- スキル名で検索
- スキルの説明で検索
- ディレクトリ名で検索
- リアルタイムフィルタリング、入力と同時に検索
#### ステータスフィルタ
ドロップダウンメニューでインストール状態別にフィルタリング:
| オプション | 説明 |
| ------ | ------------------ |
| すべて | すべてのスキルを表示 |
| インストール済み | インストール済みのスキルのみ表示 |
| 未インストール | 未インストールのスキルのみ表示 |
![image-20260108010324583](../../assets/image-20260108010324583.png)
#### 組み合わせて使用
検索とフィルタリングは組み合わせて使用できます:
- まず「インストール済み」でフィルタリング
- 次にキーワードで検索
- 結果にマッチ数が表示
### リストの更新
「更新」ボタンをクリックしてリポジトリを再スキャンし、最新のスキルを取得します。
<!-- TODO(v4 screenshot): Skills "Discover" view: source switch (Repositories / skills.sh), search box, "Install to" selector and the installable list -->
## スキルのインストール
### 操作手順
1. インストールしたいスキルカードを見つける
2. 「インストール」ボタンをクリック
3. インストール完了を待つ
1. 「見つける」ビューでインストールしたい Skill を見つける
2. 先に「インストール先」で有効にするアプリを選ぶ(前回の選択が記憶され、既定になります)
3. その行の「インストール」をクリックし、完了を待つ
インストール後は選んだアプリですぐに有効になり、あとから「インストール済み」でいつでも調整できます。リポジトリからのインストールのほかに、ヘッダーの「Skill を追加」メニューから次の方法も使えます:
- **「見つける」で探す**:「見つける」ビューに切り替えます
- **ZIP からインストール**:`SKILL.md` を含む ZIP ファイルを選びます。ZIP 内でフォルダー名がすでに使われている Skill はスキップされます。ZIP 内のバージョンに置き換えるには、先に同名のものをアンインストールしてからインストールしてください
- **このコンピューターから取り込む**:このコンピューターの各アプリのフォルダーにあるが CC Switch の管理下にない Skill を取り込みます。取り込みでは CC Switch のフォルダーにコピーされ、元のファイルは変更されません
ページ上部に「このコンピューターに CC Switch の管理外の Skill が N 件あります」と表示されたら、「確認して取り込む」をクリックできます。
### インストール先
| アプリ | インストールディレクトリ |
| -------- | --------------------- |
| Claude | `~/.claude/skills/` |
| Claude Code | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| Gemini | `~/.gemini/skills/` |
| Gemini CLI | `~/.gemini/skills/` |
| Grok Build | `~/.grok/skills/` |
| OpenCode | `~/.config/opencode/skills/` |
| Hermes | `~/.hermes/skills/` |
| Pi | `~/.pi/agent/skills/` |
| MiniMax Code | `~/.minimax/skills/` |
設定で設定ディレクトリを上書きしている場合、インストールディレクトリもそれに合わせて変わります(MiniMax Code のデータディレクトリは環境変数 `MINIMAX_DATA_DIR` で指定でき、Pi はさらに `PI_CODING_AGENT_DIR` も認識します)。スキルのマスターコピーは「スキル保存場所」で選択したディレクトリ(デフォルトは `~/.cc-switch/skills/`。下記の [保存場所の切り替え](#保存場所の切り替え) を参照)に保存され、シンボリックリンクまたはファイルのコピーで各アプリのディレクトリに同期されます。
設定で設定ディレクトリを上書きしている場合、インストールディレクトリもそれに合わせて変わります(MiniMax Code のデータディレクトリは環境変数 `MINIMAX_DATA_DIR` で指定でき、Pi はさらに `PI_CODING_AGENT_DIR` も認識します)。スキルのマスターコピーは「保存と同期」で選択したディレクトリ(デフォルトは `~/.cc-switch/skills/`。下記の [保存と同期](#保存と同期) を参照)に保存され、シンボリックリンクまたはファイルのコピーで各アプリのディレクトリに同期されます。
### インストール内容
@@ -122,9 +108,8 @@ CC Switch は強力な検索とフィルタリング機能を提供していま
### 操作手順
1. インストール済みのスキルカードを見つける
2. 「アンインストール」ボタンをクリック
3. アンインストールを確認
1. 「インストール済み」でその Skill を見つけ、行の ⋯ メニューの「アンインストール」をクリック(複数選択して一括アンインストールもできます)
2. アンインストールを確認
### アンインストールの効果
@@ -138,9 +123,9 @@ CC Switch は強力な検索とフィルタリング機能を提供していま
以前アンインストールしたスキルを復元する場合:
1. Skills ページを開く
2. **バックアップから復元** ボタンをクリック
3. リスト(スキル名とバックアップ日が表示)から復元したいバックアップを選択
4. スキルが復元され、現在のアプリで有効化される
2. ヘッダーの ⋯ メニューの **バックアップから復元** をクリック
3. リスト(スキル名とバックアップ日時が表示)から復元したいバックアップを選び、「復元」をクリック
4. スキルが復元され、「見つける」の「インストール先」で選んだアプリで有効になる
### バックアップの削除
@@ -154,105 +139,77 @@ CC Switch は強力な検索とフィルタリング機能を提供していま
### リポジトリ管理を開く
ページ上部の「リポジトリ管理」ボタンをクリックします。
ヘッダーの ⋯ メニューの「リポジトリの管理」をクリックします(「見つける」ビューの「リポジトリ」ボタンの下にも「リポジトリの追加・管理」の入口があります)。
### カスタムリポジトリの追加
1. 「リポジトリを追加」をクリック
2. リポジトリ情報を入力:
- Owner:GitHub ユーザー名または組織名
- Name:リポジトリ名
- Branch:ブランチ名(デフォルト main)
- Subdirectory:スキルがあるサブディレクトリ(任意)
3. 「追加」をクリック
1. 「リポジトリ URL」に `owner/name` または完全な `https://github.com/owner/name` を入力
2. ブランチを入力(デフォルトは main)
3. スキルパスは任意:スキルがあるサブディレクトリ。空欄ならルートをスキャンします
4. 「リポジトリを追加」をクリック
### リポジトリの形式
```
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
```
例:
```
Owner: anthropics
Name: claude-skills
Branch: main
Subdirectory: skills
```
追加に成功すると、検出したスキルの数が表示されます。
### リポジトリの削除
1. リポジトリリストで削除するリポジトリを見つける
2. 「削除」ボタンをクリック
3. 削除を確認
「追加済みリポジトリ」の一覧で、リポジトリの右側の削除ボタンをクリックします。
リポジトリを削除しても、そのリポジトリのスキルはリストから消えませんが、更新はできなくなります。
リポジトリを削除しても、インストール済みのスキルは消えませんが、そのリポジトリからの更新はできなくなります。
## スキルカードの情報
## スキル行の情報
各スキルカードには以下が表示されます:
「インストール済み」の各行には以下が表示されます:
| 情報 | 説明 |
| ---- | --------------- |
| 名前 | スキル名 |
| 説明 | 機能の説明 |
| ソース | 所属リポジトリ |
| ステータス | インストール済み / 未インストール |
| 情報 | 説明 |
| ---- | ---- |
| 名前、説明 | スキル名と機能の説明 |
| ソース | 所属リポジトリ。ローカルから取り込んだものは「ローカル」と表示 |
| 各アプリのスイッチ | どのアプリで有効か。書き込みに失敗したアプリは表示され、「同期方法を変更」から調整できます |
| 新しいバージョン | リモートに更新があると「更新あり」と表示 |
## スキルの更新
v3.13.0 より、Skills は **自動更新検出** と **一括更新** に対応しました —— アンインストール&再インストールの必要はありません。
Skills は **更新検出** と **一括更新** に対応しており、アンインストールして再インストールする必要はありません。
### 更新検出の仕組み
CC Switch は **SHA-256 コンテンツハッシュ** によってローカルにインストールされた skill とリモートリポジトリのバージョンを比較します。リモートに何らかのファイル変更があれば、対応するローカル skill カードに「新しいバージョンあり」のインジケーターが自動的に表示されます。
CC Switch は **SHA-256 コンテンツハッシュ** によってローカルにインストールされた skill とリモートリポジトリのバージョンを比較します。リモートに何らかのファイル変更があれば、対応する skill に「更新あり」と表示されます。
### 単体更新
### 更新の確認
更新が必要な skill について:
ヘッダーの ⋯ メニューの「更新を確認」、または「インストール済み」の検索ボックス横の「更新を確認」をクリックして、リモートリポジトリを再スキャンします。ページに「前回の確認」の時刻が表示されます。読み込めなかったリポジトリがある場合はその旨が表示され、更新結果が不完全な可能性があります。
1. Skills パネルで更新インジケーター付きの skill カードを見つける
2. カード上の **更新** ボタンをクリック
3. ダウンロード完了を待つ —— ステータスは自動的に更新されます
### 単体更新とすべて更新
### 一括更新
- 新しいバージョンがある Skill は、その行の「更新」をクリック
- 更新できる Skill があると、ヘッダーに「N 件の更新」が表示され、クリックすると更新があるものだけを表示できます。絞り込みバーの「すべて更新(N 件)」で一括更新でき、更新前に確認が表示されます
複数の skill に更新が必要な場合:
> ⚠️ 更新するとローカルのフォルダーがリポジトリの内容で置き換えられ、ローカルで変更した部分はバックアップにだけ残ります。
1. Skills パネル上部の **すべて更新** ボタンをクリック(スライドインアニメーション付きで表示)
2. CC Switch が更新が必要なすべての skill を一括ダウンロード
3. 完了後パネルが自動的に更新され、更新インジケーターは消えます
## 保存と同期
> **ヒント**:定期的に「更新」ボタンをクリックしてリモートスキャンをトリガーし、更新検出の結果を最新に保ってください。
ヘッダーの ⋯ メニューの「保存と同期」をクリックすると、次の 2 つを設定できます:
## 保存場所の切り替え
v3.13.0 より、Skills の **ソース保存場所** は 2 つの場所から切り替え可能になりました:
### マスターコピーの保存先
| 場所 | 説明 |
| ------------------------ | -------------------------------------------------------------------- |
| **CC Switch 内蔵保存** | デフォルト位置 `~/.cc-switch/skills/`、CC Switch が一元管理 |
| **`~/.agents/skills`** | コミュニティの agent ツール規約に準拠した共有ディレクトリ、他ツールとの連携に適する |
| **CC Switch フォルダ** | デフォルト位置 `~/.cc-switch/skills/`、CC Switch が一元管理 |
| **共通フォルダ**(`~/.agents/skills`) | コミュニティの agent ツール規約に準拠した共有ディレクトリ、他ツールとの連携に適する |
### 切り替え方法
切り替えるときは「移動して切り替え」をクリックします。CC Switch はマスターコピーを 1 つずつ移動し、各アプリのリンクを新しい場所に向け直すため、skill の状態は失われません。移動が終わるまで CC Switch を終了しないでください。
「設定 → 一般 → スキル保存場所」で対象の保存場所を選択します。切り替えの際 **skill の状態は失われません** —— CC Switch が既存の skill を新しい場所へスムーズに移行します。
> ⚠️ 「共通フォルダ」を選ぶと、Codex、Gemini CLI、OpenCode などはこのディレクトリを直接読むため、各アプリのスイッチはそれらに対して完全には効かなくなります。
> ⚠️ **区別**:本節の「保存場所の切り替え」は skill の **ソース保存** を管理します。一方、[1.5 個人設定 → Skills 同期方式](../1-getting-started/1.5-settings.md) は skill を **各アプリディレクトリへどう配布するか**(シンボリックリンク vs コピー)を管理します。両者は併用します。
### 各アプリへの同期方法
## 公式レジストリ検索(skills.sh)
| 方法 | 説明 |
| ---- | ---- |
| 自動(推奨) | シンボリックリンクを優先し、失敗したらコピー |
| シンボリックリンクのみ | Windows では開発者モードを有効にする必要があります |
| コピーのみ | ディスク容量を多く使い、更新のたびにコピーし直します |
v3.13.0 では **skills.sh** 公式レジストリ検索を統合し、CC Switch 内から直接コミュニティ skill を発見できます。
### 使用手順
1. 「リポジトリ管理」ボタンをクリックしてダイアログを開く
2. ダイアログ内の **skills.sh 検索** 入力欄を使用
3. キーワードを入力してリアルタイムで結果をフィルタリング
4. 対象の skill をクリックして自分のリポジトリリストに素早く追加
v3.13.0 では skills.sh のリンク切れと空の説明への対応も修正され、コミュニティ skill のメタデータ表示がより安定しました。
変更はこの後に有効化または更新した Skill にのみ適用されます。すでに有効な Skill も現在の方式に切り替えるには、「今すぐ再同期」をクリックしてください。
## トラブルシューティング
@@ -266,7 +223,7 @@ v3.13.0 では skills.sh のリンク切れと空の説明への対応も修正
解決方法:
- ネットワーク接続を確認
- 「更新」をクリックしてリトライ
- 「リポジトリを読み直す」をクリックしてリトライ
- リポジトリ設定を確認
### インストールに失敗する場合
@@ -292,5 +249,5 @@ v3.13.0 では skills.sh のリンク切れと空の説明への対応も修正
解決方法:
- 「更新」をクリックして再スキャン
- 「更新を確認」をクリックして再スキャン
- リポジトリ設定が正しいブランチとパスを指していることを確認
@@ -20,77 +20,78 @@
## セッションマネージャーを開く
上部ナビゲーションバーの **セッション管理** アイコンボタンをクリックします。開くとデフォルトで現在のアプリのセッションが表示され、フィルターメニューで他のアプリや「すべて」に切り替えられます。
左サイドバーの **セッション** をクリックします。これはグローバルなページで、開くとデフォルトで現在のアプリのセッションが表示されます。ページ左上のアプリドロップダウンで他のアプリや「すべてのアプリ」に切り替えられます(各項目の後ろにそのアプリのセッション数が表示されます)。
> **注意**:Claude Desktop 入口では Claude Code のセッションビューを再利用します。Hermes のページにはセッションボタンがないため、Hermes のセッションはフィルターメニューで「すべて」を選択して確認してください。
> **注意**:Claude Desktop には独自のセッション記録がなく、そのページから開いた場合に表示されるのは Claude Code のセッションです。Hermes のセッションもドロップダウンで選択します。ページには「Hermes は最新 500 件のセッションのみ表示します」と表示されます。
![セッションマネージャー](../../../../assets/release-notes/v4.0.0/session-en.png)
## インターフェースのレイアウト
セッションマネージャーは **2 カラムレイアウト** を採用しています:
セッションマネージャーは 2 つの階層に分かれています:
- **左パネル**:検索とフィルターツールバー付きのセッションリスト
- **右パネル**:選択したセッションの詳細と会話履歴
- **セッション一覧**:上部にアプリドロップダウン、検索ボックス、「時間順 / プロジェクト別」のグループ切り替えがあり、その下にセッション一覧があります
- **セッション詳細**:任意の行をクリックして開くと、ページ全体にそのセッションの会話内容が表示されます。「セッション一覧に戻る」で一覧に戻れます。「前へ / 次へ」でセッション間を移動することもできます
### セッションリスト(左パネル)
ヘッダー右側の ⋯ メニューには、一覧を更新、複数選択、優先ターミナル(設定へ移動)、セッションの保存場所(各アプリのセッションの保存場所を一覧表示)があります。
### セッション一覧
各セッションエントリには以下が表示されます:
- プロバイダーアイコン
- アプリアイコン
- セッションタイトル
- 最終アクティブ時間(相対形式、例:「5分前」)
- 最終アクティブ時間と作成時間
- 最後のメッセージの要約
- 右側の「再開」「再開コマンドをコピー」ボタンと ⋯ メニュー
### セッション詳細(右パネル)
### セッション詳細
セッションを選択すると、右パネルに以下が表示されます:
- **タイトル**:セッションタイトル、プロジェクトディレクトリ名、またはセッション ID から取得
- **最終アクティブ日時**:完全なタイムスタンプ
- **プロジェクトディレクトリ**:クリックでフルパスをコピー(ベース名とツールチップでフルパスを表示)
- **再開コマンド**:利用可能な場合、モノスペースフォントで表示
- **会話履歴**:メッセージの全文記録
セッションを開くと、以下が表示されます:
- **タイトルとプロジェクトディレクトリ**:ディレクトリをクリックするとフルパスをコピー
- **再開**ボタンとその他の再開方法(「ディレクトリに移動して再開」コマンドのコピーなど)
- **会話内容**:質問と返信のターンごとに表示。AI の実行過程(コマンド、ファイルの読み書き、変更)は、展開できる 1 つの「実行過程」にまとめられます
- **ビュー切り替え**:すべて / 会話 / 変更。会話だけ、またはファイルの変更だけを表示できます
- **会話の目次**:特定の質問にすばやく移動
- **検索**:現在のセッション内を検索
- **コピー / エクスポート**:全体を Markdown としてコピー、または Markdown ファイルにエクスポート
## 検索とフィルタリング
### 全文検索
左パネル上部の検索ボックスを使用して、以下の項目を横断的に検索できます:
- セッション ID
ページ上部の検索ボックスを使用して、以下の項目を検索できます:
- タイトル
- サマリー
- プロジェクトディレクトリ
- ソースファイルパス
- 最初と最後のメッセージ
- セッション ID
前方一致検索に対応し、リアルタイムで結果をフィルタリングします。**Esc** で検索をクリアできます。
検索ボックスではタイトル、ディレクトリ、最初と最後のメッセージ、セッション ID を検索でき、リアルタイムで結果をフィルタリングします。**Esc** で検索をクリアできます。
### プロバイダーフィルター
### アプリ別フィルター
左パネル右上のプロバイダーフィルタードロップダウンをクリックして、アプリ別にフィルタリングします:
- **すべて** — すべてのアプリのセッションを表示(Hermes を含む)
- **Codex**
- **Grok Build**
- **Claude Code**
- **OpenCode**
- **OpenClaw**
- **Gemini CLI**
- **MiniMax Code**
- **Pi**
左上のアプリドロップダウンをクリックして選択します:
- **すべてのアプリ** — すべてのアプリのセッションを表示(Hermes を含む)
- Claude Code、Codex、OpenCode、Hermes、Gemini CLI、Pi、Grok Build、OpenClaw、MiniMax Code
セッションリストは「一覧」と「分類」の 2 つのビューを切り替えられます。「分類」ビューでは、アプリとプロジェクトディレクトリごとにグループ化して表示します。
セッション一覧は、右側のセグメントコントロールで「時間順」(今日 / 昨日 / 今週 / それ以前)と「プロジェクト別」の 2 つのグループ表示を切り替えられます。
フィルターは検索と組み合わせて使用できます。
### 更新
更新ボタン(循環矢印アイコン)をクリックすると、すべてのプロバイダーディレクトリを再スキャンして新しいセッションや削除済みセッションを検出します。
ヘッダーの ⋯ メニューの「一覧を更新」をクリックすると、各アプリのディレクトリを再スキャンして、追加または削除されたセッションを検出します。
## セッション操作
### セッションの再開
選択したセッションの **再開** ボタン(再生アイコン)をクリックして、会話を続行します。
セッション行(またはセッション詳細)の **再開** ボタンをクリックして、会話を続行します。
**macOS の場合:**
- CC Switch は設定済みのターミナルで再開コマンドを起動します
- ターミナルはセッションのプロジェクトディレクトリで開きます
- ターミナルの起動に失敗した場合、コマンドがクリップボードにコピーされます
- 優先ターミナルはヘッダー ⋯ メニューの「優先ターミナル」で変更できます
**対応ターミナル(macOS):** Terminal.app、iTerm2、Ghostty、Otty、Kitty、WezTerm、Kaku、Alacritty、Warp
@@ -98,24 +99,24 @@
- 再開コマンドがクリップボードにコピーされます
- ターミナルに貼り付けてセッションを再開してください
> 再開コマンドが利用できないセッションでは、再開ボタンは無効になります。OpenClaw と Hermes のセッションは現在再開に対応していません。
> 再開コマンドが利用できないセッションでは、再開ボタンは無効になります。OpenClaw のセッションはゲートウェイが管理し、Hermes のセッションはまだコマンドラインからの再開に対応していないため、どちらもここからは再開できません。Codex はプロバイダーごとに履歴を分けて保存するため、プロバイダーを切り替えたあと、古いセッションは続行できないことがあります。
再開時、ターミナルはセッションの元のプロジェクトディレクトリで開きます。別のディレクトリで特定の Claude プロバイダーを使ってターミナルを開きたい場合は、Claude プロバイダーカードの「ターミナルを開く」ボタンを使用してください。このボタンでは、まず作業ディレクトリを選択します。
### セッションの削除
**削除** ボタン(ゴミ箱アイコン)をクリックすると、セッションファイルが完全に削除されます。削除前に確認ダイアログが表示されます。
セッション行の ⋯ メニューの「削除」をクリックすると、セッションファイルが完全に削除されます。ディスクから直接削除され、ゴミ箱には入らず、元に戻せません。削除前に、具体的に何が削除されるかを説明する確認ダイアログが表示されます。
> ローカルソースパスのないセッション(不変のセッションなど)は削除できません。
> ローカルソースパスのないセッションは削除できません。MiniMax Code のセッションは MiniMax Code で削除してください。
### 一括操作
複数のセッションを一度に管理するには:
1. 左パネルツールバーの **一括モード** ボタン(チェックボックスアイコン)をクリック
1. ヘッダーの ⋯ メニューの **複数選択** をクリック
2. 表示されるチェックボックスでセッションを選択
3. **すべて選択** でフィルタリング結果をすべて選択、または **クリア** で選択解除
4. **一括削除**(赤いゴミ箱アイコン)をクリックして選択したすべてのセッションを削除
3. **一致したものをすべて選択** でフィルタリング結果をすべて選択、**クリア** で選択解除、**選択を終了** で一括モードを終了
4. 「N 件のセッションを削除」をクリックして選択したすべてのセッションを削除
削除前に件数を表示する確認ダイアログが表示されます。結果には成功した削除件数と失敗件数が報告されます。
@@ -123,22 +124,18 @@
### メッセージの表示
メッセージは役割ごとに色分けされます:
- **ユーザー** メッセージ:緑、左寄せ
- **AI**(アシスタント)メッセージ:青、右寄せ
- **システム** メッセージ:アンバー
- **ツール** メッセージ:パープル
会話は「質問 - 返信」のターンごとに表示されます:
- あなたの質問と AI の最終的な返信は通常どおり表示されます
- AI の実行過程(コマンドの実行、ファイルの読み取りや変更、MCP の呼び出し、サブエージェントなど)は「実行過程 · N ステップ」の 1 つにまとめられ、展開して各ステップのパラメーター、出力、ファイルの変更を確認できます。失敗したステップには印が付きます
- 思考内容は別に表示されます(一部のツールの思考内容は表示できません)
- 長い内容は既定で折りたたまれ、「全文を表示」で展開できます。2 MB を超える内容は、ソースファイルのパスをコピーしてローカルで確認してください
### 目次
長い会話の場合、目次機能が利用できます:
- **デスクトップ(XL+ 画面)**:右側のサイドバーにユーザーメッセージのプレビューを表示
- **小さい画面**:右下のフローティングボタン(リストアイコン)をクリックするとダイアログが開く
エントリをクリックすると該当メッセージにスクロールし、一時的にハイライト表示されます。
「会話の目次」には、このセッションの各質問(ステップ数、失敗や中断の有無を含む)が一覧表示され、任意の項目をクリックすると該当位置に移動します。
## ヒント
- セッションは最終アクティブ時間の新しい順にソートされます
- セッション数バッジは検索やフィルタリングに応じて更新されます
- アプリドロップダウンのセッション数は検索に応じて更新されます
- OpenCode のセッションは JSON ファイルと SQLite データベースの両方から取得される場合があります(重複は自動的に除去されます)
@@ -4,7 +4,7 @@
ワークスペースパネルは、**OpenClaw** 向けのファイル管理とデイリーメモリー機能を提供します。ワークスペース設定ファイルの編集やデイリーメモリージャーナルの管理が可能です。
> この機能は OpenClaw 専用です。ワークスペースボタンは、OpenClaw が選択されている場合にナビゲーションバーに表示されます。
> この機能は OpenClaw 専用で、OpenClaw のアプリページ内にあります。サイドバーで OpenClaw を選ぶと、ヘッダーの下に「プロバイダー / ワークスペース / 設定」の 3 つのタブがあるので、「ワークスペース」をクリックします。
## ワークスペースファイル
@@ -12,7 +12,7 @@
すべてのワークスペースファイルは `~/.openclaw/workspace/` に保存されます。
パネル上部のディレクトリパスをクリックすると、ファイルマネージャーで開きます。
パネル上部のディレクトリパスをクリックすると、ファイルマネージャーで開きます(ホバーすると「ファイルマネージャーで開く」と表示されます)。
### 利用可能なファイル
@@ -50,7 +50,7 @@ CC Switch は 9 つのワークスペースファイルを管理しており、
### デイリーメモリーへのアクセス
ワークスペースファイルグリッドの **デイリーメモリー** カードをクリックして、メモリーパネルを開きます。
ワークスペースファイルグリッドの **デイリーメモリーファイル** カード(「デイリーメモリーの閲覧・管理」)をクリックして、メモリーパネルを開きます。
### ファイルリスト
@@ -61,7 +61,7 @@ CC Switch は 9 つのワークスペースファイルを管理しており、
### 今日のノートを作成
**今日のノートを作成** ボタンをクリックすると:
**メモリーを追加** ボタンをクリックすると:
- 今日の日付(`YYYY-MM-DD.md`)で新しいノートを開く
- 今日のノートがすでに存在する場合は、編集用に開く
- ファイルは保存をクリックした後に保存される
@@ -70,10 +70,10 @@ CC Switch は 9 つのワークスペースファイルを管理しており、
すべてのデイリーメモリーファイルを横断検索できます:
1. **Cmd/Ctrl+F** を押すか、検索アイコンをクリック
1. **⌘/Ctrl+F** を押すか、検索アイコンをクリック
2. 検索語を入力
3. 結果には以下が表示されます:
- ファイルごとのマッチ数
- ファイルごとのマッチ数(「N件一致」)
- マッチした行のスニペットプレビュー
- ファイルの日付とサイズ
+48 -80
View File
@@ -16,46 +16,39 @@
## ローカルルーティングの起動
### 方法 1:設定ページ
ローカルルーティングサービスは、通常は手動で起動する必要がありません。
1. 「設定 → ルーティング → ローカルルーティング」を開く
2. 「ルーティング総スイッチ」をオンにして、ローカルサービスを起動
3. 「ルーティング有効」で、ルーティングするアプリ(Claude / Codex / Gemini / Grok Build)をオンにする
- アプリページ(サイドバーでアプリを選択)の上部で「ルーティング」タブに切り替えて「ルーティングを開始」をクリックし、確認すると、そのアプリはローカルルーティング経由で転送されるようになります。サービスが動いていなければ自動的に起動します。ルーティング・集約のどちらのモードでも、リクエストはまずこのマシンのルーティングサービスを経由します
- Claude Desktop がモデルマッピングを使うプロバイダーを使用しているときも、サービスは自動的に起動して動き続けます。詳しくは [2.6 Claude Desktop](../2-providers/2.6-claude-desktop.md) を参照してください
![image-20260108011338922](../../assets/image-20260108011338922.png)
上部の「直接接続 / ルーティング / 集約」タブをクリックしても表示が切り替わるだけで、設定は変わりません。実際に切り替えるには、タブの下に結果が書かれているボタン(「ルーティングを開始」「集約に切り替え」「直接接続に戻す」)を押します。
### 方法 2:メイン画面のスイッチ
<!-- TODO(v4 screenshot): App page header with the Direct / Routing / Aggregation tabs, Routing selected but not active, showing the "Start routing" button -->
「設定 → ルーティング → ローカルルーティング」で「メインページにルーティング切り替えを表示」をオンにすると、Claude、Codex、Gemini、Grok Build の各ページ上部にローカルルーティングのスイッチが表示されます(Claude Desktop のページには専用のルーティングスイッチがあります。[2.6 Claude Desktop](../2-providers/2.6-claude-desktop.md) を参照)。
「設定 → ローカルルーティング」の「サービス」エリアで「起動」を押して手動で起動することもできます。サービスが停止している状態でいずれかのアプリがルーティングまたは集約モードになっていると、アプリページに「ルーティングサービスが動いていないためリクエストは失敗します」と表示され、「サービスを起動」と「直接接続に戻す」の 2 つのボタンが現れます。
このスイッチは**現在のアプリ**のルーティングだけを制御します:
- オンにしたとき、ローカルルーティングがまだ起動していなければ自動的に起動します
- オフにしたときは現在のアプリのルーティングだけを無効にします。ほかにルーティングが有効なアプリがなければ、ローカルルーティングは自動的に停止します
スイッチの状態:
- ⚪ 白:現在のアプリはルーティング無効
- 🟢 緑:現在のアプリはローカルルーティング経由で転送中
![image-20260108011353927](../../assets/image-20260108011353927.png)
<!-- TODO(v4 screenshot): Settings → Local routing page, service area (running status, stats, listen address and port, log request usage) -->
## ルーティング設定
### 基本設定
「設定 → ローカルルーティング → サービス」で設定します:
| 設定項目 | 説明 | デフォルト値 |
|--------|------|--------|
| リッスンアドレス | ローカルルーティングがバインドする IP アドレス | `127.0.0.1` |
| リッスンアドレス | ローカルルーティングがバインドする IP アドレス。IPv4、IPv6、`localhost` に対応 | `127.0.0.1` |
| リッスンポート | ローカルルーティングがリッスンするポート(1024–65535) | `15721` |
| リクエスト使用量を記録 | ルーティングしたリクエストの使用量と状態をローカルの統計データベースに書き込む | オン |
| リクエストの使用量を記録 | ルーティングしたリクエストの使用量と状態をローカルの統計データベースに書き込む。オフにすると、使用量統計にルーティング経由のリクエストの明細が残らない | オン |
リッスンアドレスとポートは、ローカルルーティングの停止中にのみ表示されます。「リクエスト使用量を記録」スイッチは、ローカルルーティングの実行中に表示されます。リトライ回数とタイムアウトは「設定 → ルーティング → 自動フェイルオーバー」でアプリごとに設定します。[4.3 フェイルオーバー](./4.3-failover.md) を参照してください。
リトライ回数とタイムアウトはアプリごとに設定します。[4.3 フェイルオーバー](./4.3-failover.md) を参照してください。
### 設定の変更
1. **「ルーティング総スイッチ」をオフにする**(ローカルルーティングを先に停止しないと、アドレスとポートの設定は表示されません)
2. リッスンアドレスまたはポートを変更
3. 「保存」をクリック
4. 「ルーティング総スイッチ」を再びオンにする
1. 「待ち受けアドレスとポート」でアドレスまたはポートを変更
2. 「保存してサービスを再起動」をクリック(変更があるときのみ押せます)
保存すると、サービスが自動的に再起動し、新しいアドレスとポートが使われます。
### リッスンアドレスの説明
@@ -66,57 +59,29 @@
## 実行状態
ローカルルーティングの実行中、パネルには以下の情報が表示されます:
### サービスアドレス
```
http://127.0.0.1:15721
```
「コピー」ボタンでアドレスをコピーできます。
### 現在のプロバイダー
各アプリが現在使用しているプロバイダーを表示:
```
Claude: PackyCode
Codex: AIGoCode
Gemini: Google 公式
```
### 統計データ
「設定 → ローカルルーティング → サービス」の上部にサービスの状態が表示されます。実行中は「実行中 · 稼働 X 時間 Y 分」、そうでなければ「停止中」と表示されます。サービスの実行中は、右側に次の統計も表示されます:
| 指標 | 説明 |
|------|------|
| リクエスト数 | 起動以来の総リクエスト数 |
| 成功率 | リクエスト成功の割合 |
| アクティブ接続 | 現在処理中のリクエスト数 |
| 総リクエスト数 | 起動以来の総リクエスト数 |
| 成功率 | リクエスト成功の割合(>90% 緑、≤90% 黄) |
| 稼働時間 | ローカルルーティングの稼働時間 |
### ルーティングを使用中のアプリ
「ルーティングを使用中のアプリ」には、ルーティングまたは集約モードになっているすべてのアプリと、それぞれの転送先が表示されます。例:
```
Claude Code · ルーティング 転送先 PackyCode
Codex · 集約 既定 AIGoCode
Claude Desktop · モデルマッピング · 自動で稼働を維持 現在のプロバイダー xxx
```
各行右側の「開く」でそのアプリのページが開きます。ルーティングを使っているアプリがないときは、「ルーティングを使っているアプリはありません」と表示されます。
### フェイルオーバーキュー
パネルにはアプリごとにフェイルオーバーキューが表示されます:
```
Claude
├── 1. PackyCode [使用中] ●
├── 2. AIGoCode ●
└── 3. バックアップ ○
Codex
├── 1. AIGoCode [使用中] ●
└── 2. バックアップ ●
```
キューの説明:
- 数字は優先順位を示す
- 「使用中」ラベルは現在使用しているプロバイダーを示す
- ヘルスバッジはプロバイダーの状態を示す:
- 🟢 緑:正常(連続失敗 0 回)
- 🟡 黄:低下(失敗はあるがサーキットブレーカー未発動)
- 🔴 赤:サーキットオープン(サーキットブレーカーが発動し、一時的にスキップ中。閾値は [4.3 フェイルオーバー](./4.3-failover.md#サーキットブレーカーの設定) を参照)
キューは各アプリページの「ルーティング」タブで管理し、パラメータは「設定 → ローカルルーティング」の「自動フェイルオーバー」で調整します。詳しくは [4.3 フェイルオーバー](./4.3-failover.md) を参照してください。
## 動作原理
@@ -138,7 +103,7 @@ sequenceDiagram
### 設定の変更
ローカルルーティングを起動してアプリのルーティングを有効にすると、CC Switch はそのアプリのリクエスト先アドレスをローカルルーティングに書き換えます:
アプリがルーティングモードに入ると、CC Switch はそのアプリのリクエスト先アドレスをローカルルーティングに書き換えます:
**Claude**:
```json
@@ -162,7 +127,7 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
**Grok Build**:`~/.grok/config.toml` のリクエスト先アドレスが `http://127.0.0.1:15721/grokbuild/v1` を指すようになります。
ルーティングが有効な間、設定ファイル内の API Key はプレースホルダーに置き換えられます。実際の Key は CC Switch に保存され、ローカルルーティングが転送時に付与します。
ルーティング中は、設定ファイル内の API Key はプレースホルダーに置き換えられます。実際の Key は CC Switch に保存され、ローカルルーティングが転送時に付与します。
## インターフェースフォーマット変換
@@ -187,31 +152,34 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
上流フォーマットは、プロバイダーの追加・編集時に高度なオプションでプロバイダーごとに設定します。詳しくは [2.1 プロバイダーの追加 → 上流フォーマット(Claude)](../2-providers/2.1-add.md#上流フォーマットclaude) と [Codex / Grok Build の上流フォーマットとモデルマッピング](../2-providers/2.1-add.md#codex--grok-build-の上流フォーマットとモデルマッピング) を参照してください。
> **注意**:フォーマット変換には、ローカルルーティングが実行中で、かつ対象アプリのルーティングが有効になっている必要があります。
> **注意**:フォーマット変換には、ローカルルーティングが実行中で、かつ対象アプリがルーティングモードになっている必要があります。
## ローカルルーティングの停止
### 方法 1:設定ページ
アプリがルーティングまたは集約モードの間は、サービスを停止できません。「設定 → ローカルルーティング → サービス」の「停止」ボタンはグレーになり、「ルーティングサービスを使っているアプリがあります。先に直接接続へ戻してください」と表示されます。
「設定 → ルーティング → ローカルルーティング」で「ルーティング総スイッチ」をオフにします。
アプリをルーティングから抜けさせる方法は 2 つあります:
### 方法 2:メイン画面のスイッチ
- アプリページで「直接接続に戻す」をクリックする(一度に 1 つのアプリだけ抜けます)
- 「設定 → ローカルルーティング」で「すべて直接接続に戻す」をクリックし、確認すると、すべてのアプリに直接接続の設定が書き戻され、その後ルーティングサービスが停止します。転送先、フェイルオーバーキュー、集約のリストは保持されます
各アプリのページ上部にあるローカルルーティングのスイッチをオフにします(「メインページにルーティング切り替えを表示」がオンになっている必要があります)。すべてのアプリのルーティングがオフになると、ローカルルーティングは自動的に停止します。
ルーティングを使っているアプリがなければ、「停止」をクリックしてそのままサービスを止められます。
### 停止後の処理
### 終了後の処理
ローカルルーティングの停止時、CC Switch は以下を実行します:
アプリがルーティングから抜けるとき、CC Switch は以下を実行します:
1. 各アプリの設定ファイルを直接接続のプロバイダー(ルーティング有効化前に使っていた、カードに「直接接続」と表示されているもの)に書き戻す
1. アプリの設定ファイルを直接接続のプロバイダー(ルーティングに入る前に使っていた、カードに「直接接続」と表示されているもの)に書き戻す
2. リクエストログを保存
3. すべての接続を閉じる
3. 接続を閉じる
CC Switch を終了するときも、先に直接接続へ書き戻します。アプリのモードは変わらず、次回の起動時に再び接続されます。接続できなかった場合は、アプリは直接接続に戻り、通知が表示されます。
## リクエストログ
### 記録の有効化
ローカルルーティングの設定で「リクエスト使用量を記録」スイッチをオンにします(デフォルトはオン)。
「設定 → ローカルルーティング → サービス」で「リクエストの使用量を記録」スイッチをオンにします(デフォルトはオン)。
### ログの内容
@@ -229,7 +197,7 @@ GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
### ログの表示
「設定 → 利用統計」タブでリクエストログを表示できます。
サイドバーの「使用量」でリクエストログを表示できます。
## よくある質問
+54 -52
View File
@@ -2,47 +2,50 @@
## 機能説明
アプリケーションルーティングとは、CC Switch のルーティングサービスが特定アプリの API リクエストをルーティングすることです。
アプリケーションルーティングとは、CC Switch に特定アプリの API リクエストをルーティングさせることです。各アプリには 3 つの接続モードがあり、アプリページ上部の「直接接続 / ルーティング / 集約」タブで確認できます:
ルーティングを有効にすると:
| モード | 説明 |
|------|------|
| 直接接続 | クライアントがプロバイダーに直接接続します。切り替えで書き換わるのは設定ファイルの主要フィールドだけです |
| ルーティング | リクエストはまずこのマシンの CC Switch を経由してからプロバイダーに転送されます。フォーマット変換とフェイルオーバーが使えます |
| 集約 | Claude Code と Codex のみ。`/model` で選んだモデルに応じてリクエストを複数のプロバイダーに振り分けます。フェイルオーバーはしません。公式アカウントは既定のプロバイダーにしかできず、集約には加えられません |
このページでは「ルーティング」を説明します。ルーティングに入ると:
- アプリの API リクエストがローカルルーティング経由で転送される
- リクエストログと使用量の統計を記録できる
- フェイルオーバー機能を使用できる
## 前提条件
アプリケーションルーティング機能を使用する前に、ルーティングサービスを起動する必要があります。
ルーティングには CC Switch が起動し続けている必要があります。ルーティングサービスを事前に起動しておく必要はなく、ルーティングに入るときに自動的に起動します。
## ルーティングの有効化
ルーティングに対応するアプリ:Claude Code、Codex、Gemini CLI、Grok Build。
## ルーティングの開始
### 操作場所
設定 → ルーティング → ローカルルーティング → 「ルーティング有効」エリア
アプリページ上部の「ルーティング」タブ。
### 操作手順
1. ルーティングサービスが起動していることを確認(「ルーティング総スイッチ」がオン)
2. 「ルーティング有効」エリアを見つける
3. 必要なアプリのスイッチをオンにする
1. サイドバーでルーティングするアプリを選択
2. 上部の「ルーティング」タブをクリック(表示が切り替わるだけで、設定は変わりません)
3. 「ルーティングを開始」をクリックし、表示される確認ダイアログで「転送先」のプロバイダーを選んで、「ルーティングを開始」で確定
### ルーティングスイッチ
確認ダイアログには結果が書かれています。クライアント設定内のアドレスとキーを書き換えること(本物のキーは CC Switch に残り、ほかの設定は変わりません)、以後「ルーティング」タブでプロバイダーを変えても設定ファイルは書き換えないこと、CC Switch を起動したままにする必要があること(終了時に直接接続へ書き戻し、次回起動時に再接続します)が示されます。
| スイッチ | 作用 |
|------|------|
| Claude ルーティング | Claude Code のリクエストをルーティング |
| Codex ルーティング | Codex のリクエストをルーティング |
| Gemini ルーティング | Gemini CLI のリクエストをルーティング |
| Grok Build ルーティング | Grok Build のリクエストをルーティング |
<!-- TODO(v4 screenshot): Confirmation dialog after clicking "Start routing" on an app page's Routing tab -->
複数のアプリのルーティングを同時に有効にできます。
複数のアプリを同時にルーティングに入れられます。「設定 → ローカルルーティング」の「ルーティングを使用中のアプリ」にそれらが一覧表示されます。
> ⚠️ 公式プロバイダー(Claude Official など)はローカルルーティング経由で転送できないため、ルーティングが有効な間はこの種のプロバイダーに切り替えられません。ただし Codex の OpenAI Official は例外です。
> ⚠️ 公式プロバイダー(Claude Official など)はローカルルーティング経由で転送できないため、ルーティングモードではこの種のプロバイダーに切り替えられません。カードには「公式サブスクリプションはルーティングを通りません。直接接続に戻すと使えます。」と表示されます。ただし Codex の OpenAI Official は例外です。
## ルーティングの仕組み
### 設定の変更
ルーティングを有効にすると、CC Switch はアプリの設定ファイルを変更し、API エンドポイントをローカルルーティングに向けます。
ルーティングに入ると、CC Switch はアプリの設定ファイルを変更し、API エンドポイントをローカルルーティングに向けます。
**Claude 設定の変更**:
@@ -84,54 +87,53 @@ GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
**Grok Build 設定の変更**:`~/.grok/config.toml` 内の、ルーティングで使うプロバイダーのモデルテーブルのリクエスト先アドレスが `http://127.0.0.1:15721/grokbuild/v1` に変わります。Grok Build の公式アカウントはローカルルーティング経由では使用できません。現在公式プロバイダーを使っている場合、ルーティングを有効にするとエラーになるため、先にサードパーティのプロバイダーに切り替えてください。
**Grok Build 設定の変更**:`~/.grok/config.toml` 内の、ルーティングで使うプロバイダーのモデルテーブルのリクエスト先アドレスが `http://127.0.0.1:15721/grokbuild/v1` に変わります。Grok Build の公式アカウントはローカルルーティング経由では使用できません。現在公式プロバイダーを使っている場合、ルーティングを開始するとエラーになるため、先にサードパーティのプロバイダーに切り替えてください。
ルーティング中、設定ファイル内の API Key はプレースホルダー `PROXY_MANAGED` に置き換えられ、実際の Key はローカルルーティングが転送時に付与します。プロバイダーの切り替えと同様に、ルーティングを有効にしても変更されるのはこれらの主要フィールドだけで、設定ファイル内のその他の内容は変更されません。
ルーティング中、設定ファイル内の API Key はプレースホルダー `PROXY_MANAGED` に置き換えられ、実際の Key はローカルルーティングが転送時に付与します。プロバイダーの切り替えと同様に、ルーティングに入っても変更されるのはこれらの主要フィールドだけで、設定ファイル内のその他の内容は変更されません。
### リクエストの転送
ルーティングサービスがリクエストを受信すると:
1. リクエスト元を識別(Claude/Codex/Gemini/Grok Build)
2. そのアプリで現在有効なプロバイダーを検索
2. そのアプリの現在のルーティング先を検索(フェイルオーバーが有効な場合はキューに従う)
3. 必要に応じてインターフェースフォーマットを変換し、プロバイダーの実際のエンドポイントにリクエストを転送
4. リクエストログを記録
5. アプリにレスポンスを返却
## ルーティングステータスの表示
## ルーティング状態の表示
### メイン画面の表示
### アプリページの表示
ルーティングを有効にすると、メイン画面に以下の変化があります:
ルーティングが有効になると:
- **ルーティング Logo の色**:無色から緑に変化
- **プロバイダーカード**:現在アクティブなプロバイダーに緑の枠が表示
- 「ルーティング」タブに有効マークが付き、タブの右側に「ルーティングが有効 → プロバイダー名」と表示されます(フェイルオーバー有効時は「キュー順」)
- ルーティング中のプロバイダーカードに「転送中」と表示されます
- ルーティングサービスが動いていない場合、アプリページに案内が表示され、「サービスを起動」と「直接接続に戻す」のボタンが現れます
### プロバイダーカードの状態
| 状態 | 枠の色 | 説明 |
|------|----------|------|
| 現在有効 | 青 | 設定ファイル内のプロバイダー(非ルーティングモード) |
| ルーティングアクティブ | 緑 | ルーティングが実際に使用しているプロバイダー |
| 通常 | デフォルト | 使用されていないプロバイダー |
| 状態 | 説明 |
|------|------|
| 転送中 | ルーティングが実際に使用しているプロバイダー |
| 直接接続 | 直接接続のプロバイダー。ルーティングを抜けるとここに戻ります(マウスを重ねると「ルーティングを終了するとこのプロバイダーに戻ります」と表示) |
| ここへ転送 | ほかのプロバイダーにあるボタン。クリックするとルーティング先がそのプロバイダーに変わります |
ルーティングモードでは、直接接続のプロバイダーのカードに「直接接続」ラベルも表示されます。ルーティングを無効にすると、このプロバイダーに戻ることを示しています。
## ルーティングの無効化
## ルーティングの終了
### 操作手順
1. ルーティングパネルで対応するアプリのルーティングスイッチをオフにする
2. またはルーティングサービスを直接停止
- アプリページで「直接接続に戻す」をクリックする(そのアプリだけが抜けます)
- または「設定 → ローカルルーティング」で「すべて直接接続に戻す」をクリックする(すべてのアプリが抜け、ルーティングサービスも停止します)。詳しくは [4.1 ローカルルーティングサービス](./4.1-service.md#ローカルルーティングの停止) を参照してください
### 設定の復元
ルーティングを無効にすると、CC Switch は以下を実行します:
ルーティングを抜けるとき、CC Switch は以下を実行します:
1. アプリの設定ファイルを直接接続のプロバイダー(ルーティング有効化前に使っていた、カードに「直接接続」と表示されているもの)に書き戻す。ルーティング有効化時のバックアップには依存しない
1. アプリの設定ファイルを直接接続のプロバイダー(ルーティングに入る前に使っていた、カードに「直接接続」と表示されているもの)に書き戻す。ルーティングに入るときのバックアップには依存しない
2. 現在のリクエストログを保存
CC Switch を終了するときも、まず設定ファイルを直接接続のプロバイダーに書き戻し、ルーティングのスイッチはそのまま維持します。次回 CC Switch を起動したときに、ローカルルーティングに再接続します。
CC Switch を終了するときも、まず設定ファイルを直接接続のプロバイダーに書き戻します。アプリのモードは変わらず、次回 CC Switch を起動したときにローカルルーティングへ再接続します。
## ルーティングとプロバイダーの切り替え
@@ -139,17 +141,17 @@ CC Switch を終了するときも、まず設定ファイルを直接接続の
ルーティングモードでプロバイダーを切り替える場合:
1. メイン画面でプロバイダーの「有効化」ボタンをクリック
1. 「ルーティング」タブでプロバイダーカードの「ここへ転送」をクリック(フェイルオーバー有効時は、キューで調整します。[4.3 フェイルオーバー](./4.3-failover.md) を参照)
2. ルーティングサービスが新しいプロバイダーを使用してリクエストを即座に転送
3. **CLI ツールの再起動は不要**
これがルーティングモードの大きなメリットです:プロバイダーの切り替えが即座に反映されます。Codex、Gemini CLI、Grok Build を切り替えた後も画面には再起動の案内が表示されますが、ルーティングが有効で、切り替えによってモデルが変わらない限り、再起動しなくても構いません。
これがルーティングモードの大きなメリットです:プロバイダーの切り替えが即座に反映されます。Codex、Gemini CLI、Grok Build を切り替えた後も画面には再起動の案内が表示されますが、ルーティング中で、切り替えによってモデルが変わらない限り、再起動しなくても構いません。
ルーティングモードで切り替わるのは、ルーティングが使うプロバイダーだけです。直接接続のプロバイダーはそのまま残り、カードに「直接接続」と表示され、ルーティングを無効にするとそのプロバイダーに戻ります。新しいプロバイダーが設定ファイルに書き込む内容(ローカルアドレス、モデル名など)が以前と同じであれば、切り替えても設定ファイルは変更されません。異なる場合(モデル名が違うなど)は、CC Switch が先に設定ファイルを更新します。このとき Codex、Gemini CLI、Grok Build は、新しいモデルを使うために再起動が必要です。
ルーティングモードで切り替わるのは、ルーティングが使うプロバイダーだけです。直接接続のプロバイダーはそのまま残り、カードに「直接接続」と表示され、ルーティングを抜けるとそのプロバイダーに戻ります。新しいプロバイダーが設定ファイルに書き込む内容(ローカルアドレス、モデル名など)が以前と同じであれば、切り替えても設定ファイルは変更されません。異なる場合(モデル名が違うなど)は、CC Switch が先に設定ファイルを更新します。このとき Codex、Gemini CLI、Grok Build は、新しいモデルを使うために再起動が必要です。
### 非ルーティングモードでのプロバイダー切り替え
### 直接接続モードでの切り替え
非ルーティングモードでプロバイダーを切り替える場合:
直接接続モードでプロバイダーを切り替える場合:
1. 設定ファイルを変更
2. CLI ツールの再起動が必要
@@ -166,7 +168,7 @@ CC Switch を終了するときも、まず設定ファイルを直接接続の
### シーン 1:使用量の監視
ルーティング + 「リクエスト使用量を記録」を有効にすると、ローカルルーティングを通過したリクエストを 1 件ずつ記録します。ルーティングを有効にしていない場合も、CC Switch は各ツールのローカルのセッションログから使用量を集計します。詳しくは [4.4 使用量統計](./4.4-usage.md) を参照してください。
ルーティング + 「リクエストの使用量を記録」を有効にすると、ローカルルーティングを通過したリクエストを 1 件ずつ記録します。ルーティングを使っていない場合も、CC Switch は各ツールのローカルのセッションログから使用量を集計します。詳しくは [4.4 使用量統計](./4.4-usage.md) を参照してください。
### シーン 2:素早い切り替え
@@ -174,11 +176,11 @@ CC Switch を終了するときも、まず設定ファイルを直接接続の
### シーン 3:インターフェースフォーマットの変換
OpenAI や Gemini フォーマットのプロバイダーを Claude Code で使う場合や、Chat Completions / Anthropic Messages フォーマットのプロバイダーを Codex や Grok Build で使う場合は、いずれもルーティングを有効にする必要があります。
OpenAI や Gemini フォーマットのプロバイダーを Claude Code で使う場合や、Chat Completions / Anthropic Messages フォーマットのプロバイダーを Codex や Grok Build で使う場合は、いずれもルーティングに入る必要があります。
### シーン 4:フェイルオーバー
ルーティングの有効化はフェイルオーバー機能を使用するための前提条件です。
ルーティングに入ることは、フェイルオーバー機能を使うための前提条件です。
## 注意事項
@@ -192,23 +194,23 @@ OpenAI や Gemini フォーマットのプロバイダーを Claude Code で使
### 設定のバックアップ
ルーティングの有効化はバックアップに依存しません。ルーティングを無効にすると、CC Switch は直接接続のプロバイダーに基づいて設定ファイルを書き直します。また、CC Switch は各設定ファイルを初めて書き換える前に、元のファイルを `~/.cc-switch/backups/live-first-write/` にバックアップします。
ルーティングに入るときはバックアップに依存しません。ルーティングを抜けるとき、CC Switch は直接接続のプロバイダーに基づいて設定ファイルを書き直します。また、CC Switch は各設定ファイルを初めて書き換える前に、元のファイルを `~/.cc-switch/backups/live-first-write/` にバックアップします。
## よくある質問
### ルーティング後にリクエストが失敗する
確認事項:
- ルーティングサービスが正常に実行されているか
- ルーティングサービスが正常に実行されているか(設定 → ローカルルーティング)
- プロバイダーの設定が正しいか
- ネットワークが正常か
### ルーティングを無効にしても設定が復元されない
### 直接接続に戻っても設定が復元されない
考えられる原因:
- ルーティングサービスの異常終了
- ルーティングの異常終了
- 設定ファイルが他のプログラムに変更された
解決方法:
- プロバイダーを手動で編集して保存し直す
- または再度ルーティングを有効にしてから無効にする
- または再度ルーティングに入ってから抜ける
+51 -67
View File
@@ -13,74 +13,58 @@
フェイルオーバー機能を使用するには:
1. ✅ ローカルルーティングを起動
2. ✅ 対象アプリのルーティングを有効化
3. ✅ フェイルオーバーキューを設定
4. ✅ 自動フェイルオーバーを有効化
1. ✅ アプリがルーティングモードに入っている(アプリページの「ルーティング」タブで「ルーティングを開始」をクリック)
2. ✅ 「ルーティング」タブでフェイルオーバーのスイッチをオンにする
3. ✅ キューにプロバイダーがある
## フェイルオーバーキューの設定
フェイルオーバーは Claude Code、Codex、Gemini CLI、Grok Build の 4 つのアプリのみに対応しています。集約モードではフェイルオーバーしません(キューと設定は保持され、ルーティングモードに戻すと復元されます)。共存型アプリ(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code)にはフェイルオーバーキューがありません。公式アカウントはキューに入れられません。クライアント自身のログインを使うため、ほかのプロバイダーと交代できないからです。
### 設定ページを開く
設定 → ルーティング → 自動フェイルオーバー
### アプリの選択
ページ上部に 4 つのタブがあります:
- Claude
- Codex
- Gemini
- Grok Build
設定するアプリを選択します。フェイルオーバーはこの 4 つのアプリのみに対応しています。共存型アプリ(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code)にはフェイルオーバーキューがありません。
### バックアッププロバイダーの追加
1. 「フェイルオーバーキュー」エリアで、ドロップダウンリストから追加するプロバイダーを選択
2. 右側の **+** ボタンをクリックすると、プロバイダーがキューに追加される
ローカルルーティングが実行されていない場合や、そのアプリのルーティングが有効になっていない場合、キューのコントロールはグレー表示になり操作できません。
### 優先順位の調整
キューの順序はホームのプロバイダー一覧の順序と同じです。ホームでプロバイダーカードをドラッグして調整します:
- 番号が小さいほど(P1 が最優先)優先度が高い
- メインプロバイダーが失敗すると、順番にバックアッププロバイダーを試行
### プロバイダーの削除
プロバイダーの右側にある削除ボタン(ゴミ箱アイコン)をクリックします。
## メイン画面でのクイック操作
「設定 → ルーティング → 自動フェイルオーバー」で「メインページにフェイルオーバー切り替えを表示」をオンにすると、メイン画面の上部にフェイルオーバースイッチが表示されます。そのアプリのルーティングを有効にするまで、このスイッチはグレー表示です。
そのアプリのルーティングが有効で、かつ自動フェイルオーバーがオンのとき、プロバイダーカードの「有効化」ボタンが「追加 / キュー内」に変わり、キューへの追加や削除に使えます。
### キューに追加
1. プロバイダーカードを見つける
2. 「追加」をクリック
3. プロバイダーがキューに追加
### キューから削除
1. プロバイダーカードの「キュー内」をもう一度クリック
2. プロバイダーがキューから削除
## 自動フェイルオーバーの有効化
## フェイルオーバーの有効化
### 操作手順
1. フェイルオーバー設定ページで
2. 「自動フェイルオーバー」スイッチをオンにする
1. アプリページで「ルーティング」タブに切り替え、そのアプリがルーティングモードになっていることを確認
2. タブバー右側の「フェイルオーバー」のヒントが付いたスイッチ(アイコンは交差する 2 本の矢印)をオンにする
3. 初回は確認ダイアログが表示されるので、「理解しました、有効にする」をクリック
<!-- TODO(v4 screenshot): Failover switch and "Routing settings" button on the right of the Routing tab bar on an app page -->
このスイッチは、アプリがすでにルーティングモードで、かつ「ルーティング」タブを表示しているときだけ現れます。
### スイッチの説明
| 状態 | 動作 |
|------|------|
| オフ | 失敗を記録するのみ、自動切り替えなし |
| オン | 直ちにキューの P1 に切り替え、リクエスト失敗時はキュー内の次のプロバイダーに自動的に切り替え |
| オフ | 選択した 1 つのプロバイダーにだけルーティングし、自動では切り替えない |
| オン | 直ちにキューの P1 に切り替え、リクエスト失敗時はキュー内の次のプロバイダーに自動的に切り替える。ステータス行に「キュー順」と表示される |
## フェイルオーバーキューの管理
フェイルオーバーをオンにすると、「ルーティング」タブのプロバイダーは 2 つのグループに分かれます:
- **キュー · 優先順**:リクエストはまず先頭(P1)に送られ、連続して失敗すると次に切り替わります
- **キュー外**:まだキューに入れていないプロバイダー
### バックアッププロバイダーの追加
「キュー外」で、プロバイダーカードの「キューに追加」をクリックします。
### 優先順位の調整
カードの上へ・下へボタン、またはカードのドラッグで順序を調整します。番号が小さいほど優先度が高く、キューの順序はホームのプロバイダー一覧の順序と同じです。
### プロバイダーの削除
キュー内のプロバイダーカードの「キューから外す」をクリックします。
## リトライ・タイムアウト・サーキットブレーカーの調整
パラメータはアプリごとに設定します。入口は 2 つあります:
- アプリページの「ルーティング」タブバー右側にある「ルーティング設定」ボタン:サイドパネルが開き、現在のアプリのパラメータを調整できます。パネル下部の「その他のルーティング設定」から設定ページに移動できます
- 「設定 → ローカルルーティング → 自動フェイルオーバー」:上部でアプリを選び、そのアプリのパラメータを調整します
パネルは「リトライとタイムアウト設定」と「サーキットブレーカー設定」の 2 つに分かれています。それぞれの意味は以下の各節を参照してください。
## フェイルオーバーのフロー
@@ -158,7 +142,7 @@ stateDiagram-v2
### プロバイダーカード
カードにヘルスステータスバッジが表示されます:
ルーティングモードでは、プロバイダーカードにヘルスステータスバッジが表示されます:
| バッジ | 状態 | 説明 |
|------|------|------|
@@ -166,9 +150,9 @@ stateDiagram-v2
| 🟡 | 低下 | 失敗はあるがサーキットブレーカー未発動 |
| 🔴 | サーキットオープン | 一時的にスキップ |
### キューリスト
### キュー
フェイルオーバーキューにも各プロバイダーのヘルスステータスが表示されます。
フェイルオーバーキュー内のプロバイダーカードにも同じくヘルスステータスが表示されます。「転送中」のマークは、実際に使われているプロバイダーを示します(フェイルオーバーが成功すると切り替わるため、先頭とは限りません)。
## フェイルオーバーログ
@@ -211,9 +195,9 @@ stateDiagram-v2
### フェイルオーバーがトリガーされない
確認事項:
1. ローカルルーティングが実行中か
2. 対象アプリのルーティングが有効か
3. 自動フェイルオーバーが有効か
1. ローカルルーティングが実行中か(設定 → ローカルルーティング)
2. アプリがルーティングモードか(集約モードではフェイルオーバーしません)
3. 「ルーティング」タブのフェイルオーバースイッチがオンか
4. キューにバックアッププロバイダーがあるか
### フェイルオーバーが頻繁にトリガーされる
@@ -230,6 +214,6 @@ stateDiagram-v2
### すべてのプロバイダーがサーキットブレーカー発動中
サーキットブレーカー期間満了後に自動復旧を待つか、以下を実行:
1. ローカルルーティングを手動で再起動
2. サーキットブレーカーの状態をリセット
サーキットブレーカー期間の満了後に自動で復旧するのを待つか、以下を実行:
1. 「設定 → ローカルルーティング」でアプリをいったん直接接続に戻し、サービスを停止してからルーティングを開始し直す
2. またはサーキットブレーカーのパラメータを調整する
+71 -114
View File
@@ -9,7 +9,7 @@
- 使用パターンの分析
- 問題のトラブルシューティング
使用量データの取得元は 2 つあります:
使用量統計はサイドバーにあるグローバルなページです。使用量データの取得元は 2 つあります:
| データ取得元 | 対象範囲 | ローカルルーティングの要否 |
| ---------------------------------- | --------------------------------------- | -------------------- |
@@ -18,7 +18,7 @@
- ローカルルーティングを有効にしなくても集計できます:CC Switch はデフォルトで各ツールのローカルのセッションログを定期的にスキャンし、プロバイダーとモデルごとにリクエスト数、Token、キャッシュヒット率、費用を集計します
- **Codex セッション**:JSONL セッションログから **精密に解析** し、モデル名を正規化することで料金検索の整合性を保証
- 使用量パネルは **アプリ別フィルタリング** に対応し、データが混在しません
- 使用量ページは **アプリ別フィルタリング** に対応し、データが混在しません
- OpenClaw と Hermes は現在、使用量統計に対応していません。Claude Desktop は、ローカルルーティング経由で転送された「モデルマッピング」リクエストのみを集計し、Claude Code のフィルターに含めます
## 前提条件
@@ -28,18 +28,28 @@
**ルーティングリクエストログ**(ローカルルーティング経由で転送されたすべてのリクエストを対象):
1. ✅ ローカルルーティングを起動
2. ✅ 対象アプリのルーティングを有効化
3. ✅ 「リクエスト使用量を記録」をオン(デフォルトでオン)
2. ✅ 対象アプリのルーティングをオン
3. ✅ 「リクエストの使用量を記録」をオン(デフォルトでオン。設定 → ローカルルーティング にあります)
**CLI セッションログ**(ローカルルーティング不要):
1. ✅ 対応する CLI にセッション履歴ファイルがあること
2. ✅ 「セッションログの自動スキャン」をオンのままにする(デフォルトでオン)。オフにすると、手動同期時のみスキャンします
3. ✅ CC Switch が定期的にセッションディレクトリをスキャンして使用量をインポートします
2. ✅ 「セッションログを自動スキャン」をオンのままにする(デフォルトでオン)。オフにすると、「今すぐ同期」を押したときだけスキャンします
3. ✅ CC Switch は起動時に 1 回スキャンし、その後は 60 秒ごとにスキャンして使用量をインポートします
> セッションログからはどのプロバイダーか区別できないため、この種の記録のプロバイダー列には「{アプリ} · セッションログ」と表示されます。
## 使用量統計を開く
設定 → 利用統計 タブ
左サイドバーの **使用量** をクリックします。グローバルなページなので、先にアプリを選ぶ必要も、ローカルルーティングを起動する必要もありません。
ページ右上には次のものがあります:
- **今すぐ同期**:セッションログを今すぐ 1 回スキャンします(横に前回の同期時刻が表示されます)
- **自動更新**:ページデータの自動更新間隔を設定します。オフにもできます
- **データソース**:サイドパネルを開き、セッションログのスキャン、「リクエストの使用量を記録」、Codex 使用量メンテナンスを管理します(後述)
![使用量統計](../../../../assets/release-notes/v4.0.0/usage-en.png)
## 統計概要
@@ -49,155 +59,100 @@
| 指標 | 説明 |
|------|------|
| 総コスト | 料金設定に基づいて見積もった費用 |
| 総リクエスト数 | 統計期間内のリクエスト総数 |
| 実消費トークン | 入力 + 出力 + キャッシュ作成 + キャッシュ読取をキャッシュ正規化した合計 |
| キャッシュヒット率 | キャッシュ可能な入力に対するキャッシュ読取 Token の割合 |
| 推定費用 | 料金設定に基づいて計算された費用 |
| 成功率 | 成功したリクエストの割合 |
| 実消費トークン | 新規入力 + 出力 + キャッシュ書き込み + キャッシュヒット |
| キャッシュヒット率 | キャッシュヒット ÷(新規入力 + キャッシュ書き込み + キャッシュヒット) |
v3.15.0 以降、使用量ページ上部はフィルター連動の Hero カードになりました。日付範囲、アプリ、プロバイダー、モデルフィルターを変更すると、Hero の実消費トークン、キャッシュヒット率、リクエスト数、費用が同時に更新され、下部のログや統計一覧と整合します。
「その他の指標」をクリックすると、新規入力・出力・キャッシュ書き込み・キャッシュヒットの内訳が展開されます。一部のプロトコル(OpenAI など)はキャッシュ書き込みを報告しないため、キャッシュ書き込みと実消費が少なめに出ることがあります。
> 注意:v3.15.0 ではキャッシュ読取、キャッシュ作成、OpenAI 系プロトコルのキャッシュ報告方式を正規化しています。過去の Token や費用の数値は旧バージョンの推定値と一致しない場合があります。現在の数値は正規化後のルールに基づきます。
期間、アプリ、プロバイダー、モデルのフィルターを切り替えると、これらの数値も同時に更新され、下部のログや統計一覧と整合します。
### 期間
### 期間とフィルター
統計の期間を選択できます:
| オプション | 範囲 |
| 期間 | 説明 |
|------|------|
| 当日 | 当日 00:00 から現在まで |
| 1d / 7d / 14d / 30d | 直近 1 / 7 / 14 / 30 日間 |
| 過去 24 時間 / 過去 7 日間 / 過去 14 日間 / 過去 30 日間 | 直近のそれぞれの期間 |
| すべて | 全履歴 |
| カレンダーフィルター | 開始と終了の日付・時刻を自由に指定 |
ページ上部では、ほかにも次の操作ができます:
フィルター行では次の操作ができます:
- アプリでフィルタリング:すべて / Claude Code / Codex / Gemini / OpenCode / Grok Build / Pi / MiniMax Code(ローカルルーティング経由の Claude Desktop のリクエストは Claude Code に含まれます)
- プロバイダー(「すべてのソース」)とモデル(「すべてのモデル」)のドロップダウンでフィルタリング
- 「自動更新間隔」を設定
- プロバイダーとモデルのドロップダウンでフィルタリング(モデル一覧は選択したプロバイダーに連動します)
![image-20260108011730105](../../assets/image-20260108011730105.png)
OpenClaw と Hermes は現在、使用量統計に対応していません。
## トレンドグラフ
## ヒートマップとトレンドグラフ
### リクエストトレンド
### 使用量ヒートマップ
折れ線グラフでリクエスト数の変化傾向を表示:
過去 53 週間の日別使用量を表示します。色が濃いほど使用量が多いことを示します。
- X 軸:時間
- Y 軸:リクエスト数
- 時間単位/日単位で表示可能
- ズームとドラッグに対応
### 利用トレンド
### Token トレンド
折れ線グラフで時間に伴う変化を表示します。**Tokens / リクエスト / コスト** の 3 つの指標を切り替えられます:
Token 使用量の変化を表示:
- 過去 24 時間(および当日):時間単位で表示
- 7 日間、30 日間などより長い範囲:日単位で表示
- マウスを重ねると、その時点の具体的な数値を確認できます
- 入力 Token(青)- ユーザーが送信した prompt の内容
- 出力 Token(緑)- AI が生成した回答の内容
- キャッシュ作成 Token(オレンジ)- 初回キャッシュ作成で消費された Token
- キャッシュヒット Token(紫)- キャッシュ再利用で節約された Token
- コスト(赤い破線、右側 Y 軸)- 推定費用
> 💡 **キャッシュ Token の説明**:Anthropic API は Prompt Caching 機能をサポートしています。キャッシュ作成時は高い料金(通常、入力価格の 1.25 倍)がかかりますが、その後のキャッシュヒット時は 0.1 倍の価格のみで、繰り返しリクエストのコストを大幅に削減できます。
### 時間粒度
- **今日**:時間単位で表示(24 データポイント)
- **7 日間/30 日間**:日単位で表示
![image-20260108011742847](../../assets/image-20260108011742847.png)
> 💡 **キャッシュ Token の説明**:Anthropic API は Prompt Caching をサポートしています。キャッシュ作成時は高い料金(通常、入力価格の 1.25 倍)がかかりますが、その後のキャッシュヒット時は 0.1 倍の価格のみで、繰り返しリクエストのコストを大幅に削減できます。
## 詳細データ
ページ下部に 3 つのデータタブがあります:
ページ下部には 4 つのタブがあります:**リクエストログ**、**プロバイダー**、**モデル**、**料金**(料金は次の節を参照)。
### リクエストログ
各リクエストの詳細記録:
各リクエストの記録:
| フィールド | 説明 |
|------|------|
| 時間 | リクエスト時刻 |
| プロバイダー | 使用されたプロバイダー名 |
| モデル | リクエストされたモデル(課金モデル) |
| 入力 Token | 入力の Token 数 |
| 出力 Token | 出力の Token 数 |
| キャッシュ読取 | キャッシュヒットの Token 数 |
| キャッシュ作成 | キャッシュ作成の Token 数 |
| 総費用 | 推定費用(ドル) |
| 所要時間情報 | リクエスト時間、初回 Token 時間、ストリーム/非ストリーム |
| ステータス | HTTP ステータスコード |
| アプリ | 所属アプリ |
| プロバイダー | 使用されたプロバイダー名(セッションログからインポートしたものは「{アプリ} · セッションログ」と表示) |
| モデル | リクエストされたモデル |
| 新規入力 | キャッシュを含まない入力 Token 数 |
| 出力 | 出力 Token 数 |
| キャッシュヒット | キャッシュヒットの Token 数 |
| コスト | 見積もり費用(ドル)。料金のないモデルは「価格未設定」と表示 |
| 速度 | 1 秒あたりの出力トークン数(後述) |
#### 所要時間情報の説明
マウスを重ねると、所要時間、最初のトークンまでの時間、キャッシュ書き込みなどの詳細を確認できます。リクエスト行をクリックすると詳細パネルが開き、ソース(ルーティングサービスとステータスコード、またはセッションログ)、トークン使用量、コスト内訳、パフォーマンス情報を確認できます。表の右上のステータスコードフィルターで、特定のステータスコードのリクエストだけを表示できます。
所要時間情報列には複数のバッジが表示されます:
#### 速度の計算方法
| バッジ | 説明 | 色のルール |
|------|------|----------|
| 総所要時間 | リクエストの総時間(秒) | ≤5s 緑、≤120s オレンジ、>120s 赤 |
| 初回 Token | ストリームリクエストの最初の Token 時間 | ≤5s 緑、≤120s オレンジ、>120s 赤 |
| ストリーム/非ストリーム | リクエストタイプ | ストリーム:青、非ストリーム:紫 |
速度は 1 秒あたりに出力されるトークン数で、最初のトークンから終了までで計算します。ローカルルーティング経由で、出力が 100 トークン以上のリクエストだけが対象です。思考過程が外部に出ないモデルでは近似値になります。
#### 詳細の表示
ルーティングを使っていない場合、速度はセッションログのタイムスタンプから推定され、「≈ xx tok/s」と表示されます。最初のトークンの計測がなく、最初のトークンを待つ時間も含まれるため低めに出ます。また、出力が 200 トークン以上のリクエストだけが推定対象です。
リクエスト行をクリックすると詳細情報を表示:
### プロバイダー
- 完全なリクエストパラメータ
- レスポンス内容のサマリー
- エラー情報(失敗した場合)
プロバイダー別の集計:リクエスト数、トークン、コスト、成功率、速度。
#### ログのフィルタリング
### モデル
リクエストログの表には、独自のフィルターが 2 つあります:
モデル別の集計:リクエスト数、トークン、コスト、平均コスト、成功率、速度。
| フィルタ項目 | オプション |
|--------|------|
| ステータスコード | すべて / 200 OK / 400 / 401 / 429 / 500 |
| 日付範囲 | 日付範囲を選択 |
## データソースパネル
アプリ、プロバイダー、モデル、期間はページ上部のフィルターでまとめて制御され、リクエストログもそれに合わせて更新されます。
ページ右上の「データソース」をクリックして開きます:
![image-20260108011859974](../../assets/image-20260108011859974.png)
### プロバイダー統計
プロバイダー別の集計データ:
| フィールド | 説明 |
|------|------|
| プロバイダー | プロバイダー名 |
| リクエスト数 | そのプロバイダーの総リクエスト数 |
| 成功数 | 成功したリクエスト数 |
| 失敗数 | 失敗したリクエスト数 |
| 成功率 | 成功の割合 |
| 総 Token | Token 使用量の合計 |
| 推定費用 | そのプロバイダーの費用 |
![image-20260108011907928](../../assets/image-20260108011907928.png)
### モデル統計
モデル別の集計データ:
| フィールド | 説明 |
|------|------|
| モデル | モデル名 |
| リクエスト数 | そのモデルの総リクエスト数 |
| 入力 Token | 入力 Token の合計 |
| 出力 Token | 出力 Token の合計 |
| 平均レイテンシ | 平均応答時間 |
| 推定費用 | そのモデルの費用 |
![image-20260108011915381](../../assets/image-20260108011915381.png)
- **セッションログを自動スキャン**:スイッチで、「今すぐ同期」もできます。パネルには対象アプリと、「Hermes と OpenClaw は使用量統計にまだ対応していません」という注記が表示されます
- **リクエストの使用量を記録**:オンかどうかを表示し、「変更」をクリックすると 設定 → ローカルルーティング に移動して調整できます
- **Codex 使用量メンテナンス**:「Codex 使用量を再構築」は、既存の Codex セッションの明細と集計を消去し、ローカルの Codex ログから再インポートします。再構築の前にデータベースが自動でバックアップされます。すでに削除されたログに対応する履歴は再インポートできません
## 料金設定
### 料金設定を開く
設定 → 利用統計 → コスト計算
使用量ページ → **料金** タブ
手動で入力するほか、「価格設定を追加」/「価格設定を編集」ダイアログで「models.dev からインポート」をクリックして、公開されているモデル料金をインポートすることもできます。
ページ上部の「課金のデフォルト設定」で、各アプリが「リクエストモデル」と「応答モデル」のどちらで料金を照合するかを決めます。「変更」をクリックして調整します。ルーティング経由のリクエストにのみ適用され、セッションログから取り込んだ使用量はログに記録されたモデルで計算します。
下にあるのが「モデル料金」の表です。手動で入力するほか、「価格設定を追加」/「価格設定を編集」ダイアログで「models.dev からインポート」をクリックして、公開されているモデル料金をインポートすることもできます。
### モデル価格の設定
@@ -240,7 +195,9 @@ Token 使用量の変化を表示:
- **編集**:行末の編集アイコンで変更
- **削除**:行末の削除アイコンで削除
![image-20260108011933565](../../assets/image-20260108011933565.png)
料金タブには「models.dev 料金の自動同期」もあります。オンにすると、CC Switch は起動時(最大 6 時間に 1 回)に、選んだモデルの価格を models.dev から更新します。同じモデル ID の組み込み価格と手動で設定した価格は上書きされるため、オンにする前に確認ダイアログが表示されます。「モデルを選択」で選ぶこともでき、よく使うモデルを自動的に含めることもできます。
<!-- TODO(v4 screenshot): Usage page "Pricing" tab (billing defaults + model pricing table) -->
### プリセット価格
@@ -326,8 +283,8 @@ CC Switch は一般的なモデルの公式価格(100 万 Token あたり)
### 統計データが空
確認事項:
- 「セッションログの自動スキャン」がオンになっているか、対応する CLI にセッション履歴があるか(ローカルルーティングを使わない場合のデータ取得元)
- ルーティングリクエストログを使う場合:ローカルルーティングが実行中か、対象アプリのルーティングが有効か、「リクエスト使用量を記録」がオンか
- 「セッションログを自動スキャン」がオンになっているか、対応する CLI にセッション履歴があるか(ローカルルーティングを使わない場合のデータ取得元)
- ルーティングリクエストログを使う場合:ローカルルーティングが実行中か、対象アプリのルーティングが有効か、「リクエストの使用量を記録」がオンか
- そのアプリが使用量統計に対応しているか(OpenClaw と Hermes は現在非対応)
### 費用の見積もりが不正確
+10 -11
View File
@@ -12,12 +12,12 @@
> 💡 v3.16.3 より前は、この機能は「モデルテスト」(Stream Check)という名前で、プロバイダーに実際のストリーミングモデルリクエストを送信していました。多くのサードパーティゲートウェイがこの種のリクエストをブロックして誤判定を招いていたため、現在は接続チェックに変更され、テストモデルの設定も不要になりました。
MiniMax Code を除き、各アプリの非公式プロバイダーはすべてチェックできます。公式プロバイダー(Claude Official、Claude Desktop Official など)には探査できるアドレスがありません。公式プロバイダーと MiniMax Code のプロバイダーカードでは、チェックボタンがグレー表示になりクリックできません。
MiniMax Code を除き、各アプリの非公式プロバイダーはすべてチェックできます。公式プロバイダー(Claude Official、Claude Desktop Official など)には探査できるアドレスがなく、MiniMax Code のプロバイダーもチェックに対応していません。これらのカードのメニューには「接続チェック」がありません。
## チェックの実行
1. プロバイダーカードにマウスを合わせて、操作ボタンを表示
2. **接続チェック** ボタンをクリック
1. プロバイダーカードにマウスを合わせ、右側の「その他」(⋯)ボタンをクリック
2. メニューから **接続チェック** を選択
3. チェックの完了を待つと、結果が通知メッセージで表示されます
| 結果 | 説明 |
@@ -28,13 +28,13 @@ MiniMax Code を除き、各アプリの非公式プロバイダーはすべて
## チェックパラメーター
設定 → 詳細 → 接続チェック設定
チェックのパラメーターは現在、画面上に設定項目がなく、固定のデフォルト値が使われます:
| パラメーター | 説明 | デフォルト値 | 範囲 |
|------|------|--------|------|
| タイムアウト(秒) | 1 回の探査の最大待機時間 | 8 | 2-60 |
| 最大リトライ回数 | タイムアウト系の失敗時のみリトライ。接続拒否や DNS の失敗などはすぐに結果を返す | 1 | 0-5 |
| 低速判定しきい値(ミリ秒) | 到達可能でもレイテンシがこの値を超えると「低速」とマーク | 6000 | 1000-30000 |
| パラメーター | 説明 | 値 |
|------|------|-----|
| タイムアウト | 1 回の探査の最大待機時間 | 8 秒 |
| 最大リトライ回数 | タイムアウト系の失敗時のみリトライ。接続拒否や DNS の失敗などはすぐに結果を返す | 1 回 |
| 低速判定しきい値 | 到達可能でもレイテンシがこの値を超えると「低速」とマーク | 6000 ミリ秒 |
## フェイルオーバーとの関係
@@ -53,7 +53,7 @@ MiniMax Code を除き、各アプリの非公式プロバイダーはすべて
考えられる原因:
- リクエスト先アドレスの入力ミス
- ネットワークがつながっていない、またはプロキシ経由でないとアクセスできない(「設定 → ルーティング → グローバル送信プロキシ」で設定できます)
- ネットワークがつながっていない、またはプロキシ経由でないとアクセスできない(「設定 → ネットワーク → グローバル送信プロキシ」で設定できます)
- ファイアウォールが接続をブロックしている
### レイテンシが高すぎる
@@ -64,4 +64,3 @@ MiniMax Code を除き、各アプリの非公式プロバイダーはすべて
解決方法:
- [エンドポイント速度テスト](../2-providers/2.1-add.md#エンドポイント速度テスト) でより高速なエンドポイントを選択
- 低速判定しきい値を調整
@@ -0,0 +1,97 @@
# 4.6 集約モード
## 機能説明
集約モードは、複数のプロバイダーのモデルを Claude Code または Codex の同じモデル一覧にまとめます。クライアントの `/model` で選んだモデルに応じてリクエストが該当のプロバイダーに送られるため、CC Switch に戻ってプロバイダーを切り替える必要がありません。
集約モードは **Claude Code** と **Codex** のみに対応しています。
![集約モード:既定のプロバイダー 1 社と、追加した複数のプロバイダー](../../../../assets/release-notes/v4.0.0/agg-en.png)
## ルーティングとの違い
| | ルーティング | 集約 |
|------|------|------|
| 同時に使うプロバイダー | 1 社(またはフェイルオーバーキューに従って交代) | 複数。選んだモデルに応じて振り分け |
| フェイルオーバー | 対応 | 非対応 |
| プロバイダーの切り替え方法 | CC Switch で切り替える | クライアントの `/model` でモデルを選ぶ |
| 対応アプリ | Claude Code / Codex / Gemini CLI / Grok Build | Claude Code / Codex のみ |
どちらもこのマシンのルーティングサービスを経由するため、CC Switch を起動し続ける必要があります。1 つのアプリは、同時に直接接続・ルーティング・集約のいずれか 1 つのモードにしかなれません。
## 集約モードに入る
### 操作場所
サイドバーで Claude Code または Codex を選択 → ページ上部の「集約」タブ
### 操作手順
1. 「集約」タブをクリックします。タブをクリックしても表示が切り替わるだけで、設定は変わりません
2. 「既定のプロバイダー」エリアで既定のプロバイダーを確認します(後述)
3. 「集約に切り替え」をクリックします
4. 表示される確認ダイアログで、既定のプロバイダーと `/model` に表示されるモデルを確認し、「集約に切り替え」で確定します
切り替えると、ページに「集約が有効 · 既定」と、既定のプロバイダーおよびほかの何社・合計何モデルが追加されているかが表示されます。直接接続に戻すには「直接接続に戻す」をクリックします。ルーティングに切り替えるには、「ルーティング」タブの「ルーティングを開始」をクリックします。
## プロバイダーの追加と削除
### 追加
「集約」タブの「追加できるもの」リストには、まだ追加していないプロバイダーが並んでいます。カードの「追加」をクリックすると、そのプロバイダーのモデルがクライアントのモデル一覧に表示されます。
### 削除
「追加済み」リストで、カードの「削除」をクリックします。追加済みのプロバイダーは、クライアントの設定にも同時に書き込まれます。
> ⚠️ 既定のプロバイダーは削除できません。先に別のプロバイダーを既定にしてください。
### 各プロバイダーのモデルを設定する
プロバイダーを編集するときに、フォームに「モデル一覧」があります:
- これらのモデルが `/model` に表示され、選ぶとリクエストがそのプロバイダーに直接送られます
- 先頭(★)がそのプロバイダーの既定モデルです。そのプロバイダーが既定に設定されている場合、Claude Code の起動時とバックグラウンドタスク、Codex の既定モデルにこれが使われます
- モデルを設定していないプロバイダーは、集約に追加しても `/model` にモデルが増えません
- 「手動で追加」でモデルを補えます
## 既定のプロバイダー
既定のプロバイダーは、プレフィックスのないすべてのリクエストを受けます。プロバイダーカードの「既定にする」で変更できます。
公式サブスクリプション(Claude 公式アカウント、Codex の OpenAI Official)を使っている場合は、公式アカウントを既定のプロバイダーにしてください。
## `/model` の `ccs-` プレフィックス
既定のプロバイダー以外の追加済みプロバイダーのモデルは、`ccs-` プレフィックス付きで `/model` に表示されます。`ccs-` プレフィックス付きのモデルを選ぶと、リクエストは対応するプロバイダーに送られます。プレフィックスなしのモデルを選ぶと、既定のプロバイダーに送られます。
![Codex のモデル選択に複数のプロバイダーのモデルが並んでいる様子](../../../../assets/release-notes/v4.0.0/agg-codex-en.png)
> 同じセッションの途中でモデルを変えると、新しいモデルでプロンプトキャッシュを作り直すため、最初の 1 ターンは費用が高くなります。Claude Code は 2.1.243 以降が必要です。
## 再起動が必要なとき
| アプリ | 集約のモデル一覧が変わったとき |
|------|------------------|
| Claude Code | すぐに反映 |
| Codex | 完全な再起動が必要 |
Codex はモデル一覧を起動時にしか読み込みません。集約に入る・抜ける、プロバイダーを追加・削除する、プロバイダーのモデルを変更するといった操作の後、ページに「Codex が古いモデル一覧を使っているため、集約したモデルが表示されません」と表示されます。クライアントの形態に応じて次のように対処します:
- **CLI**:codex を開き直すだけでは足りません。案内にある「Codex デーモンを再起動」をクリックしてください。すべてのターミナルの codex がこのデーモンを共有しているため、実行中のタスクは中断されます
- **デスクトップ版**:完全に終了してから開き直します。macOS では ⌘Q を押します。ウィンドウを閉じるだけでは不十分です
- **エディター拡張**:エディターのウィンドウを開き直します
また、CC Switch がクライアント設定を書き換えるたびに、`/model` で集約したモデルを選択している場合は、もう一度選び直す必要があります。
## 制限事項
- **フェイルオーバーはしません**:集約モードの間もキューと設定は保持され、ルーティングモードに戻すと復元されます
- **公式アカウントは既定のプロバイダーにしかできず**、集約には追加できません
- **既定のプロバイダーは削除できません**
- **CC Switch を起動し続ける必要があります**:CC Switch を終了すると自動的に直接接続に戻り、次回の起動時に再び接続されます
- ルーティングモードに戻すと、集約したモデルは `/model` から外れます(リストは保持)。選択中の集約したモデルは通常のモデルに戻す必要があります
## 謝辞
集約モードの設計の多くは [opencodex](https://github.com/lidge-jun/opencodex) を参考にしています。作者とコントリビューターの皆さんに感謝します。
+40 -12
View File
@@ -6,7 +6,7 @@
デフォルトの場所:`~/.cc-switch/`
設定で場所をカスタマイズ可能です(クラウド同期用)。
「設定 → データ → 保存場所」で「CC Switch 設定ディレクトリ」を変更できます(クラウド同期用)。変更後はアプリの再起動が必要です。CC Switch は既存のファイルを自動では移動しないため、先に手動でコピーしておいてください。
### ディレクトリ構造
@@ -16,6 +16,9 @@
├── settings.json # デバイスレベルの設定
├── live-state.json # このマシンの状態:各ツールが直接接続かローカルルーティング経由か、前回何を書き込んだか
├── codex-login-stash.json # 一時保存された Codex 公式ログイン(公式プロバイダーに戻したときに復元)
├── copilot_auth.json # GitHub Copilot のログイン認証情報(アカウント)
├── codex_oauth_auth.json # ChatGPT / Codex OAuth のログイン認証情報(アカウント)
├── xai_oauth_auth.json # xAI OAuth のログイン認証情報(アカウント)
├── skills/ # スキルのマスターコピーディレクトリ(保存場所に「CC Switch」を選んだ場合)
├── skill-backups/ # スキルバックアップ(アンインストール時に作成)
├── backups/ # データベースと環境変数のバックアップ
@@ -26,6 +29,8 @@
`settings.json`、`live-state.json`、`codex-login-stash.json` と `backups/live-first-write/` はこのマシン専用です。常に `~/.cc-switch/` にあり、設定の「CC Switch 設定ディレクトリ」を変更しても移動せず、クラウド同期の対象にもなりません。
`live-state.json` は、切り替え型アプリ(Claude Code、Codex、Gemini CLI、Grok Build)それぞれが現在、直接接続・ルーティング・集約のどれなのかと、CC Switch が前回各ツールの設定ファイルに何を書き込んだかを記録します。CC Switch の終了後やクラッシュ後の再起動時に、設定ファイルを正しい状態に戻すために使われるため、手動で編集しないでください。
### データベースの内容
`cc-switch.db` は SQLite データベースで、以下を保存しています:
@@ -53,9 +58,9 @@
```json
{
"language": "zh",
"theme": "system",
"windowBehavior": "minimize",
"autoStart": false,
"showInTray": true,
"minimizeToTrayOnClose": true,
"launchOnStartup": false,
"claudeConfigDir": null,
"codexConfigDir": null,
"geminiConfigDir": null,
@@ -67,17 +72,19 @@
}
```
これらの設定はデバイス間で同期されません。
このほか、各アプリの「現在使用中のプロバイダー」(直接接続のポインター)もこのファイルに記録されます。これらの設定はデバイス間で同期されません。各アプリの設定ディレクトリは「設定 → アプリ設定」で変更できます。Claude Desktop と MiniMax Code はディレクトリの上書きに対応していません。
### 自動バックアップ
`backups/` ディレクトリにデータベースのバックアップが保存されます:
- 「設定 → 詳細 → バックアップと復元」で設定した間隔で自動バックアップ(デフォルトは 24 時間)
- 「設定 → データ → バックアップと復元」で設定した間隔で自動バックアップ(デフォルトは 24 時間)
- 設定のインポート、バックアップからの復元、クラウドからのダウンロードなど、上書きを伴う操作の前にも自動作成
- デフォルトで最新の 10 件のバックアップを保持
- ファイル名にタイムスタンプを含む
データベースのバックアップ以外にも、CC Switch は別の場所にバックアップを残します(環境変数のクリーンアップ時のバックアップ、スキルのバックアップ、設定ファイルの元ファイルなど)。「設定 → データ → バックアップと復元」の下にある「その他のバックアップ」に、これらの場所と使用サイズが一覧表示され、カテゴリごとに削除できます。
## Claude Code の設定
### 設定ディレクトリ
@@ -131,6 +138,26 @@ MCP サーバーの設定は `~/.claude.json` にあります:
}
```
## Claude Desktop の設定
Claude Desktop は切り替え型アプリですが、設定ディレクトリは CC Switch では上書きできません。
| OS | 場所 |
|------|------|
| macOS | `~/Library/Application Support/Claude/` と `Claude-3p/` |
| Windows | `%LOCALAPPDATA%` 配下の `Claude` と `Claude-3p` ディレクトリ |
| Linux | `~/.config/Claude/` と `Claude-3p/` |
```
Claude/claude_desktop_config.json # Claude Desktop のメイン設定
Claude-3p/claude_desktop_config.json # サードパーティ推論(gateway)モードの設定
Claude-3p/configLibrary/*.json # CC Switch が書き込む gateway 設定
```
デフォルトの「直接接続」モードでは、CC Switch はプロバイダーのアドレスと Key を gateway 設定に直接書き込みます。「モデルマッピング」モードでは、gateway 設定はローカルルーティングの `/claude-desktop` プレフィックスを指し、実際のアドレスと Key は CC Switch の中にだけ保存されるため、CC Switch を起動し続ける必要があります。切り替えた後は、Claude Desktop を完全に終了してから開き直してください。
Claude Desktop には独自の MCP、Skills、プロンプト、セッションのデータはありません。これらのページが操作するのは Claude Code のデータです。
## Codex の設定
### 設定ディレクトリ
@@ -149,7 +176,7 @@ MCP サーバーの設定は `~/.claude.json` にあります:
### auth.json
`auth.json` には OpenAI 公式の ChatGPT ログイン認証情報だけが保存され、Codex の `codex login` によって書き込まれます。サードパーティのプロバイダーに切り替えても、CC Switch はサードパーティの API Key をこのファイルに**書き込みません**。ローカルルーティングを使わずに直接切り替える場合、公式ログインを保持するかどうかは「設定 → 一般 → Codex アプリ拡張 → 直接切替時に公式ログインを保持」で決まります(デフォルトはオフ、つまり `auth.json` を削除)。ローカルルーティングが有効な間は、公式ログインは常に保持されます。削除する前に、CC Switch はこのログインを `~/.cc-switch/codex-login-stash.json` に一時保存し、公式プロバイダーに戻したときにそのまま復元するため、再ログインは不要です。
`auth.json` には OpenAI 公式の ChatGPT ログイン認証情報だけが保存され、Codex の `codex login` によって書き込まれます。サードパーティのプロバイダーに切り替えても、CC Switch はサードパーティの API Key をこのファイルに**書き込みません**。ローカルルーティングを使わずに直接切り替える場合、公式ログインを保持するかどうかは「設定 → アプリ設定」の「直接切替時に公式ログインを保持」で決まります(デフォルトはオフ、つまり `auth.json` を削除)。ルーティングが有効な間は、公式ログインは常に保持されます。削除する前に、CC Switch はこのログインを `~/.cc-switch/codex-login-stash.json` に一時保存し、公式プロバイダーに戻したときにそのまま復元するため、再ログインは不要です。
### config.toml
@@ -170,7 +197,7 @@ command = "uvx"
args = ["mcp-server-fetch"]
```
サードパーティプロバイダーは常に `[model_providers.custom]` というテーブルに書き込まれ、API Key はこのテーブルの `experimental_bearer_token` にあります。ローカルルーティングが有効な間は、プレースホルダー `PROXY_MANAGED` に置き換えられます。モデルマッピングを設定したプロバイダーでは、`cc-switch-model-catalog.json` を指す `model_catalog_json` も書き込まれます。
サードパーティプロバイダーは常に `[model_providers.custom]` というテーブルに書き込まれ、API Key はこのテーブルの `experimental_bearer_token` にあります。ルーティングまたは集約モードでは、ここにはローカルルーティングのアドレスが書き込まれ、Key はプレースホルダー `PROXY_MANAGED` に置き換えられます。モデルマッピングを設定したプロバイダーでは、`cc-switch-model-catalog.json` を指す `model_catalog_json` も書き込まれます。
プロバイダーを切り替えるとき、CC Switch が変更するのは `config.toml` の主要フィールドだけです:`model_provider`、`model`、推論レベルなどのトップレベルキーと `[model_providers.custom]` テーブル、および一部の互換オプション(`model_context_window`、`web_search` など)。`[mcp_servers]`、`[projects]`、自分で追加した他のプロバイダーテーブル、コメントや書式は変更されません。
@@ -228,7 +255,7 @@ GEMINI_MODEL=gemini-pro
```
~/.config/opencode/
├── opencode.json # メイン設定ファイル
├── opencode.json # メイン設定ファイル。MCP は mcp キーの下
├── AGENTS.md # システムプロンプト
└── skills/ # スキルディレクトリ
└── ...
@@ -258,7 +285,7 @@ Grok Build は切り替え型アプリです。プロバイダーを切り替え
### 設定ディレクトリ
デフォルト:`~/.hermes/`
デフォルト:`~/.hermes/`(Windows のデフォルトは `%LOCALAPPDATA%\hermes\`。環境変数 `HERMES_HOME` でも指定可能)
### 主要ファイル
@@ -349,6 +376,7 @@ OpenClaw は JSON5 形式の設定ファイルを使用し、主に以下のセ
```
~/.pi/agent/
├── models.json # カスタムプロバイダーとモデル(CC Switch が書き込む)
├── mcp.json # MCP サーバー(CC Switch が書き込む)
├── settings.json # Pi のグローバル設定。現在の defaultProvider / defaultModel を含む(CC Switch は読み取りのみ)
├── auth.json # Pi のログイン認証情報(CC Switch は読み書きしない)
├── AGENTS.md # グローバルプロンプト
@@ -378,7 +406,7 @@ CC Switch が管理するのは、`custom_provider` のうち `kind` が省略
## どの設定を誰が管理するか
Claude Code、Codex、Gemini CLI、Grok Build の設定ファイルは、2 つの部分に分けて管理されます:
切り替え型アプリ(Claude Code、Codex、Gemini CLI、Grok Build)の設定ファイルは、2 つの部分に分けて管理されます(共存型アプリの OpenCode、OpenClaw、Hermes、Pi、MiniMax Code は、プロバイダーを 1 件ずつ設定ファイルに書き込み、複数が共存します。切り替えでは置き換えません):
| 部分 | 含まれるもの | 保存場所 | 変更する人 |
|------|------|----------|--------|
@@ -434,7 +462,7 @@ CC Switch v3.7.0 で JSON ファイルから SQLite に移行しました:
定期的に設定をエクスポートすることを推奨します:
1. 設定 → 詳細 → データ管理
1. 設定 → データ → データ管理
2. 「SQL バックアップをエクスポート」をクリック
3. 安全な場所に保存
+57 -30
View File
@@ -53,13 +53,36 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
**原因**:CLI ツールが設定を再読み込みする必要がある
**解決方法**:
- Claude Code:ターミナルを閉じて再度開く、または IDE を再起動
- Codex、Grok Build:ターミナルを閉じて再度開く
- Gemini CLI:終了してから `gemini` を再実行
- Claude Desktop:Claude Desktop を再起動
- Claude Code:ホットスイッチに対応しており、通常は再起動不要です。反映されない場合は、ターミナルを閉じて再度開くか、IDE を再起動
- Codex、Gemini CLI、Grok Build:ターミナルまたは CLI ツールを閉じて再度開く(切り替えに成功すると案内が表示されます)
- Claude Desktop:Claude Desktop を完全に終了してから開き直す。「モデルマッピング」を使っている場合は CC Switch も起動したままにする
- 共存型アプリ(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code):「追加」(Pi は「有効化」)をクリック済みか、ツール側で対応するモデルを選択しているかを確認
ローカルルーティングを有効にしている場合、切り替えは以降のリクエストに即座に反映されます。詳しくは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md) を参照してください。
ルーティングモードでは、リクエストは即座に新しいプロバイダーへ転送されます。ただし、切り替えでモデルが変わった場合、Codex、Gemini CLI、Grok Build は再起動が必要になることがあります。集約モードでは、Claude Code は即座に反映されます。Codex は、集約に入る・抜ける、集約のモデル一覧を変更するといった操作の後に完全な再起動が必要です(次の項目を参照)。詳しくは [4.2 アプリケーションルーティング](../4-proxy/4.2-routing.md) を参照してください。
### Codex の集約モードで、/model に集約したモデルが表示されない
Codex はモデル一覧を起動時にしか読み込みません。集約モードに入る・抜ける、集約のプロバイダーを追加・削除する、プロバイダーの集約モデルを変更するといった操作の後は、Codex を完全に再起動してください:
- **Codex CLI**:ターミナルを閉じて `codex` を開き直すだけでは足りません。すべてのターミナルの `codex` が 1 つのバックグラウンドデーモンを共有しています。Codex が古い一覧を使っていることを CC Switch が検出すると、Codex ページ上部に案内が表示されるので、その中の「Codex デーモンを再起動」をクリックしてください(デーモン内で実行中のタスクは中断されます)。
- **Codex デスクトップ版**:完全に終了してから開き直します(macOS では ⌘Q。ウィンドウを閉じるだけでは不十分です)。
- **エディター拡張**:エディターのウィンドウを開き直します。
### プロバイダーを切り替えると、プラグインや Hook などの設定が変わってしまいますか
いいえ。Claude Code、Codex、Gemini CLI、Grok Build でプロバイダーを切り替えるとき、CC Switch が置き換えるのは設定ファイルの主要フィールド(リクエスト先アドレス、Key、モデル名、API プロトコルなど)だけです。プラグイン、Hook、権限、MCP、自分で追加した環境変数、コメント、書式はそのまま保持されます。どのキーを変更するかは [5.1 設定ファイルの説明](./5.1-config-files.md) を参照してください。
### ツールでモデルを変えたのに、切り替えて戻すと元に戻ってしまう
モデルは主要フィールドで、プロバイダーに属します。ツール内で変えたモデル(Claude Code の `/model` など)は、次に切り替えるまで有効です。切り替え時には切り替え先のプロバイダーに保存されているモデルに置き換わり、CC Switch がツールで変えたモデルを元のプロバイダーに保存し直すことはありません。特定のモデルを長く使いたい場合は、CC Switch でそのプロバイダーを編集してください。
### 使用中のプロバイダーを削除できないのはなぜですか
Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build は同時に 1 つのプロバイダーしか有効にできず、使用中の設定が必ず 1 つ残ります。そうでないとそのアプリが正常に使えなくなるためです。削除したい場合は、先に別のプロバイダーに切り替えてください。集約モードの既定のプロバイダーも同様に削除できないため、先に別のプロバイダーを既定にしてください。共存型アプリにはこの制限はありません。
### Claude Code で OpenAI 互換インターフェース、Gemini、ローカルモデルを使うには
ルーティングが必要です。プロバイダーを編集し、「高級オプション」の「上流フォーマット」でプロバイダーのインターフェースに合うフォーマットを選びます。Chat Completions インターフェースしか提供しないサービスは「OpenAI Chat Completions」、Responses インターフェースを提供するものは「OpenAI Responses API」、Gemini は「Gemini Native generateContent」を選択します。そのうえで、Claude Code ページの「ルーティング」タブで「ルーティングを開始」をクリックします。フォーマットを間違えたり、ルーティングを開始していなかったりすると、通常は 404 または 405 エラーになります。
### API Key が無効
@@ -73,11 +96,11 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
**操作手順**:
1. プロバイダー一覧で、組み込みの公式プロバイダー(Claude Official、OpenAI Official、Google Official、Grok Official など。削除した場合はプリセットから追加し直せます)を見つける
2. 「有効化」をクリック
2. 「有効にする」をクリック(ルーティングモードでは公式プロバイダーに切り替えられません。先に「直接接続に戻す」をクリックしてください。Codex の OpenAI Official カードは例外です)
3. 対応する CLI ツールを再起動
4. CLI ツールのログインフローに従って操作
## ローカルルーティングに関する問題
## ルーティングと集約に関する問題
### ローカルルーティングの起動に失敗する
@@ -93,7 +116,11 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
netstat -ano | findstr :15721
```
2. ポートを使用しているプログラムを終了
3. または「設定 → ルーティング → ローカルルーティング」で「ルーティング総スイッチ」をいったんオフにし、別のポート(1024–65535)に変更して「保存」をクリックしてから、再びオンにする
3. または「設定 → ローカルルーティング → サービス」で、まずルーティングサービスを停止し(ルーティングを使っているアプリがある場合は、先に直接接続へ戻す)、「待ち受けポート」を別のポート(1024–65535)に変更して「保存してサービスを再起動」をクリックする
### ルーティングを開始したら、設定ファイルのアドレスが 127.0.0.1 になっているのはなぜですか
ルーティングと集約モードでは、ツールのリクエストはまず CC Switch のローカルルーティング(デフォルトは `http://127.0.0.1:15721`)に送られ、そこから選択したプロバイダーに転送されます。そのため、ツールの設定ファイルにはローカルアドレスとプレースホルダーキー `PROXY_MANAGED` だけが書かれます。Claude Code のモデル名も `claude-sonnet-5` のような固定のエイリアスになります(`/model` メニューには実際のモデル名が表示されます)。実際のプロバイダーのアドレス、Key、モデルは CC Switch の中に保存されています。ルーティングと集約には CC Switch が起動し続けている必要があります。CC Switch を終了すると自動的に直接接続へ書き戻され、次回の起動時に再び接続されます。
### ローカルルーティングを有効にするとリクエストがタイムアウトする
@@ -104,26 +131,26 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
**解決方法**:
1. ネットワーク接続を確認
2. プロバイダーの API に直接アクセスを試みる(ローカルルーティングを無効にして)
2. プロバイダーの API に直接アクセスを試みる(ローカルルーティングを使わずに)
3. プロバイダーの設定が正しいか確認
### ローカルルーティングを無効にしても設定が復元されない
### 直接接続に戻っても設定が復元されない
**考えられる原因**:ローカルルーティングの異常終了
**考えられる原因**:CC Switch の異常終了
**解決方法**:
1. 現在のプロバイダーを編集
2. エンドポイントアドレスが正しいか確認
3. 保存して設定を更新
1. CC Switch を開き直します。起動時にこのマシンの状態に基づいて各ツールの設定を復元します
2. または対象のアプリページで「直接接続に戻す」をクリックします。「設定 → ローカルルーティング」の「すべて直接接続に戻す」で、すべてのアプリをまとめて処理できます
3. それでもおかしい場合は、現在のプロバイダーのエンドポイントアドレスが正しいか確認します。`~/.cc-switch/backups/live-first-write/` から、CC Switch が初めて書き換える前の元の設定ファイルを取り戻すこともできます
## フェイルオーバーに関する問題
### フェイルオーバーがトリガーされない
**チェックリスト**:
- [ ] ローカルルーティングが実行中か
- [ ] 対象アプリのルーティングが有効か
- [ ] 自動フェイルオーバーが有効か
- [ ] 対象アプリがルーティングモードか(集約モードではフェイルオーバーしません)
- [ ] ローカルルーティングサービスが実行中か
- [ ] そのアプリページの「ルーティング」タブで自動フェイルオーバーがオンか
- [ ] キューにバックアッププロバイダーがあるか
### フェイルオーバーが頻繁にトリガーされる
@@ -141,7 +168,7 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
**解決方法**:
1. サーキットブレーカー期間満了を待つ(デフォルト 60 秒)
2. またはローカルルーティングを再起動して状態をリセット
2. または「設定 → ローカルルーティング → サービス」でルーティングサービスをいったん停止してから再起動し、状態をリセット
## データに関する問題
@@ -152,8 +179,8 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
- データベースが破損
**解決方法**:
1. `~/.cc-switch/` ディレクトリが存在するか確認
2. バックアップから復元:`~/.cc-switch/backups/`
1. `~/.cc-switch/` ディレクトリが存在するか確認(「設定 → データ → 保存場所」で設定ディレクトリを変更した場合は、変更後のディレクトリを確認)
2. バックアップから復元:「設定 → データ → バックアップと復元」(バックアップファイルは `~/.cc-switch/backups/` にあります)
3. または以前にエクスポートした設定ファイルからインポート
### 設定のインポートに失敗する
@@ -170,8 +197,8 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
### 使用量統計のデータが空
**チェックリスト**:
- [ ] 「セッションログの自動スキャン」がオンになっているか、対応する CLI にセッション履歴があるか(ローカルルーティングを使わない場合のデータ取得元)
- [ ] ルーティングリクエストログを使う場合:ローカルルーティングが実行中か、対象アプリのルーティングが有効か、「リクエスト使用量を記録」がオンか
- [ ] 「セッションログを自動スキャン」がオンになっているか、対応する CLI にセッション履歴があるか(ローカルルーティングを使わない場合のデータ取得元)
- [ ] ルーティングリクエストログを使う場合:ローカルルーティングが実行中か、対象アプリがルーティングまたは集約モードか、「設定 → ローカルルーティング → サービス」の「リクエストの使用量を記録」がオンか
- [ ] そのアプリが使用量統計に対応しているか(OpenClaw と Hermes は現在非対応)
## クォータ・残高
@@ -183,8 +210,8 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
### 公式サブスクリプションのプロバイダーにクォータが表示されない
**確認事項**:
1. プロバイダーが「現在有効」状態であることを確認(非アクティブ時はクエリがトリガーされません)
2. Copilot / Codex OAuth の場合、OAuth Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示されたら **設定 → 認証** で再ログインしてください
1. プロバイダーが「使用中」状態であることを確認(未使用時はクエリがトリガーされません)
2. Copilot / Codex OAuth の場合、OAuth Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示されたら サイドバーの「アカウント」で再ログインしてください
3. ネットワーク接続を確認
4. カード上の更新アイコンをクリックして手動で再取得
@@ -194,7 +221,7 @@ CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
1. 「使用量クエリ」パネルで「利用状況照会を有効にする」スイッチがオンになっているか
2. 適切な内蔵テンプレートが選択されて保存されているか
3. 「スクリプトをテスト」をクリックして具体的なエラーを確認
4. プロバイダーが「現在有効」状態のときのみバックグラウンド自動更新が動作します
4. プロバイダーが「使用中」状態のときのみバックグラウンド自動更新が動作します
### Codex の使用量が直接接続時と合わない
@@ -210,14 +237,14 @@ Codex OAuth リバースプロキシは **リバースエンジニアリング
### Codex OAuth のログイン方法は?
完全な Device Code ログインフロー(認証コード + ブラウザ認証)、2 つの入口(プロバイダー追加パネル / OAuth 認証センター)、マルチアカウント管理、よくある失敗シナリオは [2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ(Claude プロバイダー)](../2-providers/2.1-add.md#codex-oauth-リバースプロキシclaude-プロバイダー) を参照してください。
完全な Device Code ログインフロー(認証コード + ブラウザ認証)、2 つの入口(プロバイダー追加パネル / アカウント)、マルチアカウント管理、よくある失敗シナリオは [2.1 プロバイダーの追加 → Codex OAuth リバースプロキシ(Claude プロバイダー)](../2-providers/2.1-add.md#codex-oauth-リバースプロキシclaude-プロバイダー) を参照してください。
### Codex OAuth にログインしたがクォータが表示されない
**解決方法**:
1. **OAuth 認証センター**(設定 → 認証、Beta ラベル付き)で OAuth ログインフローが完了していることを確認
1. サイドバーの「アカウント」で OAuth ログインフローが完了していることを確認
2. Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は Token が更新できない状態
3. 期限切れの場合は、OAuth 認証センターでアカウントを削除して再ログインしてください
3. 期限切れの場合は、「アカウント」でアカウントを削除して再ログインしてください
## その他の問題
@@ -237,7 +264,7 @@ Codex OAuth リバースプロキシは **リバースエンジニアリング
**解決方法**:
1. テーマを切り替えてみる(ライト/ダーク)
2. アプリを再起動
3. `~/.cc-switch/settings.json` を削除して設定をリセット
3. `~/.cc-switch/settings.json` を削除して設定をリセット(各アプリの現在のプロバイダーのポインターもこのファイルに記録されているため、リセット後は確認し直しが必要です)
### 更新に失敗する
@@ -277,7 +304,7 @@ Codex OAuth リバースプロキシは **リバースエンジニアリング
### ログファイル
CC Switch のログはアプリケーション設定ディレクトリに保存されます。既定ではホームディレクトリ内の `.cc-switch` です。詳細設定で設定ディレクトリを変更した場合は、その場所を使用してください。
CC Switch のログはアプリケーション設定ディレクトリに保存されます。既定ではホームディレクトリ内の `.cc-switch` です。「設定 → データ → 保存場所」で設定ディレクトリを変更した場合は、その場所を使用してください。
Issue を提出する際は、問題に応じて次のファイルを添付してください:
+7 -8
View File
@@ -39,7 +39,7 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&...
| パラメータ | 必須 | 説明 |
|------|------|------|
| `resource` | はい | リソースタイプ:`provider` / `mcp` / `prompt` / `skill` |
| `app` | はい | アプリタイプ(provider、prompt で必要):`claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `openclaw` / `hermes`。prompt ではさらに `pi` に対応 |
| `app` | はい | アプリタイプ(provider、prompt で必要):`claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `openclaw` / `hermes`。prompt ではさらに `pi` に対応。Claude Desktop、Pi、MiniMax Code のプロバイダーは現在ディープリンクでのインポートに対応していません |
| `name` | provider、prompt で必須 | 名前(MCP のサーバー ID は `config` 内の `mcpServers` のキーから取得。Skill では不要) |
**プロバイダーパラメータ**(resource=provider):
@@ -79,11 +79,11 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&...
| パラメータ | 必須 | 説明 |
|------|------|------|
| `apps` | はい | アプリリスト(カンマ区切り、例:`claude,codex,gemini,grokbuild`)。指定可能な値:`claude` / `codex` / `gemini` / `grokbuild` / `opencode` / `hermes`。MiniMax Code は現在非対応 |
| `apps` | はい | アプリリスト(カンマ区切り、例:`claude,codex,gemini,grokbuild`)。指定可能な値:`claude` / `codex` / `gemini` / `grokbuild`(`grok` とも書けます)/ `opencode` / `hermes`。`openclaw` は MCP に対応しておらず無視されます。Pi、MiniMax Code は現在非対応 |
| `config` | はい | MCP 設定の JSON。形式は `{"mcpServers": {"<サーバー ID>": {...}}}` で、Base64 エンコードが必要(さらに URL エスケープ) |
| `enabled` | いいえ | 有効にするかどうか(ブール値) |
**Skill パラメータ**(resource=skill):
**Skill パラメータ**(resource=skill):ディープリンクで追加されるのは Skill リポジトリで、Skill が直接インストールされるわけではありません。追加後に「Skills」ページでインストールする Skill を選びます。
| パラメータ | 必須 | 説明 |
|------|------|------|
@@ -123,7 +123,7 @@ ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1
### Skill のインポート
```
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
ccswitch://v1/import?resource=skill&repo=owner/repo&directory=skills/my-skill&branch=main
```
## ディープリンクの生成
@@ -171,6 +171,8 @@ CC Switch 公式のオンラインディープリンク生成ツールを使用
- 設定のプレビュー
- 確認/キャンセルボタン
確認後の動作はタイプによって異なります:プロバイダーは対応するアプリのプロバイダー一覧に追加されますが、自動では切り替わりません。MCP は指定したすべてのアプリの設定ファイルにすぐ書き込まれます。プロンプトはインポート後すぐに有効になり、同じアプリの他のプロンプトは無効になります。設定に疑わしい内容(ローカルや社内ネットワークを指すアドレス、プロセスの読み込み動作を変えられる環境変数、シェルでコマンド全体を実行するもの、使用量照会スクリプトなど)が含まれる場合、ダイアログにリスク警告が表示されるので、項目ごとに確認してください。
**セキュリティ上の注意**:信頼できるソースからの設定のみインポートしてください。
## プロトコルの登録
@@ -184,10 +186,7 @@ CC Switch のインストール時に `ccswitch://` プロトコルが自動登
プロトコルが正しく登録されていない場合:
**macOS**:
アプリを再インストールするか、以下を実行:
```bash
/usr/bin/open -a "CC Switch" --args --register-protocol
```
アプリを再インストールしてください(CC Switch を「アプリケーション」フォルダに入れ、少なくとも一度起動します)。
**Windows**:
アプリを再インストールするか、レジストリを確認:
@@ -37,10 +37,10 @@ CC Switch は、システム環境変数とアプリ設定の競合を自動的
| ソース | 説明 |
|------|------|
| ユーザーレジストリ | Windows のユーザーレベル環境変数 |
| システムレジストリ | Windows のシステムレベル環境変数 |
| Shell 設定 | macOS/Linux の Shell 設定ファイル |
| システム環境 | システムレベルの環境変数 |
| ユーザー環境変数(レジストリ) | Windows のユーザーレベル環境変数 |
| システム環境変数(レジストリ) | Windows のシステムレベル環境変数 |
| システム環境変数 | macOS/Linux の現在のプロセス環境にある変数 |
| Shell 設定ファイル | macOS/Linux の Shell 設定ファイル(`~/.zshrc` など)。画面ではファイルパスとして表示されます |
## 競合の処理
@@ -52,8 +52,8 @@ CC Switch は、システム環境変数とアプリ設定の競合を自動的
### 変数の削除
1. 「選択 N 件を削除」ボタンをクリック
2. 削除操作を確認
3. CC Switch が自動的にバックアップしてから、選択した変数を削除
2. 「環境変数を削除しますか?」ダイアログで「削除を確認」をクリック
3. CC Switch が自動的にバックアップしてから、選択した変数を削除します。削除後は、アプリまたはターミナルを再起動すると反映されます
### 自動バックアップ
@@ -62,13 +62,14 @@ CC Switch は、システム環境変数とアプリ設定の競合を自動的
- バックアップの場所:`~/.cc-switch/backups/env-backup-<タイムスタンプ>.json`
- バックアップ形式:JSON ファイル
- 変数名、値、ソースなどの情報を含む
- この種のバックアップは「設定 → データ → バックアップと復元」の下にある「その他のバックアップ」で確認できます(名前は「環境変数クリーンアップのバックアップ」)。そこで削除することもできますが、削除すると、削除した変数の元の値は確認できなくなります
## 警告を無視する
競合が使用に影響しないことが確認できる場合:
1. 警告バナーの右側にある閉じるボタン(×)をクリック
2. 警告が一時的に非表示になる
2. 警告は今回の起動中は非表示になる
3. 次回の起動時に再度検出が行われる
## 手動での処理
+18 -16
View File
@@ -34,7 +34,8 @@
│ ├── 4.2 アプリケーションルーティング
│ ├── 4.3 フェイルオーバー
│ ├── 4.4 使用量統計
│ └── 4.5 接続チェック
│ ├── 4.5 接続チェック
│ └── 4.6 集約モード
│
└── 5. よくある質問
├── 5.1 設定ファイルの説明
@@ -51,16 +52,16 @@
|------|------|
| [1.1-introduction.md](./1-getting-started/1.1-introduction.md) | ソフトウェア紹介、主要機能、対応プラットフォーム |
| [1.2-installation.md](./1-getting-started/1.2-installation.md) | Windows/macOS/Linux インストールガイド |
| [1.3-interface.md](./1-getting-started/1.3-interface.md) | インターフェースレイアウト、ナビゲーションバー、プロバイダーカードの説明 |
| [1.3-interface.md](./1-getting-started/1.3-interface.md) | サイドバーのレイアウト、接続モードのタブ、プロバイダーカードの説明 |
| [1.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5 分でできるクイックスタートチュートリアル |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 言語、テーマ、ディレクトリ、クラウド同期の設定 |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 設定の 6 グループ:一般、アプリ設定、ローカルルーティング、ネットワーク、データ、情報 |
### 2. プロバイダー管理
| ファイル | 内容 |
|------|------|
| [2.1-add.md](./2-providers/2.1-add.md) | プリセットの使用、カスタム設定、統一プロバイダー |
| [2.2-switch.md](./2-providers/2.2-switch.md) | メイン画面での切り替え、トレイでの切り替え、反映方法 |
| [2.2-switch.md](./2-providers/2.2-switch.md) | 直接接続/ルーティング/集約、トレイでの切り替え、反映方法 |
| [2.3-edit.md](./2-providers/2.3-edit.md) | 設定の編集、API Key の変更、グローバル設定と編集の競合 |
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | ドラッグで並べ替え、プロバイダーの複製、削除 |
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | 使用量クエリ、残額表示、複数プラン表示 |
@@ -71,7 +72,7 @@
| ファイル | 内容 |
|------|------|
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP プロトコル、サーバーの追加、アプリバインド |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | プリセットの作成、有効化の切り替え、スマートバックフィル |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | プロンプトの作成、有効化の切り替え、対象ファイル |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | スキルの発見、インストール・アンインストール、リポジトリ管理 |
| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | セッションマネージャー:閲覧、検索、再開、削除 |
| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | ワークスペースファイルとデイリーメモリー(OpenClaw) |
@@ -85,6 +86,7 @@
| [4.3-failover.md](./4-proxy/4.3-failover.md) | フェイルオーバーキュー、サーキットブレーカー、ヘルスステータス |
| [4.4-usage.md](./4-proxy/4.4-usage.md) | 使用量統計、トレンドグラフ、料金設定 |
| [4.5-model-test.md](./4-proxy/4.5-model-test.md) | 接続チェック、チェックパラメータ |
| [4.6-aggregation.md](./4-proxy/4.6-aggregation.md) | 集約モード、デフォルトプロバイダー、ccs- プレフィックス、Codex の再起動 |
### 5. よくある質問
@@ -106,19 +108,19 @@
## バージョン情報
- ドキュメントバージョン:v3.20.4
- 最終更新:2026-09-26
- CC Switch v3.20.4+ 対応
- ドキュメントバージョン:v4.0.4
- 最終更新:2026-10-07
- CC Switch v4.0.4+ 対応
### 最近の主な変更
### 最近の主な変更(v4.0)
- **管理対象アプリの追加**:Grok Build(v3.18.0)、Pi(v3.20.0)、MiniMax Code(v3.20.4)が加わり、管理対象アプリは計 10 個になりました — 詳細は [1.1 ソフトウェア紹介](./1-getting-started/1.1-introduction.md)
- **Codex 公式プリセットがネイティブ Responses 直結に**:DeepSeek、Zhipu GLM(v3.20.2)、Kimi(v3.20.3)などは、プロトコル変換のためにローカルルーティングを有効にする必要がなくなりました — 詳細は [2.1 プロバイダーの追加](./2-providers/2.1-add.md)
- **Codex の切り替えは config.toml のみに書き込み**:サードパーティの API Key は `auth.json` に書き込まれなくなりました(v3.20.1)— 詳細は [1.5 個人設定 → Codex アプリ拡張](./1-getting-started/1.5-settings.md#codex-アプリ拡張)
- **「上流フォーマット」が「ローカルルーティングが必要」トグルに代わりました**(v3.16.5)— 詳細は [2.1 プロバイダーの追加](./2-providers/2.1-add.md#codex--grok-build-の上流フォーマットとモデルマッピング)
- **接続チェックがモデルテストに代わりました**:アドレスに到達できるかだけを確認し、実際のモデルリクエストは送信しません(v3.16.3)— 詳細は [4.5 接続チェック](./4-proxy/4.5-model-test.md)
- **ローカルルーティングなしでも使用量を集計**:各ツールのローカルセッションログからインポートします — 詳細は [4.4 使用量統計](./4-proxy/4.4-usage.md)
- **クラウド同期が S3 互換ストレージに対応** — 詳細は [1.5 個人設定](./1-getting-started/1.5-settings.md)
- **インターフェースの刷新**:上部のナビゲーションが左サイドバーになり、使用量、アカウント、MCP、Skills、プロンプト、セッション、アプリがそれぞれ独立したページになりました。設定は一般、アプリ設定、ローカルルーティング、ネットワーク、データ、情報の 6 グループに分かれています — 詳細は [1.3 インターフェース概要](./1-getting-started/1.3-interface.md)、[1.5 個人設定](./1-getting-started/1.5-settings.md)
- **直接接続 / ルーティング / 集約の 3 つの接続モード**:各アプリページの上部で選び、直接接続へは 1 ステップで戻せます — 詳細は [2.2 プロバイダーの切り替え](./2-providers/2.2-switch.md)
- **集約モードを追加**:Claude Code と Codex で、1 つのセッションの中で複数のプロバイダーのモデルを使い分けられます — 詳細は [4.6 集約モード](./4-proxy/4.6-aggregation.md)
- **切り替えはキーとなるフィールドだけを変更**:アドレス、キー、モデルなど以外の設定はそのまま残り、共通設定スニペットは使われなくなりました — 詳細は [2.3 プロバイダーの編集](./2-providers/2.3-edit.md)
- **アカウント**:ChatGPT、GitHub Copilot、xAI などのログインをサイドバーの「アカウント」でまとめて管理します — 詳細は [1.5 個人設定](./1-getting-started/1.5-settings.md)
- **「アプリ」ページ**:各 CLI ツールのインストールとアップグレード、サイドバーに表示するアプリの選択ができます — 詳細は [1.2 インストールガイド](./1-getting-started/1.2-installation.md)
- すべての変更点は [v4.0 リリースノート](../../release-notes/v4.0.4-ja.md) をご覧ください
## コントリビュート
@@ -30,8 +30,10 @@ CC Switch 通过统一的界面解决这些问题。
- **Prompts**:管理系统提示词预设,快速切换不同场景
- **Skills**:安装和管理技能扩展
- **会话管理器**:浏览、搜索各工具的会话历史,复制恢复命令继续对话
- **授权中心**:集中管理 ChatGPT(Codex)、GitHub Copilot、xAI 等 OAuth 账号
### 本地路由与高可用
### 连接模式、本地路由与高可用
- 三种连接模式:**直连**(客户端直接连供应商)、**路由**(请求经本机 CC Switch 转发)、**聚合**(Claude Code 和 Codex 专用,多家供应商的模型同列在 `/model` 里)
- 本地路由在 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 和 Gemini Native 之间转换请求格式
- 自动故障转移,主供应商失败时自动切换备用
- 熔断器机制,防止频繁重试失败的供应商
@@ -55,7 +57,7 @@ CC Switch 通过统一的界面解决这些问题。
- **切换**:同一时间只启用一个供应商,切换时改写该工具的配置文件。
- **共存**:多个供应商同时写入工具自身的配置,在工具里选择使用哪一个。
各工具支持哪些功能(本地路由、托盘切换、MCP、Skills、提示词、会话、用量统计)不尽相同,详见 [1.3 界面概览](./1.3-interface.md) 与各功能章节。
各工具支持哪些功能(本地路由、聚合、托盘切换、MCP、Skills、提示词、会话、用量统计)不尽相同,详见 [1.3 界面概览](./1.3-interface.md) 与各功能章节。
## 支持的平台
@@ -18,7 +18,7 @@ CC Switch 本身不需要 Node.js 或其他运行环境。它管理的是你已
### 方式一:在 CC Switch 里一键安装(推荐)
打开「设置 → 关于」,工具列表会显示每个工具的当前版本和最新版本。未安装的工具旁有安装按钮,已安装的可以单独升级或「全部升级」。支持 Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi。详见 [1.5 个性化配置 → 关于页面](./1.5-settings.md#关于页面)。
点侧栏底部的「应用」,列表会显示每个工具的当前版本和最新版本。未安装的工具旁有安装按钮,已安装的可以单独升级;也可以在这里选择在侧栏显示哪些应用。支持 Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code。Claude Desktop 是桌面应用,不能在这里安装。详见 [1.3 界面概览](./1.3-interface.md#应用管理页)。
### 方式二:按各工具的官方方式安装
@@ -33,7 +33,7 @@ CC Switch 本身不需要 Node.js 或其他运行环境。它管理的是你已
| Hermes | `curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash` |
| Pi | `npm i -g @earendil-works/pi-coding-agent` |
Claude Desktop、MiniMax Code 以及 Windows 上的安装方式,请参考各工具的官方文档。
Claude Desktop、MiniMax Code(可用方式一安装)以及 Windows 上的安装方式,请参考各工具的官方文档。
用 npm 安装需要先装好 Node.js。各工具要求的版本不同(例如 Claude Code 需要 22 及以上,OpenClaw 需要 24.16 以上的 24.x 或 26.1 以上),建议安装当前的 LTS 版本;版本不够时 npm 会给出提示。
@@ -150,7 +150,7 @@ chmod +x CC-Switch-v{版本号}-Linux-*.AppImage
1. 应用窗口正常显示
2. 系统托盘出现 CC Switch 图标
3. 应用切换器中能看到已启用的受管应用,并能切换到目标应用面板
3. 左侧栏的应用列表里能看到已显示的受管应用,点击即可进入对应应用的供应商页
## 自动更新
@@ -2,154 +2,156 @@
## 主界面布局
![image-20260108001629138](../../assets/image-20260108001629138.png)
![CC Switch 主界面](../../../../assets/release-notes/v4.0.0/main-zh.png)
## 顶部导航栏
主窗口分成左侧栏和右侧内容区:
| 序号 | 元素 | 功能说明 |
|------|------|----------|
| ① | Logo | 点击访问官网 ccswitch.io |
| ② | 设置按钮 | 打开设置页面(快捷键 `Cmd/Ctrl + ,`) |
| ③ | 本地路由开关 | Claude Code / Codex / Gemini CLI / Grok Build 页面:开启/关闭当前应用的本地路由(需在「设置 → 路由 → 本地路由」中打开「在主页面显示本地路由开关」);Claude Desktop 页面:始终显示,启停 Claude Desktop 使用的本地路由 |
| ④ | 应用切换器 | 在 10 个受管应用之间切换 |
| ⑤ | 功能区 | 当前应用支持的功能入口 |
| ⑥ | 添加按钮 | 添加新供应商 |
- **左侧栏**:选择要管理的应用,或进入全局功能页
- **内容区**:顶部是页头(应用名、「添加供应商」按钮和 ⋯ 菜单),下面是当前页的内容
另外还有几个按条件出现的入口:
## 左侧栏
- **项目切换器**:默认显示(MiniMax Code 页面除外),可在「设置 → 通用 → 主页面显示」中关闭「显示项目切换」
- **故障转移开关**:在「设置 → 路由 → 自动故障转移」中打开「在主页面显示故障转移开关」后显示
- **使用统计按钮**:当前应用开启本地路由时显示
左侧栏从上到下分三块:
### 应用切换器
| 区域 | 内容 |
|------|------|
| 应用列表 | 你选择显示的受管应用(最多 10 个)。点一个应用,右侧显示它的供应商页。应用名旁的小标记表示它当前用的是路由、聚合或模型映射,出问题时会提示「需要处理」 |
| 全局页 | MCP、Skills、提示词、会话、授权中心、用量统计(有今日花费时会在旁边显示「今日 $xx」)。这些页面不属于某个应用,每个只有一个入口 |
| 底部 | 「应用」(安装、升级、选择在侧栏显示哪些应用)和「设置」 |
点击顶部的应用图标切换当前管理的应用(窗口较窄时,放不下的应用会收进「更多应用」菜单):
点侧栏顶部的收起按钮,侧栏会缩成只剩图标;再点一次展开。「应用」或「设置」旁出现圆点,表示有命令行工具或 CC Switch 本身有新版本。
- **Claude** - 管理 Claude Code 配置
> 快捷键 `Cmd/Ctrl + ,` 随时打开设置。
### 受管应用
- **Claude Code** - 管理 Claude Code 配置
- **Claude Desktop** - 管理 Claude Desktop 第三方供应商与官方模式
- **Codex** - 管理 Codex 配置
- **Gemini** - 管理 Gemini CLI 配置
- **Grok Build** - 管理 Grok Build 配置
- **OpenCode** - 管理 OpenCode 配置
- **OpenClaw** - 管理 OpenClaw 配置
- **Hermes** - 管理 Hermes Agent 供应商与 Memory
- **Grok Build** - 管理 Grok Build 配置
- **Hermes** - 管理 Hermes Agent 供应商与记忆
- **Pi** - 管理 Pi 的供应商与模型
- **MiniMax Code** - 管理 MiniMax Code 的自定义供应商
切换后,供应商列表会显示对应应用的配置。不常用的应用可以在「设置 → 通用 → 主页面显示」中隐藏。
不常用的应用可以在侧栏的「应用」页里关掉显示。关掉后它不再出现在侧栏,也不出现在 MCP / Skills 的应用列和提示词、会话的应用下拉里,已有配置不受影响。
### 功能区按钮
### 全局页
不同应用显示的功能按钮不同:
| 入口 | 用途 |
|------|------|
| MCP | 管理 MCP 服务器,并按应用启用,见 [3.1 MCP](../3-extensions/3.1-mcp.md) |
| Skills | 安装和管理技能,见 [3.3 Skills](../3-extensions/3.3-skills.md) |
| 提示词 | 管理系统提示词,见 [3.2 Prompts](../3-extensions/3.2-prompts.md) |
| 会话 | 浏览、搜索各工具的会话历史 |
| 授权中心 | 集中管理 ChatGPT(Codex)、GitHub Copilot、xAI 等 OAuth 账号 |
| 用量统计 | 请求统计概览、趋势图、请求日志、供应商/模型统计和成本定价 |
| 应用 | 功能区按钮 |
|------|------------|
| Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、MiniMax Code | Skills、Prompts、会话、MCP |
| Pi | Skills、Prompts、会话(Pi 没有 MCP) |
| Claude Desktop | 与 Claude Code 相同,操作的是 Claude Code 的数据 |
| Hermes | Skills、记忆管理、Hermes Web UI、MCP |
| OpenClaw | 工作区、环境变量、工具、Agents、会话 |
不是每个应用都支持所有功能:Claude Desktop 和 OpenClaw 不在 MCP、Skills 里;Claude Desktop 页面上的 MCP、Skills、提示词、会话操作的是 Claude Code 的数据。
各应用的 MCP、Skills、Prompts 支持范围详见 [3.1 MCP](../3-extensions/3.1-mcp.md)、[3.2 Prompts](../3-extensions/3.2-prompts.md)、[3.3 Skills](../3-extensions/3.3-skills.md)。
## 应用页
## 供应商卡片
### 应用页页头
每个供应商以卡片形式展示,从左到右依次包含以下元素:
页头显示应用名和页面名(如「Claude Code 供应商」),右侧是:
### 卡片元素(从左到右)
- **添加供应商**:添加新的供应商
- **项目切换**:默认隐藏,可在「设置 → 通用 → 侧栏与页头」打开「显示项目切换」(MiniMax Code 页面没有)
- **⋯ 菜单**:查看会话、配置目录、安装与升级、在侧栏隐藏、查看此应用的用量
- Hermes 页头还有「Web UI」按钮
| 序号 | 元素 | 图标 | 功能说明 |
|------|------|------|----------|
| ① | 拖拽手柄 | ≡ | 按住上下拖动调整供应商顺序 |
| ② | 供应商图标 | 🔷 | 显示供应商品牌图标,可自定义颜色 |
| ③ | 供应商信息 | - | 名称、备注/端点地址(可点击打开官网) |
| ④ | 用量信息 | - | 显示剩余额度,多套餐时显示套餐数量 |
| ⑤ | 启用按钮 | ▶ | 切换为当前使用的供应商 |
| ⑥ | 编辑按钮 | ✏️ | 编辑供应商配置 |
| ⑦ | 复制按钮 | 📋 | 复制供应商(创建副本) |
| ⑧ | 检测连通 | 🧪 | 探测供应商地址是否可达,并显示延迟 |
| ⑨ | 用量查询 | 📊 | 配置用量查询脚本 |
| ⑩ | 打开终端 | ⌨️ | 选择工作目录后,用该供应商的配置打开一个终端(仅 Claude Code) |
| ⑪ | 删除按钮 | 🗑️ | 删除供应商(当前启用时禁用) |
OpenClaw 和 Hermes 在页头下有一排页签,可以在供应商页和它们的专属页之间切换:
> 💡 **提示**:操作按钮区域(⑤-⑪)在鼠标悬停时显示,平时隐藏以保持界面简洁。
| 应用 | 页签 |
|------|------|
| OpenClaw | 供应商、工作区、配置 |
| Hermes | 供应商、记忆 |
部分供应商卡片会显示 **「需要路由」** 或 **「不支持路由」** 徽章:前者表示该供应商需要开启本地路由才能使用(例如接口格式需要转换),后者表示该供应商不能经本地路由转发(如 Claude Official)。
### 连接模式
### 按钮详细说明
Claude Code、Codex、Gemini CLI、Grok Build 的供应商页顶部有 **直连 / 路由 / 聚合** 三个标签(聚合只有 Claude Code 和 Codex 有;Claude Desktop 的是直连 / 模型映射)。标签上的圆点表示当前生效的模式,旁边的文字写明现在连的是哪一家。
| 按钮 | 状态变化 | 说明 |
|------|----------|------|
| **启用** | 已启用时显示 ✓ 并禁用 | 故障转移模式下变为「加入/已加入」 |
| **编辑** | 始终可用 | 打开编辑面板修改配置 |
| **复制** | 始终可用 | 创建供应商副本,名称后缀 `copy` |
| **检测连通** | 检测中显示加载动画 | 只探测地址是否可达,不发送真实模型请求;官方供应商和 MiniMax Code 的供应商上为灰色不可用 |
| **用量查询** | 多数供应商可用 | 配置用量查询模板或脚本;Copilot、Codex OAuth、xAI OAuth 等配额自动显示的供应商上为灰色不可用 |
| **删除** | 当前启用时半透明禁用 | 需先切换到其他供应商才能删除 |
点标签只是查看那个模式下的列表,不会改配置。要真正切换,点下方写明后果的按钮:「开始路由」、「切换到聚合模式」、「回到直连」。路由见 [4.2 路由](../4-proxy/4.2-routing.md),聚合见 [4.6 聚合模式](../4-proxy/4.6-aggregation.md)。
### 卡片状态
### 供应商卡片
| 状态 | 边框颜色 | 说明 |
|------|----------|------|
| **当前启用** | 🔵 蓝色边框 | 普通模式下当前使用的供应商 |
| **路由活跃** | 🟢 绿色边框 | 开启本地路由时实际转发请求的供应商 |
| **普通状态** | 默认边框 | 未启用的供应商 |
| **故障转移中** | 显示优先级徽章 | 如 P1、P2 表示故障转移优先级 |
每个供应商是一张卡片,从左到右包含:
### 健康状态徽章
| 元素 | 功能说明 |
|------|----------|
| 拖拽手柄 | 拖动调整供应商顺序(悬停时出现) |
| 供应商图标 | 品牌图标 |
| 供应商信息 | 名称、备注或端点地址,点击可打开官网;名称旁可能有「官方」「需要路由」等标签 |
| 用量信息 | 剩余额度或余额,多套餐时显示多行 |
| 状态 / 主操作 | 当前生效的卡片显示「使用中」(路由模式下是「路由中」);其他卡片是一个播放按钮,直连下用于切换,路由下用于「路由到此」,聚合下用于设为默认或添加 |
| 编辑按钮 | 编辑供应商配置 |
| ⋯ 更多 | 复制、检测连通、配置用量查询、打开终端(仅 Claude Code)、删除 |
开启本地路由后,加入故障转移队列的供应商会显示健康状态:
正在使用的供应商不能删除,需先切到别家。「检测连通」只探测地址是否可达,不发送真实模型请求;官方供应商和 MiniMax Code 的供应商上不可用。Copilot、Codex OAuth、xAI OAuth 等额度自动显示的供应商没有「配置用量查询」。
| 徽章 | 颜色 | 说明 |
|------|------|------|
| 正常 | 🟢 绿色 | 连续失败 0 次 |
| 降级 | 🟡 黄色 | 有失败但未触发熔断 |
| 熔断 | 🔴 红色 | 已触发熔断,暂时跳过(阈值见 [4.3 故障转移](../4-proxy/4.3-failover.md#熔断器配置)) |
**「需要路由」** 标签表示这个供应商必须经本地路由才能用(例如接口格式需要转换),直连切换过去客户端会无法使用它;**官方订阅不经过路由**(Codex 的 OpenAI Official 例外),路由模式下不能切到它。
OpenCode、OpenClaw、Hermes、Pi、MiniMax Code 是「共存」式应用,卡片上的按钮是「添加 / 移除」(Pi 是「启用 / 移除」),没有直连 / 路由 / 聚合标签。
### 故障转移队列与健康状态
在路由模式下,供应商页分成「队列 · 按优先级」和「不在队列」两部分。队列里的供应商按顺序接请求,前一位连续失败时自动换到下一位,可用上移、下移或拖动调整顺序;设置方法见 [4.3 故障转移](../4-proxy/4.3-failover.md)。
队列里的供应商会显示健康状态:
| 状态 | 说明 |
|------|------|
| 正常 | 连续失败 0 次 |
| 降级 | 有失败但未触发熔断 |
| 熔断 | 已触发熔断,暂时跳过(阈值见 [4.3 故障转移](../4-proxy/4.3-failover.md#熔断器配置)) |
### 应用管理页
侧栏底部的「应用」页用来管理命令行工具:
- 查看每个工具的当前版本和最新版本,安装未装的,升级已装的
- 选择哪些应用显示在侧栏
- 「手动安装命令」可复制各工具的安装命令
Claude Desktop 是桌面应用,不能在这里安装或升级,页面只显示它是否已接入。启动时是否检查新版本由「设置 → 通用 → 各应用的新版本」控制。
## 系统托盘
CC Switch 在系统托盘显示图标,提供快速操作入口。
### 托盘菜单结构
<!-- TODO(v4 截图): 展开后的托盘菜单(含 Claude Code / Codex 等应用子菜单) -->
![image-20260108002153668](../../assets/image-20260108002153668.png)
### 菜单功能
### 托盘菜单
| 菜单项 | 功能 |
|--------|------|
| 打开主界面 | 显示主窗口并聚焦 |
| 打开 CC Switch | 显示主窗口并聚焦,始终在最上面 |
| 应用子菜单 | Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build 五个切换式应用各一个子菜单,标题显示当前供应商和模式;子菜单里点供应商即可切换,当前的带勾选标记,还可以打开该应用页面或添加供应商,部分应用会显示额度摘要 |
| 项目 | 切换项目(整套供应商、MCP、Skills、提示词状态),仅在开启「显示项目切换」后出现 |
| 轻量模式 | 勾选框,进入或退出仅托盘运行模式 |
| 打开官方网站 | 在浏览器中打开 ccswitch.io |
| 项目 | 切换项目(整套供应商、MCP、Skills、提示词状态) |
| 应用子菜单 | 按 Claude / Codex / Gemini / Grok Build 分组的折叠子菜单(如 "Claude · PackyCode"),可显示当前供应商与缓存用量摘要 |
| 供应商列表 | 在每个子菜单内,点击切换,当前启用的显示勾选标记 |
| 轻量模式 | 勾选框切换,进入/退出仅托盘运行模式 |
| 退出 | 完全退出应用 |
| 退出 CC Switch | 完全退出应用。有应用在用路由或聚合时,菜单项会写明「路由服务会停止」 |
> **注意**:每个托盘子菜单的标题会显示当前供应商名称(如 "Claude · PackyCode")。没有配置供应商的应用会显示禁用的"(无供应商)"条目。托盘目前只包含 Claude Code、Codex、Gemini CLI、Grok Build 四个支持本地路由的应用;其他应用请在主界面切换;主界面显示哪些应用由设置中的「主页面显示」控制。
路由服务没启动、某个应用切换失败等问题,会显示在菜单最上方,托盘图标上也会出现一个小圆点。
> **注意**:累加式(共存)应用(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code)不进托盘,请在主界面里操作。没有配置供应商的应用在子菜单里会显示相应提示。托盘里显示哪些应用,由「应用」页的显示开关决定。
### 多语言支持
托盘菜单支持四种语言,根据设置自动切换:
| 语言 | 打开主界面 | 退出 |
|------|-----------|------|
| 简体中文 | 打开主界面 | 退出 |
| 繁體中文 | 開啟主介面 | 退出 |
| English | Open main window | Quit |
| 日本語 | メインウィンドウを開く | 終了 |
托盘菜单跟随界面语言,支持简体中文、繁體中文、English、日本語;还没设置过语言时按系统语言。
### 轻量模式
托盘菜单包含 **轻量模式** 切换开关(勾选框)。启用后:
托盘菜单包含 **轻量模式** 勾选框。启用后:
- 主窗口关闭以释放资源
- 应用仅在系统托盘中运行
- 你仍可通过托盘子菜单切换供应商
- 在 macOS 上,Dock 图标也会隐藏
要退出轻量模式,取消勾选该选项或点击"打开主界面" — 主窗口将被重建并显示。
要退出轻量模式,取消勾选该选项或点击「打开 CC Switch」,主窗口将被重建并显示。
### 使用场景
@@ -160,65 +162,59 @@ CC Switch 在系统托盘显示图标,提供快速操作入口。
- 后台运行时管理配置
- 使用轻量模式以最小化资源占用
## 设置页面
## 设置
设置页面分为多个 Tab:
点侧栏底部的「设置」,侧栏会换成设置目录,右侧显示当前分组;点「返回」或按 `Esc` 回到主界面。设置分为 6 个分组:
### 通用 Tab
### 通用
- 语言设置(简体中文/繁體中文/English/日本語)
- 主题设置(跟随系统/浅色/深色)
- 主页面显示(应用与项目切换入口)
- Skills 存储位置与同步方式
- Codex 应用增强(保留官方登录、统一会话历史)
- 窗口行为(开机自启、关闭行为)
- 首选终端
- **外观**:界面语言(简体中文/繁體中文/English/日本語)、明暗主题(跟随系统/浅色/深色)
- **侧栏与页头**:在侧栏显示哪些应用(跳转到「应用」页)、显示项目切换
- **各应用的新版本**:启动时检查各应用的新版本
- **窗口与终端**:开机自启、关闭按钮的行为(隐藏到托盘或退出)、首选终端
### 路由 Tab
### 应用配置
- 本地路由(路由总开关、按应用启用、监听地址与端口)
- 各应用的配置目录覆盖(Claude Desktop 和 MiniMax Code 除外)
- 各应用自己的选项,如 Claude Code 的「应用到 Claude Code 插件」「跳过 Claude Code 初次安装确认」,Codex 的非接管切换时保留官方登录
### 本地路由
- 服务:监听地址与端口、启停
- 正在使用路由的应用
- 自动故障转移
- 整流器
- 全部退出路由
### 网络
- 全局出站代理
### 认证 Tab
### 数据
- OAuth 认证中心(GitHub Copilot、ChatGPT、xAI 账号)
### 高级 Tab
- 配置文件目录
- 数据管理(导入导出)
- 备份与恢复
- 存储位置(CC Switch 配置目录)
- 数据管理(SQL 导入导出)
- 备份与恢复(含「其他备份」总览)
- 云同步
- 连通检测配置
- 应用诊断日志
### 使用统计 Tab
### 关于
- 请求统计概览
- 趋势图表
- 请求日志
- 供应商/模型统计
- 成本定价
### 关于 Tab
- 版本信息与更新检查
- CLI 工具的版本检测、安装与升级
- 版本信息、检查更新
- GitHub、官方网站、发行说明
## 快捷键
| 快捷键 | 功能 |
|--------|------|
| `Cmd/Ctrl + ,` | 打开设置 |
| `Cmd/Ctrl + F` | 搜索供应商 |
| `Esc` | 关闭弹窗/搜索 |
| `Cmd/Ctrl + F` | 搜索供应商(在供应商页) |
| `Esc` | 关闭搜索;在设置页返回主界面 |
## 搜索功能
按 `Cmd/Ctrl + F` 打开搜索框:
在供应商页按 `Cmd/Ctrl + F` 打开搜索框:
- 支持按名称、备注、URL 搜索
- 支持按名称、备注、网址搜索
- 实时过滤供应商列表
- 按 `Esc` 关闭搜索
@@ -4,28 +4,28 @@
## 第一步:添加供应商
1. 点击主界面右上角的 **+** 按钮
1. 在左侧栏选中要管理的工具,点击页面右上角的 **+**(添加供应商)
2. 在「预设供应商」中选择你的供应商
- 常用预设:智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode
- 或选择「自定义」手动配置
3. 填写 **API Key**
4. 点击「添加」
![image-20260108002807657](../../assets/image-20260108002807657.png)
<!-- TODO(v4 截图): 添加供应商面板:搜索框、预设列表和 API Key 表单 -->
> 💡 **提示**:预设会自动填充端点地址,你只需要填写 API Key。
> 💡 **提示**:添加面板支持按中文名和域名搜索,同一家的不同套餐和地区合并成一行。预设会自动填充端点地址,你只需要填写 API Key。
## 第二步:切换供应商
添加完成后,供应商会出现在列表中。
**方式一:主界面切换**
- 点击供应商卡片的「启用」按钮
**方式一:应用页切换**
- 点击供应商卡片的「切换」按钮,状态会显示为「使用中」
- OpenCode、OpenClaw、Hermes、MiniMax Code 是共存式应用,按钮为「添加」(Pi 为「启用」),可以同时添加多个供应商
**方式二:托盘快速切换**
- 右键系统托盘图标
- 直接点击供应商名称(支持 Claude Code、Codex、Gemini CLI、Grok Build)
- 每个工具一行,显示「名称 · 模式 · 供应商 · 额度」,在子菜单里直接点击供应商名称(支持 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build)
## 第三步:生效方式
@@ -42,17 +42,27 @@
| OpenClaw | 需要关闭并重新打开终端 |
| Hermes / Pi / MiniMax Code | 供应商添加后写入工具的配置;Pi、MiniMax Code 在工具里选择要使用的模型,Hermes 可在卡片上点击「启用」设为当前供应商 |
开启本地路由后,Claude Code、Codex、Gemini CLI、Grok Build 切换供应商会立即作用于后续请求;但如果切换改变了模型,Codex、Gemini CLI 和 Grok Build 仍可能需要重启。
处于路由模式时,Claude Code、Codex、Gemini CLI、Grok Build 切换供应商会立即作用于后续请求;但如果切换改变了模型,Codex、Gemini CLI 和 Grok Build 仍可能需要重启。
## 直连、路由和聚合(可选)
Claude Code、Codex、Gemini CLI、Grok Build 的页面顶部有「直连 / 路由」标签,Claude Code 和 Codex 还有「聚合」。点标签只是切换查看的内容,不会改动配置;真正切换要点页面上写明后果的按钮:「开始路由」、「切换到聚合模式」,回到直连点「回到直连」。
- **直连**(默认):客户端直接连供应商,日常使用选它
- **路由**:请求经本机 CC Switch 转发(默认 `127.0.0.1:15721`),可以转换接口格式、做故障转移。想在 Claude Code 里用 OpenAI 或 Gemini 格式的供应商,或在 Codex 里用 Claude,选它
- **聚合**:把多家供应商的模型放进同一个模型列表,选哪个模型请求就发给哪一家,不做故障转移
路由和聚合需要 CC Switch 保持运行;退出 CC Switch 会自动回到直连,下次启动再接上。官方订阅不经过路由(Codex 的 OpenAI Official 例外)。详见 [开启本地路由](../4-proxy/4.1-service.md)。
### Claude Code 首次安装提示
如果 Claude Code 首次启动时提示需要**登录**或显示初始化引导,请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项:
1. 打开 CC Switch「设置 → 通用」
1. 打开 CC Switch「设置 → 应用配置」,找到 Claude Code 一块
2. 开启「跳过 Claude Code 初次安装确认」开关
3. 重新启动 Claude Code
![image-20260108002626389](../../assets/image-20260108002626389.png)
<!-- TODO(v4 截图): 设置 → 应用配置 → Claude Code 里的「跳过 Claude Code 初次安装确认」开关 -->
> ⚠️ **注意**:此选项会在 `~/.claude.json` 中写入 `hasCompletedOnboarding: true`,跳过官方的初次安装确认流程。
@@ -84,6 +94,8 @@ openclaw
如果 AI 能正常回复,说明配置成功。
> **注意**:首次启动时,CC Switch 会自动把 Claude Code、Codex、Gemini CLI、Grok Build 的现有配置导入为名为 `default` 的供应商,并为这几个工具和 Claude Desktop 添加官方供应商,原有配置不会丢失。
## 下一步
恭喜!你已经完成了基础配置。接下来可以:
@@ -92,6 +104,7 @@ openclaw
- [配置 MCP 服务器](../3-extensions/3.1-mcp.md) - 扩展 AI 工具的能力
- [设置系统提示词](../3-extensions/3.2-prompts.md) - 自定义 AI 的行为
- [开启本地路由](../4-proxy/4.1-service.md) - 使用需要格式转换的供应商、自动故障转移
- [管理 AI 编程工具](./1.2-installation.md#可选安装要管理的工具) - 在侧栏「应用」页安装、升级工具,选择侧栏显示哪些应用
- [查看用量统计](../4-proxy/4.4-usage.md) - 统计请求数、Token 和花费
## 常见问题
@@ -4,33 +4,36 @@
## 打开设置
- 点击左上角 **⚙️** 按钮
- 或使用快捷键 `Cmd/Ctrl + ,`
- 点击左侧栏底部的 **设置**
- 或使用快捷键 `Cmd/Ctrl + ,`(直接打开「通用」)
## 语言设置
设置单独占一屏,左侧栏换成设置目录,分为 6 组:**通用、应用配置、本地路由、网络、数据、关于**。点目录上方的「返回」(或按 `Esc`)回到之前的页面。设置里只放偏好;MCP、Skills、提示词、会话等功能页都在左侧栏。
CC Switch 支持四种语言:
开关类设置即时保存;路径类设置(配置目录)改完要点该块的「保存」。
| 语言 | 说明 |
| -------- | -------- |
| 简体中文 | 默认语言 |
| 繁體中文 | 繁体中文界面 |
| English | 英文界面 |
| 日本語 | 日文界面 |
## 通用
切换语言后立即生效,无需重启。
### 外观
## 主题设置
| 设置 | 说明 |
| ---- | ---- |
| 界面语言 | 简体中文、繁體中文、English、日本語,切换后立即生效,无需重启 |
| 明暗 | 跟随系统 / 浅色 / 深色 |
| 选项 | 说明 |
| -------- | --------------------------- |
| 跟随系统 | 自动匹配系统的深色/浅色模式 |
| 浅色 | 始终使用浅色主题 |
| 深色 | 始终使用深色主题 |
### 侧栏与页头
## 窗口行为
- **在侧栏显示哪些应用**:点「前往「应用」」跳到侧栏的「应用」页,在那里选择显示哪些应用(可选 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code,至少保留一个)
- **显示项目切换**:打开后,Claude Code、Claude Desktop、Codex 页面顶部会出现项目切换器。默认关闭
### 开机自启
> 💡 **使用场景**:如果你只使用 Claude Code 和 Codex,可以隐藏其他应用,保持侧栏简洁。
### 各应用的新版本
**启动时检查各应用的新版本**:打开后,每次启动 CC Switch 会查一次已安装的命令行应用有没有新版本,查到了就在侧栏「应用」上显示一个圆点。不会自动升级。升级在「应用」页进行,见 [1.2 安装指南](./1.2-installation.md#可选安装要管理的工具)。
### 窗口与终端
#### 开机自启
开启后,系统启动时自动运行 CC Switch。
@@ -38,7 +41,9 @@ CC Switch 支持四种语言:
- **macOS**:通过 LaunchAgent 实现
- **Linux**:通过 XDG autostart 实现
### 关闭行为
开启后会多出一个 **静默启动** 开关:启动时不显示主窗口,仅在系统托盘运行。
#### 关闭时最小化到托盘
| 「关闭时最小化到托盘」 | 点击窗口关闭按钮时 |
| ---------------------- | -------------------------- |
@@ -47,9 +52,23 @@ CC Switch 支持四种语言:
推荐保持开启,方便通过托盘快速切换供应商。
### 轻量模式
#### 启用应用级窗口按钮(仅 Linux)
v3.13.0 起新增「轻量模式」——一种**仅托盘运行**的状态,用于把空闲时的桌面占用降到最低。
开启后使用应用自建的最小化、最大化/还原、关闭按钮;关闭后沿用系统窗口模式。
#### 首选终端
选择点击供应商卡片上的「打开终端」时使用的终端应用。选的终端不可用时,改用系统默认终端。
| 平台 | 终端选项 |
| ------- | ------------------------------------------------------------------ |
| macOS | Terminal、iTerm2、Alacritty、Kitty、Ghostty、Otty、WezTerm、Kaku、Warp |
| Windows | 命令提示符、PowerShell、Windows Terminal |
| Linux | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |
#### 轻量模式
轻量模式是一种**仅托盘运行**的状态,用于把空闲时的桌面占用降到最低。
**触发方式**:右键系统托盘图标 → 点击「轻量模式」。主窗口会被**销毁**(而不是隐藏),UI 资源和内存随之释放。
@@ -63,55 +82,22 @@ v3.13.0 起新增「轻量模式」——一种**仅托盘运行**的状态,
| 托盘切换功能 | 可用 | 可用 |
| 深链接唤起 | 可用 | 可用(按需重建) |
> 💡 **使用场景**:如果你 CC Switch 长时间常驻后台,主要通过托盘菜单切换供应商,开启轻量模式能显著降低内存占用。
> ⚠️ **注意**:轻量模式状态不持久 — 下次正常启动时会回到普通模式。需要长期使用可搭配开机自启。
### 应用到 Claude Code 插件
## 应用配置
开启后,VS Code 中 Claude Code 插件的供应商会随 CC Switch 切换(写入 `~/.claude/config.json` 的 `primaryApiKey`)。
每个应用一块,放只属于它的开关和配置目录。
> 💡 **使用场景**:如果你同时使用 Claude Code CLI 和 VS Code 插件,开启此选项可以保持两者配置一致。
### Claude Code
### 跳过 Claude Code 初次安装确认
- **应用到 Claude Code 插件**:开启后,VS Code 中 Claude Code 插件的供应商会随 CC Switch 切换(写入 `~/.claude/config.json` 的 `primaryApiKey`)。同时使用 Claude Code CLI 和 VS Code 插件时,开启它可以保持两者一致
- **跳过 Claude Code 初次安装确认**:开启后跳过 Claude Code 首次启动时的初次安装确认。
开启后,跳过 Claude Code 首次启动时的初次安装确认,适合已熟悉 Claude Code 的用户。
> ⚠️ **注意**:此选项会在 `~/.claude.json` 中写入 `hasCompletedOnboarding: true`;关闭时删除该字段。
### 主页面显示
选择在主页面的应用切换器中显示哪些应用。每个应用可以独立开关,但至少保留一个。
可配置的应用:Claude Code、Claude Desktop、Codex、Gemini、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code。
同一组里还有 **显示项目切换** 开关,控制主页面顶部是否显示项目切换入口。
> 💡 **使用场景**:如果你只使用 Claude Code 和 Codex CLI,可以隐藏其他应用,保持界面简洁。
### Skills 存储位置
选择 CC Switch 存放 Skills 主副本的目录:
| 选项 | 说明 |
| ----------------- | -------------------------------------------------------------------- |
| CC Switch(默认) | 存放在 `~/.cc-switch/skills/`,由 CC Switch 统一管理并同步到各应用 |
| `~/.agents/skills` | 存放在 `~/.agents/skills/`,遵循 Agent Skills 开放标准,兼容的工具可以直接读取 |
### Skills 同步方式
设置技能安装到各应用目录时的同步方式:
| 方式 | 说明 |
| ----------------- | ---------------------------------------------------- |
| 软连接 | 创建符号链接指向技能源文件,占用空间小,更新实时同步 |
| 文件复制 | 将技能文件完整复制到目标目录 |
> 💡 **推荐**:默认使用软连接方式。如果遇到权限问题,可切换为文件复制方式。
> ⚠️ **注意**:「跳过 Claude Code 初次安装确认」会在 `~/.claude.json` 中写入 `hasCompletedOnboarding: true`;关闭时删除该字段。
### Codex 应用增强
包含两个开关,默认都关闭:
Codex 这一块有两个开关,默认都关闭:
**非接管切换时保留官方登录**:
@@ -122,50 +108,59 @@ v3.13.0 起新增「轻量模式」——一种**仅托盘运行**的状态,
**统一 Codex 会话历史**:开启后,官方订阅以共享的 custom 供应商标识运行,官方与第三方会话出现在同一个历史列表中,并可选择把现有官方会话一并迁入(迁移前自动备份);关闭时可按备份恢复。注意:跨供应商继续旧会话时,对方后端可能无法解密会话中的推理内容,导致继续失败。详见攻略 [统一 Codex 会话历史](../../../guides/codex-unified-session-history-guide-zh.md)。
### 首选终端
### 配置目录
选择 CC Switch 打开终端时使用的终端应用程序。
Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi 这 8 个应用各有一行「配置目录」,可以指向别的位置;留空用默认值。MCP、Skills、提示词路径会随之变化。
支持的终端(按平台):
| 应用 | 默认值 |
| --------------- | --------------------- |
| Claude Code | `~/.claude/` |
| Codex | `~/.codex/` |
| Gemini CLI | `~/.gemini/` |
| Grok Build | `~/.grok/` |
| OpenCode | `~/.config/opencode/` |
| OpenClaw | `~/.openclaw/` |
| Hermes | `~/.hermes/` |
| Pi | `~/.pi/agent/` |
| 平台 | 终端选项 |
| ------- | ------------------------------------------------------------------ |
| macOS | Terminal、iTerm2、Alacritty、Kitty、Ghostty、Otty、WezTerm、Kaku、Warp |
| Windows | CMD、PowerShell、Windows Terminal |
| Linux | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |
Claude Desktop 和 MiniMax Code 不支持在这里覆盖目录(所以应用配置里没有它们)。MiniMax Code 的数据目录默认为 `~/.minimax/`,可以用环境变量 `MINIMAX_DATA_DIR`(或 `MAVIS_DATA_DIR`)指定;Hermes 另外识别 `HERMES_HOME`,Pi 另外识别 `PI_CODING_AGENT_DIR`。
## 目录配置
设置 → 高级 → 配置文件目录
### 应用配置目录
CC Switch 自身数据的存储位置,默认为 `~/.cc-switch/`。
### CLI 工具目录
可以自定义各 CLI 工具的配置目录:
| 配置 | 默认值 | 说明 |
| --------------- | --------------------- | ---------------------- |
| Claude 目录 | `~/.claude/` | Claude Code 配置目录 |
| Codex 目录 | `~/.codex/` | Codex 配置目录 |
| Gemini 目录 | `~/.gemini/` | Gemini CLI 配置目录 |
| Grok Build 目录 | `~/.grok/` | Grok Build 配置目录 |
| OpenCode 目录 | `~/.config/opencode/` | OpenCode 配置目录 |
| OpenClaw 目录 | `~/.openclaw/` | OpenClaw 配置目录 |
| Hermes 目录 | `~/.hermes/` | Hermes 配置目录 |
| Pi 目录 | `~/.pi/agent/` | Pi 的 agent 配置目录 |
Claude Desktop 和 MiniMax Code 不支持在这里覆盖目录。MiniMax Code 的数据目录默认为 `~/.minimax/`,可以用环境变量 `MINIMAX_DATA_DIR`(或 `MAVIS_DATA_DIR`)指定;Hermes 另外识别 `HERMES_HOME`,Pi 另外识别 `PI_CODING_AGENT_DIR`。
> 💡 **WSL**:CC Switch 不会自动识别 WSL。在 Windows 上可以把目录改成 WSL 里的路径(如 `\\wsl.localhost\Ubuntu\home\<用户名>\.claude`),CC Switch 就会读写 WSL 里的配置,「关于」页也会在对应的 WSL 发行版里检测和升级该工具。
> 💡 **WSL**:CC Switch 不会自动识别 WSL。在 Windows 上可以把目录改成 WSL 里的路径(如 `\\wsl.localhost\Ubuntu\home\<用户名>\.claude`),CC Switch 就会读写 WSL 里的配置。
> ⚠️ **注意**:修改目录后需要重启应用,且对应的 CLI 工具也需要配置相同的目录。
## 数据管理
> 💡 **Skills 的存储位置和同步方式**不在设置里:在侧栏「Skills」页点「存储与同步」,可以选主副本放在「CC Switch 目录」还是「通用目录」(`~/.agents/skills`),以及同步到各应用用软链接还是复制。
### 导出配置
## 本地路由
设置 → 本地路由
这一组集中管理本地路由的全局部分:
- **服务**:显示路由服务的运行状态(已运行时间、总请求数、成功率、活跃连接),可「启动」/「停止」;「监听地址与端口」默认 `127.0.0.1`,修改后点「保存并重启服务」;「记录请求用量」关闭后,用量统计里没有经路由的请求明细。还有应用在用路由服务时不能停止,需要先让它们回到直连
- **正在使用路由的应用**:列出当前处于路由或聚合模式的应用,点「前往」跳到该应用页;「全部回到直连」让所有应用写回直连配置并停止路由服务,路由目标、队列和聚合名单会保留
- **自动故障转移**:调各应用的超时、重试和熔断。队列在各应用页的「路由」页签里管理。详见 [4.3 故障转移](../4-proxy/4.3-failover.md)
- **整流器**:自动修复部分上游不兼容的请求,例如 Thinking 签名不兼容时移除相关内容后重试
进入路由或聚合的入口在各应用页顶部的「直连 / 路由 / 聚合」标签,详见 [4.1 本地路由服务](../4-proxy/4.1-service.md)。
## 网络
设置 → 网络
**全局出站代理**:配置 CC Switch 访问外部 API 时使用的 HTTP/HTTPS 代理,适用于需要通过代理访问外部 API 的场景。
## 数据
设置 → 数据
### 存储位置
**CC Switch 配置目录**:CC Switch 自身数据的存储位置,默认为 `~/.cc-switch/`,可以指定到云同步文件夹。改完点「保存」,需要重启应用生效。
### 数据管理
#### 导出配置
点击「导出 SQL 备份」按钮,保存包含以下内容的 SQL 备份文件:
@@ -177,49 +172,15 @@ Claude Desktop 和 MiniMax Code 不支持在这里覆盖目录。MiniMax Code
导出文件名格式为 `cc-switch-export-{timestamp}.sql`。
### 导入配置
#### 导入配置
1. 点击「选择 SQL 文件」
1. 点击「选择 SQL 文件」(仅支持导入由 CC Switch 导出的备份)
2. 选择之前导出的备份文件
3. 按钮变为「导入」后,点击它开始导入
4. 导入成功后,界面会显示本次导入前自动创建的备份 ID
> ⚠️ **注意**:导入会覆盖现有配置,建议先导出当前配置作为备份。
## 路由设置
设置 → 路由 Tab
路由 Tab 集中管理本地路由相关功能:
### 本地路由
启动/停止本地路由,按应用开启路由,配置监听地址和端口。详见 [4.1 本地路由服务](../4-proxy/4.1-service.md)。
### 自动故障转移
按应用(Claude / Codex / Gemini / Grok Build)配置故障转移队列和自动切换策略。详见 [4.3 故障转移](../4-proxy/4.3-failover.md)。
### 整流器
自动修复部分上游不兼容的请求,例如 Thinking 签名不兼容时移除相关内容后重试。
### 全局出站代理
配置 CC Switch 的出站 HTTP/HTTPS 代理,适用于需要通过代理访问外部 API 的场景。
## 高级设置
设置 → 高级 Tab
### 配置文件目录
自定义各应用的配置文件目录。详见上方「目录配置」章节。
### 数据管理
导入/导出配置备份。详见上方「数据管理」章节。
### 备份与恢复
备份管理面板提供对数据库备份的全面控制。
@@ -251,6 +212,12 @@ Claude Desktop 和 MiniMax Code 不支持在这里覆盖目录。MiniMax Code
> ⚠️ **重要**:恢复备份会覆盖当前数据库。恢复操作前始终会自动创建安全备份,以便在需要时恢复。
#### 其他备份
备份列表下方的「其他备份」总览列出 CC Switch 在各处留下的备份(Skill 卸载备份、配置文件首次写入备份、Codex 会话迁移备份、Hermes / OpenClaw 配置备份、旧版遗留文件等),显示每项的位置和占用大小,合计占用写在标题旁。每项可「在文件管理器中显示」,也可以自己选择「删除」(需确认,永久删除)。数据库备份在上方列表中管理。
> ⚠️ 有些备份删除后无法恢复对应内容,例如删掉「配置文件首次写入备份」后找不到改写前的原文件,删掉「Skill 卸载备份」后已卸载的 Skill 无法再恢复;每项下方的说明会写清后果。
### 云同步
通过 **WebDAV** 或 **S3 兼容存储** 在多台设备间同步配置,两种方式同一时间只能启用一种。使用 **v2 协议**,支持双层版本控制,提高可靠性。
@@ -321,11 +288,9 @@ Claude Desktop 和 MiniMax Code 不支持在这里覆盖目录。MiniMax Code
- **debug** - 记录调试信息
- **trace** - 记录所有详细信息
## OAuth 认证中心(Beta)
## 授权中心(Beta)
设置 → **认证** Tab
v3.13.0 新增的 **OAuth 认证中心**(Beta)统一管理第三方 OAuth 凭据,目前支持三类账号:
登录入口在左侧栏的「授权中心」,不在设置里。授权中心统一管理第三方 OAuth 凭据,目前支持三类账号:
| 账号类型 | 用途 |
| ---------------------------- | ----------------------------------------------- |
@@ -358,35 +323,16 @@ xAI 集成**不使用**注册给 CC Switch 的 OAuth 应用,而是复用 xAI
## 关于页面
设置 → 关于 Tab
设置 → 关于
### 版本信息
显示当前 CC Switch 版本号,支持:
- 查看发布说明
- 检查更新
- 下载并安装新版本
- 检查更新,有新版本时点「更新到 vX」下载并安装(便携版需手动下载)
- 查看 GitHub、官方网站、更新日志
- 「近期更新」:重新查看最近几个版本的更新摘要
### 本地环境检查
### 工具的安装与升级
自动检测已安装的 CLI 工具版本:
| 工具 | 检测内容 |
| ----------- | ------------------ |
| Claude Code | 当前版本、最新版本 |
| Codex | 当前版本、最新版本 |
| Gemini CLI | 当前版本、最新版本 |
| Grok Build | 当前版本、最新版本 |
| OpenCode | 当前版本、最新版本 |
| OpenClaw | 当前版本、最新版本 |
| Hermes | 当前版本、最新版本 |
| Pi | 当前版本、最新版本 |
点击「刷新」按钮可重新检测;检测到新版时可单独升级,也可以点击「全部升级」。未检测到的工具会显示安装按钮。安装与升级在后台静默执行,按钮上会显示进度,完成后自动刷新版本。已安装但当前环境无法运行(例如 Node.js 版本不够)的工具会标为「已安装·无法运行」。
在 Windows 上,如果在「配置文件目录」里把某个工具的目录设为 WSL 路径,「关于」页会在对应的 WSL 发行版里检测和升级该工具。
### 手动安装命令
该区域默认折叠,点击标题展开,可以一键复制所有工具的安装命令:Claude Code、OpenCode、Hermes 使用官方安装脚本(Claude Code 和 OpenCode 失败时回退到 npm),其余工具使用 npm 安装。Windows 上 Hermes 使用 PowerShell 安装脚本,其余工具使用 npm。各工具的安装命令也可参考 [1.2 安装指南](./1.2-installation.md#可选安装要管理的工具)。
各 AI 编程工具的版本检测、安装、升级和「全部升级」不在这里,而在左侧栏的「应用」页,详见 [1.2 安装指南](./1.2-installation.md#可选安装要管理的工具)。在 Windows 上,如果在「应用配置」里把某个工具的目录设为 WSL 路径,「应用」页会在对应的 WSL 发行版里检测和升级该工具。
+91 -183
View File
@@ -1,61 +1,61 @@
# 2.1 添加供应商
## 打开添加面板
## 打开添加页
点击主界面右上角的 **+** 按钮,打开添加供应商面板。
先在侧栏选中要添加的应用,再点击页头右侧的 **添加供应商** 按钮(带 + 号)。应用页顶部有「直连 / 路由 / 聚合」标签时,添加页会按你当前看的那一格打开:在「聚合」标签下添加,页头会标上「(聚合模式)」,表单用简化的聚合布局(Claude Code 和 Codex 才有)。
面板分为两个 Tab:
- **应用专属供应商**:仅用于当前选中的应用
- **统一供应商**:跨应用共享的配置
添加页是整页界面,盖在内容区上,分两步:
1. **选预设**:挑一个预设,或选「自定义配置」
2. **填写**:表单最上面只剩一条预设条,点右侧「更换」可以回到第 1 步;顶部的返回按钮在第 2 步显示「返回选择预设」,第 1 步是「返回供应商列表」
第 2 步里只要动过表单(输入文字、勾选开关、换选项),这时通过侧栏、托盘或设置离开当前页,会先弹出「有未保存的修改」确认:「放弃修改并离开」或「继续编辑」。点页脚的「取消」则直接关闭添加页。
## 使用预设添加
预设是预先配置好的供应商模板,只需填写 API Key 即可使用。
预设是预先配置好的供应商模板,通常只需填写 API Key 即可使用。
### 选择预设
第 1 步的布局:
- **搜索框**:常驻在顶部,打开就能直接输入,可以搜名称、网址或常见叫法(例如 kimi、智谱、openrouter);⌘F / Ctrl+F 可回到搜索框
- **左侧分类**:「全部」「账号登录」「模型厂商」「第三方平台」「云服务商」,OpenCode 另有「插件配置」;分类按预设自身的属性自动归类,每项后面带匹配数量
- **右侧两列列表**:所有预设按显示名排序(中文名按拼音排进字母序),没有置顶,也没有星标;「自定义配置」固定在「全部」的最上面
各分类大致装的是:
| 分类 | 内容 |
|------|------|
| 账号登录 | 不用 API Key,用已有账号登录,如 Claude 官方、ChatGPT(Codex)、GitHub Copilot、xAI、Google 官方。除 Claude 以外都要经过路由 |
| 模型厂商 | 厂商自己的 API 和编程套餐。同一家的国内站、海外站、不同套餐会合成一行,选中后在下一步用「套餐」「地区」「版本」切换 |
| 第三方平台 | 聚合多家模型的平台,或转售官方模型的中转服务 |
| 云服务商 | 用云厂商账号调用模型,如 AWS Bedrock |
| 插件配置 | OpenCode 插件的模型分配配置 |
某些预设后面带「需要路由」徽章,表示上游协议和客户端不一致,要开启[本地路由](../4-proxy/4.1-service.md)才能用。
在同一家的多个版本之间切换时,如果已经填过内容,会提示「表单会按新版本重新填写,已填的 API Key 和其他修改会清空」,确认后才切换。
### 操作步骤
1. 在「预设」下拉框中选择供应商
1. 在搜索框或左侧分类里找到供应商,点击它
2. 名称和端点会自动填充
3. 填写你的 **API Key**
4. (可选)填写备注
5. 点击「添加」
5. 点击页脚的「添加」
### 常用预设
找不到想要的厂商时,搜索无结果的提示里有「用自定义配置添加」按钮,手动填写请求地址和 API Key 即可。
> 预设列表随版本更新,以应用内实际显示为准。下面只说各应用预设的共同特点和需要注意的地方。
#### Claude 预设
| 预设名称 | 说明 |
|----------|------|
| Claude 官方 | 使用 Anthropic 官方账号登录 |
| DeepSeek | DeepSeek 模型 |
| 智谱 GLM | 智谱 AI 的 GLM 模型 |
| 智谱 GLM en | 智谱 AI(英文版) |
| 百炼 | 阿里云百炼(通义千问) |
| Kimi | Moonshot Kimi 模型 |
| Kimi For Coding | Kimi 编程专用模型 |
| StepFun | 阶跃星辰 Step模型 |
| ModelScope | 魔搭社区 |
| KAT-Coder | KAT-Coder 模型 |
| Longcat | Longcat AI |
| MiniMax | MiniMax 模型 |
| MiniMax en | MiniMax(英文版) |
| 火山 豆包AI | 豆包 Seed 模型 |
| BaiLing | 百灵 AI |
| AiHubMix | AiHubMix 聚合服务 |
| SiliconFlow | 硅基流动 |
| SiliconFlow en | 硅基流动(英文版) |
| DMXAPI | DMXAPI 中转服务 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| RightCode | RightCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| OpenRouter | 聚合路由服务 |
| Nvidia | Nvidia AI 服务 |
| Xiaomi MiMo | 小米 MiMo 模型 |
| Command Code | Command Code 聚合服务 |
Claude Code 的预设最全,涵盖厂商官方、编程套餐、聚合和中转平台。其中:
> 预设选择器中带 ⭐ 的是合作伙伴预设。预设列表可能随版本更新,以应用内实际显示为准。
- **Claude 官方**:使用 Anthropic 官方账号登录,在「账号登录」分类
- **GitHub Copilot / Codex(ChatGPT 账号)/ xAI (Grok)**:同样在「账号登录」,需要先在授权中心登录对应账号,见下文「Codex OAuth 反向代理」
- 其余预设填 API Key 即可;预设里已写好的上游格式、模型映射不用手动改
#### Claude Desktop 预设
@@ -78,103 +78,15 @@ Codex 供应商要按**所选端点的协议**配置:
> **旧卡不会自动升级**:供应商保存的是创建时的预设快照。DeepSeek、GLM(v3.20.2)和 Kimi(v3.20.3)等预设已陆续改为原生 Responses,要让旧卡片直连,建议重新添加最新版预设;手动迁移时,把「上游格式」改为 Responses,并确认请求地址和模型映射与厂商的 Responses 端点匹配。详见 [v3.20.3 更新说明](../../../release-notes/v3.20.3-zh.md)。
其他常见 Codex 预设包括:
| 预设名称 | 说明 |
|----------|------|
| OpenAI 官方 | 使用 OpenAI 官方账号登录 |
| Azure OpenAI | Azure OpenAI 服务 |
| AiHubMix | AiHubMix 聚合服务 |
| DMXAPI | DMXAPI 中转服务 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| RightCode | RightCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| OpenRouter | 聚合路由服务 |
> 💡 预设列表持续更新,以应用内实际显示为准。上游格式、模型映射和思考能力的说明见下文「Codex / Grok Build 的上游格式与模型映射」。
#### Gemini 预设
| 预设名称 | 说明 |
|----------|------|
| Google 官方 | 使用 Google OAuth 登录 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| OpenRouter | 聚合路由服务 |
| 自定义 | 手动配置所有参数 |
Gemini CLI 的预设包括「Google 官方」(用 Google 账号登录,不需要 API Key)和多家中转、聚合服务。需要手动配置所有参数时选「自定义配置」。
#### OpenCode 预设
#### OpenCode / OpenClaw 预设
| 预设名称 | 说明 |
|----------|------|
| DeepSeek | DeepSeek 模型 |
| 智谱 GLM | 智谱 AI 的 GLM 模型 |
| 智谱 GLM en | 智谱 AI(英文版) |
| 百炼 | 阿里云百炼 |
| Kimi k2.5 | Moonshot Kimi-k2.5 模型 |
| Kimi For Coding | Kimi 编程专用模型 |
| StepFun | 阶跃星辰 Step模型 |
| ModelScope | 魔搭社区 |
| KAT-Coder | KAT-Coder 模型 |
| Longcat | Longcat AI |
| MiniMax | MiniMax 模型 |
| MiniMax en | MiniMax(英文版) |
| 火山 豆包AI | 豆包 Seed 模型 |
| BaiLing | 百灵 AI |
| Xiaomi MiMo | 小米 MiMo 模型 |
| AiHubMix | AiHubMix 聚合服务 |
| DMXAPI | DMXAPI 中转服务 |
| OpenRouter | 聚合路由服务 |
| Nvidia | Nvidia AI 服务 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| RightCode | RightCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| OpenAI Compatible | OpenAI 兼容接口 |
| Oh My OpenCode | Oh My OpenCode 服务 |
> 💡 预设列表持续更新中,以应用内实际显示为准。
#### OpenClaw 预设
| 预设名称 | 说明 |
|----------|------|
| DeepSeek | DeepSeek 模型 |
| 智谱 GLM | 智谱 AI 的 GLM 模型 |
| 智谱 GLM en | 智谱 AI(英文版) |
| Qwen Coder | 通义千问编码模型 |
| Kimi k2.5 | Moonshot Kimi-k2.5 模型 |
| Kimi For Coding | Kimi 编程专用模型 |
| StepFun | 阶跃星辰 Step模型 |
| MiniMax | MiniMax 模型 |
| MiniMax en | MiniMax(英文版) |
| KAT-Coder | KAT-Coder 模型 |
| Longcat | Longcat AI |
| 火山 豆包AI | 豆包 Seed 模型 |
| BaiLing | 百灵 AI |
| Xiaomi MiMo | 小米 MiMo 模型 |
| AiHubMix | AiHubMix 聚合服务 |
| DMXAPI | DMXAPI 中转服务 |
| OpenRouter | 聚合路由服务 |
| ModelScope | 魔搭社区 |
| SiliconFlow | 硅基流动 |
| SiliconFlow en | 硅基流动(英文版) |
| Nvidia | Nvidia AI 服务 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| RightCode | RightCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| AICoding | AICoding 服务 |
| CrazyRouter | CrazyRouter 服务 |
| SSSAiCode | SSSAiCode 服务 |
| AWS Bedrock | AWS Bedrock 服务 |
| OpenAI Compatible | OpenAI 兼容接口 |
OpenCode 和 OpenClaw 是累加式应用:点击「添加」会把供应商写进各自的配置文件,多个供应商可以同时存在。预设覆盖主流模型厂商、聚合平台和中转服务,另有「OpenAI Compatible」预设用于任意 OpenAI 兼容接口;OpenCode 还有 Oh My OpenCode 的「插件配置」分类。
#### Grok Build 预设
@@ -190,14 +102,14 @@ Pi 预设覆盖 Kimi、火山方舟等官方平台和多家中转服务。点击
#### MiniMax Code 预设
MiniMax Code 的预设由 Pi 预设目录派生(v3.20.4 共 41 个),只保留使用 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 三种接口、且不需要 Pi 专用兼容选项的预设。点击「添加」会把供应商写入 `~/.minimax/config.yaml` 的 `custom_provider`,之后在 MiniMax Code 里选择模型。CC Switch 只管理自定义供应商,MiniMax 官方账号由 MiniMax Code 自己管理。
MiniMax Code 的预设由 Pi 预设目录派生,只保留使用 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 三种接口、且不需要 Pi 专用兼容选项的预设。点击「添加」会把供应商写入 `~/.minimax/config.yaml` 的 `custom_provider`,之后在 MiniMax Code 里选择模型。CC Switch 只管理自定义供应商,MiniMax 官方账号由 MiniMax Code 自己管理。
## 自动获取模型
添加或编辑供应商时,可以自动从供应商端点发现可用模型列表,免去手动复制粘贴模型 ID 的繁琐流程。
1. 确保已填写 **API Key** 和 **端点地址**
2. 点击模型输入框旁的 **获取模型** 按钮(下载图标)
2. 点击模型输入框旁的 **获取模型列表** 按钮(下载图标)
3. CC Switch 使用配置的 API Key 调用 OpenAI 兼容的 `/v1/models` 端点
4. 从按类别分组的下拉菜单中选择模型
@@ -300,14 +212,17 @@ requires_openai_auth = true
### 创建统一供应商
1. 切换到「统一供应商」Tab
2. 点击「添加统一供应商」
3. 填写通用配置:
统一供应商只在 Claude Code、Codex、Gemini CLI 的添加页里出现,在选预设那一步的左侧分类最下面,「跨应用」下的「统一供应商」:
1. 点击「统一供应商」分类,选一个预设类型
2. 在弹出的表单里填写通用配置:
- 名称
- API Key
- 端点地址
4. 勾选要同步的应用(Claude Code / Codex / Gemini)
5. 保存
- API 地址
3. 勾选要同步的应用(Claude Code / Codex / Gemini)
4. 保存
已有的统一供应商,在这个分类里点「管理已有的统一供应商 ›」查看、编辑、复制、删除。
### 同步机制
@@ -329,7 +244,7 @@ requires_openai_auth = true
如果需要手动触发同步:
1. 在统一供应商卡片上点击「同步」按钮
1. 在「管理已有的统一供应商」里,点统一供应商卡片上的「同步」按钮
2. 确认同步操作
3. 配置会覆盖各应用中关联的供应商
@@ -354,8 +269,8 @@ CC Switch 支持两种方式导入供应商配置:
从 SQL 备份文件批量导入:
1. 打开「设置 → 高级 → 数据管理」
2. 点击「选择文件」
1. 打开「设置 → 数据」,找到「数据管理」里的「SQL 导入导出」
2. 点击「选择 SQL 文件」
3. 选择之前导出的 `.sql` 备份文件
4. 点击「导入」
5. 确认覆盖现有配置
@@ -370,7 +285,7 @@ CC Switch 支持两种方式导入供应商配置:
## Codex OAuth 反向代理(Claude 供应商)
v3.13.0 起,CC Switch 新增了 **Codex OAuth 反向代理**路径,让你可以**用 ChatGPT 账号**在 Claude Code 中复用 Codex 服务。
CC Switch 提供 **Codex OAuth 反向代理**路径,让你可以**用 ChatGPT 账号**在 Claude Code 中复用 Codex 服务。
> 💡 **位置提示**:这项功能作为一个**新的 Claude 供应商卡片类型**出现,而不是 Codex 侧的预设。添加后会和普通 API-Key 型供应商并列在 Claude 的供应商列表中。
@@ -384,21 +299,21 @@ v3.13.0 起,CC Switch 新增了 **Codex OAuth 反向代理**路径,让你可
你可以从下面任意一个入口开始:
#### 入口 A:从添加供应商面板开始(推荐新用户)
#### 入口 A:从添加供应商页开始(推荐新用户)
1. 切换到 **Claude** 应用
2. 点击右上角的 **+** 按钮打开添加供应商面板
3. 在预设列表的第三方分类下选择 **Codex** 预设(以 UI 中显示的名称为准)
4. 如果尚未登录 ChatGPT 账号,面板会**自动引导**你进入登录流程(见下文"登录流程")
5. 登录成功后,供应商表单会显示已登录的账号,点击「保存」完成添加
2. 点击页头的 **添加供应商**
3. 在「账号登录」分类里选择 **Codex**(用 ChatGPT 账号登录)预设(以应用内显示的名称为准)
4. 如果尚未登录 ChatGPT 账号,表单里会引导你进入登录流程(见下文"登录流程")
5. 登录成功后,表单会显示已登录的账号,点击「添加」完成
#### 入口 B:从 OAuth 认证中心开始(适合多账号管理)
#### 入口 B:从授权中心开始(适合多账号管理)
1. 打开 **设置 → 认证**(OAuth 认证中心,顶部带 **Beta** 标记)
2. 在 **ChatGPT (Codex OAuth)** 区块点击 **使用 ChatGPT 登录** 按钮
1. 点击侧栏的 **授权中心**
2. 在 **ChatGPT** 区块点击 **添加账号**
3. 完成登录流程(见下文)
4. 登录完成后,回到 **Claude** 应用 → **添加供应商** → 选择同一个 Codex 预设
5. 在表单中的「选择账号」下拉框选择刚登录的账号,保存即可
5. 在表单中的「选择账号」下拉框选择刚登录的账号,添加即可
### 登录流程(Device Code)
@@ -414,16 +329,16 @@ v3.13.0 起,CC Switch 新增了 **Codex OAuth 反向代理**路径,让你可
- 输入上一步复制的验证码
- 确认授权
3. **自动轮询完成**:CC Switch 会在后台持续轮询 OpenAI 服务器,检测到授权成功后自动关闭等待界面
4. **显示已登录账号**:登录的 ChatGPT 账号会出现在 **OAuth 认证中心 → 已登录账号**列表中,显示登录邮箱
4. **显示已登录账号**:登录的 ChatGPT 账号会出现在 **授权中心** 的 ChatGPT 区块里,显示登录账号
> ⏱️ **验证码有效期约 15 分钟**。如果超时,界面会显示"Device Code 已过期",点击「重试」即可重新获取验证码。
> ⏱️ **验证码有效期约 15 分钟**。如果超时,界面会提示授权没有完成,重新发起一次登录即可获取新的验证码。
### 启用与使用
添加并保存 Codex OAuth 供应商后:
1. 确认已开启[本地路由](../4-proxy/4.1-service.md)并为 Claude 启用路由(卡片上会显示「需要路由」徽章)
2. 在 Claude 供应商列表中找到它,点击卡片的 **启用** 按钮 — 和普通供应商完全一致
1. 卡片上会显示「需要路由」徽章:先在应用页顶部切到「路由」标签,点「开始路由」(详见[本地路由](../4-proxy/4.1-service.md))
2. 在 Claude 供应商列表中找到它,点击卡片上的「路由到此」— 其余操作和普通供应商一致
3. Claude Code CLI 即可通过反向代理使用 ChatGPT 订阅
4. 托盘菜单的 **Claude** 子菜单中也会出现这个供应商,支持快速切换
@@ -442,21 +357,22 @@ Codex OAuth 预设的默认模型映射:
预设还会把 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 和 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设为 `372000`,与 ChatGPT Codex 后端的上下文窗口一致。
v3.15.0 起,Codex OAuth 模型选择不再只依赖硬编码列表。打开模型选择时,CC Switch 会按需从 ChatGPT Codex 后端拉取可用模型,默认映射仍可按需覆盖。
Codex OAuth 的模型选择不只依赖内置列表。打开模型选择时,CC Switch 会按需从 ChatGPT Codex 后端拉取可用模型,默认映射仍可按需覆盖。
你可以在供应商的 JSON 编辑器中覆盖 `ANTHROPIC_MODEL` 等环境变量来自定义。
### 多账号管理(OAuth 认证中心)
### 多账号管理(授权中心)
**OAuth 认证中心**支持同时管理多个 ChatGPT 账号:
**授权中心**可以同时管理多个 ChatGPT 账号(GitHub Copilot、xAI 账号也在这里):
| 操作 | 说明 |
| ---------------- | ---------------------------------------------------- |
| 添加其他账号 | 点击「添加其他账号」重复登录流程 |
| 设为默认 | 在账号行点击「设为默认」—— 新建供应商默认使用该账号 |
| 添加其他账号 | 点击「添加账号」重复登录流程 |
| 设为默认 | 在账号行的更多操作里选「设为默认」—— 没指定账号的供应商用默认账号 |
| 为供应商选账号 | 供应商表单中通过「选择账号」下拉框指定特定账号 |
| 移除账号 | 点击账号右侧的红色 × 移除(Token 被清除) |
| 注销所有账号 | 底部「注销所有账号」按钮一键清除 |
| 重新登录 | 账号显示「需要重新登录」时,在更多操作里选「重新登录」 |
| 移除账号 | 在账号行的更多操作里选「删除账号」(Token 被清除) |
| 移除全部账号 | 在区块的更多操作里选「删除全部账号」 |
> 💡 **使用场景**:如果你和团队共享一台开发机,可以为每个成员的 ChatGPT 账号各建一个供应商,通过托盘菜单快速切换。
@@ -466,28 +382,22 @@ v3.15.0 起,Codex OAuth 模型选择不再只依赖硬编码列表。打开模
- Refresh Token 存储在本地数据目录,不会上传到任何地方
- **不支持**导出 Token(防止泄露)
### 配额展示
### 额度展示
登录并启用供应商后,**供应商卡片底部**会自动显示账号配额:
登录后,**授权中心**的账号行右侧会显示这个账号的额度条(按「剩余」画)和「x 分钟前」的更新时间,点刷新图标可手动重新查询。
| 显示元素 | 示例 | 颜色规则 |
| ------------ | ------------------ | ------------------------------------------- |
| 使用百分比 | `45%` | < 70% 绿色,70–89% 橙色,≥ 90% 红色 |
| 重置倒计时 | `7d12h 后重置` | ChatGPT 账号的滑动窗口或每日限额 |
| 刷新按钮 | 圆形箭头 | 手动重新查询配额 |
> ⚠️ **会话已过期**:如果 Token 完全失效(无法自动刷新),卡片底部会显示黄色警告框「会话已过期」。此时请到 **设置 → 认证**移除该账号并重新登录。
> ⚠️ **需要重新登录**:如果 Token 完全失效(无法自动刷新),账号行会标出「需要重新登录」。到 **授权中心** 对该账号选「重新登录」,或删除后重新添加。
### 常见失败
| 场景 | 表现 | 解决方法 |
| -------------------- | ------------------------------- | --------------------------------------- |
| 验证码超时 | 显示"Device Code 已过期" | 点击「重试」重新获取验证码 |
| 浏览器拒绝授权 | 显示"用户拒绝授权" | 重新登录,在浏览器中点击"授权" |
| 验证码超时 | 提示登录没有完成 | 重新发起登录,获取新的验证码 |
| 浏览器拒绝授权 | 提示登录没有完成 | 重新登录,在浏览器中点击"授权" |
| 网络错误 | 显示具体错误信息 | 检查网络连接,确认能访问 OpenAI 域名 |
| 创建供应商前未登录 | "请先登录 ChatGPT 账号"提示 | 先到 设置 → 认证 完成登录 |
| Token 失效无法刷新 | 配额框显示"会话已过期" | 移除账号后重新登录 |
| 配额查询失败 | 配额框显示"查询失败" | 点击「刷新」按钮重试 |
| 添加供应商前未登录 | "请先登录 ChatGPT 账号"提示 | 先到 授权中心 完成登录 |
| Token 失效无法刷新 | 账号行显示"需要重新登录" | 对该账号重新登录 |
| 额度查询失败 | 账号行显示"额度没查到" | 点击刷新图标重试 |
### ⚠️ 风险提示(重要)
@@ -520,7 +430,7 @@ Codex OAuth 反向代理通过**逆向工程的 OAuth 流程**访问 ChatGPT 账
### 完整 URL 端点模式
v3.13.0 起新增的高级选项。默认情况下,CC Switch 会把配置的 `base_url` 视作**前缀**,再在其后拼接 `/v1/chat/completions` 等固定路径。对于部分厂商(如需要非标准 URL 布局的第三方服务),这种拼接方式会导致请求失败。
默认情况下,CC Switch 会把配置的 `base_url` 视作**前缀**,再在其后拼接 `/v1/chat/completions` 等固定路径。对于部分厂商(如需要非标准 URL 布局的第三方服务),这种拼接方式会导致请求失败。
**启用方式**:
@@ -578,8 +488,6 @@ Codex 原生使用 OpenAI Responses API。Grok Build 与 Codex 共用同一套 R
选择后两种时,必须开启[本地路由服务](../4-proxy/4.1-service.md)并为对应应用启用路由,使用过程中需保持本地路由开启。选择预设时上游格式已自动设置,无需手动调整。
> 💡 v3.16.5 之前,这里是一个「需要本地路由映射」开关,现已由「上游格式」取代;模型映射也不再依赖该开关。
#### 模型映射(仅 Codex)
Codex 非官方供应商的表单里都有 **模型映射** 表,用于声明该供应商可用的模型:
@@ -618,7 +526,7 @@ Codex 非官方供应商的表单里都有 **模型映射** 表,用于声明
- **启用时**:在 config.toml 中设置 `model_context_window = 1000000` 并自动填充 `model_auto_compact_token_limit = 900000`
- **禁用时**:移除这两个字段
开关开启后显示的文本框可自定义自动压缩限制值。v3.15.0 起,该开关仅在新增 Codex 供应商时显示;编辑已有供应商时可通过高级配置直接调整相关字段。
开关开启后显示的文本框可自定义自动压缩限制值。该开关仅在新增 Codex 供应商时显示;编辑已有供应商时可通过高级配置直接调整相关字段。
### 自定义图标
@@ -631,7 +539,7 @@ Codex 非官方供应商的表单里都有 **模型映射** 表,用于声明
填写供应商的官网或控制台地址,方便快速访问:
- 点击供应商卡片的链接图标可直接打开
- 在供应商卡片上可直接打开
- 用于查看余额、获取 API Key 等
### 备注
@@ -659,4 +567,4 @@ Codex 非官方供应商的表单里都有 **模型映射** 表,用于声明
- 🟠 橙色:延迟 500–800ms
- 🔴 红色:延迟 ≥ 800ms
![image-20260108005327817](../../assets/image-20260108005327817.png)
<!-- TODO(v4 截图): 编辑供应商里点「管理与测速」后的端点测速面板(含多个端点与延迟结果) -->

Some files were not shown because too many files have changed in this diff Show More