lywsvip/cc-switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-05-07 06:07:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure user manual for i18n and add EN/JA translations

Browse Source 
Reorganize docs/user-manual/ from flat structure to language subdirectories
(zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/,
fix image paths, add multilingual navigation README, and translate all 23
markdown files (~4500 lines each) to English and Japanese.
This commit is contained in:
Jason
2026-03-03 08:40:52 +08:00
parent ce9c23833a
commit bbed2a1fe1
70 changed files with 8916 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/user-manual/README.md
View File

@@ -1,111 +1,22 @@
# CC Switch 用户手册
# CC Switch User Manual / 用户手册 / ユーザーマニュアル
> Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw 全方位辅助工具
> Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw
## 目录结构
## Language / 语言 / 言語
```
📚 CC Switch 用户手册
│
├── 1. 快速入门
│ ├── 1.1 软件介绍
│ ├── 1.2 安装指南
│ ├── 1.3 界面概览
│ ├── 1.4 快速上手
│ └── 1.5 个性化配置
│
├── 2. 供应商管理
│ ├── 2.1 添加供应商
│ ├── 2.2 切换供应商
│ ├── 2.3 编辑供应商
│ ├── 2.4 排序与复制
│ └── 2.5 用量查询
│
├── 3. 扩展功能
│ ├── 3.1 MCP 服务器管理
│ ├── 3.2 Prompts 提示词管理
│ └── 3.3 Skills 技能管理
│
├── 4. 代理与高可用
│ ├── 4.1 代理服务
│ ├── 4.2 应用接管
│ ├── 4.3 故障转移
│ ├── 4.4 用量统计
│ └── 4.5 模型检查
│
└── 5. 常见问题
├── 5.1 配置文件说明
├── 5.2 FAQ
├── 5.3 深度链接协议
└── 5.4 环境变量冲突
```
| Language | Link |
|----------|------|
| [中文](./zh/README.md) | 简体中文用户手册 |
| [English](./en/README.md) | English User Manual |
| [日本語](./ja/README.md) | 日本語ユーザーマニュアル |
## 文件列表
## Version / 版本 / バージョン
### 1. 快速入门
- Documentation version: v3.11.1
- Last updated: 2026-03-02
- Compatible with CC Switch v3.11.1+
| 文件 | 内容 |
|------|------|
| [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.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5 分钟快速上手教程 |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 语言、主题、目录、云同步配置 |
### 2. 供应商管理
| 文件 | 内容 |
|------|------|
| [2.1-add.md](./2-providers/2.1-add.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) | 用量查询、剩余额度、多套餐显示 |
### 3. 扩展功能
| 文件 | 内容 |
|------|------|
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP 协议、添加服务器、应用绑定 |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | 创建预设、激活切换、智能回填 |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | 发现技能、安装卸载、仓库管理 |
### 4. 代理与高可用
| 文件 | 内容 |
|------|------|
| [4.1-service.md](./4-proxy/4.1-service.md) | 启动代理、配置项、运行状态 |
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | 应用接管、配置修改、状态指示 |
| [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) | 模型检查、健康检测、延迟测试 |
### 5. 常见问题
| 文件 | 内容 |
|------|------|
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch 存储、CLI 配置文件格式 |
| [5.2-questions.md](./5-faq/5.2-questions.md) | 常见问题解答 |
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | 深度链接协议、生成和使用方法 |
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | 环境变量冲突检测与处理 |
## 快速链接
- **新用户**：从 [1.1 软件介绍](./1-getting-started/1.1-introduction.md) 开始
- **安装问题**：查看 [1.2 安装指南](./1-getting-started/1.2-installation.md)
- **配置供应商**：查看 [2.1 添加供应商](./2-providers/2.1-add.md)
- **使用代理**：查看 [4.1 代理服务](./4-proxy/4.1-service.md)
- **遇到问题**：查看 [5.2 FAQ](./5-faq/5.2-questions.md)
## 版本信息
- 文档版本：v3.11.1
- 最后更新：2026-02-28
- 适用于 CC Switch v3.11.1+
## 贡献
欢迎提交 Issue 或 PR 改进文档：
## Links
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
- [GitHub Repository](https://github.com/farion1231/cc-switch)

65
docs/user-manual/en/1-getting-started/1.1-introduction.md Normal file
View File

@@ -0,0 +1,65 @@
# 1.1 Introduction
## What is CC Switch
CC Switch is a cross-platform desktop application designed for developers who use AI coding tools. It helps you centrally manage configurations for five major AI coding tools: **Claude Code**, **Codex**, **Gemini CLI**, **OpenCode**, and **OpenClaw**.
## What Problems Does It Solve
In your daily development workflow, you may encounter these pain points:
- **Tedious multi-provider switching**: Using different API providers (official, proxy services) requires manually editing configuration files
- **Scattered configurations**: Claude, Codex, Gemini, OpenCode, and OpenClaw each have independent configuration files in different formats
- **No usage monitoring**: No visibility into how many API calls were made or how much they cost
- **Service instability**: When a single provider goes down, your entire workflow is interrupted
CC Switch solves these problems through a unified interface.
## Core Features
### Provider Management
- One-click switching between multiple API provider configurations
- Preset templates for quickly adding common providers
- Universal provider feature for sharing configurations across apps
- Usage query and balance display
- Endpoint speed testing
### Extensions
- **MCP Servers**: Manage Model Context Protocol servers to extend AI capabilities
- **Prompts**: Manage system prompt presets for quick scenario switching
- **Skills**: Install and manage skill extensions
### Proxy & High Availability
- Local proxy service for request logging and usage statistics
- Automatic failover that switches to a backup provider when the primary one fails
- Circuit breaker mechanism to prevent repeated retries against failing providers
- Detailed token usage tracking and cost estimation
## Supported Applications
| Application | Description |
|-------------|-------------|
| **Claude Code** | Anthropic's official AI coding assistant |
| **Codex** | OpenAI's code generation tool |
| **Gemini CLI** | Google's AI command-line tool |
| **OpenCode** | Open-source AI coding terminal tool |
| **OpenClaw** | Open-source AI coding assistant (multi-provider gateway) |
## Supported Platforms
- **Windows** 10 and above
- **macOS** 10.15 (Catalina) and above
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+
## Technical Architecture
CC Switch is built with a modern technology stack:
- **Frontend**: React 18 + TypeScript + Tailwind CSS
- **Backend**: Tauri 2 + Rust
- **Data Storage**: SQLite (providers, MCP, Prompts) + JSON (device settings)
This architecture ensures:
- Consistent cross-platform experience
- Native-level performance
- Secure local data storage

229
docs/user-manual/en/1-getting-started/1.2-installation.md Normal file
View File

@@ -0,0 +1,229 @@
# 1.2 Installation Guide
## Prerequisites
### Install Node.js
The CLI tools managed by CC Switch (Claude Code, Codex, Gemini CLI) require a Node.js environment.
**Recommended version**: Node.js 18 LTS or higher
#### Windows
1. Visit the [Node.js official website](https://nodejs.org/)
2. Download the LTS version installer
3. Run the installer and follow the prompts
4. Verify installation:
```bash
node --version
npm --version
```
#### macOS
```bash
# Install with Homebrew
brew install node
# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
```
#### Linux
```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
# Or use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
```
### Install CLI Tools
#### Claude Code
**Option 1: Homebrew (recommended for macOS)**
```bash
brew install claude-code
```
**Option 2: npm**
```bash
npm install -g @anthropic-ai/claude-code
```
#### Codex
**Option 1: Homebrew (recommended for macOS)**
```bash
brew install codex
```
**Option 2: npm**
```bash
npm install -g @openai/codex
```
#### Gemini CLI
**Option 1: Homebrew (recommended for macOS)**
```bash
brew install gemini-cli
```
**Option 2: npm**
```bash
npm install -g @google/gemini-cli
```
---
## Windows
### Installer
1. Visit the [Releases page](https://github.com/farion1231/cc-switch/releases)
2. Download `CC-Switch-v{version}-Windows.msi`
3. Double-click to run the installer
4. Follow the prompts to complete installation
### Portable Version (No Installation Required)
1. Download `CC-Switch-v{version}-Windows-Portable.zip`
2. Extract to any directory
3. Run `CC-Switch.exe`
## macOS
### Option 1: Homebrew (Recommended)
```bash
# Add tap
brew tap farion1231/ccswitch
# Install
brew install --cask cc-switch
```
Update to the latest version:
```bash
brew upgrade --cask cc-switch
```
### Option 2: Manual Download
1. Download `CC-Switch-v{version}-macOS.zip`
2. Extract to get `CC Switch.app`
3. Drag it to the Applications folder
### First Launch Warning
Since the developer does not have an Apple Developer account, a "developer cannot be verified" warning may appear on first launch:
**Recommended solution**:
Open Terminal and run the following command:
```bash
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
```
**Alternative solution (via System Settings)**:
1. Close the warning dialog
2. Open "System Settings" > "Privacy & Security"
3. Find the CC Switch prompt and click "Open Anyway"
4. Reopen the app to use it normally
## Linux
### ArchLinux
Install using an AUR helper:
```bash
# Using paru
paru -S cc-switch-bin
# Or using yay
yay -S cc-switch-bin
```
### Debian / Ubuntu
1. Download `CC-Switch-v{version}-Linux.deb`
2. Install:
```bash
sudo dpkg -i CC-Switch-v{version}-Linux.deb
# If there are dependency issues
sudo apt-get install -f
```
### AppImage (Universal)
1. Download `CC-Switch-v{version}-Linux.AppImage`
2. Add execute permission:
```bash
chmod +x CC-Switch-v{version}-Linux.AppImage
```
3. Run:
```bash
./CC-Switch-v{version}-Linux.AppImage
```
## Verify Installation
After installation, launch CC Switch:
1. The app window displays correctly
2. A CC Switch icon appears in the system tray
3. You can switch between Claude / Codex / Gemini apps
## Auto Update
CC Switch includes built-in auto-update functionality:
- Automatically checks for updates on startup
- Displays an update prompt in the UI when a new version is available
- Click to download and install
You can also manually check for updates in "Settings > About".
## Uninstall
### Windows
- Uninstall via "Settings > Apps"
- Or run the uninstaller in the installation directory
### macOS
- Move `CC Switch.app` to Trash
- Optional: Delete the configuration directory `~/.cc-switch/`
### Linux
```bash
# Debian/Ubuntu
sudo apt remove cc-switch
# ArchLinux
paru -R cc-switch-bin
```

170
docs/user-manual/en/1-getting-started/1.3-interface.md Normal file
View File

@@ -0,0 +1,170 @@
# 1.3 Interface Overview
## Main Interface Layout
![image-20260108001629138](../../assets/image-20260108001629138.png)
## Top Navigation Bar
| # | Element | Description |
|---|---------|-------------|
| 1 | Logo | Click to visit the GitHub project page |
| 2 | Settings Button | Open the settings page (shortcut `Cmd/Ctrl + ,`) |
| 3 | Proxy Toggle | Start/stop the local proxy service |
| 4 | App Switcher | Switch between Claude / Codex / Gemini / OpenCode / OpenClaw |
| 5 | Feature Area | Skills / Prompts / MCP entry points |
| 6 | Add Button | Add a new provider |
### App Switcher
Click the dropdown menu to switch the currently managed application:
- **Claude** - Manage Claude Code configuration
- **Codex** - Manage Codex configuration
- **Gemini** - Manage Gemini CLI configuration
- **OpenCode** - Manage OpenCode configuration
- **OpenClaw** - Manage OpenClaw configuration
After switching, the provider list displays the configurations for the selected application.
### Feature Area Buttons
| Button | Function | Visibility |
|--------|----------|------------|
| Skills | Skill extension management | Always visible |
| Prompts | System prompt management | Always visible |
| MCP | MCP server management | Always visible |
## Provider Cards
Each provider is displayed as a card, containing the following elements from left to right:
### Card Elements (Left to Right)
| # | Element | Icon | Description |
|---|---------|------|-------------|
| 1 | Drag Handle | ≡ | Hold and drag up/down to reorder providers |
| 2 | Provider Icon | - | Displays provider brand icon with customizable color |
| 3 | Provider Info | - | Name, notes/endpoint URL (clickable to open website) |
| 4 | Usage Info | - | Shows remaining balance; displays plan count for multi-plan |
| 5 | Enable Button | - | Switch to this provider |
| 6 | Edit Button | - | Edit provider configuration |
| 7 | Duplicate Button | - | Duplicate provider (create a copy) |
| 8 | Speed Test Button | - | Test model availability and response speed |
| 9 | Usage Query | - | Configure usage query script |
| 10 | Delete Button | - | Delete provider (disabled when currently active) |
> **Tip**: The action buttons area (5-10) appears on hover and is hidden by default to keep the interface clean.
### Button Details
| Button | State Changes | Notes |
|--------|---------------|-------|
| **Enable** | Shows checkmark and disables when active | Changes to "Join/Joined" in failover mode |
| **Edit** | Always available | Opens edit panel to modify configuration |
| **Duplicate** | Always available | Creates a copy with `copy` suffix |
| **Speed Test** | Shows loading animation during test | Only available when proxy service is running |
| **Usage Query** | Always available | Configure custom usage query script |
| **Delete** | Semi-transparent/disabled when active | Must switch to another provider first |
### Card States
| State | Border Color | Description |
|-------|--------------|-------------|
| **Currently Active** | Blue border | Current provider in normal mode |
| **Proxy Active** | Green border | Provider actually in use during proxy takeover mode |
| **Normal** | Default border | Inactive provider |
| **In Failover** | Shows priority badge | e.g., P1, P2 indicates failover priority |
### Health Status Badges
In proxy mode, providers in the failover queue display health status:
| Badge | Color | Description |
|-------|-------|-------------|
| Healthy | Green | 0 consecutive failures |
| Warning | Yellow | 1-2 consecutive failures |
| Unhealthy | Red | 3+ consecutive failures, may trigger circuit breaker |
## System Tray
CC Switch displays an icon in the system tray, providing quick access to operations.
### Tray Menu Structure
![image-20260108002153668](../../assets/image-20260108002153668.png)
### Menu Functions
| Menu Item | Function |
|-----------|----------|
| Open Main Window | Show and focus the main window |
| App Groups | Providers grouped by Claude/Codex/Gemini/OpenCode/OpenClaw |
| Provider List | Click to switch; currently active one shows a checkmark |
| Quit | Fully exit the application |
### Multi-language Support
The tray menu supports three languages, automatically switching based on settings:
| Language | Open Main Window | Quit |
|----------|-----------------|------|
| Chinese | Open Main Window | Quit |
| English | Open main window | Quit |
| Japanese | Open main window | Quit |
### Use Cases
Switching providers via the tray menu doesn't require opening the main window, suitable for:
- Frequently switching providers
- Quick operations when the main window is minimized
- Managing configurations while running in the background
## Settings Page
The settings page is divided into multiple tabs:
### General Tab
- Language settings (Chinese/English/Japanese)
- Theme settings (System/Light/Dark)
- Window behavior (launch on startup, close behavior)
### Advanced Tab
- Configuration directory settings
- Proxy service configuration
- Failover settings
- Pricing configuration
- Data import/export
### Usage Tab
- Request statistics overview
- Trend charts
- Request logs
- Provider/model statistics
### About Tab
- Version information
- Update check
- Open source license
## Keyboard Shortcuts
| Shortcut | Function |
|----------|----------|
| `Cmd/Ctrl + ,` | Open Settings |
| `Cmd/Ctrl + F` | Search providers |
| `Esc` | Close dialog/search |
## Search
Press `Cmd/Ctrl + F` to open the search bar:
- Search by name, notes, or URL
- Real-time provider list filtering
- Press `Esc` to close search

92
docs/user-manual/en/1-getting-started/1.4-quickstart.md Normal file
View File

@@ -0,0 +1,92 @@
# 1.4 Quick Start
This section helps you complete the initial setup in 5 minutes.
## Step 1: Add a Provider
1. Click the **+** button in the top-right corner of the main interface
2. Select your provider from the "Preset" dropdown
- Common presets: Zhipu GLM, MiniMax, DeepSeek, Kimi, PackyCode
- Or select "Custom" for manual configuration
3. Enter your **API Key**
4. Click "Add"
![image-20260108002807657](../../assets/image-20260108002807657.png)
> **Tip**: Presets auto-fill the endpoint URL, so you only need to enter your API Key.
## Step 2: Switch Provider
After adding, the provider appears in the list.
**Option 1: Switch from the main interface**
- Click the "Enable" button on the provider card
**Option 2: Quick switch via system tray**
- Right-click the CC Switch icon in the system tray
- Click the provider name directly
## Step 3: Activation
After switching providers, each CLI tool activates differently:
| Application | Activation Method |
|-------------|-------------------|
| Claude Code | Instant effect (supports hot reload) |
| Codex | Requires closing and reopening the terminal |
| Gemini | Instant effect (re-reads config on each request) |
### Claude Code First Launch Prompt
If Claude Code prompts you to **log in** or shows an onboarding wizard on first launch, enable the "Skip Claude Code first-run confirmation" option in CC Switch:
1. Open CC Switch "Settings > General"
2. Enable the "Skip Claude Code first-run confirmation" toggle
3. Restart Claude Code
![image-20260108002626389](../../assets/image-20260108002626389.png)
> **Note**: This option writes the `skipIntroduction` field to `~/.claude/settings.json`, skipping the official onboarding flow.
## Verify Configuration
After restarting, launch the corresponding CLI tool and enter a simple question to test:
```bash
# Claude Code - enter a test question after launching
claude
> Hello, please briefly introduce yourself
# Codex - enter a test question after launching
codex
> Hello, please briefly introduce yourself
# Gemini - enter a test question after launching
gemini
> Hello, please briefly introduce yourself
```
If the AI responds normally, the configuration is successful.
## Next Steps
Congratulations! You have completed the basic configuration. Next, you can:
- [Add more providers](../2-providers/2.1-add.md) - Configure multiple providers for easy switching
- [Configure MCP servers](../3-extensions/3.1-mcp.md) - Extend AI tool capabilities
- [Set up system prompts](../3-extensions/3.2-prompts.md) - Customize AI behavior
- [Enable proxy service](../4-proxy/4.1-service.md) - Monitor usage and enable automatic failover
## Common Issues
### Not taking effect after switching?
Make sure you restarted the terminal or CLI tool. The configuration file is updated at switch time, but running programs do not automatically reload it.
### Can't find a preset?
If your provider is not in the preset list, select "Custom" for manual configuration. See [Add Provider](../2-providers/2.1-add.md) for configuration format details.
### How to restore official login?
Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini), restart the client, and follow the login flow.

255
docs/user-manual/en/1-getting-started/1.5-settings.md Normal file
View File

@@ -0,0 +1,255 @@
# 1.5 Personalization
This section describes how to configure CC Switch according to your preferences.
## Open Settings
- Click the **gear** button in the top-left corner
- Or use the shortcut `Cmd/Ctrl + ,`
## Language Settings
CC Switch supports three languages:
| Language | Description |
|----------|-------------|
| Simplified Chinese | Default language |
| English | English interface |
| Japanese | Japanese interface |
Language changes take effect immediately without restarting.
## Theme Settings
| Option | Description |
|--------|-------------|
| System | Automatically matches the system's dark/light mode |
| Light | Always use the light theme |
| Dark | Always use the dark theme |
## Window Behavior
### Launch on Startup
When enabled, CC Switch automatically runs when the system starts.
- **Windows**: Implemented via the registry
- **macOS**: Implemented via LaunchAgent
- **Linux**: Implemented via XDG autostart
### Close Behavior
| Option | Description |
|--------|-------------|
| Minimize to tray | Clicking the close button hides to the system tray |
| Exit directly | Clicking the close button fully exits the app |
"Minimize to tray" is recommended for convenient provider switching via the tray.
### Claude Plugin Integration
When enabled, CC Switch automatically syncs the configuration to the VS Code Claude Code extension (writes `primaryApiKey` to `~/.claude/config.json`) when switching providers.
> **Use case**: If you use both Claude Code CLI and the VS Code extension, enable this option to keep both configurations in sync.
### Skip Claude Onboarding
When enabled, skips the Claude Code onboarding flow, suitable for users already familiar with Claude Code.
> **Note**: This option writes the `skipIntroduction` field to `~/.claude/settings.json`.
### App Visibility
Choose which applications to display in the app switcher. Each app can be toggled independently, but at least one must remain visible.
Configurable apps: Claude, Codex, Gemini, OpenCode, OpenClaw.
> **Use case**: If you only use Claude Code and Codex CLI, you can hide the other apps to keep the interface clean.
### Skill Sync Method
Set the sync method when installing skills to each app's directory:
| Method | Description |
|--------|-------------|
| Symlink | Creates symbolic links pointing to skill source files; saves space, syncs in real-time |
| Copy | Copies skill files entirely to the target directory |
> **Recommended**: Symlink is the default method. Switch to Copy if you encounter permission issues.
### Terminal Settings
Choose the terminal application that CC Switch uses when opening a terminal.
Supported terminals (by platform):
| Platform | Terminal Options |
|----------|-----------------|
| macOS | Terminal, iTerm2, Alacritty, Kitty, Ghostty, WezTerm |
| Windows | CMD, PowerShell, Windows Terminal |
| Linux | GNOME Terminal, Konsole, Xfce4 Terminal, Alacritty, Kitty, Ghostty |
## Directory Configuration
### App Configuration Directory
The storage location for CC Switch's own data, defaulting to `~/.cc-switch/`.
### CLI Tool Directories
You can customize each CLI tool's configuration directory:
| Setting | Default | Description |
|---------|---------|-------------|
| Claude Directory | `~/.claude/` | Claude Code configuration directory |
| Codex Directory | `~/.codex/` | Codex configuration directory |
| Gemini Directory | `~/.gemini/` | Gemini CLI configuration directory |
| OpenCode Directory | `~/.opencode/` | OpenCode configuration directory |
| OpenClaw Directory | `~/.openclaw/` | OpenClaw configuration directory |
> **Note**: After changing directories, the app must be restarted, and the corresponding CLI tools must also be configured to use the same directory.
## Data Management
### Export Configuration
Click the "Export" button to save a backup file containing:
- All provider configurations
- MCP server configurations
- Prompt presets
- App settings
The backup file is in JSON format and can be viewed with a text editor.
### Import Configuration
1. Click "Select File"
2. Select a previously exported backup file
3. Click "Import"
4. Confirm to overwrite existing configuration
> **Note**: Importing will overwrite existing configuration. It is recommended to export your current configuration as a backup first.
## Proxy Settings
Settings > Proxy Tab
The Proxy tab centralizes all proxy-related features:
### Local Proxy
Start/stop the local proxy service, configure the listen address and port. See [4.1 Proxy Service](../4-proxy/4.1-service.md) for details.
### Failover
Configure failover queues and automatic switching strategies by app (Claude/Codex/Gemini). See [4.3 Failover](../4-proxy/4.3-failover.md) for details.
### Pricing Rectifier
Configure model pricing correction rules for proxy billing statistics calibration.
### Global Outbound Proxy
Configure CC Switch's outbound HTTP/HTTPS proxy, applicable for scenarios where external API access requires a proxy.
## Advanced Settings
Settings > Advanced Tab
### Configuration Directories
Customize configuration file directories for each app. See the "Directory Configuration" section above for details.
### Data Management
Import/export configuration backups. See the "Data Management" section above for details.
### Backup & Restore
Manage automatic backups:
| Setting | Description |
|---------|-------------|
| Backup Interval | Time interval for automatic backups (hours) |
| Retention Count | Number of backups to retain |
Supports viewing the backup list and restoring from backups.
### Cloud Sync (WebDAV)
Sync configurations across multiple devices via the WebDAV protocol.
| Setting | Description |
|---------|-------------|
| Service Preset | Jianguoyun / Nextcloud / Synology / Custom |
| Server URL | WebDAV server URL |
| Username | Login username |
| Password | Login password (app-specific password) |
| Remote Directory | Remote storage path (default: `cc-switch-sync`) |
| Profile Name | Device profile name (default: `default`) |
| Auto Sync | Automatically upload changes when enabled |
Operations:
- **Test Connection**: Verify WebDAV configuration is correct
- **Save**: Save configuration and auto-test
- **Upload**: Upload local data to the remote server
- **Download**: Download data from the remote server to local
> **Note**: Upload will overwrite remote data, and download will overwrite local data. Please confirm before proceeding.
### Log Configuration
| Setting | Description |
|---------|-------------|
| Enable Logging | Enable/disable application logging |
| Log Level | error / warn / info / debug / trace |
Log level descriptions:
- **error** - Critical errors only
- **warn** - Warnings and errors
- **info** - General information (recommended)
- **debug** - Detailed debugging information
- **trace** - All verbose information
## About Page
Settings > About Tab
### Version Information
Displays the current CC Switch version number, with support for:
- Viewing release notes
- Checking for updates
- Downloading and installing new versions
### Local Environment Check
Automatically detects installed CLI tool versions:
| Tool | Detection Contents |
|------|-------------------|
| Claude | Current version, latest version |
| Codex | Current version, latest version |
| Gemini | Current version, latest version |
| OpenCode | Current version, latest version |
| OpenClaw | Current version, latest version |
Click the "Refresh" button to re-detect.
### One-click Install Commands
Provides quick commands to install/update CLI tools:
```bash
npm i -g @anthropic-ai/claude-code@latest
npm i -g @openai/codex@latest
npm i -g @google/gemini-cli@latest
npm i -g opencode@latest
npm i -g openclaw@latest
```
Click the "Copy" button to copy to clipboard.

354
docs/user-manual/en/2-providers/2.1-add.md Normal file
View File

@@ -0,0 +1,354 @@
# 2.1 Add Provider
## Open the Add Panel
Click the **+** button in the top-right corner of the main interface to open the Add Provider panel.
The panel has two tabs:
- **App-specific Provider**: Only for the currently selected app (Claude/Codex/Gemini/OpenCode/OpenClaw)
- **Universal Provider**: Shared configuration across apps
## Add Using Presets
Presets are pre-configured provider templates that only require an API Key to use.
### Steps
1. Select a provider from the "Preset" dropdown
2. Name and endpoint are auto-filled
3. Enter your **API Key**
4. (Optional) Add notes
5. Click "Add"
### Common Presets
#### Claude Presets
| Preset Name | Description |
|-------------|-------------|
| Claude Official | Log in with an Anthropic official account |
| DeepSeek | DeepSeek model |
| Zhipu GLM | Zhipu AI GLM model |
| Zhipu GLM en | Zhipu AI (English version) |
| Bailian | Alibaba Cloud Bailian (Qwen) |
| Kimi | Moonshot Kimi model |
| Kimi For Coding | Kimi coding-specific model |
| ModelScope | ModelScope community |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| DouBaoSeed | DouBao Seed model |
| BaiLing | BaiLing AI |
| AiHubMix | AiHubMix aggregation service |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow (English version) |
| DMXAPI | DMXAPI proxy service |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
| Nvidia | Nvidia AI service |
| Xiaomi MiMo | Xiaomi MiMo model |
> The preset list may be updated with new versions. Refer to the actual list shown in the app.
#### Codex Presets
| Preset Name | Description |
|-------------|-------------|
| OpenAI Official | Log in with an OpenAI official account |
| Azure OpenAI | Azure OpenAI service |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI proxy service |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
#### Gemini Presets
| Preset Name | Description |
|-------------|-------------|
| Google Official | Log in with Google OAuth |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
| Custom | Manually configure all parameters |
#### OpenCode Presets
| Preset Name | Description |
|-------------|-------------|
| DeepSeek | DeepSeek model |
| Zhipu GLM | Zhipu AI GLM model |
| Zhipu GLM en | Zhipu AI (English version) |
| Bailian | Alibaba Cloud Bailian |
| Kimi k2.5 | Moonshot Kimi-k2.5 model |
| Kimi For Coding | Kimi coding-specific model |
| ModelScope | ModelScope community |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| DouBaoSeed | DouBao Seed model |
| BaiLing | BaiLing AI |
| Xiaomi MiMo | Xiaomi MiMo model |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI proxy service |
| OpenRouter | Aggregation routing service |
| Nvidia | Nvidia AI service |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| OpenAI Compatible | OpenAI-compatible interface |
| Oh My OpenCode | Oh My OpenCode service |
> The preset list is continuously updated. Refer to the actual list shown in the app.
#### OpenClaw Presets
| Preset Name | Description |
|-------------|-------------|
| DeepSeek | DeepSeek model |
| Zhipu GLM | Zhipu AI GLM model |
| Zhipu GLM en | Zhipu AI (English version) |
| Qwen Coder | Qwen coding model |
| Kimi k2.5 | Moonshot Kimi-k2.5 model |
| Kimi For Coding | Kimi coding-specific model |
| MiniMax | MiniMax model |
| MiniMax en | MiniMax (English version) |
| KAT-Coder | KAT-Coder model |
| Longcat | Longcat AI |
| DouBaoSeed | DouBao Seed model |
| BaiLing | BaiLing AI |
| Xiaomi MiMo | Xiaomi MiMo model |
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI proxy service |
| OpenRouter | Aggregation routing service |
| ModelScope | ModelScope community |
| SiliconFlow | SiliconFlow |
| SiliconFlow en | SiliconFlow (English version) |
| Nvidia | Nvidia AI service |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| AICoding | AICoding service |
| CrazyRouter | CrazyRouter service |
| SSSAiCode | SSSAiCode service |
| AWS Bedrock | AWS Bedrock service |
| OpenAI Compatible | OpenAI-compatible interface |
## Custom Configuration
After selecting the "Custom" preset, you need to manually edit the JSON configuration.
### Claude Configuration Format
```json
{
"env": {
"ANTHROPIC_API_KEY": "your-api-key",
"ANTHROPIC_BASE_URL": "https://api.example.com"
}
}
```
| Field | Required | Description |
|-------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes | API key |
| `ANTHROPIC_BASE_URL` | No | Custom endpoint URL |
| `ANTHROPIC_AUTH_TOKEN` | No | Alternative authentication method to API_KEY |
### Codex Configuration Format
Codex uses two configuration files:
**1. auth.json** (`~/.codex/auth.json`) - Stores API key:
```json
{
"OPENAI_API_KEY": "your-api-key"
}
```
**2. config.toml** (`~/.codex/config.toml`) - Stores model and endpoint configuration:
```toml
# Basic configuration
model_provider = "custom"
model = "gpt-5.2"
model_reasoning_effort = "high"
disable_response_storage = true
# Custom provider configuration
[model_providers.custom]
name = "custom"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
```
**auth.json field descriptions**:
| Field | Required | Description |
|-------|----------|-------------|
| `OPENAI_API_KEY` | Yes | API key |
**config.toml field descriptions**:
| Field | Required | Description |
|-------|----------|-------------|
| `model_provider` | Yes | Model provider name (must match `[model_providers.xxx]`) |
| `model` | Yes | Model to use (e.g., `gpt-5.2`, `gpt-4o`) |
| `model_reasoning_effort` | No | Reasoning effort: `low` / `medium` / `high` |
| `disable_response_storage` | No | Whether to disable response storage |
| `base_url` | Yes | API endpoint URL |
| `wire_api` | No | API protocol type (usually `responses`) |
| `requires_openai_auth` | No | Whether to use OpenAI authentication |
### Gemini Configuration Format
```json
{
"env": {
"GEMINI_API_KEY": "your-api-key",
"GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
}
}
```
| Field | Required | Description |
|-------|----------|-------------|
| `GEMINI_API_KEY` | Yes | API key |
| `GOOGLE_GEMINI_BASE_URL` | No | Custom endpoint URL |
| `GEMINI_MODEL` | No | Specify model |
> Authentication type is automatically detected by CC Switch (PackyCode API proxy / Google OAuth / generic API Key), no manual configuration needed.
## Universal Provider
Universal providers can share configurations across Claude/Codex/Gemini/OpenCode/OpenClaw, suitable for proxy services that support multiple API formats.
### Create a Universal Provider
1. Switch to the "Universal Provider" tab
2. Click "Add Universal Provider"
3. Fill in the common configuration:
- Name
- API Key
- Endpoint URL
4. Check the apps to sync to (Claude/Codex/Gemini/OpenCode/OpenClaw)
5. Save
### Sync Mechanism
Universal providers automatically sync to the selected apps:
- After modifying a universal provider, all linked app configurations are updated
- After deleting a universal provider, linked app configurations are also deleted
### Save and Sync
When editing a universal provider, you can choose:
| Action | Description |
|--------|-------------|
| Save | Save configuration only, without immediate sync |
| Save and Sync | Save configuration and immediately sync to all enabled apps |
### Manual Sync
If you need to manually trigger a sync:
1. Click the "Sync" button on the universal provider card
2. Confirm the sync operation
3. Configuration will overwrite the linked provider in each app
## Import Providers
CC Switch supports two ways to import provider configurations:
### Option 1: Deep Link Import
One-click import via `ccswitch://` protocol links:
1. Click or visit the deep link
2. CC Switch opens automatically and shows the import confirmation
3. Preview the configuration information
4. Click "Confirm Import"
**Getting deep links**:
- Obtain from shared links by others
- Create using the [online generator tool](https://farion1231.github.io/cc-switch/deplink.html)
### Option 2: Database Backup Import
Batch import from SQL backup files:
1. Open "Settings > Advanced > Data Management"
2. Click "Select File"
3. Select a previously exported `.sql` backup file
4. Click "Import"
5. Confirm to overwrite existing configuration
**Imported contents**:
- All provider configurations
- MCP server configurations
- Prompt presets
- Usage logs
> **Note**: Importing will overwrite the existing database. It is recommended to export your current configuration as a backup first. The exported file name format is `cc-switch-export-{timestamp}.sql`.
## Advanced Options
### Custom Icon
Click the icon area to the left of the name to:
- Select a preset icon
- Customize icon color
### Website Link
Enter the provider's website or console URL for quick access:
- Click the link icon on the provider card to open directly
- Useful for checking balance, obtaining API keys, etc.
### Notes
Add notes such as:
- Account purpose (personal/work)
- Plan information
- Expiration date
Notes are displayed on the provider card and are searchable.
### Endpoint Speed Test
After adding a provider, you can speed-test API endpoints:
1. Click the "Speed Test" button on the provider card
2. Add multiple endpoint URLs in the speed test panel
3. Click "Test" to run the test
4. Select the endpoint with the lowest latency
**Test results**:
- Green: Latency < 500ms (Excellent)
- Yellow: Latency 500-1000ms (Fair)
- Red: Latency > 1000ms (Slow)
![image-20260108005327817](../../assets/image-20260108005327817.png)

111
docs/user-manual/en/2-providers/2.2-switch.md Normal file
View File

@@ -0,0 +1,111 @@
# 2.2 Switch Provider
## Switch from Main Interface
In the provider list, click the "Enable" button on the target provider card.
### Switching Flow
1. Click the "Enable" button
2. CC Switch updates the configuration file
3. The card status changes to "Currently Active"
4. Claude/Gemini take effect immediately, Codex requires a terminal restart
### Status Indicators
| Status | Display | Description |
|--------|---------|-------------|
| Currently Active | Blue border + label | Current provider in the configuration file |
| Proxy Active | Green border | Provider actually in use during proxy mode |
| Normal | Default style | Inactive provider |
## Quick Switch via System Tray
Quickly switch providers via the system tray without opening the main interface.
### Steps
1. Right-click the CC Switch icon in the system tray
2. Find the corresponding app (Claude/Codex/Gemini/OpenCode) in the menu
3. Click the provider name you want to switch to
4. Switching completes with a brief tray notification
### Tray Menu Structure
![image-20260108004348993](../../assets/image-20260108004348993.png)
## Activation Methods
### Claude Code
**Takes effect immediately after switching**, no restart needed.
Claude Code supports hot reload and automatically detects configuration file changes and reloads.
### Codex
Requires restart after switching:
- Close the current terminal window
- Reopen the terminal
### Gemini CLI
**Takes effect immediately after switching**, no restart needed.
Gemini CLI re-reads the `.env` file on each request.
## Configuration File Changes
When switching providers, CC Switch modifies the following files:
### Claude
```
~/.claude/settings.json
```
Modified content:
```json
{
"env": {
"ANTHROPIC_API_KEY": "new API Key",
"ANTHROPIC_BASE_URL": "new endpoint"
}
}
```
### Codex
```
~/.codex/auth.json
~/.codex/config.toml (if additional configuration exists)
```
### Gemini
```
~/.gemini/.env
~/.gemini/settings.json
```
## Handling Switch Failures
If switching fails, possible reasons:
### Configuration File Is Locked
Another program is using the configuration file.
**Solution**: Close the running CLI tool and try switching again.
### Insufficient Permissions
No write permission to the configuration file.
**Solution**: Check the permission settings of the configuration directory.
### Invalid Configuration Format
The provider's JSON configuration has format errors.
**Solution**: Edit the provider, check and fix the JSON format.

145
docs/user-manual/en/2-providers/2.3-edit.md Normal file
View File

@@ -0,0 +1,145 @@
# 2.3 Edit Provider
## Open the Edit Panel
1. Find the provider card you want to edit
2. Hover over the card to reveal action buttons
3. Click the "Edit" button
## Editable Content
### Basic Information
| Field | Description |
|-------|-------------|
| Name | Provider display name |
| Notes | Additional notes |
| Website Link | Provider website or console URL |
| Icon | Custom icon and color |
### Icon Customization
CC Switch provides rich icon customization features:
#### Icon Picker
1. Click the icon area to open the icon picker
2. Use the search box to search icons by name
3. Click to select the desired icon
The icon library includes common AI service provider and technology icons, supporting:
- Fuzzy search by name
- Icon name tooltips
- Real-time preview of selected icon
![image-20260108004734882](../../assets/image-20260108004734882.png)
### Configuration
JSON-formatted configuration content, including:
- API Key
- Endpoint URL
- Other environment variables
### Editing the Currently Active Provider
When editing the currently active provider, a special "backfill" mechanism applies:
1. When opening the edit panel, the latest content is read from the live configuration file
2. If you manually modified the configuration in the CLI tool, those changes are synced back
3. After saving, modifications are written to the live configuration file
This ensures CC Switch and CLI tool configurations stay in sync.
## Modify API Key
When editing a provider, you can modify the key directly in the **API Key** input field:
1. Click the "Edit" button on the provider card
2. Enter the new key in the "API Key" input field
3. Click "Save"
> **Tip**: The API Key input field supports a show/hide toggle. Click the eye icon on the right to view the full key.
## Modify Endpoint URL
When editing a provider, you can modify the URL directly in the **Endpoint URL** input field:
1. Click the "Edit" button on the provider card
2. Enter the new URL in the "Endpoint URL" input field
3. Click "Save"
### Endpoint URL Format
| Application | Format Example |
|-------------|----------------|
| Claude | `https://api.example.com` |
| Codex | `https://api.example.com/v1` |
| Gemini | `https://api.example.com` |
## Add Custom Endpoints
Providers can be configured with multiple endpoints for:
- Testing multiple addresses during speed tests
- Backup endpoints for failover
### Auto-collection
When adding a provider, CC Switch automatically extracts endpoint URLs from the configuration.
### Manual Addition
When editing a provider, in the "Endpoint Management" area you can:
- Add new endpoints
- Delete existing endpoints
- Set a default endpoint
## JSON Editor
Configuration uses JSON format, and the editor provides:
- Syntax highlighting
- Format validation
- Error messages
### Common Errors
**Missing quotes**:
```json
// Wrong
{ env: { KEY: "value" } }
// Correct
{ "env": { "KEY": "value" } }
```
**Trailing comma**:
```json
// Wrong
{ "env": { "KEY": "value", } }
// Correct
{ "env": { "KEY": "value" } }
```
**Unclosed brackets**:
```json
// Wrong
{ "env": { "KEY": "value" }
// Correct
{ "env": { "KEY": "value" } }
```
## Save and Activate
1. Click the "Save" button
2. If this is the currently active provider, the configuration is immediately written to the live file
3. Restart the CLI tool for changes to take effect
## Cancel Editing
Click "Cancel" or press the `Esc` key to close the edit panel. All modifications will be discarded.

76
docs/user-manual/en/2-providers/2.4-sort-duplicate.md Normal file
View File

@@ -0,0 +1,76 @@
# 2.4 Sort & Duplicate
## Drag to Reorder
Adjust the display order of providers by dragging.
### Steps
1. Move the mouse to the **≡** drag handle on the left side of the provider card
2. Hold the left mouse button
3. Drag up or down to the target position
4. Release the mouse to complete reordering
### Reorder Uses
- **Prioritize frequently used**: Place frequently used providers at the top of the list
- **Failover order**: Sorting affects the default order of the failover queue
## Duplicate Provider
Quickly create a copy of a provider, useful for:
- Creating variations based on existing configurations
- Backing up current configurations
- Creating test configurations
### Steps
1. Hover over the provider card to reveal action buttons
2. Click the "Duplicate" button
3. A copy is automatically created with a `copy` name suffix
4. Edit the copy to modify the configuration
### Duplicated Content
Duplication creates a complete copy, including:
| Content | Duplicated |
|---------|------------|
| Name | Yes (with `copy` suffix) |
| Configuration | Fully duplicated |
| Notes | Yes |
| Website Link | Yes |
| Icon | Yes |
| Endpoint List | Yes |
| Sort Position | Inserted below the original provider |
### After Duplication
After duplication, you typically need to modify:
1. **Name**: Change to a meaningful name
2. **API Key**: If using a different account
3. **Endpoint**: If using a different service
## Delete Provider
### Steps
1. Hover over the provider card to reveal action buttons
2. Click the "Delete" button
3. Confirm deletion
### Deletion Confirmation
A confirmation dialog appears before deletion, showing:
- Provider name
- Warning that deletion cannot be undone
### Deletion Restrictions
- **Currently active provider**: Can be deleted, but it is recommended to switch to another provider first
- **Universal provider**: Deleting will also remove linked app configurations
![image-20260108004946288](../../assets/image-20260108004946288.png)

181
docs/user-manual/en/2-providers/2.5-usage-query.md Normal file
View File

@@ -0,0 +1,181 @@
# 2.5 Usage Query
## Overview
The usage query feature allows you to configure custom scripts to query a provider's remaining balance, used amount, and other information in real time.
**Use cases**:
- Check API account remaining balance
- Monitor plan usage
- Multi-plan balance summary display
## Open Configuration
1. Hover over the provider card to reveal action buttons
2. Click the "Usage Query" button (chart icon)
3. Opens the usage query configuration panel
## Enable Usage Query
At the top of the configuration panel, enable the "Enable Usage Query" toggle.
## Preset Templates
CC Switch provides three preset templates:
### Custom Template
Fully customizable request and extraction logic, suitable for special API formats.
### Generic Template
Suitable for most providers with standard API formats:
```javascript
({
request: {
url: "{{baseUrl}}/user/balance",
method: "GET",
headers: {
"Authorization": "Bearer {{apiKey}}",
"User-Agent": "cc-switch/1.0"
}
},
extractor: function(response) {
return {
isValid: response.is_active || true,
remaining: response.balance,
unit: "USD"
};
}
})
```
**Configuration parameters**:
| Parameter | Description |
|-----------|-------------|
| API Key | Authentication key (optional, uses provider's key if empty) |
| Base URL | API base URL (optional, uses provider's endpoint if empty) |
### New API Template
Designed specifically for New API-type proxy services:
```javascript
({
request: {
url: "{{baseUrl}}/api/user/self",
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}",
"New-Api-User": "{{userId}}"
},
},
extractor: function (response) {
if (response.success && response.data) {
return {
planName: response.data.group || "Default Plan",
remaining: response.data.quota / 500000,
used: response.data.used_quota / 500000,
total: (response.data.quota + response.data.used_quota) / 500000,
unit: "USD",
};
}
return {
isValid: false,
invalidMessage: response.message || "Query failed"
};
},
})
```
**Configuration parameters**:
| Parameter | Description |
|-----------|-------------|
| Base URL | New API service URL |
| Access Token | Access token |
| User ID | User ID |
## General Configuration
### Timeout
Request timeout in seconds, default 10 seconds.
### Auto Query Interval
Interval for automatically refreshing usage data (minutes):
- Set to `0` to disable auto query
- Range: 0-1440 minutes (up to 24 hours)
- Only effective when the provider is in "Currently Active" status
## Extractor Return Format
The extractor function must return an object containing the following fields:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `isValid` | boolean | No | Whether the account is valid, defaults to true |
| `invalidMessage` | string | No | Message when invalid |
| `remaining` | number | Yes | Remaining balance |
| `unit` | string | Yes | Unit (e.g., USD, CNY, times) |
| `planName` | string | No | Plan name (supports multi-plan) |
| `total` | number | No | Total balance |
| `used` | number | No | Used amount |
| `extra` | object | No | Additional information |
## Test Script
After configuration, click the "Test Script" button to verify:
1. Sends a request to the configured URL
2. Executes the extractor function
3. Displays the returned result or error message
## Display
After successful configuration, the provider card displays:
- **Single plan**: Directly shows remaining balance
- **Multi-plan**: Shows plan count, click to expand for details
## Variable Placeholders
The following placeholders can be used in scripts and are automatically replaced at runtime:
| Placeholder | Description |
|-------------|-------------|
| `{{apiKey}}` | Configured API Key |
| `{{baseUrl}}` | Configured Base URL |
| `{{accessToken}}` | Configured Access Token (New API) |
| `{{userId}}` | Configured User ID (New API) |
## Common Provider Configuration Examples
### Troubleshooting
### Query Failed
**Check**:
1. Is the API Key correct
2. Is the Base URL correct
3. Is the network accessible
4. Is the timeout sufficient
### Empty Response Data
**Check**:
1. Does the extractor function have a `return` statement
2. Does the response data structure match the extractor
3. Use "Test Script" to view the raw response
### Format Failed
When there is a script syntax error, clicking the "Format" button will indicate the error location.
## Notes
- Usage queries consume a small amount of API request quota
- Set a reasonable auto query interval to avoid frequent requests
- Sensitive information (API Key, Token) is securely stored locally

209
docs/user-manual/en/3-extensions/3.1-mcp.md Normal file
View File

@@ -0,0 +1,209 @@
# 3.1 MCP Server Management
## What is MCP
MCP (Model Context Protocol) is a protocol that allows AI tools to access external data sources and tools. Through MCP servers, you can enable AI to:
- Access file systems
- Make network requests
- Query databases
- Call external APIs
## Open the MCP Panel
Click the **MCP** button in the top navigation bar.
## Panel Overview
![image-20260108005723522](../../assets/image-20260108005723522.png)
## Add MCP Server
### Using Preset Templates
1. Click the **+** button in the top-right corner
2. Select a template from the "Preset" dropdown
3. Modify the configuration as needed
4. Click "Save"
![image-20260108005739731](../../assets/image-20260108005739731.png)
### Common Presets
| Preset | Package Name | Description |
|--------|-------------|-------------|
| fetch | mcp-server-fetch | HTTP request tool that enables AI to fetch web content |
| time | @modelcontextprotocol/server-time | Time tool that provides current time information |
| memory | @modelcontextprotocol/server-memory | Memory tool that enables AI to store and retrieve information |
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking | Chain-of-thought tool that enhances AI reasoning |
| context7 | @upstash/context7-mcp | Documentation search tool for querying technical docs |
### Custom Configuration
After selecting "Custom", fill in:
| Field | Required | Description |
|-------|----------|-------------|
| Server ID | Yes | Unique identifier |
| Name | No | Display name |
| Description | No | Function description |
| Transport Type | Yes | stdio / http / sse |
| Command | Yes* | Required for stdio type |
| Arguments | No | Command-line arguments |
| URL | Yes* | Required for http/sse type |
| Headers | No | Request headers for http/sse type |
| Environment Variables | No | Environment variables passed to the server |
## Transport Types
### stdio (Standard I/O)
The most common type, communicating by launching a local process.
```json
{
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {}
}
```
**Requirements**:
- The corresponding command must be installed (e.g., `uvx`, `npx`)
- The server program must be in PATH
### http
Communicates with a remote server via HTTP protocol.
```json
{
"url": "http://localhost:8080/mcp"
}
```
### sse (Server-Sent Events)
Communicates with a server via SSE protocol, supporting real-time push.
```json
{
"url": "http://localhost:8080/sse"
}
```
## App Binding
Each MCP server can independently control which apps it is enabled for.
### Toggle Description
| Toggle | Effect | Configuration File Path |
|--------|--------|------------------------|
| Claude | Sync to Claude Code | `~/.claude.json`'s `mcpServers` |
| Codex | Sync to Codex | `~/.codex/config.toml`'s `[mcp_servers]` |
| Gemini | Sync to Gemini CLI | `~/.gemini/settings.json`'s `mcpServers` |
| OpenCode | Sync to OpenCode | `~/.opencode/config.json`'s `mcpServers` |
> **Note**: OpenClaw does not currently support MCP server management. MCP functionality is currently only supported for Claude, Codex, Gemini, and OpenCode.
### Toggle Implementation
When enabling an app's toggle, CC Switch will:
1. **Update database**: Set the server's `apps.claude/codex/gemini/opencode` status to `true`
2. **Sync to live configuration**: Write the server configuration to the corresponding app's configuration file
3. **Take effect immediately**: The new MCP server is automatically loaded the next time the CLI tool starts
When disabling an app's toggle, CC Switch will:
1. **Update database**: Set the corresponding app status to `false`
2. **Remove from live configuration**: Delete the server from the app's configuration file
3. **Take effect immediately**: The MCP server is no longer loaded the next time the CLI tool starts
### Sync Conditions
MCP server sync only executes when the corresponding app is installed:
- **Claude**: Requires `~/.claude/` directory or `~/.claude.json` file to exist
- **Codex**: Requires `~/.codex/` directory to exist
- **Gemini**: Requires `~/.gemini/` directory to exist
- **OpenCode**: Requires `~/.opencode/` directory to exist
> **Tip**: If a CLI tool is not installed, enabling its toggle will not cause an error, but the configuration will not be written.
When the toggle is disabled, the configuration is removed from the file.
## Edit Server
1. Click the "Edit" button on the right side of the server row
2. Modify the configuration
3. Click "Save"
Changes are immediately synced to enabled app configuration files.
## Delete Server
1. Click the "Delete" button on the right side of the server row
2. Confirm deletion
After deletion, the configuration is removed from all app configuration files.
## Import Existing Configurations
If you have already configured MCP servers in CLI tools, you can import them into CC Switch:
1. Click the "Import" button
2. Select the app to import from (Claude/Codex/Gemini/OpenCode)
3. CC Switch reads the existing configuration and imports it
## Configuration File Formats
### Claude (`~/.claude.json`)
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```
### Gemini (`~/.gemini/settings.json`)
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
## FAQ
### Server Fails to Start
Check:
- Is the command properly installed (e.g., `uvx`)
- Is the command in PATH
- Are the arguments correct
### Configuration Not Taking Effect
Ensure:
- The corresponding app toggle is enabled
- The CLI tool has been restarted

160
docs/user-manual/en/3-extensions/3.2-prompts.md Normal file
View File

@@ -0,0 +1,160 @@
# 3.2 Prompts Management
## Overview
The Prompts feature manages system prompt presets. System prompts influence the AI's behavior and response style.
With CC Switch, you can:
- Create multiple prompt presets
- Quickly switch prompts for different scenarios
- Sync prompt configurations across devices
## Open the Prompts Panel
Click the **Prompts** button in the top navigation bar.
## Panel Overview
![image-20260108010110382](../../assets/image-20260108010110382.png)
## Create a Preset
### Steps
1. Click the **+** button in the top-right corner
2. Enter a preset name
3. Write the prompt in the Markdown editor
4. Click "Save"
### Markdown Editor
The editor provides:
- Syntax highlighting
- Live preview
- Common format shortcuts
### Prompt Writing Tips
**Structured format**:
```markdown
# Role Definition
You are a professional code review expert.
## Core Capabilities
- Code quality analysis
- Performance optimization suggestions
- Security vulnerability detection
## Response Style
- Clear and concise
- Provide specific examples
- Give improvement suggestions
## Notes
- Do not modify business logic
- Maintain consistent code style
```
## Activate a Preset
### How to Activate
Click the toggle switch on the preset item to change its activation status.
### Single Activation
Only one preset can be active at a time. Activating a new preset automatically deactivates the previous one.
### Sync Target
After activation, the prompt is written to the corresponding app's file:
| Application | File Path |
|-------------|-----------|
| Claude | `~/.claude/CLAUDE.md` |
| Codex | `~/.codex/AGENTS.md` |
| Gemini | `~/.gemini/GEMINI.md` |
| OpenCode | `~/.opencode/AGENTS.md` |
| OpenClaw | `~/.openclaw/AGENTS.md` |
## Edit a Preset
1. Click the "Edit" button on the preset item
2. Modify the name or content
3. Click "Save"
If the currently active preset is edited, changes are immediately synced to the configuration file.
## Delete a Preset
1. Click the "Delete" button on the preset item
2. Confirm deletion
Active presets cannot be deleted. Deactivate the preset first before deleting.
## Smart Backfill
CC Switch provides a smart backfill protection mechanism to ensure your manual modifications are not lost.
### How It Works
1. Before switching presets, automatically reads the current configuration file content
2. Compares file content with the preset in the database
3. If the content differs, it means the user has manually modified it
4. Saves the manually modified content to the current preset
5. Then switches to the new preset
### Protection Scenarios
| Scenario | Handling |
|----------|----------|
| Directly editing `CLAUDE.md` in CLI | Changes auto-saved to current preset |
| Modifying config file with external editor | Changes auto-saved to current preset |
| Switching to another preset | Current changes saved first, then switched |
### Technical Details
The backfill mechanism triggers at these moments:
- **When switching presets**: Saves current live file content to the current preset
- **When editing the current preset**: Reads latest content from the live file
- **On first launch**: Automatically imports existing live file content
### Notes
- Backfill only triggers when switching to a different preset
- If no preset is currently active, backfill is not triggered
- Backfill failure does not affect the switching process
## Cross-app Usage
Prompts are managed separately per app:
- When switched to Claude, Claude's presets are shown
- When switched to Codex, Codex's presets are shown
- When switched to Gemini, Gemini's presets are shown
- When switched to OpenCode, OpenCode's presets are shown
- When switched to OpenClaw, OpenClaw's presets are shown
To use the same prompt across multiple apps, you need to create them separately.
## Import & Export
### Share via Deep Link
You can generate deep links to share presets:
```
ccswitch://import/prompt?data=<base64-encoded preset>
```
### Via Configuration Export
Exporting configuration includes all presets, which can be restored upon import.

207
docs/user-manual/en/3-extensions/3.3-skills.md Normal file
View File

@@ -0,0 +1,207 @@
# 3.3 Skills Management
## Overview
Skills are reusable capability extensions that give AI tools specialized abilities in specific domains.
Skills exist as folders containing:
- Prompt templates
- Tool definitions
- Example code
## Supported Applications
Skills are supported across all four applications:
- **Claude Code**
- **Codex**
- **Gemini CLI**
- **OpenCode**
## Open the Skills Page
Click the **Skills** button in the top navigation bar.
> Note: The Skills button is visible in all app modes.
## Page Overview
![image-20260108010253926](../../assets/image-20260108010253926.png)
## Discover Skills
### Pre-configured Repositories
CC Switch comes pre-configured with the following GitHub repositories:
| Repository | Description |
|------------|-------------|
| Anthropic Official | Official skills provided by Anthropic |
| ComposioHQ | Community-maintained skill collection |
| Community Picks | Curated high-quality skills |
![image-20260108010308060](../../assets/image-20260108010308060.png)
### 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.
## Install Skills
### Steps
1. Find the skill card you want to install
2. Click the "Install" button
3. Wait for installation to complete
### Installation Location
| Application | Install Directory |
|-------------|-------------------|
| Claude | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| Gemini | `~/.gemini/skills/` |
| OpenCode | `~/.opencode/skills/` |
### Installation Contents
Installation copies the skill folder to your local machine:
```
~/.claude/skills/
└── skill-name/
├── README.md
├── prompt.md
└── tools/
└── ...
```
## Uninstall Skills
### Steps
1. Find the installed skill card
2. Click the "Uninstall" button
3. Confirm uninstallation
### Uninstall Effect
- Deletes the local skill folder
- Updates installation status
## Repository Management
### Open Repository Management
Click the "Repository Management" button at the top of the page.
### Add Custom Repository
1. Click "Add Repository"
2. Fill in repository information:
- Owner: GitHub username or organization name
- Name: Repository name
- Branch: Branch name (default: main)
- Subdirectory: Subdirectory containing skills (optional)
3. Click "Add"
### Repository Format
```
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
```
Example:
```
Owner: anthropics
Name: claude-skills
Branch: main
Subdirectory: skills
```
### Delete Repository
1. Find the repository in the repository list
2. Click the "Delete" button
3. Confirm deletion
After deleting a repository, its skills will not disappear from the list, but they can no longer be updated.
## Skill Card Information
Each skill card displays:
| Information | Description |
|-------------|-------------|
| Name | Skill name |
| Description | Function description |
| Source | Source repository |
| Status | Installed / Not Installed |
## Skill Updates
Automatic updates are not currently supported. To update a skill:
1. Uninstall the existing skill
2. Refresh the list
3. Reinstall
### Empty Skill List
Possible causes:
- Network issues preventing GitHub access
- Incorrect repository configuration
Solutions:
- Check network connection
- Click "Refresh" to retry
- Verify repository configuration
### Installation Failed
Possible causes:
- Network issues
- Insufficient disk space
- Permission issues
Solutions:
- Check network connection
- Check disk space
- Check directory permissions

222
docs/user-manual/en/4-proxy/4.1-service.md Normal file
View File

@@ -0,0 +1,222 @@
# 4.1 Proxy Service
## Overview
The proxy service starts a local HTTP proxy through which all API requests are forwarded.
**Primary uses**:
- Record request logs
- Track API usage
- Support failover
- Centrally manage requests from multiple applications
## Start the Proxy
### Option 1: Main Interface Toggle
Click the **Proxy Toggle** button at the top of the main interface.
Toggle states:
- White: Proxy not running
- Green: Proxy running
![image-20260108011353927](../../assets/image-20260108011353927.png)
### Option 2: Settings Page
1. Open "Settings > Advanced > Proxy Service"
2. Click the toggle in the top-right corner
![image-20260108011338922](../../assets/image-20260108011338922.png)
## Proxy Configuration
### Basic Configuration
| Setting | Description | Default |
|---------|-------------|---------|
| Listen Address | IP address the proxy binds to | `127.0.0.1` |
| Listen Port | Port the proxy listens on | `15721` |
| Enable Logging | Whether to record request logs | Enabled |
### Modify Configuration
1. **Stop the proxy service** (must stop first)
2. Modify the listen address or port
3. Click "Save"
4. Restart the proxy
> Modifying address/port requires stopping the proxy service first
### Listen Address Options
| Address | Description |
|---------|-------------|
| `127.0.0.1` | Only accessible from local machine (recommended) |
| `0.0.0.0` | Allow LAN access |
## Running Status
When the proxy is running, the panel displays the following information:
### Service Address
```
http://127.0.0.1:15721
```
Click the "Copy" button to copy the address.
### Current Providers
Displays the currently used provider for each app:
```
Claude: PackyCode
Codex: AIGoCode
Gemini: Google Official
```
### Statistics
| Metric | Description |
|--------|-------------|
| Active Connections | Number of requests currently being processed |
| Total Requests | Total number of requests since startup |
| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
| Uptime | How long the proxy has been running |
### Failover Queue
The proxy panel displays the failover queue by app type:
```
Claude
├── 1. PackyCode [Currently Using] ●
├── 2. AIGoCode ●
└── 3. Backup Provider ○
Codex
├── 1. AIGoCode [Currently Using] ●
└── 2. Backup Provider ●
```
Queue details:
- Numbers indicate priority order
- "Currently Using" label indicates the active provider
- Health badges show provider status:
- Green: Healthy (0 consecutive failures)
- Yellow: Degraded (1-2 consecutive failures)
- Red: Unhealthy (3+ consecutive failures)
## How It Works
### Request Flow
```mermaid
sequenceDiagram
participant CLI as CLI Tool (Claude)
participant Proxy as Local Proxy (CC Switch)
participant API as API Provider (Anthropic)
participant DB as Data Store (Logger)
CLI->>Proxy: Send API request
Proxy->>DB: Record request log / track usage
Proxy->>API: Forward request
API-->>Proxy: Return response
Proxy-->>CLI: Return response
```
### Configuration Changes
After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
**Claude**:
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
```
**Codex**:
```toml
base_url = "http://127.0.0.1:15721/v1"
```
**Gemini**:
```
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
## Stop the Proxy
### Option 1: Main Interface Toggle
Click the proxy toggle button to turn it off.
### Option 2: Settings Page
Turn off the toggle in the proxy service panel.
### Post-stop Processing
When stopping the proxy, CC Switch will:
1. Restore app configurations to their original state
2. Save request logs
3. Close all connections
## Log Recording
### Enable Logging
Enable the "Enable Logging" toggle in the proxy panel.
### Log Contents
Each request record includes:
| Field | Description |
|-------|-------------|
| Time | Request time |
| App | Claude / Codex / Gemini |
| Provider | Provider used |
| Model | Requested model |
| Tokens | Input/output token count |
| Latency | Request duration |
| Status | Success/failure |
### View Logs
View request logs in the "Settings > Usage" tab.
## FAQ
### Port Already in Use
Error message: `Address already in use`
Solution:
1. Change the port (e.g., to 5001)
2. Or close the program occupying the port
### Proxy Fails to Start
Check:
- Is the port occupied
- Are there sufficient permissions
- Is the firewall blocking it
### Request Timeout
Possible causes:
- Network issues
- Provider server issues
- Incorrect proxy configuration
Solutions:
- Check network connection
- Try accessing the provider API directly
- Check provider configuration

195
docs/user-manual/en/4-proxy/4.2-takeover.md Normal file
View File

@@ -0,0 +1,195 @@
# 4.2 App Takeover
## Overview
App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.
When takeover is enabled:
- The app's API requests are forwarded through the local proxy
- Request logs and usage statistics can be recorded
- Failover functionality becomes available
## Prerequisites
The proxy service must be started before using the app takeover feature.
## Enable Takeover
### Location
Settings > Advanced > Proxy Service > App Takeover area
### Steps
1. Ensure the proxy service is started
2. Find the "App Takeover" area
3. Enable the toggle for the desired apps
### Takeover Toggles
| Toggle | Effect |
|--------|--------|
| Claude Takeover | Intercept Claude Code requests |
| Codex Takeover | Intercept Codex requests |
| Gemini Takeover | Intercept Gemini CLI requests |
Multiple app takeovers can be enabled simultaneously.
## How Takeover Works
### Configuration Changes
When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.
**Claude configuration change**:
```json
// Before takeover
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}
// After takeover
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
```
**Codex configuration change**:
```toml
# Before takeover
base_url = "https://api.openai.com/v1"
# After takeover
base_url = "http://127.0.0.1:15721/v1"
```
**Gemini configuration change**:
```bash
# Before takeover
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
# After takeover
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
### Request Forwarding
When the proxy receives a request:
1. Identifies the request source (Claude/Codex/Gemini)
2. Looks up the currently enabled provider for that app
3. Forwards the request to the provider's actual endpoint
4. Records the request log
5. Returns the response to the app
## Takeover Status Indicators
### Main Interface Indicators
When takeover is enabled, the main interface shows the following changes:
- **Proxy logo color**: Changes from colorless to green
- **Provider cards**: The currently active provider shows a green border
### Provider Card States
| State | Border Color | Description |
|-------|--------------|-------------|
| Currently Active | Blue | Provider in the config file (non-proxy mode) |
| Proxy Active | Green | Provider actually used by the proxy |
| Normal | Default | Unused provider |
## Disable Takeover
### Steps
1. Turn off the corresponding app's takeover toggle in the proxy panel
2. Or directly stop the proxy service
### Configuration Restoration
When disabling takeover, CC Switch will:
1. Restore the app configuration to its pre-takeover state
2. Save current request logs
## Takeover and Provider Switching
### Switching Providers in Takeover Mode
When switching providers in takeover mode:
1. Click the "Enable" button on a provider in the main interface
2. The proxy immediately uses the new provider to forward requests
3. **No need to restart the CLI tool**
This is a major advantage of takeover mode: provider switching takes effect instantly.
### Switching Without Takeover
When switching providers without takeover:
1. Configuration file is modified
2. CLI tool must be restarted for changes to take effect
## Multi-app Takeover
Multiple apps can be taken over simultaneously, each managed independently:
- Independent provider configurations
- Independent failover queues
- Independent request statistics
## Use Cases
### Scenario 1: Usage Monitoring
Enable takeover + log recording to monitor API usage.
### Scenario 2: Quick Switching
With takeover enabled, switching providers does not require restarting CLI tools.
### Scenario 3: Failover
Enabling takeover is a prerequisite for using the failover feature.
## Notes
### Performance Impact
The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.
### Network Requirements
In takeover mode, CLI tools must be able to access the local proxy address.
### Configuration Backup
Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.
## FAQ
### Requests Fail After Takeover
Check:
- Is the proxy service running normally
- Is the provider configuration correct
- Is the network working properly
### Configuration Not Restored After Disabling Takeover
Possible causes:
- Proxy exited abnormally
- Configuration file was modified by another program
Solutions:
- Manually edit the provider and re-save
- Or re-enable and then disable takeover

232
docs/user-manual/en/4-proxy/4.3-failover.md Normal file
View File

@@ -0,0 +1,232 @@
# 4.3 Failover
## Overview
The failover feature automatically switches to a backup provider when the primary provider's request fails, ensuring uninterrupted service.
**Applicable scenarios**:
- Unstable provider services
- High availability requirements
- Long-running tasks
## Prerequisites
Using the failover feature requires:
1. Proxy service started
2. App takeover enabled
3. Failover queue configured
4. Auto failover enabled
## Configure the Failover Queue
### Open Configuration Page
Settings > Advanced > Failover
### Select Application
Three tabs at the top of the page:
- Claude
- Codex
- Gemini
Select the application to configure.
### Add Backup Providers
1. In the "Failover Queue" area
2. Click "Add Provider"
3. Select a provider from the dropdown list
4. The provider is added to the end of the queue
### Adjust Priority
Drag providers to adjust their order:
- Lower numbers mean higher priority
- After the primary provider fails, backup providers are tried in order
### Remove Provider
Click the "Remove" button to the right of the provider.
## Main Interface Quick Actions
When both proxy and failover are enabled, provider cards display a failover toggle.
### Add to Queue
1. Find the provider card
2. Enable the failover toggle
3. The provider is automatically added to the queue
### Remove from Queue
1. Disable the failover toggle on the provider card
2. The provider is removed from the queue
## Enable Auto Failover
### Steps
1. On the failover configuration page
2. Enable the "Auto Failover" toggle
### Toggle Description
| State | Behavior |
|-------|----------|
| Off | Only records failures, no automatic switching |
| On | Automatically switches to the next provider on failure |
## Failover Flow
```mermaid
graph TD
Start[Request arrives at proxy] --> Send[Send to current provider]
Send --> CheckSuccess{Success?}
CheckSuccess -- Yes --> Return[Return response]
CheckSuccess -- No --> LogFail[Record failure]
LogFail --> CheckCircuit{Check circuit breaker}
CheckCircuit -- Tripped --> Skip[Skip this provider]
CheckCircuit -- Not tripped --> IncFail[Increment failure count]
Skip --> Next{Next in queue?}
IncFail --> Next
Next -- Yes --> Switch[Switch provider]
Switch --> Retry[Retry request]
Retry --> Send
Next -- No --> Error[Return error]
```
## Circuit Breaker Configuration
The circuit breaker prevents frequent retries against failing providers.
### Configuration Items
Different apps have independent default configurations. Below are general defaults; Claude has its own relaxed configuration.
| Setting | Description | General Default | Claude Default | Range |
|---------|-------------|-----------------|----------------|-------|
| Failure Threshold | Consecutive failures to trigger circuit breaker | 4 | 8 | 1-20 |
| Recovery Success Threshold | Successes needed in half-open state to close breaker | 2 | 3 | 1-10 |
| Recovery Wait Time | Time before attempting recovery after tripping (seconds) | 60 | 90 | 0-300 |
| Error Rate Threshold | Error rate that opens the circuit breaker | 60% | 70% | 0-100% |
| Minimum Requests | Minimum requests before calculating error rate | 10 | 15 | 5-100 |
> Claude has more relaxed default settings due to longer request times, tolerating more failures.
### Timeout Configuration
| Setting | Description | General Default | Claude Default | Range |
|---------|-------------|-----------------|----------------|-------|
| Stream First Byte Timeout | Max wait time for first data chunk (seconds) | 60 | 90 | 1-120 |
| Stream Idle Timeout | Max interval between data chunks (seconds) | 120 | 180 | 60-600 (0 to disable) |
| Non-stream Timeout | Total timeout for non-streaming requests (seconds) | 600 | 600 | 60-1200 |
### Retry Configuration
| Setting | Description | General Default | Claude Default | Range |
|---------|-------------|-----------------|----------------|-------|
| Max Retries | Number of retries on request failure | 3 | 6 | 0-10 |
> Gemini's default max retries is 5.
### Circuit Breaker States
| State | Description |
|-------|-------------|
| Closed | Normal state, requests allowed |
| Open | Circuit broken, this provider is skipped |
| Half-Open | Attempting recovery, sending probe requests |
### State Transitions
```mermaid
stateDiagram-v2
[*] --> Closed: Initialize
Closed --> Open: Failures >= threshold
Open --> HalfOpen: Recovery wait time expires
HalfOpen --> Closed: Probe successes >= recovery threshold
HalfOpen --> Open: Probe failed
```
## Health Status Indicators
### Provider Cards
Cards display health status badges:
| Badge | Status | Description |
|-------|--------|-------------|
| Green | Healthy | 0 consecutive failures |
| Yellow | Warning | Has failures but circuit not tripped |
| Red | Circuit Broken | Circuit breaker tripped, temporarily skipped |
### Queue List
The failover queue also displays each provider's health status.
## Failover Logs
Each failover event records:
| Information | Description |
|-------------|-------------|
| Time | When it occurred |
| Original Provider | The provider that failed |
| New Provider | The provider switched to |
| Failure Reason | Error message |
Viewable in the request logs within usage statistics.
## Best Practices
### Queue Configuration Recommendations
1. **Primary provider**: The most stable and fastest provider
2. **First backup**: Second-best choice
3. **Second backup**: Last resort
### Circuit Breaker Configuration Recommendations
| Scenario | Failure Threshold | Recovery Wait |
|----------|-------------------|---------------|
| High availability requirement | 2 | 30 seconds |
| General scenario | 3 | 60 seconds |
| Tolerant of occasional failures | 5 | 120 seconds |
### Monitoring Recommendations
Periodically check:
- Health status of each provider
- Failover frequency
- Circuit breaker trigger frequency
## FAQ
### Failover Not Triggering
Check:
1. Is the proxy service running
2. Is app takeover enabled
3. Is auto failover enabled
4. Are there backup providers in the queue
### Failover Triggering Too Frequently
Possible causes:
- Unstable primary provider
- Network issues
- Configuration errors
Solutions:
- Check primary provider status
- Adjust circuit breaker parameters
- Consider changing the primary provider
### All Providers Circuit-Broken
Wait for the recovery wait time to expire for automatic recovery, or:
1. Manually restart the proxy service
2. Reset circuit breaker states

291
docs/user-manual/en/4-proxy/4.4-usage.md Normal file
View File

@@ -0,0 +1,291 @@
# 4.4 Usage Statistics
## Overview
The usage statistics feature records and analyzes API request data, helping you:
- Understand API usage patterns
- Estimate cost expenditure
- Analyze usage patterns
- Troubleshoot issues
## Prerequisites
Using the usage statistics feature requires:
1. Proxy service started
2. App takeover enabled
3. Log recording enabled
## Open Usage Statistics
Settings > Usage Tab
## Statistics Overview
### Summary Cards
Key metrics displayed at the top of the page:
| Metric | Description |
|--------|-------------|
| Total Requests | Total number of requests in the time period |
| Total Tokens | Total input + output tokens |
| Estimated Cost | Cost calculated based on pricing configuration |
| Success Rate | Percentage of successful requests |
### Time Range
Select the time range for statistics:
| Option | Range |
|--------|-------|
| Today | From 00:00 today to now |
| Last 7 Days | Past 7 days |
| Last 30 Days | Past 30 days |
![image-20260108011730105](../../assets/image-20260108011730105.png)
## Trend Charts
### Request Trend
Line chart showing the trend of request counts:
- X-axis: Time
- Y-axis: Request count
- Viewable by hour/day
- Supports zoom and drag
### Token Trend
Shows token usage trends:
- Input Tokens (blue) - Prompt content sent by the user
- Output Tokens (green) - Response content generated by AI
- Cache Creation Tokens (orange) - Tokens consumed when first creating cache
- Cache Hit Tokens (purple) - Tokens saved by reusing cache
- Cost (red dashed line, right Y-axis) - Estimated cost
> **Cache Token explanation**: Anthropic API supports Prompt Caching. Creating cache incurs a higher fee (typically 1.25x input price), but subsequent cache hits only charge 0.1x, significantly reducing costs for repeated requests.
### Time Granularity
- **Today**: Displayed by hour (24 data points)
- **7 Days/30 Days**: Displayed by day
![image-20260108011742847](../../assets/image-20260108011742847.png)
## Detailed Data
Three data tabs at the bottom of the page:
### Request Logs
Detailed record of each request:
| Field | Description |
|-------|-------------|
| Time | Request time |
| Provider | Provider name used |
| Model | Requested model (billing model) |
| Input Tokens | Number of input tokens |
| Output Tokens | Number of output tokens |
| Cache Read | Cache hit token count |
| Cache Creation | Cache creation token count |
| Total Cost | Estimated cost (USD) |
| Timing Info | Request duration, time to first token, streaming/non-streaming |
| Status | HTTP status code |
#### Timing Information
The timing info column displays multiple badges:
| Badge | Description | Color Rules |
|-------|-------------|-------------|
| Total Duration | Total request time (seconds) | <=5s green, <=120s orange, >120s red |
| First Token | Time to first token in streaming requests | <=5s green, <=120s orange, >120s red |
| Stream/Non-stream | Request type | Streaming blue, non-streaming purple |
#### View Details
Click a request row to view detailed information:
- Complete request parameters
- Response content summary
- Error messages (if failed)
#### Filter Logs
Supports filtering by the following criteria:
| Filter | Options |
|--------|---------|
| App Type | All / Claude / Codex / Gemini |
| Status Code | All / 200 / 400 / 401 / 429 / 500 |
| Provider | Text search |
| Model | Text search |
| Time Range | Start time - End time (datetime picker) |
Action buttons:
- **Search**: Apply filter criteria
- **Reset**: Restore defaults (past 24 hours)
- **Refresh**: Reload data
![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)
## Pricing Configuration
### Open Pricing Configuration
Settings > Advanced > Pricing Configuration
### Configure Model Prices
Set prices for each model (per million tokens):
| Field | Description |
|-------|-------------|
| Model ID | Model identifier (e.g., claude-3-sonnet) |
| Display Name | Custom display name |
| Input Price | Price per million input tokens |
| Output Price | Price per million output tokens |
| Cache Read Price | Price per million cache hit tokens |
| Cache Creation Price | Price per million cache creation tokens |
### Operations
- **Add**: Click the "Add" button to add model pricing
- **Edit**: Click the edit icon at the end of the row to modify
- **Delete**: Click the delete icon at the end of the row to remove
![image-20260108011933565](../../assets/image-20260108011933565.png)
### Preset Prices
CC Switch includes preset official prices for common models (per million tokens):
**Claude Series (USD)**:
| Model | Input | Output | Cache Read | Cache Creation |
|-------|-------|--------|------------|----------------|
| **Claude 4.5 Series** | | | | |
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
| **Claude 4 Series** | | | | |
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
| **Claude 3.5 Series** | | | | |
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
**OpenAI Series / Codex (USD)**:
| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| **GPT-5.2 Series** | | | |
| gpt-5.2 | $1.75 | $14 | $0.175 |
| **GPT-5.1 Series** | | | |
| gpt-5.1 | $1.25 | $10 | $0.125 |
| **GPT-5 Series** | | | |
| gpt-5 | $1.25 | $10 | $0.125 |
> Note: Codex presets include low/medium/high variants with prices identical to the base model.
**Gemini Series (USD)**:
| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| **Gemini 3 Series** | | | |
| gemini-3-pro-preview | $2 | $12 | $0.20 |
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
| **Gemini 2.5 Series** | | | |
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
**Chinese Provider Models (CNY)**:
| Model | Input | Output | Cache Read |
|-------|-------|--------|------------|
| **DeepSeek** | | | |
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
| **Kimi (Moonshot)** | | | |
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
| **MiniMax** | | | |
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
| **Others** | | | |
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
| mimo-v2-flash | Free | Free | - |
### Custom Prices
If using proxy services, prices may differ:
1. Click the "Edit" button
2. Modify prices
3. Save
## FAQ
### Statistics Data Is Empty
Check:
- Is the proxy service running
- Is app takeover enabled
- Is log recording enabled
- Have requests been going through the proxy
### Cost Estimates Are Inaccurate
Possible causes:
- Pricing configuration doesn't match actual prices
- Using a proxy service with special pricing
Solutions:
- Update pricing configuration
- Refer to the provider's actual invoices
### Token Count Differs from Provider
CC Switch uses its own method to estimate token counts, which may slightly differ from the provider's calculation. Refer to the provider's invoice for authoritative numbers.

156
docs/user-manual/en/4-proxy/4.5-model-test.md Normal file
View File

@@ -0,0 +1,156 @@
# 4.5 Model Test
## Overview
The model test feature verifies whether a provider's configured model is available by sending actual API requests to test:
- Whether the model exists
- Whether the API Key is valid
- Whether the endpoint responds normally
- Whether the response latency is acceptable
## Open Configuration
Settings > Advanced > Model Test Config
## Test Model Configuration
Configure the model used for testing per application:
| Application | Setting | Default | Notes |
|-------------|---------|---------|-------|
| Claude | Claude Model | System default | Recommend using Haiku series (low cost, fast) |
| Codex | Codex Model | System default | Recommend using mini series |
| Gemini | Gemini Model | System default | Recommend using Flash series |
### Model Selection Tips
When choosing a test model, consider:
1. **Cost**: Choose lower-priced models (e.g., Haiku, Mini, Flash)
2. **Speed**: Choose fast-responding models
3. **Availability**: Choose models supported by the provider
## Test Parameter Configuration
### Timeout
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| Timeout | Single request timeout | 45 seconds | 10-120 seconds |
Setting it too short may cause false negatives; too long delays fault detection.
### Retries
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| Max Retries | Retries after failure | 2 times | 0-5 times |
Increase retries when the network is unstable.
### Degradation Threshold
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| Degradation Threshold | Responses exceeding this time are marked as degraded | 6000ms | 1000-30000ms |
Providers exceeding the threshold are marked as "degraded" but remain usable.
## Execute Model Test
### Manual Test
Click the "Test" button on the provider card:
1. Sends a test request to the configured endpoint
2. Uses the configured test model
3. Waits for response or timeout
4. Displays the test result
### Test Content
The test request:
- Sends a short prompt (e.g., "Hi")
- Limits maximum output tokens (typically 10-50)
- Uses streaming response to detect time to first byte
## Test Results
### Health Status
| Status | Icon | Description |
|--------|------|-------------|
| Healthy | Green | Normal response, latency within threshold |
| Degraded | Yellow | Normal response, but latency exceeds threshold |
| Unavailable | Red | Request failed or timed out |
### Result Information
After testing completes, displays:
- Response latency (milliseconds)
- Time to first byte (TTFB)
- Error message (if failed)
## Integration with Failover
Model testing works in conjunction with the failover feature:
### Health Checks
After enabling the proxy service, the system periodically performs health checks on providers in the failover queue:
1. Sends a request using the configured test model
2. Updates health status based on the response
3. Unhealthy providers are temporarily skipped
### Circuit Breaker Recovery
When a provider recovers from a circuit-broken state:
1. Performs a model test to verify availability
2. If the test passes, normal status is restored
3. If the test fails, the circuit breaker remains active
## FAQ
### Test Fails But Actually Available
**Possible causes**:
- The test model differs from the actually used model
- The provider doesn't support the configured test model
**Solutions**:
- Change the test model to one supported by the provider
- Check the provider's model list
### High Latency
**Possible causes**:
- Network latency
- High server load on the provider
- Slow model response
**Solutions**:
- Use a faster test model
- Adjust the degradation threshold
- Consider using mirror endpoints
### Frequent Timeouts
**Possible causes**:
- Timeout set too short
- Unstable network
- Unstable provider service
**Solutions**:
- Increase the timeout
- Increase retry count
- Check network connection
## Notes
- Model testing consumes a small amount of API quota
- Recommend using low-cost models for testing
- Testing frequency should not be too high to avoid wasting quota
- Different providers may support different models

340
docs/user-manual/en/5-faq/5.1-config-files.md Normal file
View File

@@ -0,0 +1,340 @@
# 5.1 Configuration Files
## CC Switch Data Storage
### Storage Directory
Default location: `~/.cc-switch/`
Customizable location in settings (for cloud sync).
### Directory Structure
```
~/.cc-switch/
├── cc-switch.db # SQLite database
├── settings.json # Device-level settings
└── backups/ # Automatic backups
├── backup-20251230-120000.json
├── backup-20251229-180000.json
└── ...
```
### Database Contents
`cc-switch.db` is a SQLite database that stores:
| Table | Contents |
|-------|----------|
| providers | Provider configurations |
| provider_endpoints | Provider endpoint candidate list |
| mcp_servers | MCP server configurations |
| prompts | Prompt presets |
| skills | Skill installation status |
| skill_repos | Skill repository configurations |
| proxy_config | Proxy configuration |
| proxy_request_logs | Proxy request logs |
| provider_health | Provider health status |
| model_pricing | Model pricing |
| settings | App settings |
### Device Settings
`settings.json` stores device-level settings:
```json
{
"language": "zh",
"theme": "system",
"windowBehavior": "minimize",
"autoStart": false,
"claudeConfigDir": null,
"codexConfigDir": null,
"geminiConfigDir": null,
"opencodeConfigDir": null,
"openclawConfigDir": null
}
```
These settings are not synced across devices.
### Automatic Backups
The `backups/` directory stores automatic backups:
- Automatically created before each configuration import
- Retains the most recent 10 backups
- File names include timestamps
## Claude Code Configuration
### Configuration Directory
Default: `~/.claude/`
### Key Files
```
~/.claude/
├── settings.json # Main configuration file
├── CLAUDE.md # System prompt
└── skills/ # Skills directory
└── ...
```
### settings.json
```json
{
"env": {
"ANTHROPIC_API_KEY": "sk-xxx",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
},
"permissions": {
"allow_file_access": true
}
}
```
| Field | Description |
|-------|-------------|
| `env.ANTHROPIC_API_KEY` | API key |
| `env.ANTHROPIC_BASE_URL` | API endpoint (optional) |
| `env.ANTHROPIC_AUTH_TOKEN` | Alternative authentication method |
### MCP Configuration
MCP server configuration is in `~/.claude.json`:
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
## Codex Configuration
### Configuration Directory
Default: `~/.codex/`
### Key Files
```
~/.codex/
├── auth.json # Authentication configuration
├── config.toml # Main configuration + MCP
└── AGENTS.md # System prompt
```
### auth.json
```json
{
"OPENAI_API_KEY": "sk-xxx"
}
```
### config.toml
```toml
# Basic configuration
base_url = "https://api.openai.com/v1"
model = "gpt-4"
# MCP servers
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```
## Gemini CLI Configuration
### Configuration Directory
Default: `~/.gemini/`
### Key Files
```
~/.gemini/
├── .env # Environment variables (API Key)
├── settings.json # Main configuration + MCP
└── GEMINI.md # System prompt
```
### .env
```bash
GEMINI_API_KEY=xxx
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GEMINI_MODEL=gemini-pro
```
### settings.json
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
| Field | Description |
|-------|-------------|
| `mcpServers` | MCP server configuration |
## OpenCode Configuration
### Configuration Directory
Default: `~/.opencode/`
### Key Files
```
~/.opencode/
├── config.json # Main configuration file
├── AGENTS.md # System prompt
└── skills/ # Skills directory
└── ...
```
## OpenClaw Configuration
### Configuration Directory
Default: `~/.openclaw/`
### Key Files
```
~/.openclaw/
├── openclaw.json # Main configuration file (JSON5 format)
├── AGENTS.md # System prompt
└── skills/ # Skills directory
└── ...
```
### openclaw.json
OpenClaw uses a JSON5 format configuration file with the following main sections:
```json5
{
// Model provider configuration
models: {
mode: "merge",
providers: {
"custom-provider": {
baseUrl: "https://api.example.com/v1",
apiKey: "your-api-key",
api: "openai-completions",
models: [{ id: "model-id", name: "Model Name" }]
}
}
},
// Environment variables
env: {
ANTHROPIC_API_KEY: "sk-..."
},
// Agent default model configuration
agents: {
defaults: {
model: {
primary: "provider/model"
}
}
},
// Tool configuration
tools: {},
// Workspace file configuration
workspace: {}
}
```
| Field | Description |
|-------|-------------|
| `models.providers` | Provider configuration (mapped to CC Switch's "providers") |
| `env` | Environment variable configuration |
| `agents.defaults` | Agent default model settings |
| `tools` | Tool configuration |
| `workspace` | Workspace file management |
## Configuration Priority
CC Switch's priority when modifying configurations:
1. **CC Switch Database** - Single source of truth (SSOT)
2. **Live Configuration Files** - Written when switching providers
3. **Backfill Mechanism** - Reads from live files when editing the current provider
## Manual Configuration Editing
### Safe to Edit Manually
- CLI tool configuration files (will be backfilled by CC Switch)
- CC Switch's `settings.json`
### Not Recommended to Edit Manually
- `cc-switch.db` database file
- Backup files
### Sync After Editing
If you manually edit CLI tool configurations:
1. Open CC Switch
2. Edit the corresponding provider
3. You will see the manual changes have been backfilled
4. Save to sync to the database
## Configuration Migration
### Migrating from Older Versions
CC Switch v3.7.0 migrated from JSON files to SQLite:
- Automatic migration on first launch
- Displays a notification upon successful migration
- Old configuration files are retained as backups
### Cross-device Migration
1. Export configuration on the source device
2. Import configuration on the target device
3. Or use the cloud sync feature
## Configuration Backup Recommendations
### Regular Backups
It is recommended to regularly export configurations:
1. Settings > Advanced > Data Management
2. Click "Export"
3. Save to a secure location
### Backup Contents
The export file includes:
- All provider configurations
- MCP server configurations
- Prompt presets
- App settings
### Not Included
- Usage logs (large data volume)
- Device-level settings (not suitable for cross-device)

220
docs/user-manual/en/5-faq/5.2-questions.md Normal file
View File

@@ -0,0 +1,220 @@
# 5.2 Frequently Asked Questions
## Installation Issues
### macOS Shows "Unidentified Developer"
**Problem**: First launch shows "Cannot open because it is from an unidentified developer"
**Solution 1**: Via System Settings
1. Close the warning dialog
2. Open "System Settings" > "Privacy & Security"
3. Find the CC Switch prompt
4. Click "Open Anyway"
5. Reopen the app
**Solution 2**: Via Terminal command (recommended)
```bash
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
```
The app can be opened normally after running this command.
### Windows: App Doesn't Launch After Installation
**Possible causes**:
- Missing WebView2 runtime
- Antivirus software blocking
**Solutions**:
1. Install [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
2. Add CC Switch to your antivirus software's whitelist
### Linux: Startup Error
**Problem**: AppImage won't start
**Solution**:
```bash
# Add execute permission
chmod +x CC-Switch-*.AppImage
# If it still fails, try
./CC-Switch-*.AppImage --no-sandbox
```
## Provider Issues
### Provider Switch Doesn't Take Effect
**Cause**: The CLI tool needs to reload its configuration
**Solutions**:
- Claude Code: Close and reopen the terminal, or restart the IDE
- Codex: Close and reopen the terminal
- Gemini: Tray switching takes effect immediately, no restart needed
### API Key Invalid
**Troubleshooting steps**:
1. Confirm the API Key is copied correctly (no extra spaces)
2. Confirm the API Key hasn't expired
3. Confirm the endpoint URL is correct
4. Use the speed test to verify connectivity
### How to Restore Official Login
**Steps**:
1. Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini)
2. Click "Enable"
3. Restart the corresponding CLI tool
4. Follow the CLI tool's login flow
## Proxy Issues
### Proxy Service Fails to Start
**Possible cause**: Port is occupied
**Solution**:
1. Check port usage:
```bash
# macOS/Linux
lsof -i :49152
# Windows
netstat -ano | findstr :49152
```
2. Close the program occupying the port
3. Or try modifying the configuration to restore the default port:
- Open "Settings > Proxy Service"
- Click the "Reset to Default" button
### Request Timeout in Proxy Mode
**Possible causes**:
- Network issues
- Provider server issues
- Incorrect proxy configuration
**Solutions**:
1. Check network connection
2. Try accessing the provider API directly (disable proxy)
3. Check if provider configuration is correct
### Configuration Not Restored After Disabling Proxy
**Possible cause**: Proxy exited abnormally
**Solution**:
1. Edit the current provider
2. Check if the endpoint URL is correct
3. Save to update the configuration
## Failover Issues
### Failover Not Triggering
**Checklist**:
- [ ] Is the proxy service running
- [ ] Is app takeover enabled
- [ ] Is auto failover enabled
- [ ] Are there backup providers in the queue
### Failover Triggering Too Frequently
**Possible causes**:
- Unstable primary provider
- Circuit breaker threshold set too low
**Solutions**:
1. Check primary provider status
2. Increase the failure threshold (e.g., from 3 to 5)
3. Consider changing the primary provider
### All Providers Are Circuit-Broken
**Solutions**:
1. Wait for the recovery wait time to expire (default 60 seconds)
2. Or restart the proxy service to reset states
## Data Issues
### Configuration Lost
**Possible causes**:
- Configuration directory was deleted
- Database corruption
**Solutions**:
1. Check if the `~/.cc-switch/` directory exists
2. Restore from backup: `~/.cc-switch/backups/`
3. Or import from a previously exported configuration file
### Import Configuration Failed
**Possible causes**:
- Incorrect file format
- Version incompatibility
**Solutions**:
1. Confirm the file was exported by CC Switch
2. Check if the file content is complete
3. Try opening with a text editor to check format
### Usage Statistics Data Is Empty
**Checklist**:
- [ ] Is the proxy service running
- [ ] Is app takeover enabled
- [ ] Is log recording enabled
- [ ] Have requests been going through the proxy
## Other Issues
### Tray Icon Not Showing
**macOS**:
- Check menu bar icon settings in System Settings
**Windows**:
- Check taskbar settings to ensure the CC Switch icon is not hidden
**Linux**:
- System tray support may need to be installed (e.g., `libappindicator`)
### UI Display Issues
**Solutions**:
1. Try switching themes (light/dark)
2. Restart the app
3. Delete `~/.cc-switch/settings.json` to reset settings
### Update Failed
**Solutions**:
1. Check network connection
2. Manually download and install the latest version
3. If using Homebrew: `brew upgrade --cask cc-switch`
## Getting Help
### Submit an Issue
If none of the above solutions work:
1. Visit [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
2. Search for similar issues
3. If none found, create a new Issue
4. Provide the following information:
- Operating system and version
- CC Switch version
- Problem description and reproduction steps
- Error messages (if any)
### Log Files
Attach log files when submitting an Issue:
- macOS/Linux: `~/.cc-switch/logs/`
- Windows: `%APPDATA%\cc-switch\logs\`

256
docs/user-manual/en/5-faq/5.3-deeplink.md Normal file
View File

@@ -0,0 +1,256 @@
# 5.3 Deep Link Protocol
## Overview
CC Switch supports the `ccswitch://` deep link protocol, enabling one-click configuration import via links.
**Use cases**:
- Team configuration sharing
- One-click setup in tutorials
- Quick sync across devices
## Online Generator Tool
CC Switch provides an online deep link generator tool:
**URL**: [https://farion1231.github.io/cc-switch/deplink.html](https://farion1231.github.io/cc-switch/deplink.html)
### How to Use
1. Open the above URL
2. Select the import type (Provider/MCP/Prompt)
3. Fill in the configuration information
4. Click "Generate Link"
5. Copy the generated deep link
6. Share with others or use on other devices
## Protocol Format
### V1 Protocol
Uses URL parameter format, easy to read and generate:
```
ccswitch://v1/import?resource={type}&app={app}&name={name}&...
```
**Common parameters**:
| Parameter | Required | Description |
|-----------|----------|-------------|
| `resource` | Yes | Resource type: `provider` / `mcp` / `prompt` / `skill` |
| `app` | Yes | App type: `claude` / `codex` / `gemini` / `opencode` / `openclaw` |
| `name` | Yes | Name |
**Provider parameters** (resource=provider):
| Parameter | Required | Description |
|-----------|----------|-------------|
| `endpoint` | No | API endpoint URL (supports comma-separated multiple URLs) |
| `apiKey` | No | API key |
| `homepage` | No | Provider website |
| `model` | No | Default model |
| `haikuModel` | No | Haiku model (Claude only) |
| `sonnetModel` | No | Sonnet model (Claude only) |
| `opusModel` | No | Opus model (Claude only) |
| `notes` | No | Notes |
| `icon` | No | Icon |
| `config` | No | Base64-encoded configuration content |
| `configFormat` | No | Configuration format: `json` / `toml` |
| `configUrl` | No | Remote configuration URL |
| `enabled` | No | Whether to enable (boolean) |
| `usageScript` | No | Usage query script |
| `usageEnabled` | No | Whether to enable usage query (default true) |
| `usageApiKey` | No | Usage query API Key |
| `usageBaseUrl` | No | Usage query base URL |
| `usageAccessToken` | No | Usage query access token |
| `usageUserId` | No | Usage query user ID |
| `usageAutoInterval` | No | Auto query interval (minutes) |
**Prompt parameters** (resource=prompt):
| Parameter | Required | Description |
|-----------|----------|-------------|
| `content` | Yes | Prompt content |
| `description` | No | Description |
| `enabled` | No | Whether to enable (boolean) |
**MCP parameters** (resource=mcp):
| Parameter | Required | Description |
|-----------|----------|-------------|
| `apps` | Yes | App list (comma-separated, e.g., `claude,codex,gemini,opencode`) |
| `config` | Yes | MCP server configuration (JSON format) |
| `enabled` | No | Whether to enable (boolean) |
**Skill parameters** (resource=skill):
| Parameter | Required | Description |
|-----------|----------|-------------|
| `repo` | Yes | Repository (format: `owner/name`) |
| `directory` | No | Directory path |
| `branch` | No | Git branch |
**Example**:
```
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
```
## Import Type Examples
### Import Provider
```
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
```
### Import MCP Server
```
ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch
```
### Import Prompt Preset
```
ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6
```
### Import Skill
```
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
```
## Generate Deep Links
### Manual Generation
1. Prepare parameters
2. Assemble the URL following V1 protocol format
3. URL-encode special characters
**Example**:
```javascript
const params = new URLSearchParams({
resource: 'provider',
app: 'claude',
name: 'My Provider',
endpoint: 'https://api.example.com',
apiKey: 'sk-xxx'
});
const url = `ccswitch://v1/import?${params.toString()}`;
```
### Online Tool
Using CC Switch's official online deep link generator tool is more convenient.
## Using Deep Links
### Click the Link
Click a deep link in a browser or other application:
1. The system asks whether to open CC Switch
2. After confirming, CC Switch opens
3. An import confirmation dialog is displayed
4. Confirm the import
### Import Confirmation
A confirmation dialog is shown before import, containing:
- Import type
- Configuration preview
- Confirm/Cancel buttons
**Security tip**: Only import configurations from trusted sources.
## Protocol Registration
### Automatic Registration
CC Switch automatically registers the `ccswitch://` protocol during installation.
### Manual Registration
If the protocol is not registered correctly:
**macOS**:
Reinstall the app, or run:
```bash
/usr/bin/open -a "CC Switch" --args --register-protocol
```
**Windows**:
Reinstall the app, or check the registry:
```
HKEY_CLASSES_ROOT\ccswitch
```
**Linux**:
Check the `MimeType` configuration in the `.desktop` file.
## Security Considerations
### Sensitive Information
Deep links may contain sensitive information (e.g., API Keys):
- Do not share links containing API Keys in public
- Remove or replace sensitive information before sharing
- Use secure channels to transmit links
### Source Verification
Before import, CC Switch will:
1. Validate the data format
2. Display a configuration preview
3. Require user confirmation
### Malicious Link Protection
CC Switch checks:
- Whether the data format is valid
- Whether required fields are complete
- Whether configuration values are within reasonable ranges
## Example Links
### Example: Import Claude Provider
```
ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com
```
### Example: Import MCP Server
```
ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D
```
## Troubleshooting
### Link Won't Open
**Check**:
1. Is CC Switch installed
2. Is the protocol registered correctly
3. Is the link format correct
### Import Failed
**Possible causes**:
- Base64 encoding error
- JSON format error
- Missing required fields
**Solutions**:
1. Check the original JSON format
2. Re-encode in Base64
3. Ensure all required fields are present

108
docs/user-manual/en/5-faq/5.4-env-conflict.md Normal file
View File

@@ -0,0 +1,108 @@
# 5.4 Environment Variable Conflicts
## Overview
CC Switch automatically detects conflicts between system environment variables and app configurations, preventing configurations from being unexpectedly overridden.
**Detected environment variables**:
- `ANTHROPIC_API_KEY` - Claude API key
- `ANTHROPIC_BASE_URL` - Claude API endpoint
- `OPENAI_API_KEY` - OpenAI API key
- `GEMINI_API_KEY` - Gemini API key
- Other related environment variables
## Conflict Warning
When a conflict is detected, a yellow warning banner appears at the top of the interface:
```
Warning: Environment variable conflict detected
Found X environment variables that may conflict with CC Switch configuration
[Expand] [Dismiss]
```
## View Conflict Details
Click the "Expand" button to view detailed information:
| Field | Description |
|-------|-------------|
| Variable Name | Environment variable name |
| Variable Value | Currently set value |
| Source | Where the variable originates from |
### Source Types
| Source | Description |
|--------|-------------|
| User Registry | Windows user-level environment variable |
| System Registry | Windows system-level environment variable |
| Shell Configuration | macOS/Linux shell configuration file |
| System Environment | System-level environment variable |
## Resolve Conflicts
### Select Variables to Remove
1. Check the environment variables you want to remove
2. Or click "Select All" to select all conflicting variables
### Remove Variables
1. Click the "Remove Selected" button
2. Confirm the removal operation
3. CC Switch will automatically back up and remove the selected variables
### Automatic Backup
A backup is automatically created before removal:
- Backup location: `~/.cc-switch/env-backups/`
- Backup format: JSON file
- Includes variable name, value, source, and other information
## Dismiss Warning
If you confirm the conflict does not affect usage, you can:
1. Click the "Dismiss" button on the right side of the warning banner
2. The warning will be temporarily hidden
3. Detection will run again on next launch
## Manual Resolution
If you prefer not to use CC Switch to remove variables, you can handle them manually:
### Windows
1. Open "System Properties > Advanced > Environment Variables"
2. Find the conflicting variable in User or System variables
3. Delete or modify the variable
### macOS / Linux
1. Edit the shell configuration file (e.g., `~/.zshrc`, `~/.bashrc`)
2. Delete or comment out the relevant `export` statements
3. Reload the configuration: `source ~/.zshrc`
## Why Do Conflicts Occur
Environment variables typically take priority over configuration files, which may cause:
- CC Switch provider configurations being overridden
- API requests being sent to the wrong endpoint
- Using the wrong API key
## Best Practices
1. **Use CC Switch to manage configurations**: Avoid setting API keys in system environment variables
2. **Check regularly**: Pay attention to conflict warnings and address them promptly
3. **Back up important variables**: Confirm backups exist before removal
## Restore Deleted Variables
If you accidentally deleted environment variables:
1. Find the backup file: `~/.cc-switch/env-backups/`
2. Open the corresponding JSON file
3. Manually restore the variable to the system environment

111
docs/user-manual/en/README.md Normal file
View File

@@ -0,0 +1,111 @@
# CC Switch User Manual
> All-in-One Assistant for Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw
## Table of Contents
```
CC Switch User Manual
│
├── 1. Getting Started
│ ├── 1.1 Introduction
│ ├── 1.2 Installation Guide
│ ├── 1.3 Interface Overview
│ ├── 1.4 Quick Start
│ └── 1.5 Personalization
│
├── 2. Provider Management
│ ├── 2.1 Add Provider
│ ├── 2.2 Switch Provider
│ ├── 2.3 Edit Provider
│ ├── 2.4 Sort & Duplicate
│ └── 2.5 Usage Query
│
├── 3. Extensions
│ ├── 3.1 MCP Server Management
│ ├── 3.2 Prompts Management
│ └── 3.3 Skills Management
│
├── 4. Proxy & High Availability
│ ├── 4.1 Proxy Service
│ ├── 4.2 App Takeover
│ ├── 4.3 Failover
│ ├── 4.4 Usage Statistics
│ └── 4.5 Model Test
│
└── 5. FAQ
├── 5.1 Configuration Files
├── 5.2 FAQ
├── 5.3 Deep Link Protocol
└── 5.4 Environment Variable Conflicts
```
## File List
### 1. Getting Started
| File | Description |
|------|-------------|
| [1.1-introduction.md](./1-getting-started/1.1-introduction.md) | Introduction, core features, supported platforms |
| [1.2-installation.md](./1-getting-started/1.2-installation.md) | Windows/macOS/Linux installation guide |
| [1.3-interface.md](./1-getting-started/1.3-interface.md) | Interface layout, navigation bar, provider cards |
| [1.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5-minute quick start tutorial |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | Language, theme, directories, cloud sync settings |
### 2. Provider Management
| File | Description |
|------|-------------|
| [2.1-add.md](./2-providers/2.1-add.md) | Using presets, custom configuration, universal providers |
| [2.2-switch.md](./2-providers/2.2-switch.md) | Main UI switching, tray switching, activation methods |
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, backfill mechanism |
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | Drag-to-reorder, duplicate provider, delete |
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | Usage query, remaining balance, multi-plan display |
### 3. Extensions
| File | Description |
|------|-------------|
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP protocol, add servers, app binding |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | Create presets, activate/switch, smart backfill |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | Discover skills, install/uninstall, repository management |
### 4. Proxy & High Availability
| File | Description |
|------|-------------|
| [4.1-service.md](./4-proxy/4.1-service.md) | Start proxy, configuration, running status |
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | App takeover, configuration changes, status indicators |
| [4.3-failover.md](./4-proxy/4.3-failover.md) | Failover queue, circuit breaker, health status |
| [4.4-usage.md](./4-proxy/4.4-usage.md) | Usage statistics, trend charts, pricing configuration |
| [4.5-model-test.md](./4-proxy/4.5-model-test.md) | Model test, health check, latency testing |
### 5. FAQ
| File | Description |
|------|-------------|
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch storage, CLI configuration file formats |
| [5.2-questions.md](./5-faq/5.2-questions.md) | Frequently asked questions |
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | Deep link protocol, generation and usage |
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | Environment variable conflict detection and resolution |
## Quick Links
- **New users**: Start with [1.1 Introduction](./1-getting-started/1.1-introduction.md)
- **Installation issues**: See [1.2 Installation Guide](./1-getting-started/1.2-installation.md)
- **Configure providers**: See [2.1 Add Provider](./2-providers/2.1-add.md)
- **Using proxy**: See [4.1 Proxy Service](./4-proxy/4.1-service.md)
- **Having trouble**: See [5.2 FAQ](./5-faq/5.2-questions.md)
## Version Information
- Documentation version: v3.11.1
- Last updated: 2026-03-02
- Applicable to CC Switch v3.11.1+
## Contributing
Feel free to submit Issues or PRs to improve the documentation:
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
- [GitHub Repository](https://github.com/farion1231/cc-switch)

65
docs/user-manual/ja/1-getting-started/1.1-introduction.md Normal file
View File

@@ -0,0 +1,65 @@
# 1.1 ソフトウェア紹介
## CC Switch とは
CC Switch はクロスプラットフォームのデスクトップアプリケーションで、AI プログラミングツールを使用する開発者向けに設計されています。**Claude Code**、**Codex**、**Gemini CLI**、**OpenCode**、**OpenClaw** の 5 つの AI プログラミングツールの設定を統一的に管理できます。
## どのような問題を解決するか
日常の開発で、以下のような課題に直面することがあります：
- **複数プロバイダーの切り替えが面倒**：異なる API プロバイダー（公式、中継サービスなど）を使用する際、設定ファイルを手動で変更する必要がある
- **設定が分散して管理しづらい**：Claude、Codex、Gemini、OpenCode、OpenClaw がそれぞれ独立した設定ファイルを持ち、フォーマットも異なる
- **使用量を監視できない**：API をどれだけ呼び出したか、いくらかかったかが分からない
- **サービスが不安定**：単一プロバイダーに問題が発生すると、ワークフロー全体が中断する
CC Switch は統一されたインターフェースでこれらの問題を解決します。
## 主要機能
### プロバイダー管理
- ワンクリックで複数の API プロバイダー設定を切り替え
- プリセットテンプレートで一般的なプロバイダーを素早く追加
- 統一プロバイダー機能で、アプリ間で設定を共有
- 使用量クエリと残額表示
- エンドポイント速度テスト
### 拡張機能
- **MCP サーバー**：Model Context Protocol サーバーを管理し、AI の機能を拡張
- **Prompts**：システムプロンプトのプリセットを管理し、さまざまなシーンで素早く切り替え
- **Skills**：スキル拡張のインストールと管理
### プロキシと高可用性
- ローカルプロキシサービスで、リクエストログと使用量統計を記録
- 自動フェイルオーバー、メインプロバイダーの障害時にバックアップへ自動切り替え
- サーキットブレーカー機能で、障害プロバイダーへの頻繁なリトライを防止
- 詳細な Token 使用量トラッキングとコスト見積もり
## 対応アプリケーション
| アプリ | 説明 |
|------|------|
| **Claude Code** | Anthropic 公式の AI プログラミングアシスタント |
| **Codex** | OpenAI のコード生成ツール |
| **Gemini CLI** | Google の AI コマンドラインツール |
| **OpenCode** | オープンソース AI プログラミングターミナルツール |
| **OpenClaw** | オープンソース AI プログラミングアシスタント（マルチプロバイダーゲートウェイ） |
## 対応プラットフォーム
- **Windows** 10 以上
- **macOS** 10.15 (Catalina) 以上
- **Linux** Ubuntu 22.04+ / Debian 11+ / Fedora 34+
## 技術アーキテクチャ
CC Switch はモダンな技術スタックで構築されています：
- **フロントエンド**：React 18 + TypeScript + Tailwind CSS
- **バックエンド**：Tauri 2 + Rust
- **データストレージ**：SQLite（プロバイダー、MCP、Prompts）+ JSON（デバイス設定）
このアーキテクチャにより：
- クロスプラットフォームでの一貫した体験
- ネイティブレベルのパフォーマンス
- 安全なローカルデータストレージ

229
docs/user-manual/ja/1-getting-started/1.2-installation.md Normal file
View File

@@ -0,0 +1,229 @@
# 1.2 インストールガイド
## 前提条件
### Node.js のインストール
CC Switch が管理する CLI ツール（Claude Code、Codex、Gemini CLI）には Node.js 環境が必要です。
**推奨バージョン**：Node.js 18 LTS 以上
#### Windows
1. [Node.js 公式サイト](https://nodejs.org/) にアクセス
2. LTS バージョンのインストーラーをダウンロード
3. インストーラーを実行し、指示に従ってインストール
4. インストールの確認：
```bash
node --version
npm --version
```
#### macOS
```bash
# Homebrew でインストール
brew install node
# または nvm を使用（推奨）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
```
#### Linux
```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
# または nvm を使用
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
```
### CLI ツールのインストール
#### Claude Code
**方法 1：Homebrew（macOS 推奨）**
```bash
brew install claude-code
```
**方法 2：npm**
```bash
npm install -g @anthropic-ai/claude-code
```
#### Codex
**方法 1：Homebrew（macOS 推奨）**
```bash
brew install codex
```
**方法 2：npm**
```bash
npm install -g @openai/codex
```
#### Gemini CLI
**方法 1：Homebrew（macOS 推奨）**
```bash
brew install gemini-cli
```
**方法 2：npm**
```bash
npm install -g @google/gemini-cli
```
---
## Windows
### インストーラー方式
1. [Releases ページ](https://github.com/farion1231/cc-switch/releases) にアクセス
2. `CC-Switch-v{バージョン}-Windows.msi` をダウンロード
3. インストーラーをダブルクリックして実行
4. 指示に従ってインストール
### ポータブル版（インストール不要）
1. `CC-Switch-v{バージョン}-Windows-Portable.zip` をダウンロード
2. 任意のディレクトリに展開
3. `CC-Switch.exe` を実行
## macOS
### 方法 1：Homebrew（推奨）
```bash
# tap を追加
brew tap farion1231/ccswitch
# インストール
brew install --cask cc-switch
```
最新バージョンに更新：
```bash
brew upgrade --cask cc-switch
```
### 方法 2：手動ダウンロード
1. `CC-Switch-v{バージョン}-macOS.zip` をダウンロード
2. 展開して `CC Switch.app` を取得
3. 「アプリケーション」フォルダにドラッグ
### 初回起動時の警告
開発者が Apple 開発者アカウントを持っていないため、初回起動時に「不明な開発者」の警告が表示される場合があります：
**推奨される解決方法**：
ターミナルで以下のコマンドを実行してください：
```bash
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
```
**別の解決方法（システム設定から）**：
1. 警告ダイアログを閉じる
2. 「システム設定」→「プライバシーとセキュリティ」を開く
3. CC Switch に関する表示を見つけ、「このまま開く」をクリック
4. 再度アプリを開くと正常に使用可能
## Linux
### ArchLinux
AUR ヘルパーを使用してインストール：
```bash
# paru を使用
paru -S cc-switch-bin
# または yay を使用
yay -S cc-switch-bin
```
### Debian / Ubuntu
1. `CC-Switch-v{バージョン}-Linux.deb` をダウンロード
2. インストール：
```bash
sudo dpkg -i CC-Switch-v{バージョン}-Linux.deb
# 依存関係に問題がある場合
sudo apt-get install -f
```
### AppImage（汎用）
1. `CC-Switch-v{バージョン}-Linux.AppImage` をダウンロード
2. 実行権限を追加：
```bash
chmod +x CC-Switch-v{バージョン}-Linux.AppImage
```
3. 実行：
```bash
./CC-Switch-v{バージョン}-Linux.AppImage
```
## インストールの確認
インストール完了後、CC Switch を起動します：
1. アプリウィンドウが正常に表示される
2. システムトレイに CC Switch のアイコンが表示される
3. Claude / Codex / Gemini の 3 つのアプリを切り替えられる
## 自動更新
CC Switch には自動更新機能が内蔵されています：
- 起動時に自動で更新を確認
- 新しいバージョンがある場合、画面に更新通知を表示
- クリックするとダウンロードしてインストール
「設定 → バージョン情報」から手動で更新を確認することもできます。
## アンインストール
### Windows
- 「設定 → アプリ」からアンインストール
- またはインストールディレクトリのアンインストーラーを実行
### macOS
- `CC Switch.app` をゴミ箱に移動
- オプション：設定ディレクトリ `~/.cc-switch/` を削除
### Linux
```bash
# Debian/Ubuntu
sudo apt remove cc-switch
# ArchLinux
paru -R cc-switch-bin
```

170
docs/user-manual/ja/1-getting-started/1.3-interface.md Normal file
View File

@@ -0,0 +1,170 @@
# 1.3 インターフェース概要
## メイン画面のレイアウト
![image-20260108001629138](../../assets/image-20260108001629138.png)
## 上部ナビゲーションバー
| 番号 | 要素 | 機能説明 |
|------|------|----------|
| ① | Logo | クリックで GitHub プロジェクトページにアクセス |
| ② | 設定ボタン | 設定ページを開く（ショートカット `Cmd/Ctrl + ,`） |
| ③ | プロキシスイッチ | ローカルプロキシサービスの起動/停止 |
| ④ | アプリ切り替え | Claude / Codex / Gemini / OpenCode / OpenClaw を切り替え |
| ⑤ | 機能エリア | Skills / Prompts / MCP の入口 |
| ⑥ | 追加ボタン | 新しいプロバイダーを追加 |
### アプリ切り替え
ドロップダウンメニューをクリックして、現在管理するアプリを切り替えます：
- **Claude** - Claude Code の設定を管理
- **Codex** - Codex の設定を管理
- **Gemini** - Gemini CLI の設定を管理
- **OpenCode** - OpenCode の設定を管理
- **OpenClaw** - OpenClaw の設定を管理
切り替え後、プロバイダーリストに対応アプリの設定が表示されます。
### 機能エリアボタン
| ボタン | 機能 | 表示条件 |
|------|------|----------|
| Skills | スキル拡張管理 | 常に表示 |
| Prompts | システムプロンプト管理 | 常に表示 |
| MCP | MCP サーバー管理 | 常に表示 |
## プロバイダーカード
各プロバイダーはカード形式で表示されます。左から右へ以下の要素が含まれています：
### カード要素（左から右）
| 番号 | 要素 | アイコン | 機能説明 |
|------|------|------|----------|
| ① | ドラッグハンドル | ≡ | 長押しして上下にドラッグしてプロバイダーの順序を調整 |
| ② | プロバイダーアイコン | - | プロバイダーのブランドアイコンを表示、カラーのカスタマイズ可能 |
| ③ | プロバイダー情報 | - | 名前、メモ/エンドポイントアドレス（クリックで公式サイトを開く） |
| ④ | 使用量情報 | - | 残額を表示、複数プランの場合はプラン数を表示 |
| ⑤ | 有効化ボタン | ▶ | 現在使用中のプロバイダーに切り替え |
| ⑥ | 編集ボタン | ✏️ | プロバイダー設定を編集 |
| ⑦ | 複製ボタン | - | プロバイダーを複製（コピーを作成） |
| ⑧ | テストボタン | - | モデルの可用性と応答速度をテスト |
| ⑨ | 使用量クエリ | - | 使用量クエリスクリプトを設定 |
| ⑩ | 削除ボタン | - | プロバイダーを削除（現在有効な場合は無効） |
> **ヒント**：操作ボタンエリア（⑤-⑩）はマウスホバー時に表示され、通常は非表示で画面をすっきり保ちます。
### ボタンの詳細説明
| ボタン | 状態変化 | 説明 |
|------|----------|------|
| **有効化** | 有効化済みの場合は ✓ を表示して無効化 | フェイルオーバーモードでは「参加/参加済み」に変化 |
| **編集** | 常に使用可能 | 編集パネルを開いて設定を変更 |
| **複製** | 常に使用可能 | プロバイダーのコピーを作成、名前に `copy` が付加 |
| **テスト** | テスト中はローディングアニメーション | プロキシサービス実行中のみ使用可能 |
| **使用量クエリ** | 常に使用可能 | カスタム使用量クエリスクリプトを設定 |
| **削除** | 現在有効な場合は半透明で無効 | 先に他のプロバイダーに切り替える必要あり |
### カードの状態
| 状態 | 枠の色 | 説明 |
|------|----------|------|
| **現在有効** | 青い枠 | 通常モードで現在使用中のプロバイダー |
| **プロキシアクティブ** | 緑の枠 | プロキシ接管モードで実際に使用中のプロバイダー |
| **通常状態** | デフォルトの枠 | 有効化されていないプロバイダー |
| **フェイルオーバー中** | 優先度バッジを表示 | P1、P2 などのフェイルオーバー優先度を表示 |
### ヘルスステータスバッジ
プロキシモードでは、フェイルオーバーキューに参加しているプロバイダーにヘルスステータスが表示されます：
| バッジ | 色 | 説明 |
|------|------|------|
| 健康 | 緑 | 連続失敗回数 0 |
| 警告 | 黄 | 連続失敗回数 1-2 |
| 不健康 | 赤 | 連続失敗回数 ≥3、サーキットブレーカーが発動する可能性あり |
## システムトレイ
CC Switch はシステムトレイにアイコンを表示し、クイック操作の入口を提供します。
### トレイメニュー構造
![image-20260108002153668](../../assets/image-20260108002153668.png)
### メニュー機能
| メニュー項目 | 機能 |
|--------|------|
| メインウィンドウを開く | メインウィンドウを表示してフォーカス |
| アプリグループ | Claude/Codex/Gemini/OpenCode/OpenClaw ごとにプロバイダーを表示 |
| プロバイダーリスト | クリックで切り替え、現在有効なものにはチェックマークを表示 |
| 終了 | アプリを完全に終了 |
### 多言語対応
トレイメニューは 3 つの言語に対応し、設定に応じて自動的に切り替わります：
| 言語 | メインウィンドウを開く | 終了 |
|------|-----------|------|
| 中文 | 打开主界面 | 退出 |
| English | Open main window | Quit |
| 日本語 | メインウィンドウを開く | 終了 |
### 使用シーン
トレイからのプロバイダー切り替えはメイン画面を開く必要がなく、以下の場面に適しています：
- 頻繁にプロバイダーを切り替える場合
- メインウィンドウが最小化されているときの素早い操作
- バックグラウンド実行中の設定管理
## 設定ページ
設定ページは複数のタブに分かれています：
### 一般タブ
- 言語設定（中文/English/日本語）
- テーマ設定（システムに合わせる/ライト/ダーク）
- ウィンドウ動作（起動時に自動実行、閉じる動作）
### 詳細タブ
- 設定ディレクトリの設定
- プロキシサービスの設定
- フェイルオーバーの設定
- 料金設定
- データのインポート/エクスポート
### 使用量タブ
- リクエスト統計の概要
- トレンドグラフ
- リクエストログ
- プロバイダー/モデル統計
### バージョン情報タブ
- バージョン情報
- 更新の確認
- オープンソースライセンス
## ショートカットキー
| ショートカット | 機能 |
|--------|------|
| `Cmd/Ctrl + ,` | 設定を開く |
| `Cmd/Ctrl + F` | プロバイダーを検索 |
| `Esc` | ダイアログ/検索を閉じる |
## 検索機能
`Cmd/Ctrl + F` で検索ボックスを開きます：
- 名前、メモ、URL で検索可能
- プロバイダーリストをリアルタイムでフィルタリング
- `Esc` で検索を閉じる

92
docs/user-manual/ja/1-getting-started/1.4-quickstart.md Normal file
View File

@@ -0,0 +1,92 @@
# 1.4 クイックスタート
このセクションでは、5 分で初回設定を完了する方法を説明します。
## ステップ 1：プロバイダーの追加
1. メイン画面右上の **+** ボタンをクリック
2. 「プリセット」ドロップダウンからプロバイダーを選択
- よく使われるプリセット：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode
- または「カスタム」を選択して手動設定
3. **API Key** を入力
4. 「追加」をクリック
![image-20260108002807657](../../assets/image-20260108002807657.png)
> **ヒント**：プリセットではエンドポイントアドレスが自動入力されるため、API Key のみ入力すれば使用できます。
## ステップ 2：プロバイダーの切り替え
追加が完了すると、プロバイダーがリストに表示されます。
**方法 1：メイン画面で切り替え**
- プロバイダーカードの「有効化」ボタンをクリック
**方法 2：トレイで素早く切り替え**
- システムトレイアイコンを右クリック
- プロバイダー名を直接クリック
## ステップ 3：反映方法
プロバイダーを切り替えた後、各 CLI ツールの反映方法は異なります：
| アプリ | 反映方法 |
|------|----------|
| Claude Code | 即時反映（ホットリロード対応） |
| Codex | ターミナルを閉じて再度開く必要あり |
| Gemini | 即時反映（リクエストごとに設定を再読み込み） |
### Claude Code の初回インストール時の注意
Claude Code を初めて起動するときに**ログイン**の要求や初期化ガイドが表示される場合は、CC Switch で「Claude Code の初回確認をスキップ」オプションを有効にしてください：
1. CC Switch の「設定 → 一般」を開く
2. 「Claude Code の初回確認をスキップ」スイッチをオンにする
3. Claude Code を再起動
![image-20260108002626389](../../assets/image-20260108002626389.png)
> **注意**：このオプションは `~/.claude/settings.json` の `skipIntroduction` フィールドに書き込まれ、公式の初回ガイドフローをスキップします。
## 設定の確認
再起動後、対応する CLI ツールを起動して簡単な質問でテストします：
```bash
# Claude Code - 起動後にテスト質問を入力
claude
> こんにちは、簡単に自己紹介してください
# Codex - 起動後にテスト質問を入力
codex
> こんにちは、簡単に自己紹介してください
# Gemini - 起動後にテスト質問を入力
gemini
> こんにちは、簡単に自己紹介してください
```
AI が正常に回答すれば、設定は成功です。
## 次のステップ
基本設定が完了しました。次に以下のことができます：
- [プロバイダーの追加](../2-providers/2.1-add.md) - 複数のプロバイダーを設定して簡単に切り替え
- [MCP サーバーの設定](../3-extensions/3.1-mcp.md) - AI ツールの機能を拡張
- [システムプロンプトの設定](../3-extensions/3.2-prompts.md) - AI の動作をカスタマイズ
- [プロキシサービスの有効化](../4-proxy/4.1-service.md) - 使用量の監視と自動フェイルオーバー
## よくある質問
### 切り替えても反映されない場合
ターミナルまたは CLI ツールを再起動してください。設定ファイルは切り替え時に更新されますが、実行中のプログラムは自動的に設定を再読み込みしません。
### プリセットが見つからない場合
プロバイダーがプリセットリストにない場合は、「カスタム」を選択して手動設定してください。設定形式については [プロバイダーの追加](../2-providers/2.1-add.md) を参照してください。
### 公式ログインに戻すには
「公式ログイン」プリセット（Claude/Codex）または「Google 公式」プリセット（Gemini）を選択し、クライアントを再起動してログインフローに従ってください。

255
docs/user-manual/ja/1-getting-started/1.5-settings.md Normal file
View File

@@ -0,0 +1,255 @@
# 1.5 個人設定
このセクションでは、個人の好みに合わせて CC Switch を設定する方法を説明します。
## 設定を開く
- 左上の **⚙️** ボタンをクリック
- またはショートカット `Cmd/Ctrl + ,`
## 言語設定
CC Switch は 3 つの言語に対応しています：
| 言語 | 説明 |
| -------- | -------- |
| 簡体中文 | デフォルト言語 |
| English | 英語インターフェース |
| 日本語 | 日本語インターフェース |
言語を切り替えると即座に反映され、再起動は不要です。
## テーマ設定
| オプション | 説明 |
| -------- | --------------------------- |
| システムに合わせる | システムのダーク/ライトモードに自動的に合わせる |
| ライト | 常にライトテーマを使用 |
| ダーク | 常にダークテーマを使用 |
## ウィンドウ動作
### 起動時に自動実行
有効にすると、システム起動時に CC Switch が自動的に起動します。
- **Windows**：レジストリを使用
- **macOS**：LaunchAgent を使用
- **Linux**：XDG autostart を使用
### 閉じる動作
| オプション | 説明 |
| ------------ | ---------------------------- |
| トレイへ最小化 | 閉じるボタンをクリックするとシステムトレイに隠す |
| 直接終了 | 閉じるボタンをクリックするとアプリを完全に終了 |
トレイからプロバイダーを素早く切り替えられるため、「トレイへ最小化」の使用を推奨します。
### Claude プラグイン連携
有効にすると、CC Switch はプロバイダー切り替え時に VS Code の Claude Code 拡張に設定を自動同期します（`~/.claude/config.json` の `primaryApiKey` に書き込み）。
> **使用シーン**：Claude Code CLI と VS Code プラグインを同時に使用する場合、このオプションを有効にすると両方の設定を一致させることができます。
### Claude 初回ガイドのスキップ
有効にすると、Claude Code の初回ガイドフローをスキップします。Claude Code に慣れているユーザー向けです。
> **注意**：このオプションは `~/.claude/settings.json` の `skipIntroduction` フィールドに書き込まれます。
### アプリの表示設定
アプリ切り替えに表示するアプリを選択します。各アプリを個別にオン/オフできますが、少なくとも 1 つは有効にする必要があります。
設定可能なアプリ：Claude、Codex、Gemini、OpenCode、OpenClaw。
> **使用シーン**：Claude Code と Codex CLI のみを使用する場合、他のアプリを非表示にしてインターフェースをシンプルに保てます。
### Skills 同期方式
スキルを各アプリディレクトリにインストールする際の同期方式を設定します：
| 方式 | 説明 |
| ----------------- | ---------------------------------------------------- |
| シンボリックリンク | スキルのソースファイルへのシンボリックリンクを作成、容量が少なく、リアルタイム同期 |
| ファイルコピー | スキルファイルをターゲットディレクトリに完全コピー |
> **推奨**：デフォルトではシンボリックリンク方式を使用します。権限の問題が発生する場合は、コピー方式に切り替えてください。
### ターミナル設定
CC Switch がターミナルを開く際に使用するターミナルアプリケーションを選択します。
対応ターミナル（プラットフォーム別）：
| プラットフォーム | ターミナル選択肢 |
| ------- | ------------------------------------------------------------------ |
| macOS | Terminal、iTerm2、Alacritty、Kitty、Ghostty、WezTerm |
| Windows | CMD、PowerShell、Windows Terminal |
| Linux | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |
## ディレクトリ設定
### アプリ設定ディレクトリ
CC Switch 自体のデータの保存場所で、デフォルトは `~/.cc-switch/` です。
### CLI ツールディレクトリ
各 CLI ツールの設定ディレクトリをカスタマイズできます：
| 設定 | デフォルト値 | 説明 |
| ------------- | -------------- | -------------------- |
| Claude ディレクトリ | `~/.claude/` | Claude Code 設定ディレクトリ |
| Codex ディレクトリ | `~/.codex/` | Codex 設定ディレクトリ |
| Gemini ディレクトリ | `~/.gemini/` | Gemini CLI 設定ディレクトリ |
| OpenCode ディレクトリ | `~/.opencode/` | OpenCode 設定ディレクトリ |
| OpenClaw ディレクトリ | `~/.openclaw/` | OpenClaw 設定ディレクトリ |
> **注意**：ディレクトリを変更した後はアプリの再起動が必要で、対応する CLI ツールも同じディレクトリを設定する必要があります。
## データ管理
### 設定のエクスポート
「エクスポート」ボタンをクリックして、以下の内容を含むバックアップファイルを保存します：
- すべてのプロバイダー設定
- MCP サーバー設定
- Prompts プリセット
- アプリ設定
バックアップファイルは JSON 形式で、テキストエディタで確認できます。
### 設定のインポート
1. 「ファイルを選択」をクリック
2. 以前にエクスポートしたバックアップファイルを選択
3. 「インポート」をクリック
4. 既存の設定の上書きを確認
> **注意**：インポートは既存の設定を上書きするため、事前に現在の設定をエクスポートしてバックアップすることをお勧めします。
## プロキシ設定
設定 → プロキシ タブ
プロキシ タブではすべてのプロキシ関連機能を集中管理します：
### ローカルプロキシ
ローカルプロキシサービスの起動/停止、リスニングアドレスとポートの設定。詳しくは [4.1 プロキシサービス](../4-proxy/4.1-service.md) をご覧ください。
### フェイルオーバー
アプリ（Claude/Codex/Gemini）ごとにフェイルオーバーキューと自動切り替え戦略を設定。詳しくは [4.3 フェイルオーバー](../4-proxy/4.3-failover.md) をご覧ください。
### 料金補正器
モデル料金補正ルールを設定し、プロキシの課金統計を調整します。
### グローバル送信プロキシ
CC Switch の送信 HTTP/HTTPS プロキシを設定します。外部 API にプロキシ経由でアクセスする必要がある場合に使用します。
## 詳細設定
設定 → 詳細 タブ
### 設定ディレクトリ
各アプリの設定ファイルディレクトリをカスタマイズ。下記の「ディレクトリ設定」セクションを参照してください。
### データ管理
設定バックアップのインポート/エクスポート。下記の「データ管理」セクションを参照してください。
### バックアップと復元
自動バックアップの管理：
| 設定 | 説明 |
| -------- | -------------------------- |
| バックアップ間隔 | 自動バックアップの時間間隔（時間） |
| 保持数量 | 保持するバックアップの数 |
バックアップリストの表示とバックアップからの復元をサポートします。
### クラウド同期（WebDAV）
WebDAV プロトコルを使用して複数のデバイス間で設定を同期します。
| 設定項目 | 説明 |
| -------- | ------------------------------------- |
| サービスプリセット | 坚果云 / Nextcloud / Synology / カスタム |
| サーバー URL | WebDAV サーバー URL |
| ユーザー名 | ログインユーザー名 |
| パスワード | ログインパスワード（アプリ専用パスワード） |
| リモートディレクトリ | リモート保存パス（デフォルト `cc-switch-sync`） |
| プロファイル名 | デバイスプロファイル名（デフォルト `default`） |
| 自動同期 | 有効にすると変更を自動アップロード |
操作：
- **接続テスト**：WebDAV 設定が正しいか確認
- **保存**：設定を保存して自動テスト
- **アップロード**：ローカルデータをリモートにアップロード
- **ダウンロード**：リモートからローカルにデータをダウンロード
> **注意**：アップロードはリモートデータを、ダウンロードはローカルデータを上書きします。操作前にご確認ください。
### ログ設定
| 設定項目 | 説明 |
| -------- | ----------------------------------- |
| ログを有効化 | アプリのログ記録のオン/オフ |
| ログレベル | error / warn / info / debug / trace |
ログレベルの説明：
- **error** - エラーのみ記録
- **warn** - 警告とエラーを記録
- **info** - 一般情報を記録（推奨）
- **debug** - デバッグ情報を記録
- **trace** - すべての詳細情報を記録
## バージョン情報ページ
設定 → バージョン情報 タブ
### バージョン情報
現在の CC Switch バージョン番号を表示し、以下をサポートします：
- リリースノートの表示
- 更新の確認
- 新バージョンのダウンロードとインストール
### ローカル環境チェック
インストール済みの CLI ツールのバージョンを自動検出：
| ツール | 検出内容 |
| -------- | ------------------ |
| Claude | 現在のバージョン、最新バージョン |
| Codex | 現在のバージョン、最新バージョン |
| Gemini | 現在のバージョン、最新バージョン |
| OpenCode | 現在のバージョン、最新バージョン |
| OpenClaw | 現在のバージョン、最新バージョン |
「更新」ボタンをクリックして再検出できます。
### ワンクリックインストールコマンド
CLI ツールを素早くインストール/更新するコマンドを提供：
```bash
npm i -g @anthropic-ai/claude-code@latest
npm i -g @openai/codex@latest
npm i -g @google/gemini-cli@latest
npm i -g opencode@latest
npm i -g openclaw@latest
```
「コピー」ボタンでクリップボードにコピーできます。

354
docs/user-manual/ja/2-providers/2.1-add.md Normal file
View File

@@ -0,0 +1,354 @@
# 2.1 プロバイダーの追加
## 追加パネルを開く
メイン画面右上の **+** ボタンをクリックして、プロバイダー追加パネルを開きます。
パネルは 2 つのタブに分かれています：
- **アプリ専用プロバイダー**：現在選択中のアプリ（Claude/Codex/Gemini/OpenCode/OpenClaw）専用
- **統一プロバイダー**：アプリ間で共有する設定
## プリセットで追加
プリセットは事前に設定されたプロバイダーテンプレートで、API Key を入力するだけで使用できます。
### 操作手順
1. 「プリセット」ドロップダウンからプロバイダーを選択
2. 名前とエンドポイントが自動入力される
3. **API Key** を入力
4. （任意）メモを入力
5. 「追加」をクリック
### 主なプリセット
#### Claude プリセット
| プリセット名 | 説明 |
|----------|------|
| Claude 公式 | Anthropic 公式アカウントでログイン |
| DeepSeek | DeepSeek モデル |
| 智谱 GLM | 智谱 AI の GLM モデル |
| 智谱 GLM en | 智谱 AI（英語版） |
| 百炼 | アリクラウド百炼（通义千問） |
| Kimi | Moonshot Kimi モデル |
| Kimi For Coding | Kimi プログラミング専用モデル |
| ModelScope | 魔搭コミュニティ |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax（英語版） |
| DouBaoSeed | 豆包 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 モデル |
> ⭐ は公式パートナーを示します。プリセットリストはバージョンの更新に伴い変更される場合があります。アプリ内の実際の表示を基準にしてください。
#### Codex プリセット
| プリセット名 | 説明 |
|----------|------|
| OpenAI 公式 | OpenAI 公式アカウントでログイン |
| Azure OpenAI | Azure OpenAI サービス |
| AiHubMix | AiHubMix 統合サービス |
| DMXAPI | DMXAPI 中継サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
#### Gemini プリセット
| プリセット名 | 説明 |
|----------|------|
| Google 公式 | Google OAuth でログイン |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
| カスタム | すべてのパラメータを手動設定 |
#### OpenCode プリセット
| プリセット名 | 説明 |
|----------|------|
| DeepSeek | DeepSeek モデル |
| 智谱 GLM | 智谱 AI の GLM モデル |
| 智谱 GLM en | 智谱 AI（英語版） |
| 百炼 | アリクラウド百炼 |
| Kimi k2.5 | Moonshot Kimi-k2.5 モデル |
| Kimi For Coding | Kimi プログラミング専用モデル |
| ModelScope | 魔搭コミュニティ |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax（英語版） |
| DouBaoSeed | 豆包 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 プログラミング専用モデル |
| MiniMax | MiniMax モデル |
| MiniMax en | MiniMax（英語版） |
| KAT-Coder | KAT-Coder モデル |
| Longcat | Longcat AI |
| DouBaoSeed | 豆包 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 互換インターフェース |
## カスタム設定
「カスタム」プリセットを選択した場合、JSON 設定を手動で編集する必要があります。
### Claude 設定形式
```json
{
"env": {
"ANTHROPIC_API_KEY": "your-api-key",
"ANTHROPIC_BASE_URL": "https://api.example.com"
}
}
```
| フィールド | 必須 | 説明 |
|------|------|------|
| `ANTHROPIC_API_KEY` | はい | API キー |
| `ANTHROPIC_BASE_URL` | いいえ | カスタムエンドポイントアドレス |
| `ANTHROPIC_AUTH_TOKEN` | いいえ | API_KEY の代替認証方式 |
### Codex 設定形式
Codex は 2 つの設定ファイルを使用します：
**1. auth.json**（`~/.codex/auth.json`）- API キーを保存：
```json
{
"OPENAI_API_KEY": "your-api-key"
}
```
**2. config.toml**（`~/.codex/config.toml`）- モデルとエンドポイントの設定を保存：
```toml
# 基本設定
model_provider = "custom"
model = "gpt-5.2"
model_reasoning_effort = "high"
disable_response_storage = true
# カスタムプロバイダー設定
[model_providers.custom]
name = "custom"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
```
**auth.json フィールド説明**：
| フィールド | 必須 | 説明 |
|------|------|------|
| `OPENAI_API_KEY` | はい | API キー |
**config.toml フィールド説明**：
| フィールド | 必須 | 説明 |
|------|------|------|
| `model_provider` | はい | モデルプロバイダー名（`[model_providers.xxx]` と一致する必要あり） |
| `model` | はい | 使用するモデル（例：`gpt-5.2`、`gpt-4o`） |
| `model_reasoning_effort` | いいえ | 推論強度：`low` / `medium` / `high` |
| `disable_response_storage` | いいえ | レスポンス保存を無効にするかどうか |
| `base_url` | はい | API エンドポイントアドレス |
| `wire_api` | いいえ | API プロトコルタイプ（通常 `responses`） |
| `requires_openai_auth` | いいえ | OpenAI 認証方式を使用するかどうか |
### Gemini 設定形式
```json
{
"env": {
"GEMINI_API_KEY": "your-api-key",
"GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
}
}
```
| フィールド | 必須 | 説明 |
|------|------|------|
| `GEMINI_API_KEY` | はい | API キー |
| `GOOGLE_GEMINI_BASE_URL` | いいえ | カスタムエンドポイントアドレス |
| `GEMINI_MODEL` | いいえ | モデルの指定 |
> 認証タイプは CC Switch が自動的に検出します（PackyCode API プロキシ / Google OAuth / 汎用 API Key）。手動設定は不要です。
## 統一プロバイダー
統一プロバイダーは Claude/Codex/Gemini/OpenCode/OpenClaw 間で設定を共有でき、複数の API 形式をサポートする中継サービスに適しています。
### 統一プロバイダーの作成
1. 「統一プロバイダー」タブに切り替え
2. 「統一プロバイダーを追加」をクリック
3. 共通設定を入力：
- 名前
- API Key
- エンドポイントアドレス
4. 同期するアプリにチェック（Claude/Codex/Gemini/OpenCode/OpenClaw）
5. 保存
### 同期の仕組み
統一プロバイダーはチェックしたアプリに自動的に同期されます：
- 統一プロバイダーを変更すると、関連するすべてのアプリの設定が同期更新される
- 統一プロバイダーを削除すると、関連するアプリの設定も削除される
### 保存して同期
統一プロバイダーの編集時に選択できます：
| 操作 | 説明 |
|------|------|
| 保存 | 設定のみ保存、すぐに同期しない |
| 保存して同期 | 設定を保存し、有効なすべてのアプリに即座に同期 |
### 手動同期
手動で同期をトリガーする場合：
1. 統一プロバイダーカードの「同期」ボタンをクリック
2. 同期操作を確認
3. 各アプリの関連プロバイダーの設定が上書きされる
## プロバイダーのインポート
CC Switch は 2 つの方法でプロバイダー設定をインポートできます：
### 方法 1：ディープリンクでインポート
`ccswitch://` プロトコルリンクでワンクリックインポート：
1. ディープリンクをクリックまたはアクセス
2. CC Switch が自動的に開き、インポート確認を表示
3. 設定情報をプレビュー
4. 「インポートを確認」をクリック
**ディープリンクの取得方法**：
- 他の人からの共有で取得
- [オンライン生成ツール](https://farion1231.github.io/cc-switch/deplink.html) で作成
### 方法 2：データベースバックアップからインポート
SQL バックアップファイルから一括インポート：
1. 「設定 → 詳細 → データ管理」を開く
2. 「ファイルを選択」をクリック
3. 以前にエクスポートした `.sql` バックアップファイルを選択
4. 「インポート」をクリック
5. 既存の設定の上書きを確認
**インポート内容**：
- すべてのプロバイダー設定
- MCP サーバー設定
- Prompts プリセット
- 使用量ログ
> **注意**：インポートは既存のデータベースを上書きするため、事前に現在の設定をエクスポートしてバックアップすることをお勧めします。エクスポートファイル名の形式は `cc-switch-export-{タイムスタンプ}.sql` です。
## 高度なオプション
### カスタムアイコン
名前の左側にあるアイコンエリアをクリックすると：
- プリセットアイコンを選択
- アイコンの色をカスタマイズ
### Web サイトリンク
プロバイダーの公式サイトやコンソールのアドレスを入力して、素早くアクセスできます：
- プロバイダーカードのリンクアイコンをクリックすると直接開く
- 残額の確認や API Key の取得などに使用
### メモ
以下のようなメモ情報を追加できます：
- アカウントの用途（個人/仕事）
- プランの情報
- 有効期限
メモはプロバイダーカードに表示され、検索にも対応しています。
### エンドポイント速度テスト
プロバイダーを追加した後、API エンドポイントの速度テストができます：
1. プロバイダーカードの「テスト」ボタンをクリック
2. テストパネルで複数のエンドポイント URL を追加
3. 「テスト」をクリックして実行
4. レイテンシが最も低いエンドポイントを選択
**テスト結果**：
- 緑：レイテンシ < 500ms（優秀）
- 黄：レイテンシ 500-1000ms（普通）
- 赤：レイテンシ > 1000ms（遅い）
![image-20260108005327817](../../assets/image-20260108005327817.png)

111
docs/user-manual/ja/2-providers/2.2-switch.md Normal file
View File

@@ -0,0 +1,111 @@
# 2.2 プロバイダーの切り替え
## メイン画面での切り替え
プロバイダーリストで、対象のプロバイダーカードの「有効化」ボタンをクリックします。
### 切り替えフロー
1. 「有効化」ボタンをクリック
2. CC Switch が設定ファイルを更新
3. カードのステータスが「現在有効」に変更
4. Claude/Gemini は即時反映、Codex はターミナルの再起動が必要
### ステータス表示
| ステータス | 表示 | 説明 |
|------|------|------|
| 現在有効 | 青い枠 + ラベル | 設定ファイル内の現在のプロバイダー |
| プロキシアクティブ | 緑の枠 | プロキシモードで実際に使用中のプロバイダー |
| 通常 | デフォルトのスタイル | 有効化されていないプロバイダー |
## トレイでの素早い切り替え
システムトレイから素早く切り替えられ、メイン画面を開く必要がありません。
### 操作手順
1. システムトレイの CC Switch アイコンを右クリック
2. メニューで対応するアプリ（Claude/Codex/Gemini/OpenCode）を見つける
3. 切り替えたいプロバイダー名をクリック
4. 切り替え完了、トレイに短い通知が表示
### トレイメニュー構造
![image-20260108004348993](../../assets/image-20260108004348993.png)
## 反映方法
### Claude Code
**切り替え後に即時反映**、再起動は不要です。
Claude Code はホットリロードに対応しており、設定ファイルの変更を自動検出して再読み込みします。
### Codex
切り替え後は再起動が必要：
- 現在のターミナルウィンドウを閉じる
- ターミナルを再度開く
### Gemini CLI
**切り替え後に即時反映**、再起動は不要です。
Gemini CLI はリクエストごとに `.env` ファイルを再読み込みします。
## 設定ファイルの変更
プロバイダーを切り替える際、CC Switch は以下のファイルを変更します：
### Claude
```
~/.claude/settings.json
```
変更内容：
```json
{
"env": {
"ANTHROPIC_API_KEY": "新しい API Key",
"ANTHROPIC_BASE_URL": "新しいエンドポイント"
}
}
```
### Codex
```
~/.codex/auth.json
~/.codex/config.toml（追加設定がある場合）
```
### Gemini
```
~/.gemini/.env
~/.gemini/settings.json
```
## 切り替え失敗時の対処
切り替えに失敗した場合、考えられる原因：
### 設定ファイルがロックされている
他のプログラムが設定ファイルを使用中です。
**解決方法**：実行中の CLI ツールを閉じてから、再度切り替えを試みてください。
### 権限不足
設定ファイルへの書き込み権限がありません。
**解決方法**：設定ディレクトリの権限設定を確認してください。
### 設定形式エラー
プロバイダー設定の JSON 形式に誤りがあります。
**解決方法**：プロバイダーを編集して、JSON 形式を確認・修正してください。

145
docs/user-manual/ja/2-providers/2.3-edit.md Normal file
View File

@@ -0,0 +1,145 @@
# 2.3 プロバイダーの編集
## 編集パネルを開く
1. 編集したいプロバイダーカードを見つける
2. カードにマウスをホバーして操作ボタンを表示
3. 「編集」ボタンをクリック
## 編集可能な内容
### 基本情報
| フィールド | 説明 |
|------|------|
| 名前 | プロバイダーの表示名 |
| メモ | 付加情報 |
| Web サイトリンク | プロバイダーの公式サイトまたはコンソールアドレス |
| アイコン | カスタムアイコンと色 |
### アイコンのカスタマイズ
CC Switch は豊富なアイコンカスタマイズ機能を提供しています：
#### アイコン選択画面
1. アイコンエリアをクリックしてアイコン選択画面を開く
2. 検索ボックスで名前からアイコンを検索
3. クリックしてアイコンを選択
アイコンライブラリには一般的な AI サービスプロバイダーと技術アイコンが含まれており、以下をサポートします：
- 名前によるあいまい検索
- アイコン名のツールチップ表示
- 選択結果のリアルタイムプレビュー
![image-20260108004734882](../../assets/image-20260108004734882.png)
### 設定情報
JSON 形式の設定内容（以下を含む）：
- API Key
- エンドポイントアドレス
- その他の環境変数
### 現在有効なプロバイダーの編集
現在有効なプロバイダーを編集する場合、特別な「バックフィル」機能があります：
1. 編集パネルを開くと、live 設定ファイルから最新の内容を読み取る
2. CLI ツールで手動で設定を変更した場合、その変更が同期される
3. 保存すると、変更が live 設定ファイルに書き込まれる
これにより、CC Switch と CLI ツールの設定が常に同期されます。
## API Key の変更
プロバイダーの編集時に、**API Key** 入力ボックスから直接変更できます：
1. プロバイダーカードの「編集」ボタンをクリック
2. 「API Key」入力ボックスに新しいキーを入力
3. 「保存」をクリック
> **ヒント**：API Key 入力ボックスは表示/非表示の切り替えに対応しています。右側の目のアイコンをクリックするとキーの全文を確認できます。
## エンドポイントアドレスの変更
プロバイダーの編集時に、**エンドポイントアドレス** 入力ボックスから直接変更できます：
1. プロバイダーカードの「編集」ボタンをクリック
2. 「エンドポイントアドレス」入力ボックスに新しい URL を入力
3. 「保存」をクリック
### エンドポイントアドレスの形式
| アプリ | 形式の例 |
|------|----------|
| Claude | `https://api.example.com` |
| Codex | `https://api.example.com/v1` |
| Gemini | `https://api.example.com` |
## カスタムエンドポイントの追加
プロバイダーには複数のエンドポイントを設定でき、以下の用途に使用します：
- 速度テスト時に複数のアドレスをテスト
- フェイルオーバー時のバックアップエンドポイント
### 自動収集
プロバイダーの追加時に、CC Switch は設定からエンドポイントアドレスを自動抽出します。
### 手動追加
プロバイダーの編集時に、「エンドポイント管理」エリアで以下の操作が可能です：
- 新しいエンドポイントの追加
- 既存のエンドポイントの削除
- デフォルトエンドポイントの設定
## JSON エディタ
設定は JSON 形式を使用し、エディタは以下を提供します：
- シンタックスハイライト
- フォーマット検証
- エラー通知
### よくあるエラー
**引用符の欠落**：
```json
// ❌ 間違い
{ env: { KEY: "value" } }
// ✅ 正しい
{ "env": { "KEY": "value" } }
```
**余分なカンマ**：
```json
// ❌ 間違い
{ "env": { "KEY": "value", } }
// ✅ 正しい
{ "env": { "KEY": "value" } }
```
**閉じ括弧の欠落**：
```json
// ❌ 間違い
{ "env": { "KEY": "value" }
// ✅ 正しい
{ "env": { "KEY": "value" } }
```
## 保存と反映
1. 「保存」ボタンをクリック
2. 現在有効なプロバイダーの場合、設定は即座に live ファイルに書き込まれる
3. CLI ツールを再起動して反映
## 編集のキャンセル
「キャンセル」ボタンをクリックするか `Esc` キーを押して編集パネルを閉じると、すべての変更は保存されません。

76
docs/user-manual/ja/2-providers/2.4-sort-duplicate.md Normal file
View File

@@ -0,0 +1,76 @@
# 2.4 並べ替えと複製
## ドラッグで並べ替え
ドラッグでプロバイダーの表示順序を調整します。
### 操作手順
1. プロバイダーカード左側の **≡** ドラッグハンドルにマウスを合わせる
2. マウスの左ボタンを押し続ける
3. 目的の位置まで上下にドラッグ
4. マウスを離して並べ替え完了
### 並べ替えの用途
- **よく使うものを優先**：よく使うプロバイダーをリストの上部に配置
- **フェイルオーバーの順序**：並び順はフェイルオーバーキューのデフォルト順序に影響
## プロバイダーの複製
プロバイダーのコピーを素早く作成します。以下のような場面に適しています：
- 既存の設定をベースにバリエーションを作成
- 現在の設定をバックアップ
- テスト用の設定を作成
### 操作手順
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「複製」ボタンをクリック
3. 名前に `copy` が付加されたコピーが自動作成
4. コピーを編集して設定を変更
### コピーされる内容
コピーは完全な複製が作成され、以下を含みます：
| 内容 | コピーされるか |
|------|----------|
| 名前 | コピーされる（`copy` が付加） |
| 設定 | 完全にコピー |
| メモ | コピーされる |
| Web サイトリンク | コピーされる |
| アイコン | コピーされる |
| エンドポイントリスト | コピーされる |
| 並び順の位置 | 元のプロバイダーの下に挿入 |
### コピー後の編集
コピー完了後、通常は以下を変更します：
1. **名前**：意味のある名前に変更
2. **API Key**：異なるアカウントの場合
3. **エンドポイント**：異なるサービスの場合
## プロバイダーの削除
### 操作手順
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「削除」ボタンをクリック
3. 削除を確認
### 削除の確認
削除前に確認ダイアログが表示され、以下が表示されます：
- プロバイダー名
- 削除後は元に戻せないという注意
### 削除の制限
- **現在有効なプロバイダー**：削除可能ですが、先に他のプロバイダーに切り替えることをお勧めします
- **統一プロバイダー**：削除すると、関連するアプリの設定も削除されます
![image-20260108004946288](../../assets/image-20260108004946288.png)

181
docs/user-manual/ja/2-providers/2.5-usage-query.md Normal file
View File

@@ -0,0 +1,181 @@
# 2.5 使用量クエリ
## 機能説明
使用量クエリ機能により、カスタムスクリプトを設定して、プロバイダーの残額や使用量などの情報をリアルタイムでクエリできます。
**使用シーン**：
- API アカウントの残額確認
- プランの使用状況の監視
- 複数プランの残額を集約表示
## 設定を開く
1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「使用量クエリ」ボタンをクリック
3. 使用量クエリ設定パネルが開く
## 使用量クエリの有効化
設定パネル上部の「使用量クエリを有効にする」スイッチをオンにします。
## プリセットテンプレート
CC Switch は 3 種類のプリセットテンプレートを提供しています：
### カスタムテンプレート
リクエストと抽出ロジックを完全にカスタマイズします。特殊な API 形式に対応します。
### 汎用テンプレート
ほとんどの標準的な API 形式のプロバイダーに適しています：
```javascript
({
request: {
url: "{{baseUrl}}/user/balance",
method: "GET",
headers: {
"Authorization": "Bearer {{apiKey}}",
"User-Agent": "cc-switch/1.0"
}
},
extractor: function(response) {
return {
isValid: response.is_active || true,
remaining: response.balance,
unit: "USD"
};
}
})
```
**設定パラメータ**：
| パラメータ | 説明 |
|------|------|
| API Key | 認証用のキー（任意、空欄の場合はプロバイダーに設定されたキーを使用） |
| Base URL | API ベースアドレス（任意、空欄の場合はプロバイダーのエンドポイントを使用） |
### New API テンプレート
New API タイプの中継サービス専用に設計されています：
```javascript
({
request: {
url: "{{baseUrl}}/api/user/self",
method: "GET",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}",
"New-Api-User": "{{userId}}"
},
},
extractor: function (response) {
if (response.success && response.data) {
return {
planName: response.data.group || "デフォルトプラン",
remaining: response.data.quota / 500000,
used: response.data.used_quota / 500000,
total: (response.data.quota + response.data.used_quota) / 500000,
unit: "USD",
};
}
return {
isValid: false,
invalidMessage: response.message || "クエリ失敗"
};
},
})
```
**設定パラメータ**：
| パラメータ | 説明 |
|------|------|
| Base URL | New API サービスアドレス |
| Access Token | アクセストークン |
| User ID | ユーザー ID |
## 共通設定
### タイムアウト時間
リクエストのタイムアウト時間（秒）、デフォルトは 10 秒。
### 自動クエリ間隔
使用量データの自動更新間隔（分）：
- `0` に設定すると自動クエリを無効化
- 範囲：0-1440 分（最長 24 時間）
- プロバイダーが「現在有効」のときのみ動作
## エクストラクターの戻り値形式
エクストラクター関数は以下のフィールドを含むオブジェクトを返す必要があります：
| フィールド | 型 | 必須 | 説明 |
|------|------|------|------|
| `isValid` | boolean | いいえ | アカウントが有効かどうか、デフォルト true |
| `invalidMessage` | string | いいえ | 無効時の通知メッセージ |
| `remaining` | number | はい | 残額 |
| `unit` | string | はい | 単位（例：USD、CNY、回） |
| `planName` | string | いいえ | プラン名（複数プラン対応） |
| `total` | number | いいえ | 総額 |
| `used` | number | いいえ | 使用済み額 |
| `extra` | object | いいえ | 追加情報 |
## スクリプトのテスト
設定完了後、「スクリプトをテスト」ボタンをクリックして確認します：
1. 設定された URL にリクエストを送信
2. エクストラクター関数を実行
3. 結果またはエラー情報を表示
## 表示効果
設定が成功すると、プロバイダーカードに以下が表示されます：
- **単一プラン**：残額を直接表示
- **複数プラン**：プラン数を表示、クリックで詳細を展開
## 変数プレースホルダー
スクリプト内で以下のプレースホルダーを使用でき、実行時に自動的に置換されます：
| プレースホルダー | 説明 |
|--------|------|
| `{{apiKey}}` | 設定された API Key |
| `{{baseUrl}}` | 設定された Base URL |
| `{{accessToken}}` | 設定された Access Token（New API） |
| `{{userId}}` | 設定された User ID（New API） |
## 一般的なプロバイダーの設定例
### トラブルシューティング
### クエリ失敗
**確認事項**：
1. API Key が正しいか
2. Base URL が正しいか
3. ネットワークがアクセス可能か
4. タイムアウト時間が十分か
### 返却データが空
**確認事項**：
1. エクストラクター関数に `return` 文があるか
2. レスポンスのデータ構造がエクストラクターと一致しているか
3. 「スクリプトをテスト」で生のレスポンスを確認
### フォーマット失敗
スクリプトに構文エラーがある場合、「フォーマット」ボタンをクリックするとエラー箇所が表示されます。
## 注意事項
- 使用量クエリは少量の API リクエスト枠を消費します
- 頻繁なリクエストを避けるため、適切な自動クエリ間隔を設定してください
- 機密情報（API Key、Token）はローカルに安全に保存されます

209
docs/user-manual/ja/3-extensions/3.1-mcp.md Normal file
View File

@@ -0,0 +1,209 @@
# 3.1 MCP サーバー管理
## MCP とは
MCP (Model Context Protocol) は、AI ツールが外部データソースやツールにアクセスできるようにするプロトコルです。MCP サーバーにより、AI は以下のことが可能になります：
- ファイルシステムへのアクセス
- ネットワークリクエストの実行
- データベースのクエリ
- 外部 API の呼び出し
## MCP パネルを開く
上部ナビゲーションバーの **MCP** ボタンをクリックします。
## パネル概要
![image-20260108005723522](../../assets/image-20260108005723522.png)
## MCP サーバーの追加
### プリセットテンプレートを使用
1. 右上の **+** ボタンをクリック
2. 「プリセット」ドロップダウンからテンプレートを選択
3. 必要に応じて設定を変更
4. 「保存」をクリック
![image-20260108005739731](../../assets/image-20260108005739731.png)
### 主なプリセット
| プリセット | パッケージ名 | 機能説明 |
|------|------|----------|
| fetch | mcp-server-fetch | HTTP リクエストツール、AI が Web コンテンツを取得可能に |
| time | @modelcontextprotocol/server-time | 時間ツール、現在の時刻情報を提供 |
| 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（標準入出力）
最も一般的なタイプで、ローカルプロセスを起動して通信します。
```json
{
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {}
}
```
**要件**：
- 対応するコマンド（例：`uvx`、`npx`）がインストールされている必要あり
- サーバープログラムが PATH に含まれている必要あり
### http
HTTP プロトコルでリモートサーバーと通信します。
```json
{
"url": "http://localhost:8080/mcp"
}
```
### sse（Server-Sent Events）
SSE プロトコルでサーバーと通信し、リアルタイムプッシュをサポートします。
```json
{
"url": "http://localhost:8080/sse"
}
```
## アプリバインド
各 MCP サーバーは、有効にするアプリを個別に制御できます。
### スイッチの説明
| スイッチ | 作用 | 設定ファイルパス |
|------|------|--------------|
| Claude | Claude Code に同期 | `~/.claude.json` の `mcpServers` |
| Codex | Codex に同期 | `~/.codex/config.toml` の `[mcp_servers]` |
| Gemini | Gemini CLI に同期 | `~/.gemini/settings.json` の `mcpServers` |
| OpenCode | OpenCode に同期 | `~/.opencode/config.json` の `mcpServers` |
> **注意**：OpenClaw は現在 MCP サーバー管理に対応していません。MCP 機能は現在 Claude、Codex、Gemini、OpenCode の 4 つのアプリのみサポートしています。
### スイッチの動作
あるアプリのスイッチをオンにすると、CC Switch は以下を実行します：
1. **データベースの更新**：サーバーの `apps.claude/codex/gemini/opencode` のステータスを `true` に設定
2. **Live 設定に同期**：サーバー設定を対応アプリの設定ファイルに書き込み
3. **即時反映**：次回 CLI ツール起動時に新しい MCP サーバーが自動的にロード
あるアプリのスイッチをオフにすると、CC Switch は以下を実行します：
1. **データベースの更新**：対応アプリのステータスを `false` に設定
2. **Live 設定から削除**：アプリの設定ファイルからそのサーバーを削除
3. **即時反映**：次回 CLI ツール起動時にその MCP サーバーはロードされない
### 同期条件
MCP サーバーの同期は、対応アプリがインストールされている場合のみ実行されます：
- **Claude**：`~/.claude/` ディレクトリまたは `~/.claude.json` ファイルが存在する必要あり
- **Codex**：`~/.codex/` ディレクトリが存在する必要あり
- **Gemini**：`~/.gemini/` ディレクトリが存在する必要あり
- **OpenCode**：`~/.opencode/` ディレクトリが存在する必要あり
> **ヒント**：CLI ツールがインストールされていない場合、対応するスイッチをオンにしてもエラーにはなりませんが、設定は書き込まれません。
スイッチをオフにすると、設定はファイルから削除されます。
## サーバーの編集
1. サーバー行の右側にある「編集」ボタンをクリック
2. 設定を変更
3. 「保存」をクリック
変更は有効になっているアプリの設定ファイルに即座に同期されます。
## サーバーの削除
1. サーバー行の右側にある「削除」ボタンをクリック
2. 削除を確認
削除後、設定はすべてのアプリの設定ファイルから削除されます。
## 既存の設定のインポート
CLI ツールで既に MCP サーバーを設定している場合、CC Switch にインポートできます：
1. 「インポート」ボタンをクリック
2. インポートするアプリを選択（Claude/Codex/Gemini/OpenCode）
3. CC Switch が既存の設定を読み取ってインポート
## 設定ファイル形式
### Claude (`~/.claude.json`)
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```
### Gemini (`~/.gemini/settings.json`)
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
## よくある質問
### サーバーの起動に失敗する
確認事項：
- コマンドが正しくインストールされているか（例：`uvx`）
- コマンドが PATH に含まれているか
- 引数が正しいか
### 設定が反映されない
確認事項：
- 対応するアプリのスイッチがオンになっているか
- CLI ツールを再起動したか

160
docs/user-manual/ja/3-extensions/3.2-prompts.md Normal file
View File

@@ -0,0 +1,160 @@
# 3.2 Prompts プロンプト管理
## 機能説明
Prompts 機能は、システムプロンプトのプリセットを管理します。システムプロンプトは AI の動作や回答スタイルに影響します。
CC Switch を使用すると：
- 複数のプロンプトプリセットを作成
- さまざまなシーンのプロンプトを素早く切り替え
- デバイス間でプロンプト設定を同期
## Prompts パネルを開く
上部ナビゲーションバーの **Prompts** ボタンをクリックします。
## パネル概要
![image-20260108010110382](../../assets/image-20260108010110382.png)
## プリセットの作成
### 操作手順
1. 右上の **+** ボタンをクリック
2. プリセット名を入力
3. Markdown エディタでプロンプトを作成
4. 「保存」をクリック
### Markdown エディタ
エディタは以下を提供します：
- シンタックスハイライト
- リアルタイムプレビュー
- よく使うフォーマットのショートカットキー
### プロンプトの書き方のヒント
**構造化フォーマット**：
```markdown
# 役割定義
あなたはプロのコードレビュー専門家です。
## コア能力
- コード品質分析
- パフォーマンス最適化の提案
- セキュリティ脆弱性の検出
## 回答スタイル
- 簡潔明瞭
- 具体的な例を提供
- 改善提案を提示
## 注意事項
- ビジネスロジックを変更しない
- コードスタイルの一貫性を保つ
```
## プリセットの有効化
### 操作方法
プリセット項目のスイッチボタンをクリックして、有効/無効を切り替えます。
### 単一有効化
同時に有効にできるプリセットは 1 つだけです。新しいプリセットを有効にすると、以前のプリセットは自動的に無効になります。
### 同期先
有効化後、プロンプトは対応するアプリのファイルに書き込まれます：
| アプリ | ファイルパス |
|------|----------|
| Claude | `~/.claude/CLAUDE.md` |
| Codex | `~/.codex/AGENTS.md` |
| Gemini | `~/.gemini/GEMINI.md` |
| OpenCode | `~/.opencode/AGENTS.md` |
| OpenClaw | `~/.openclaw/AGENTS.md` |
## プリセットの編集
1. プリセット項目の「編集」ボタンをクリック
2. 名前や内容を変更
3. 「保存」をクリック
現在有効なプリセットを編集した場合、保存後に設定ファイルに即座に同期されます。
## プリセットの削除
1. プリセット項目の「削除」ボタンをクリック
2. 削除を確認
有効になっているプリセットは削除できません。先に無効にしてから削除してください。
## スマートバックフィル
CC Switch は、手動での変更を失わないようにスマートバックフィル保護機能を提供しています。
### 動作原理
1. プリセットを切り替える前に、現在の設定ファイルの内容を自動的に読み取る
2. ファイルの内容とデータベース内のプリセットを比較
3. 内容が異なる場合、ユーザーが手動で変更したことを示す
4. 手動変更の内容を現在のプリセットに保存
5. その後、新しいプリセットに切り替え
### 保護シーン
| シーン | 処理方法 |
|------|----------|
| CLI 内で `CLAUDE.md` を直接編集 | 変更が自動的に現在のプリセットに保存 |
| 外部エディタで設定ファイルを変更 | 変更が自動的に現在のプリセットに保存 |
| 別のプリセットに切り替え | 現在の変更を保存してから切り替え |
### 技術的な詳細
バックフィル機能は以下のタイミングでトリガーされます：
- **プリセットの切り替え時**：現在の live ファイルの内容を現在のプリセットに保存
- **現在のプリセットの編集時**：live ファイルから最新の内容を読み取り
- **初回起動時**：既存の live ファイルの内容を自動インポート
### 注意事項
- バックフィルは異なるプリセットに切り替えるときにのみトリガーされる
- 現在有効なプリセットがない場合、バックフィルはトリガーされない
- バックフィルの失敗は切り替えフローに影響しない
## アプリ間での使用
Prompts はアプリごとに個別に管理されます：
- Claude に切り替えると、Claude のプリセットが表示
- Codex に切り替えると、Codex のプリセットが表示
- Gemini に切り替えると、Gemini のプリセットが表示
- OpenCode に切り替えると、OpenCode のプリセットが表示
- OpenClaw に切り替えると、OpenClaw のプリセットが表示
複数のアプリで同じプロンプトを使用する場合は、それぞれで作成する必要があります。
## インポート・エクスポート
### ディープリンクで共有
ディープリンクを生成してプリセットを共有できます：
```
ccswitch://import/prompt?data=<Base64 エンコードされたプリセット>
```
### 設定のエクスポートで共有
設定をエクスポートするとすべてのプリセットが含まれ、インポートで復元できます。

207
docs/user-manual/ja/3-extensions/3.3-skills.md Normal file
View File

@@ -0,0 +1,207 @@
# 3.3 Skills スキル管理
## 機能説明
Skills は再利用可能な機能拡張で、AI ツールに特定分野の専門的な能力を与えます。
スキルはフォルダ形式で存在し、以下を含みます：
- プロンプトテンプレート
- ツール定義
- サンプルコード
## 対応アプリ
Skills 機能は以下の 4 つのアプリに対応しています：
- **Claude Code**
- **Codex**
- **Gemini CLI**
- **OpenCode**
## Skills ページを開く
上部ナビゲーションバーの **Skills** ボタンをクリックします。
> 注意：Skills ボタンはすべてのアプリモードで表示されます。
## ページ概要
![image-20260108010253926](../../assets/image-20260108010253926.png)
## スキルの発見
### プリセットリポジトリ
CC Switch は以下の GitHub リポジトリをプリセットとして設定しています：
| リポジトリ | 説明 |
| -------------- | ------------------------ |
| Anthropic 公式 | Anthropic 提供の公式スキル |
| ComposioHQ | コミュニティが管理するスキルコレクション |
| コミュニティ精選 | 厳選された高品質スキル |
![image-20260108010308060](../../assets/image-20260108010308060.png)
### 検索とフィルタリング
CC Switch は強力な検索とフィルタリング機能を提供しています：
#### 検索ボックス
- スキル名で検索
- スキルの説明で検索
- ディレクトリ名で検索
- リアルタイムフィルタリング、入力と同時に検索
#### ステータスフィルタ
ドロップダウンメニューでインストール状態別にフィルタリング：
| オプション | 説明 |
| ------ | ------------------ |
| すべて | すべてのスキルを表示 |
| インストール済み | インストール済みのスキルのみ表示 |
| 未インストール | 未インストールのスキルのみ表示 |
![image-20260108010324583](../../assets/image-20260108010324583.png)
#### 組み合わせて使用
検索とフィルタリングは組み合わせて使用できます：
- まず「インストール済み」でフィルタリング
- 次にキーワードで検索
- 結果にマッチ数が表示
### リストの更新
「更新」ボタンをクリックしてリポジトリを再スキャンし、最新のスキルを取得します。
## スキルのインストール
### 操作手順
1. インストールしたいスキルカードを見つける
2. 「インストール」ボタンをクリック
3. インストール完了を待つ
### インストール先
| アプリ | インストールディレクトリ |
| -------- | --------------------- |
| Claude | `~/.claude/skills/` |
| Codex | `~/.codex/skills/` |
| Gemini | `~/.gemini/skills/` |
| OpenCode | `~/.opencode/skills/` |
### インストール内容
インストールによりスキルフォルダがローカルにコピーされます：
```
~/.claude/skills/
└── skill-name/
├── README.md
├── prompt.md
└── tools/
└── ...
```
## スキルのアンインストール
### 操作手順
1. インストール済みのスキルカードを見つける
2. 「アンインストール」ボタンをクリック
3. アンインストールを確認
### アンインストールの効果
- ローカルのスキルフォルダを削除
- インストール状態を更新
## リポジトリ管理
### リポジトリ管理を開く
ページ上部の「リポジトリ管理」ボタンをクリックします。
### カスタムリポジトリの追加
1. 「リポジトリを追加」をクリック
2. リポジトリ情報を入力：
- Owner：GitHub ユーザー名または組織名
- Name：リポジトリ名
- Branch：ブランチ名（デフォルト main）
- Subdirectory：スキルがあるサブディレクトリ（任意）
3. 「追加」をクリック
### リポジトリの形式
```
https://github.com/{owner}/{name}/tree/{branch}/{subdirectory}
```
例：
```
Owner: anthropics
Name: claude-skills
Branch: main
Subdirectory: skills
```
### リポジトリの削除
1. リポジトリリストで削除するリポジトリを見つける
2. 「削除」ボタンをクリック
3. 削除を確認
リポジトリを削除しても、そのリポジトリのスキルはリストから消えませんが、更新はできなくなります。
## スキルカードの情報
各スキルカードには以下が表示されます：
| 情報 | 説明 |
| ---- | --------------- |
| 名前 | スキル名 |
| 説明 | 機能の説明 |
| ソース | 所属リポジトリ |
| ステータス | インストール済み / 未インストール |
## スキルの更新
現在、自動更新には対応していません。スキルを更新するには：
1. 既存のスキルをアンインストール
2. リストを更新
3. 再度インストール
### スキルリストが空の場合
考えられる原因：
- ネットワークの問題で GitHub にアクセスできない
- リポジトリ設定のエラー
解決方法：
- ネットワーク接続を確認
- 「更新」をクリックしてリトライ
- リポジトリ設定を確認
### インストールに失敗する場合
考えられる原因：
- ネットワークの問題
- ディスク容量不足
- 権限の問題
解決方法：
- ネットワーク接続を確認
- ディスク容量を確認
- ディレクトリの権限を確認

222
docs/user-manual/ja/4-proxy/4.1-service.md Normal file
View File

@@ -0,0 +1,222 @@
# 4.1 プロキシサービス
## 機能説明
プロキシサービスは、ローカルで HTTP プロキシを起動し、すべての API リクエストをプロキシ経由で転送します。
**主な用途**：
- リクエストログの記録
- API 使用量の統計
- フェイルオーバーのサポート
- 複数アプリのリクエストを一元管理
## プロキシの起動
### 方法 1：メイン画面のスイッチ
メイン画面上部の **プロキシスイッチ** ボタンをクリックします。
スイッチの状態：
- 白：プロキシ停止中
- 緑：プロキシ実行中
![image-20260108011353927](../../assets/image-20260108011353927.png)
### 方法 2：設定ページ
1. 「設定 → 詳細 → プロキシサービス」を開く
2. 右上のスイッチをクリック
![image-20260108011338922](../../assets/image-20260108011338922.png)
## プロキシ設定
### 基本設定
| 設定項目 | 説明 | デフォルト値 |
|--------|------|--------|
| リスニングアドレス | プロキシがバインドする IP アドレス | `127.0.0.1` |
| リスニングポート | プロキシがリスニングするポート | `15721` |
| ログを有効化 | リクエストログを記録するかどうか | オン |
### 設定の変更
1. **プロキシサービスを停止**（先に停止する必要あり）
2. リスニングアドレスまたはポートを変更
3. 「保存」をクリック
4. プロキシを再起動
> アドレス/ポートの変更には、先にプロキシサービスの停止が必要です
### リスニングアドレスの説明
| アドレス | 説明 |
|------|------|
| `127.0.0.1` | ローカルマシンのみアクセス可能（推奨） |
| `0.0.0.0` | LAN からのアクセスを許可 |
## 実行状態
プロキシ実行中、パネルには以下の情報が表示されます：
### サービスアドレス
```
http://127.0.0.1:15721
```
「コピー」ボタンでアドレスをコピーできます。
### 現在のプロバイダー
各アプリが現在使用しているプロバイダーを表示：
```
Claude: PackyCode
Codex: AIGoCode
Gemini: Google 公式
```
### 統計データ
| 指標 | 説明 |
|------|------|
| アクティブ接続 | 現在処理中のリクエスト数 |
| 総リクエスト数 | 起動以来の総リクエスト数 |
| 成功率 | リクエスト成功の割合（>90% 緑、≤90% 黄） |
| 実行時間 | プロキシの稼働時間 |
### フェイルオーバーキュー
プロキシパネルにはアプリタイプごとにフェイルオーバーキューが表示されます：
```
Claude
├── 1. PackyCode [使用中] ●
├── 2. AIGoCode ●
└── 3. バックアップ ○
Codex
├── 1. AIGoCode [使用中] ●
└── 2. バックアップ ●
```
キューの説明：
- 数字は優先順位を示す
- 「使用中」ラベルは現在使用しているプロバイダーを示す
- ヘルスバッジはプロバイダーの状態を示す：
- 緑：健康（連続失敗 0 回）
- 黄：低下（連続失敗 1-2 回）
- 赤：不健康（連続失敗 ≥3 回）
## 動作原理
### リクエストフロー
```mermaid
sequenceDiagram
participant CLI as CLI ツール (Claude)
participant Proxy as ローカルプロキシ (CC Switch)
participant API as API プロバイダー (Anthropic)
participant DB as データストレージ (Logger)
CLI->>Proxy: API リクエストを送信
Proxy->>DB: リクエストログの記録/使用量の統計
Proxy->>API: リクエストを転送
API-->>Proxy: レスポンスを返却
Proxy-->>CLI: レスポンスを返却
```
### 設定の変更
プロキシを起動してアプリケーション接管を有効にすると、CC Switch はアプリの設定を変更します：
**Claude**：
```json
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
```
**Codex**：
```toml
base_url = "http://127.0.0.1:15721/v1"
```
**Gemini**：
```
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
## プロキシの停止
### 方法 1：メイン画面のスイッチ
プロキシスイッチボタンをクリックしてオフにします。
### 方法 2：設定ページ
プロキシサービスパネルでスイッチをオフにします。
### 停止後の処理
プロキシの停止時、CC Switch は以下を実行します：
1. アプリの設定を元の状態に復元
2. リクエストログを保存
3. すべての接続を閉じる
## ログ記録
### ログの有効化
プロキシパネルの「ログを有効化」スイッチをオンにします。
### ログの内容
各リクエスト記録には以下が含まれます：
| フィールド | 説明 |
|------|------|
| 時間 | リクエスト時刻 |
| アプリ | Claude / Codex / Gemini |
| プロバイダー | 使用されたプロバイダー |
| モデル | リクエストされたモデル |
| Token | 入力/出力の Token 数 |
| レイテンシ | リクエストにかかった時間 |
| ステータス | 成功/失敗 |
### ログの表示
「設定 → 使用量」タブでリクエストログを表示できます。
## よくある質問
### ポートが使用中
エラーメッセージ：`Address already in use`
解決方法：
1. ポートを変更する（例：5001）
2. またはそのポートを使用しているプログラムを終了する
### プロキシの起動に失敗する
確認事項：
- ポートが使用中でないか
- 十分な権限があるか
- ファイアウォールがブロックしていないか
### リクエストがタイムアウトする
考えられる原因：
- ネットワークの問題
- プロバイダーのサーバーの問題
- プロキシ設定のエラー
解決方法：
- ネットワーク接続を確認
- プロバイダーの API に直接アクセスを試みる
- プロバイダーの設定を確認

195
docs/user-manual/ja/4-proxy/4.2-takeover.md Normal file
View File

@@ -0,0 +1,195 @@
# 4.2 アプリケーション接管
## 機能説明
アプリケーション接管とは、CC Switch のプロキシが特定アプリの API リクエストを接管することです。
接管を有効にすると：
- アプリの API リクエストがローカルプロキシ経由で転送される
- リクエストログと使用量の統計を記録できる
- フェイルオーバー機能を使用できる
## 前提条件
アプリケーション接管機能を使用する前に、プロキシサービスを起動する必要があります。
## 接管の有効化
### 操作場所
設定 → 詳細 → プロキシサービス → アプリケーション接管エリア
### 操作手順
1. プロキシサービスが起動していることを確認
2. 「アプリケーション接管」エリアを見つける
3. 必要なアプリのスイッチをオンにする
### 接管スイッチ
| スイッチ | 作用 |
|------|------|
| Claude 接管 | Claude Code のリクエストを接管 |
| Codex 接管 | Codex のリクエストを接管 |
| Gemini 接管 | Gemini CLI のリクエストを接管 |
複数のアプリの接管を同時に有効にできます。
## 接管の仕組み
### 設定の変更
接管を有効にすると、CC Switch はアプリの設定ファイルを変更し、API エンドポイントをローカルプロキシに向けます。
**Claude 設定の変更**：
```json
// 接管前
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}
// 接管後
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
```
**Codex 設定の変更**：
```toml
# 接管前
base_url = "https://api.openai.com/v1"
# 接管後
base_url = "http://127.0.0.1:15721/v1"
```
**Gemini 設定の変更**：
```bash
# 接管前
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
# 接管後
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
### リクエストの転送
プロキシがリクエストを受信すると：
1. リクエスト元を識別（Claude/Codex/Gemini）
2. そのアプリで現在有効なプロバイダーを検索
3. プロバイダーの実際のエンドポイントにリクエストを転送
4. リクエストログを記録
5. アプリにレスポンスを返却
## 接管ステータスの表示
### メイン画面の表示
接管を有効にすると、メイン画面に以下の変化があります：
- **プロキシ Logo の色**：無色から緑に変化
- **プロバイダーカード**：現在アクティブなプロバイダーに緑の枠が表示
### プロバイダーカードの状態
| 状態 | 枠の色 | 説明 |
|------|----------|------|
| 現在有効 | 青 | 設定ファイル内のプロバイダー（非プロキシモード） |
| プロキシアクティブ | 緑 | プロキシが実際に使用しているプロバイダー |
| 通常 | デフォルト | 使用されていないプロバイダー |
## 接管の無効化
### 操作手順
1. プロキシパネルで対応するアプリの接管スイッチをオフにする
2. またはプロキシサービスを直接停止
### 設定の復元
接管を無効にすると、CC Switch は以下を実行します：
1. アプリの設定を接管前の状態に復元
2. 現在のリクエストログを保存
## 接管とプロバイダーの切り替え
### 接管モードでのプロバイダー切り替え
接管モードでプロバイダーを切り替える場合：
1. メイン画面でプロバイダーの「有効化」ボタンをクリック
2. プロキシが新しいプロバイダーを使用してリクエストを即座に転送
3. **CLI ツールの再起動は不要**
これが接管モードの大きなメリットです：プロバイダーの切り替えが即座に反映されます。
### 非接管モードでのプロバイダー切り替え
非接管モードでプロバイダーを切り替える場合：
1. 設定ファイルを変更
2. CLI ツールの再起動が必要
## 複数アプリの接管
複数のアプリを同時に接管でき、それぞれ独立して管理されます：
- 独立したプロバイダー設定
- 独立したフェイルオーバーキュー
- 独立したリクエスト統計
## 使用シーン
### シーン 1：使用量の監視
接管 + ログ記録を有効にして、API の使用状況を監視します。
### シーン 2：素早い切り替え
接管を有効にすると、プロバイダーの切り替えに CLI ツールの再起動が不要になります。
### シーン 3：フェイルオーバー
接管の有効化はフェイルオーバー機能を使用するための前提条件です。
## 注意事項
### パフォーマンスへの影響
プロキシにより少量のレイテンシ（通常 < 10ms）が追加されますが、ほとんどのシーンでは無視できます。
### ネットワーク要件
接管モードでは、CLI ツールがローカルプロキシアドレスにアクセスできる必要があります。
### 設定のバックアップ
接管を有効にする前に、CC Switch は元の設定をバックアップし、無効化時に復元します。
## よくある質問
### 接管後にリクエストが失敗する
確認事項：
- プロキシサービスが正常に実行されているか
- プロバイダーの設定が正しいか
- ネットワークが正常か
### 接管を無効にしても設定が復元されない
考えられる原因：
- プロキシの異常終了
- 設定ファイルが他のプログラムに変更された
解決方法：
- プロバイダーを手動で編集して保存し直す
- または接管を再度有効にしてから無効にする

232
docs/user-manual/ja/4-proxy/4.3-failover.md Normal file
View File

@@ -0,0 +1,232 @@
# 4.3 フェイルオーバー
## 機能説明
フェイルオーバー機能は、メインプロバイダーのリクエストが失敗した場合に、自動的にバックアッププロバイダーに切り替えてサービスの中断を防ぎます。
**適用シーン**：
- プロバイダーのサービスが不安定な場合
- 高可用性が必要な場合
- 長時間実行するタスク
## 前提条件
フェイルオーバー機能を使用するには：
1. プロキシサービスを起動
2. アプリケーション接管を有効化
3. フェイルオーバーキューを設定
4. 自動フェイルオーバーを有効化
## フェイルオーバーキューの設定
### 設定ページを開く
設定 → 詳細 → フェイルオーバー
### アプリの選択
ページ上部に 3 つのタブがあります：
- Claude
- Codex
- Gemini
設定するアプリを選択します。
### バックアッププロバイダーの追加
1. 「フェイルオーバーキュー」エリアで
2. 「プロバイダーを追加」をクリック
3. ドロップダウンリストからプロバイダーを選択
4. プロバイダーがキューの末尾に追加
### 優先順位の調整
プロバイダーをドラッグして順序を調整：
- 番号が小さいほど優先度が高い
- メインプロバイダーが失敗すると、順番にバックアッププロバイダーを試行
### プロバイダーの削除
プロバイダーの右側にある「削除」ボタンをクリックします。
## メイン画面でのクイック操作
プロキシとフェイルオーバーがどちらも有効な場合、プロバイダーカードにフェイルオーバースイッチが表示されます。
### キューに追加
1. プロバイダーカードを見つける
2. フェイルオーバースイッチをオンにする
3. プロバイダーが自動的にキューに追加
### キューから削除
1. プロバイダーカードのフェイルオーバースイッチをオフにする
2. プロバイダーがキューから削除
## 自動フェイルオーバーの有効化
### 操作手順
1. フェイルオーバー設定ページで
2. 「自動フェイルオーバー」スイッチをオンにする
### スイッチの説明
| 状態 | 動作 |
|------|------|
| オフ | 失敗を記録するのみ、自動切り替えなし |
| オン | 失敗時に自動的に次のプロバイダーに切り替え |
## フェイルオーバーのフロー
```mermaid
graph TD
Start[リクエストがプロキシに到達] --> Send[現在のプロバイダーに送信]
Send --> CheckSuccess{成功？}
CheckSuccess -- はい --> Return[レスポンスを返却]
CheckSuccess -- いいえ --> LogFail[失敗を記録]
LogFail --> CheckCircuit{サーキットブレーカーの状態確認}
CheckCircuit -- 発動中 --> Skip[このプロバイダーをスキップ]
CheckCircuit -- 未発動 --> IncFail[失敗カウントを増加]
Skip --> Next{キューに次がある？}
IncFail --> Next
Next -- あり --> Switch[プロバイダーを切り替え]
Switch --> Retry[リクエストをリトライ]
Retry --> Send
Next -- なし --> Error[エラーを返却]
```
## サーキットブレーカーの設定
サーキットブレーカーは、失敗したプロバイダーへの頻繁なリトライを防止します。
### 設定項目
アプリごとに独立したデフォルト設定があります。以下は共通のデフォルト値で、Claude には独自の緩やかな設定があります。
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|------|------|--------|--------|------|
| 失敗閾値 | 連続何回失敗でサーキットブレーカーが発動 | 4 | 8 | 1-20 |
| 復旧成功閾値 | ハーフオープン状態で何回成功したら閉じるか | 2 | 3 | 1-10 |
| 復旧待機時間 | サーキットブレーカー発動後の復旧試行までの時間（秒） | 60 | 90 | 0-300 |
| エラー率閾値 | この値を超えるとサーキットブレーカーが発動 | 60% | 70% | 0-100% |
| 最小リクエスト数 | エラー率計算前の最小リクエスト数 | 10 | 15 | 5-100 |
> Claude はリクエストに時間がかかるため、デフォルト設定はより緩やかで、多くの失敗を許容します。
### タイムアウト設定
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|------|------|--------|--------|------|
| ストリーム初バイトタイムアウト | 最初のデータチャンクの最大待機時間（秒） | 60 | 90 | 1-120 |
| ストリームサイレントタイムアウト | データチャンク間の最大間隔（秒） | 120 | 180 | 60-600（0 で無効化） |
| 非ストリームタイムアウト | 非ストリームリクエストの総タイムアウト時間（秒） | 600 | 600 | 60-1200 |
### リトライ設定
| 設定 | 説明 | 共通デフォルト | Claude デフォルト | 範囲 |
|------|------|--------|--------|------|
| 最大リトライ回数 | リクエスト失敗時のリトライ回数 | 3 | 6 | 0-10 |
> Gemini のデフォルト最大リトライ回数は 5 です。
### サーキットブレーカーの状態
| 状態 | 説明 |
|------|------|
| 閉（Closed） | 正常状態、リクエストを許可 |
| 開（Open） | サーキットブレーカー発動中、このプロバイダーをスキップ |
| 半開（Half-Open） | 復旧試行中、探査リクエストを送信 |
### 状態遷移
```mermaid
stateDiagram-v2
[*] --> Closed: 初期化
Closed --> Open: 失敗回数 >= 閾値
Open --> HalfOpen: サーキットブレーカー期間満了
HalfOpen --> Closed: 探査成功 (>= 復旧閾値)
HalfOpen --> Open: 探査失敗
```
## ヘルスステータスの表示
### プロバイダーカード
カードにヘルスステータスバッジが表示されます：
| バッジ | 状態 | 説明 |
|------|------|------|
| 緑 | 健康 | 連続失敗回数 0 |
| 黄 | 警告 | 失敗はあるがサーキットブレーカー未発動 |
| 赤 | サーキットブレーカー発動 | 一時的にスキップ |
### キューリスト
フェイルオーバーキューにも各プロバイダーのヘルスステータスが表示されます。
## フェイルオーバーログ
各フェイルオーバーの記録内容：
| 情報 | 説明 |
|------|------|
| 時間 | 発生時刻 |
| 元のプロバイダー | 失敗したプロバイダー |
| 新しいプロバイダー | 切り替え先のプロバイダー |
| 失敗理由 | エラー情報 |
使用量統計のリクエストログで確認できます。
## ベストプラクティス
### キュー設定のアドバイス
1. **メインプロバイダー**：最も安定で高速なプロバイダー
2. **第 1 バックアップ**：次善の選択
3. **第 2 バックアップ**：最後の手段
### サーキットブレーカー設定のアドバイス
| シーン | 失敗閾値 | サーキットブレーカー期間 |
|------|----------|----------|
| 高可用性要件 | 2 | 30 秒 |
| 一般的なシーン | 3 | 60 秒 |
| 偶発的な失敗を許容 | 5 | 120 秒 |
### 監視のアドバイス
定期的に確認：
- 各プロバイダーのヘルスステータス
- フェイルオーバーの発生頻度
- サーキットブレーカーの発動状況
## よくある質問
### フェイルオーバーがトリガーされない
確認事項：
1. プロキシサービスが実行中か
2. アプリケーション接管が有効か
3. 自動フェイルオーバーが有効か
4. キューにバックアッププロバイダーがあるか
### フェイルオーバーが頻繁にトリガーされる
考えられる原因：
- メインプロバイダーが不安定
- ネットワークの問題
- 設定のエラー
解決方法：
- メインプロバイダーの状態を確認
- サーキットブレーカーのパラメータを調整
- メインプロバイダーの変更を検討
### すべてのプロバイダーがサーキットブレーカー発動中
サーキットブレーカー期間満了後に自動復旧を待つか、以下を実行：
1. プロキシサービスを手動で再起動
2. サーキットブレーカーの状態をリセット

291
docs/user-manual/ja/4-proxy/4.4-usage.md Normal file
View File

@@ -0,0 +1,291 @@
# 4.4 使用量統計
## 機能説明
使用量統計機能は、API リクエストデータを記録・分析して、以下をサポートします：
- API の使用状況の把握
- 費用支出の見積もり
- 使用パターンの分析
- 問題のトラブルシューティング
## 前提条件
使用量統計機能を使用するには：
1. プロキシサービスを起動
2. アプリケーション接管を有効化
3. ログ記録を有効化
## 使用量統計を開く
設定 → 使用量 タブ
## 統計概要
### 集計カード
ページ上部に主要指標が表示されます：
| 指標 | 説明 |
|------|------|
| 総リクエスト数 | 統計期間内のリクエスト総数 |
| 総 Token | 入力 + 出力 Token の合計 |
| 推定費用 | 料金設定に基づいて計算された費用 |
| 成功率 | 成功したリクエストの割合 |
### 期間
統計の期間を選択できます：
| オプション | 範囲 |
|------|------|
| 今日 | 当日 00:00 から現在まで |
| 過去 7 日間 | 直近 7 日間 |
| 過去 30 日間 | 直近 30 日間 |
![image-20260108011730105](../../assets/image-20260108011730105.png)
## トレンドグラフ
### リクエストトレンド
折れ線グラフでリクエスト数の変化傾向を表示：
- X 軸：時間
- Y 軸：リクエスト数
- 時間単位/日単位で表示可能
- ズームとドラッグに対応
### Token トレンド
Token 使用量の変化を表示：
- 入力 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)
## 詳細データ
ページ下部に 3 つのデータタブがあります：
### リクエストログ
各リクエストの詳細記録：
| フィールド | 説明 |
|------|------|
| 時間 | リクエスト時刻 |
| プロバイダー | 使用されたプロバイダー名 |
| モデル | リクエストされたモデル（課金モデル） |
| 入力 Token | 入力の Token 数 |
| 出力 Token | 出力の Token 数 |
| キャッシュ読取 | キャッシュヒットの Token 数 |
| キャッシュ作成 | キャッシュ作成の Token 数 |
| 総費用 | 推定費用（ドル） |
| 所要時間情報 | リクエスト時間、初回 Token 時間、ストリーム/非ストリーム |
| ステータス | HTTP ステータスコード |
#### 所要時間情報の説明
所要時間情報列には複数のバッジが表示されます：
| バッジ | 説明 | 色のルール |
|------|------|----------|
| 総所要時間 | リクエストの総時間（秒） | ≤5s 緑、≤120s オレンジ、>120s 赤 |
| 初回 Token | ストリームリクエストの最初の Token 時間 | ≤5s 緑、≤120s オレンジ、>120s 赤 |
| ストリーム/非ストリーム | リクエストタイプ | ストリーム：青、非ストリーム：紫 |
#### 詳細の表示
リクエスト行をクリックすると詳細情報を表示：
- 完全なリクエストパラメータ
- レスポンス内容のサマリー
- エラー情報（失敗した場合）
#### ログのフィルタリング
以下の条件でフィルタリングできます：
| フィルタ項目 | オプション |
|--------|------|
| アプリタイプ | すべて / Claude / Codex / Gemini |
| ステータスコード | すべて / 200 / 400 / 401 / 429 / 500 |
| プロバイダー | テキスト検索 |
| モデル | テキスト検索 |
| 期間 | 開始時刻 - 終了時刻（日時ピッカー） |
操作ボタン：
- **検索**：フィルタ条件を適用
- **リセット**：デフォルトに戻す（過去 24 時間）
- **更新**：データを再読み込み
![image-20260108011859974](../../assets/image-20260108011859974.png)
### プロバイダー統計
プロバイダー別の集計データ：
| フィールド | 説明 |
|------|------|
| プロバイダー | プロバイダー名 |
| リクエスト数 | そのプロバイダーの総リクエスト数 |
| 成功数 | 成功したリクエスト数 |
| 失敗数 | 失敗したリクエスト数 |
| 成功率 | 成功の割合 |
| 総 Token | Token 使用量の合計 |
| 推定費用 | そのプロバイダーの費用 |
![image-20260108011907928](../../assets/image-20260108011907928.png)
### モデル統計
モデル別の集計データ：
| フィールド | 説明 |
|------|------|
| モデル | モデル名 |
| リクエスト数 | そのモデルの総リクエスト数 |
| 入力 Token | 入力 Token の合計 |
| 出力 Token | 出力 Token の合計 |
| 平均レイテンシ | 平均応答時間 |
| 推定費用 | そのモデルの費用 |
![image-20260108011915381](../../assets/image-20260108011915381.png)
## 料金設定
### 料金設定を開く
設定 → 詳細 → 料金設定
### モデル価格の設定
各モデルの価格を設定（100 万 Token あたり）：
| フィールド | 説明 |
|------|------|
| モデル ID | モデル識別子（例：claude-3-sonnet） |
| 表示名 | カスタム表示名 |
| 入力価格 | 100 万入力 Token あたりの価格 |
| 出力価格 | 100 万出力 Token あたりの価格 |
| キャッシュ読取価格 | 100 万キャッシュヒット Token あたりの価格 |
| キャッシュ作成価格 | 100 万キャッシュ作成 Token あたりの価格 |
### 操作
- **追加**：「追加」ボタンで新しいモデル価格を追加
- **編集**：行末の編集アイコンで変更
- **削除**：行末の削除アイコンで削除
![image-20260108011933565](../../assets/image-20260108011933565.png)
### プリセット価格
CC Switch は一般的なモデルの公式価格（100 万 Token あたり）をプリセットしています：
**Claude シリーズ（ドル）**：
| モデル | 入力 | 出力 | キャッシュ読取 | キャッシュ作成 |
|------|------|------|----------|----------|
| **Claude 4.5 シリーズ** | | | | |
| claude-opus-4-5 | $5 | $25 | $0.50 | $6.25 |
| claude-sonnet-4-5 | $3 | $15 | $0.30 | $3.75 |
| claude-haiku-4-5 | $1 | $5 | $0.10 | $1.25 |
| **Claude 4 シリーズ** | | | | |
| claude-opus-4 | $15 | $75 | $1.50 | $18.75 |
| claude-opus-4-1 | $15 | $75 | $1.50 | $18.75 |
| claude-sonnet-4 | $3 | $15 | $0.30 | $3.75 |
| **Claude 3.5 シリーズ** | | | | |
| claude-3-5-sonnet | $3 | $15 | $0.30 | $3.75 |
| claude-3-5-haiku | $0.80 | $4 | $0.08 | $1.00 |
**OpenAI シリーズ / Codex（ドル）**：
| モデル | 入力 | 出力 | キャッシュ読取 |
|------|------|------|----------|
| **GPT-5.2 シリーズ** | | | |
| gpt-5.2 | $1.75 | $14 | $0.175 |
| **GPT-5.1 シリーズ** | | | |
| gpt-5.1 | $1.25 | $10 | $0.125 |
| **GPT-5 シリーズ** | | | |
| gpt-5 | $1.25 | $10 | $0.125 |
> 注：Codex プリセットには low/medium/high などの変種が含まれており、価格はベースモデルと同一です。
**Gemini シリーズ（ドル）**：
| モデル | 入力 | 出力 | キャッシュ読取 |
|------|------|------|----------|
| **Gemini 3 シリーズ** | | | |
| gemini-3-pro-preview | $2 | $12 | $0.20 |
| gemini-3-flash-preview | $0.50 | $3 | $0.05 |
| **Gemini 2.5 シリーズ** | | | |
| gemini-2.5-pro | $1.25 | $10 | $0.125 |
| gemini-2.5-flash | $0.30 | $2.50 | $0.03 |
**中国メーカーのモデル（人民元）**：
| モデル | 入力 | 出力 | キャッシュ読取 |
|------|------|------|----------|
| **DeepSeek** | | | |
| deepseek-v3.2 | ¥2.00 | ¥3.00 | ¥0.40 |
| deepseek-v3.1 | ¥4.00 | ¥12.00 | ¥0.80 |
| deepseek-v3 | ¥2.00 | ¥8.00 | ¥0.40 |
| **Kimi (月之暗面)** | | | |
| kimi-k2-thinking | ¥4.00 | ¥16.00 | ¥1.00 |
| kimi-k2 | ¥4.00 | ¥16.00 | ¥1.00 |
| kimi-k2-turbo | ¥8.00 | ¥58.00 | ¥1.00 |
| **MiniMax** | | | |
| minimax-m2.1 | ¥2.10 | ¥8.40 | ¥0.21 |
| minimax-m2.1-lightning | ¥2.10 | ¥16.80 | ¥0.21 |
| **その他** | | | |
| glm-4.7 | ¥2.00 | ¥8.00 | ¥0.40 |
| doubao-seed-code | ¥1.20 | ¥8.00 | ¥0.24 |
| mimo-v2-flash | 無料 | 無料 | - |
### カスタム価格
中継サービスを使用する場合、価格が異なる場合があります：
1. 「編集」ボタンをクリック
2. 価格を変更
3. 保存
## よくある質問
### 統計データが空
確認事項：
- プロキシサービスが実行中か
- アプリケーション接管が有効か
- ログ記録が有効か
- プロキシ経由でリクエストがあったか
### 費用の見積もりが不正確
考えられる原因：
- 料金設定が実際と異なる
- 中継サービスの特別な料金体系を使用
解決方法：
- 料金設定を更新
- プロバイダーの実際の請求書を参照
### Token 数がプロバイダーと一致しない
CC Switch は独自の方法で Token 数を推定しており、プロバイダーの計算方法と若干の差異が生じる場合があります。プロバイダーの請求書を基準にしてください。

156
docs/user-manual/ja/4-proxy/4.5-model-test.md Normal file
View File

@@ -0,0 +1,156 @@
# 4.5 モデルテスト
## 機能説明
モデルテスト機能は、プロバイダーに設定されたモデルが使用可能かどうかを確認するために、実際の API リクエストを送信してテストします：
- モデルが存在するか
- API Key が有効か
- エンドポイントが正常に応答するか
- 応答レイテンシが正常か
## 設定を開く
設定 → 詳細 → モデルテスト
## テストモデルの設定
各アプリのテスト用モデルを設定します：
| アプリ | 設定項目 | デフォルト値 | 説明 |
|------|--------|--------|------|
| Claude | Claude モデル | システムデフォルト | Haiku シリーズの使用を推奨（低コスト・高速） |
| Codex | Codex モデル | システムデフォルト | mini シリーズの使用を推奨 |
| Gemini | Gemini モデル | システムデフォルト | Flash シリーズの使用を推奨 |
### モデル選択のアドバイス
テストモデルを選択する際の考慮事項：
1. **コスト**：低価格のモデルを選択（例：Haiku、Mini、Flash）
2. **速度**：応答が速いモデルを選択
3. **可用性**：プロバイダーがサポートしているモデルを選択
## テストパラメータの設定
### タイムアウト時間
| パラメータ | 説明 | デフォルト値 | 範囲 |
|------|------|--------|------|
| タイムアウト時間 | 1 回のリクエストのタイムアウト | 45 秒 | 10-120 秒 |
短すぎると誤判定の可能性があり、長すぎると障害検出が遅れます。
### リトライ回数
| パラメータ | 説明 | デフォルト値 | 範囲 |
|------|------|--------|------|
| 最大リトライ | 失敗時のリトライ回数 | 2 回 | 0-5 回 |
ネットワークが不安定な場合はリトライ回数を増やすことを推奨します。
### デグレード閾値
| パラメータ | 説明 | デフォルト値 | 範囲 |
|------|------|--------|------|
| デグレード閾値 | この時間を超えるとデグレードとマーク | 6000ms | 1000-30000ms |
閾値を超えたプロバイダーは「デグレード」状態としてマークされますが、引き続き使用可能です。
## モデルテストの実行
### 手動テスト
プロバイダーカードの「テスト」ボタンをクリックします：
1. 設定されたエンドポイントにテストリクエストを送信
2. 設定されたテストモデルを使用
3. レスポンスまたはタイムアウトを待機
4. テスト結果を表示
### テスト内容
テストリクエストは：
- 短い prompt（例："Hi"）を送信
- 最大出力 Token を制限（通常 10-50）
- ストリームレスポンスで初バイト時間を検出
## テスト結果
### ヘルスステータス
| ステータス | アイコン | 説明 |
|------|------|------|
| 健康 | 緑 | レスポンス正常、レイテンシが閾値内 |
| デグレード | 黄 | レスポンス正常だが、レイテンシが閾値超過 |
| 利用不可 | 赤 | リクエスト失敗またはタイムアウト |
### 結果情報
テスト完了後に表示：
- 応答レイテンシ（ミリ秒）
- 初バイト時間（TTFB）
- エラー情報（失敗した場合）
## フェイルオーバーとの連携
モデルテストはフェイルオーバー機能と連携して使用します：
### ヘルスチェック
プロキシサービスを有効にすると、システムはフェイルオーバーキュー内のプロバイダーに対して定期的にヘルスチェックを実行します：
1. 設定されたテストモデルでリクエストを送信
2. レスポンスに基づいてヘルスステータスを更新
3. 不健康なプロバイダーは一時的にスキップ
### サーキットブレーカーからの復旧
プロバイダーがサーキットブレーカー状態から復旧する際：
1. モデルテストで可用性を確認
2. テスト合格後、正常状態に復旧
3. テスト不合格の場合、サーキットブレーカーを継続
## よくある質問
### テストは失敗するが実際には使用可能
**考えられる原因**：
- テストモデルと実際に使用するモデルが異なる
- プロバイダーが設定されたテストモデルをサポートしていない
**解決方法**：
- テストモデルをプロバイダーがサポートするモデルに変更
- プロバイダーのモデルリストを確認
### レイテンシが高すぎる
**考えられる原因**：
- ネットワークレイテンシ
- プロバイダーのサーバー負荷が高い
- モデルの応答が遅い
**解決方法**：
- より高速なテストモデルを使用
- デグレード閾値を調整
- ミラーエンドポイントの使用を検討
### 頻繁にタイムアウトする
**考えられる原因**：
- タイムアウト時間の設定が短すぎる
- ネットワークが不安定
- プロバイダーのサービスが不安定
**解決方法**：
- タイムアウト時間を延長
- リトライ回数を増加
- ネットワーク接続を確認
## 注意事項
- モデルテストは少量の API 枠を消費します
- テストには低コストのモデルの使用を推奨
- テスト頻度は高すぎないように、枠の浪費を避けてください
- プロバイダーごとにサポートするモデルが異なる場合があります

340
docs/user-manual/ja/5-faq/5.1-config-files.md Normal file
View File

@@ -0,0 +1,340 @@
# 5.1 設定ファイルの説明
## CC Switch のデータストレージ
### ストレージディレクトリ
デフォルトの場所：`~/.cc-switch/`
設定で場所をカスタマイズ可能です（クラウド同期用）。
### ディレクトリ構造
```
~/.cc-switch/
├── cc-switch.db # SQLite データベース
├── settings.json # デバイスレベルの設定
└── backups/ # 自動バックアップ
├── backup-20251230-120000.json
├── backup-20251229-180000.json
└── ...
```
### データベースの内容
`cc-switch.db` は SQLite データベースで、以下を保存しています：
| テーブル | 内容 |
|-----|------|
| providers | プロバイダー設定 |
| provider_endpoints | プロバイダーエンドポイント候補リスト |
| mcp_servers | MCP サーバー設定 |
| prompts | プロンプトプリセット |
| skills | スキルのインストール状態 |
| skill_repos | スキルリポジトリ設定 |
| proxy_config | プロキシ設定 |
| proxy_request_logs | プロキシリクエストログ |
| provider_health | プロバイダーヘルスステータス |
| model_pricing | モデル料金 |
| settings | アプリ設定 |
### デバイス設定
`settings.json` はデバイスレベルの設定を保存します：
```json
{
"language": "zh",
"theme": "system",
"windowBehavior": "minimize",
"autoStart": false,
"claudeConfigDir": null,
"codexConfigDir": null,
"geminiConfigDir": null,
"opencodeConfigDir": null,
"openclawConfigDir": null
}
```
これらの設定はデバイス間で同期されません。
### 自動バックアップ
`backups/` ディレクトリに自動バックアップが保存されます：
- 設定インポートのたびに自動作成
- 最新の 10 件のバックアップを保持
- ファイル名にタイムスタンプを含む
## Claude Code の設定
### 設定ディレクトリ
デフォルト：`~/.claude/`
### 主要ファイル
```
~/.claude/
├── settings.json # メイン設定ファイル
├── CLAUDE.md # システムプロンプト
└── skills/ # スキルディレクトリ
└── ...
```
### settings.json
```json
{
"env": {
"ANTHROPIC_API_KEY": "sk-xxx",
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
},
"permissions": {
"allow_file_access": true
}
}
```
| フィールド | 説明 |
|------|------|
| `env.ANTHROPIC_API_KEY` | API キー |
| `env.ANTHROPIC_BASE_URL` | API エンドポイント（任意） |
| `env.ANTHROPIC_AUTH_TOKEN` | 代替認証方式 |
### MCP 設定
MCP サーバーの設定は `~/.claude.json` にあります：
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
## Codex の設定
### 設定ディレクトリ
デフォルト：`~/.codex/`
### 主要ファイル
```
~/.codex/
├── auth.json # 認証設定
├── config.toml # メイン設定 + MCP
└── AGENTS.md # システムプロンプト
```
### auth.json
```json
{
"OPENAI_API_KEY": "sk-xxx"
}
```
### config.toml
```toml
# 基本設定
base_url = "https://api.openai.com/v1"
model = "gpt-4"
# MCP サーバー
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```
## Gemini CLI の設定
### 設定ディレクトリ
デフォルト：`~/.gemini/`
### 主要ファイル
```
~/.gemini/
├── .env # 環境変数（API Key）
├── settings.json # メイン設定 + MCP
└── GEMINI.md # システムプロンプト
```
### .env
```bash
GEMINI_API_KEY=xxx
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GEMINI_MODEL=gemini-pro
```
### settings.json
```json
{
"mcpServers": {
"mcp-fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
}
}
}
```
| フィールド | 説明 |
|------|------|
| `mcpServers` | MCP サーバー設定 |
## OpenCode の設定
### 設定ディレクトリ
デフォルト：`~/.opencode/`
### 主要ファイル
```
~/.opencode/
├── config.json # メイン設定ファイル
├── AGENTS.md # システムプロンプト
└── skills/ # スキルディレクトリ
└── ...
```
## OpenClaw の設定
### 設定ディレクトリ
デフォルト：`~/.openclaw/`
### 主要ファイル
```
~/.openclaw/
├── openclaw.json # メイン設定ファイル（JSON5 形式）
├── AGENTS.md # システムプロンプト
└── skills/ # スキルディレクトリ
└── ...
```
### openclaw.json
OpenClaw は JSON5 形式の設定ファイルを使用し、主に以下のセクションを含みます：
```json5
{
// モデルプロバイダー設定
models: {
mode: "merge",
providers: {
"custom-provider": {
baseUrl: "https://api.example.com/v1",
apiKey: "your-api-key",
api: "openai-completions",
models: [{ id: "model-id", name: "Model Name" }]
}
}
},
// 環境変数
env: {
ANTHROPIC_API_KEY: "sk-..."
},
// Agent デフォルトモデル設定
agents: {
defaults: {
model: {
primary: "provider/model"
}
}
},
// ツール設定
tools: {},
// ワークスペースファイル設定
workspace: {}
}
```
| フィールド | 説明 |
|------|------|
| `models.providers` | プロバイダー設定（CC Switch の「プロバイダー」にマッピング） |
| `env` | 環境変数設定 |
| `agents.defaults` | Agent デフォルトモデル設定 |
| `tools` | ツール設定 |
| `workspace` | ワークスペースファイル管理 |
## 設定の優先順位
CC Switch が設定を変更する際の優先順位：
1. **CC Switch データベース** - 単一事実源 (SSOT)
2. **Live 設定ファイル** - プロバイダー切り替え時に書き込み
3. **バックフィル機能** - 現在のプロバイダーの編集時に Live ファイルから読み取り
## 手動での設定編集
### 手動編集可能なもの
- CLI ツールの設定ファイル（CC Switch がバックフィルする）
- CC Switch の `settings.json`
### 手動編集を推奨しないもの
- `cc-switch.db` データベースファイル
- バックアップファイル
### 編集後の同期
CLI ツールの設定を手動で編集した場合：
1. CC Switch を開く
2. 対応するプロバイダーを編集
3. 手動変更の内容がバックフィルされていることを確認
4. 保存してデータベースに同期
## 設定の移行
### 旧バージョンからの移行
CC Switch v3.7.0 で JSON ファイルから SQLite に移行しました：
- 初回起動時に自動的に移行
- 移行成功後に通知を表示
- 旧設定ファイルはバックアップとして保持
### デバイス間の移行
1. 移行元のデバイスで設定をエクスポート
2. 移行先のデバイスで設定をインポート
3. またはクラウド同期機能を使用
## 設定のバックアップに関するアドバイス
### 定期的なバックアップ
定期的に設定をエクスポートすることを推奨します：
1. 設定 → 詳細 → データ管理
2. 「エクスポート」をクリック
3. 安全な場所に保存
### バックアップに含まれる内容
エクスポートファイルには以下が含まれます：
- すべてのプロバイダー設定
- MCP サーバー設定
- Prompts プリセット
- アプリ設定
### 含まれない内容
- 使用量ログ（データ量が大きいため）
- デバイスレベルの設定（デバイス間の移動に適さないため）

220
docs/user-manual/ja/5-faq/5.2-questions.md Normal file
View File

@@ -0,0 +1,220 @@
# 5.2 よくある質問 FAQ
## インストールに関する問題
### macOS で「不明な開発者」と表示される
**問題**：初回起動時に「開けません。身元不明の開発者のものです」と表示される
**解決方法 1**：システム設定から
1. 警告ダイアログを閉じる
2. 「システム設定」→「プライバシーとセキュリティ」を開く
3. CC Switch に関する表示を見つける
4. 「このまま開く」をクリック
5. 再度アプリを開く
**解決方法 2**：ターミナルコマンドから（推奨）
```bash
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
```
実行後、正常にアプリを開けるようになります。
### Windows でインストール後に起動できない
**考えられる原因**：
- WebView2 ランタイムが不足
- ウイルス対策ソフトによるブロック
**解決方法**：
1. [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) をインストール
2. CC Switch をウイルス対策ソフトのホワイトリストに追加
### Linux で起動エラー
**問題**：AppImage が起動しない
**解決方法**：
```bash
# 実行権限を追加
chmod +x CC-Switch-*.AppImage
# それでも失敗する場合
./CC-Switch-*.AppImage --no-sandbox
```
## プロバイダーに関する問題
### プロバイダーを切り替えても反映されない
**原因**：CLI ツールが設定を再読み込みする必要がある
**解決方法**：
- Claude Code：ターミナルを閉じて再度開く、または IDE を再起動
- Codex：ターミナルを閉じて再度開く
- Gemini：トレイからの切り替えで即時反映、再起動不要
### API Key が無効
**確認手順**：
1. API Key が正しくコピーされているか（余分なスペースがないか）
2. API Key が期限切れでないか
3. エンドポイントアドレスが正しいか
4. 速度テストで接続を確認
### 公式ログインに戻すには
**操作手順**：
1. 「公式ログイン」プリセット（Claude/Codex）または「Google 公式」プリセット（Gemini）を選択
2. 「有効化」をクリック
3. 対応する CLI ツールを再起動
4. CLI ツールのログインフローに従って操作
## プロキシに関する問題
### プロキシサービスの起動に失敗する
**考えられる原因**：ポートが使用中
**解決方法**：
1. ポートの使用状況を確認：
```bash
# macOS/Linux
lsof -i :49152
# Windows
netstat -ano | findstr :49152
```
2. ポートを使用しているプログラムを終了
3. または設定を変更してデフォルトポートに復旧：
- 「設定 → プロキシサービス」を開く
- 「デフォルトに戻す」ボタンをクリック
### プロキシモードでリクエストがタイムアウトする
**考えられる原因**：
- ネットワークの問題
- プロバイダーのサーバーの問題
- プロキシ設定のエラー
**解決方法**：
1. ネットワーク接続を確認
2. プロバイダーの API に直接アクセスを試みる（プロキシを無効にして）
3. プロバイダーの設定が正しいか確認
### プロキシを無効にしても設定が復元されない
**考えられる原因**：プロキシの異常終了
**解決方法**：
1. 現在のプロバイダーを編集
2. エンドポイントアドレスが正しいか確認
3. 保存して設定を更新
## フェイルオーバーに関する問題
### フェイルオーバーがトリガーされない
**チェックリスト**：
- [ ] プロキシサービスが実行中か
- [ ] アプリケーション接管が有効か
- [ ] 自動フェイルオーバーが有効か
- [ ] キューにバックアッププロバイダーがあるか
### フェイルオーバーが頻繁にトリガーされる
**考えられる原因**：
- メインプロバイダーが不安定
- サーキットブレーカーの閾値が低すぎる
**解決方法**：
1. メインプロバイダーの状態を確認
2. 失敗閾値を引き上げる（例：3 → 5）
3. メインプロバイダーの変更を検討
### すべてのプロバイダーがサーキットブレーカー発動中
**解決方法**：
1. サーキットブレーカー期間満了を待つ（デフォルト 60 秒）
2. またはプロキシサービスを再起動して状態をリセット
## データに関する問題
### 設定が消えた
**考えられる原因**：
- 設定ディレクトリが削除された
- データベースが破損
**解決方法**：
1. `~/.cc-switch/` ディレクトリが存在するか確認
2. バックアップから復元：`~/.cc-switch/backups/`
3. または以前にエクスポートした設定ファイルからインポート
### 設定のインポートに失敗する
**考えられる原因**：
- ファイル形式のエラー
- バージョンの非互換性
**解決方法**：
1. ファイルが CC Switch からエクスポートされた JSON ファイルであることを確認
2. ファイル内容が完全であるか確認
3. テキストエディタで開いてフォーマットを確認
### 使用量統計のデータが空
**チェックリスト**：
- [ ] プロキシサービスが実行中か
- [ ] アプリケーション接管が有効か
- [ ] ログ記録が有効か
- [ ] プロキシ経由でリクエストがあったか
## その他の問題
### トレイアイコンが表示されない
**macOS**：
- システム設定のメニューバーアイコン設定を確認
**Windows**：
- タスクバーの設定で、CC Switch のアイコンが非表示になっていないか確認
**Linux**：
- システムトレイのサポート（例：`libappindicator`）がインストールされている必要あり
### インターフェースの表示が異常
**解決方法**：
1. テーマを切り替えてみる（ライト/ダーク）
2. アプリを再起動
3. `~/.cc-switch/settings.json` を削除して設定をリセット
### 更新に失敗する
**解決方法**：
1. ネットワーク接続を確認
2. 最新版を手動でダウンロードしてインストール
3. Homebrew を使用する場合：`brew upgrade --cask cc-switch`
## ヘルプの入手
### Issue の提出
上記の方法で問題が解決しない場合：
1. [GitHub Issues](https://github.com/farion1231/cc-switch/issues) にアクセス
2. 類似の問題がないか検索
3. なければ新しい Issue を作成
4. 以下の情報を提供：
- オペレーティングシステムとバージョン
- CC Switch のバージョン
- 問題の説明と再現手順
- エラーメッセージ（ある場合）
### ログファイル
Issue を提出する際にログファイルを添付できます：
- macOS/Linux：`~/.cc-switch/logs/`
- Windows：`%APPDATA%\cc-switch\logs\`

256
docs/user-manual/ja/5-faq/5.3-deeplink.md Normal file
View File

@@ -0,0 +1,256 @@
# 5.3 ディープリンクプロトコル
## 機能説明
CC Switch は `ccswitch://` ディープリンクプロトコルをサポートしており、リンクからワンクリックで設定をインポートできます。
**使用シーン**：
- チーム内での設定共有
- チュートリアルでのワンクリック設定
- デバイス間の素早い同期
## オンライン生成ツール
CC Switch はオンラインのディープリンク生成ツールを提供しています：
**アクセス先**：[https://farion1231.github.io/cc-switch/deplink.html](https://farion1231.github.io/cc-switch/deplink.html)
### 使用方法
1. 上記の Web ページを開く
2. インポートタイプを選択（プロバイダー/MCP/Prompt）
3. 設定情報を入力
4. 「リンクを生成」をクリック
5. 生成されたディープリンクをコピー
6. 他の人に共有するか、別のデバイスで使用
## プロトコル形式
### V1 プロトコル
URL パラメータ形式で、読みやすく生成しやすい形式です：
```
ccswitch://v1/import?resource={type}&app={app}&name={name}&...
```
**共通パラメータ**：
| パラメータ | 必須 | 説明 |
|------|------|------|
| `resource` | はい | リソースタイプ：`provider` / `mcp` / `prompt` / `skill` |
| `app` | はい | アプリタイプ：`claude` / `codex` / `gemini` / `opencode` / `openclaw` |
| `name` | はい | 名前 |
**プロバイダーパラメータ**（resource=provider）：
| パラメータ | 必須 | 説明 |
|------|------|------|
| `endpoint` | いいえ | API エンドポイントアドレス（カンマ区切りで複数 URL 対応） |
| `apiKey` | いいえ | API キー |
| `homepage` | いいえ | プロバイダー公式サイト |
| `model` | いいえ | デフォルトモデル |
| `haikuModel` | いいえ | Haiku モデル（Claude のみ） |
| `sonnetModel` | いいえ | Sonnet モデル（Claude のみ） |
| `opusModel` | いいえ | Opus モデル（Claude のみ） |
| `notes` | いいえ | メモ |
| `icon` | いいえ | アイコン |
| `config` | いいえ | Base64 エンコードされた設定内容 |
| `configFormat` | いいえ | 設定形式：`json` / `toml` |
| `configUrl` | いいえ | リモート設定 URL |
| `enabled` | いいえ | 有効にするかどうか（ブール値） |
| `usageScript` | いいえ | 使用量クエリスクリプト |
| `usageEnabled` | いいえ | 使用量クエリを有効にするか（デフォルト true） |
| `usageApiKey` | いいえ | 使用量クエリ専用 API Key |
| `usageBaseUrl` | いいえ | 使用量クエリ専用アドレス |
| `usageAccessToken` | いいえ | 使用量クエリアクセストークン |
| `usageUserId` | いいえ | 使用量クエリユーザー ID |
| `usageAutoInterval` | いいえ | 自動クエリ間隔（分） |
**プロンプトパラメータ**（resource=prompt）：
| パラメータ | 必須 | 説明 |
|------|------|------|
| `content` | はい | プロンプト内容 |
| `description` | いいえ | 説明 |
| `enabled` | いいえ | 有効にするかどうか（ブール値） |
**MCP パラメータ**（resource=mcp）：
| パラメータ | 必須 | 説明 |
|------|------|------|
| `apps` | はい | アプリリスト（カンマ区切り、例：`claude,codex,gemini,opencode`） |
| `config` | はい | MCP サーバー設定（JSON 形式） |
| `enabled` | いいえ | 有効にするかどうか（ブール値） |
**Skill パラメータ**（resource=skill）：
| パラメータ | 必須 | 説明 |
|------|------|------|
| `repo` | はい | リポジトリ（形式：`owner/name`） |
| `directory` | いいえ | ディレクトリパス |
| `branch` | いいえ | Git ブランチ |
**例**：
```
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
```
## インポートタイプの例
### プロバイダーのインポート
```
ccswitch://v1/import?resource=provider&app=claude&name=My%20Provider&endpoint=https%3A%2F%2Fapi.example.com&apiKey=sk-xxx
```
### MCP サーバーのインポート
```
ccswitch://v1/import?resource=mcp&apps=claude,codex&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&name=mcp-fetch
```
### Prompt プリセットのインポート
```
ccswitch://v1/import?resource=prompt&app=claude&name=%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5&content=%23%20%E8%A7%92%E8%89%B2%0A%E4%BD%A0%E6%98%AF%E4%B8%80%E4%B8%AA%E4%B8%93%E4%B8%9A%E7%9A%84%E4%BB%A3%E7%A0%81%E5%AE%A1%E6%9F%A5%E4%B8%93%E5%AE%B6
```
### Skill のインポート
```
ccswitch://v1/import?resource=skill&name=my-skill&repo=owner/repo&directory=skills/my-skill&branch=main
```
## ディープリンクの生成
### 手動生成
1. パラメータを準備
2. V1 プロトコル形式で URL を組み立て
3. 特殊文字を URL エンコード
**例**：
```javascript
const params = new URLSearchParams({
resource: 'provider',
app: 'claude',
name: 'My Provider',
endpoint: 'https://api.example.com',
apiKey: 'sk-xxx'
});
const url = `ccswitch://v1/import?${params.toString()}`;
```
### オンラインツール
CC Switch 公式のオンラインディープリンク生成ツールを使用するとより便利です。
## ディープリンクの使用
### リンクのクリック
ブラウザや他のアプリでディープリンクをクリック：
1. システムが CC Switch を開くかどうかを確認
2. 確認後、CC Switch が起動
3. インポート確認ダイアログを表示
4. インポートを確認
### インポートの確認
インポート前に確認ダイアログが表示され、以下が含まれます：
- インポートタイプ
- 設定のプレビュー
- 確認/キャンセルボタン
**セキュリティ上の注意**：信頼できるソースからの設定のみインポートしてください。
## プロトコルの登録
### 自動登録
CC Switch のインストール時に `ccswitch://` プロトコルが自動登録されます。
### 手動登録
プロトコルが正しく登録されていない場合：
**macOS**：
アプリを再インストールするか、以下を実行：
```bash
/usr/bin/open -a "CC Switch" --args --register-protocol
```
**Windows**：
アプリを再インストールするか、レジストリを確認：
```
HKEY_CLASSES_ROOT\ccswitch
```
**Linux**：
`.desktop` ファイルの `MimeType` 設定を確認。
## セキュリティに関する考慮事項
### 機密情報
ディープリンクには機密情報（API Key など）が含まれる場合があります：
- API Key を含むリンクを公開の場で共有しない
- 共有前に機密情報を削除または置換
- 安全なチャネルでリンクを送信
### ソースの確認
インポート前に CC Switch は以下を実行します：
1. データ形式の検証
2. 設定のプレビュー表示
3. ユーザーの確認を要求
### 悪意のあるリンクからの防護
CC Switch は以下を確認します：
- データ形式が正当か
- 必須フィールドが揃っているか
- 設定値が妥当な範囲内か
## サンプルリンク
### 例：Claude プロバイダーのインポート
```
ccswitch://v1/import?resource=provider&app=claude&name=Test%20Provider&apiKey=sk-xxx&endpoint=https%3A%2F%2Fapi.example.com
```
### 例：MCP サーバーのインポート
```
ccswitch://v1/import?resource=mcp&name=mcp-fetch&apps=claude,codex,gemini&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D
```
## トラブルシューティング
### リンクが開けない
**確認事項**：
1. CC Switch がインストールされているか
2. プロトコルが正しく登録されているか
3. リンクの形式が正しいか
### インポートに失敗する
**考えられる原因**：
- Base64 エンコードのエラー
- JSON 形式のエラー
- 必須フィールドの不足
**解決方法**：
1. 元の JSON 形式を確認
2. Base64 エンコードをやり直す
3. すべての必須フィールドが存在することを確認

108
docs/user-manual/ja/5-faq/5.4-env-conflict.md Normal file
View File

@@ -0,0 +1,108 @@
# 5.4 環境変数の競合
## 機能説明
CC Switch は、システム環境変数とアプリ設定の競合を自動的に検出し、設定が意図せず上書きされるのを防ぎます。
**検出される環境変数**：
- `ANTHROPIC_API_KEY` - Claude API キー
- `ANTHROPIC_BASE_URL` - Claude API エンドポイント
- `OPENAI_API_KEY` - OpenAI API キー
- `GEMINI_API_KEY` - Gemini API キー
- その他の関連環境変数
## 競合の警告
競合が検出されると、画面の上部に黄色い警告バナーが表示されます：
```
⚠️ 環境変数の競合を検出
X 個の環境変数が CC Switch の設定と競合する可能性があります
[展開] [閉じる]
```
## 競合の詳細を確認
「展開」ボタンをクリックして詳細情報を表示します：
| フィールド | 説明 |
|------|------|
| 変数名 | 環境変数名 |
| 変数値 | 現在設定されている値 |
| ソース | 変数の出処 |
### ソースの種類
| ソース | 説明 |
|------|------|
| ユーザーレジストリ | Windows のユーザーレベル環境変数 |
| システムレジストリ | Windows のシステムレベル環境変数 |
| Shell 設定 | macOS/Linux の Shell 設定ファイル |
| システム環境 | システムレベルの環境変数 |
## 競合の処理
### 削除する変数の選択
1. 削除する環境変数にチェックを入れる
2. または「すべて選択」ですべての競合変数を選択
### 変数の削除
1. 「選択を削除」ボタンをクリック
2. 削除操作を確認
3. CC Switch が自動的にバックアップしてから、選択した変数を削除
### 自動バックアップ
削除前に自動的にバックアップが作成されます：
- バックアップの場所：`~/.cc-switch/env-backups/`
- バックアップ形式：JSON ファイル
- 変数名、値、ソースなどの情報を含む
## 警告を無視する
競合が使用に影響しないことが確認できる場合：
1. 警告バナーの右側にある「閉じる」ボタンをクリック
2. 警告が一時的に非表示になる
3. 次回の起動時に再度検出が行われる
## 手動での処理
CC Switch 経由で削除したくない場合は、手動で処理できます：
### Windows
1. 「システムのプロパティ → 詳細 → 環境変数」を開く
2. ユーザー変数またはシステム変数で競合する変数を見つける
3. 変数を削除または変更
### macOS / Linux
1. Shell 設定ファイル（例：`~/.zshrc`、`~/.bashrc`）を編集
2. 関連する `export` 文を削除またはコメントアウト
3. 設定を再読み込み：`source ~/.zshrc`
## なぜ競合が発生するのか
環境変数の優先度は通常、設定ファイルよりも高く、以下の問題を引き起こす可能性があります：
- CC Switch で設定したプロバイダー設定が上書きされる
- API リクエストが間違ったエンドポイントに送信される
- 間違った API キーが使用される
## ベストプラクティス
1. **CC Switch で設定を管理**：システム環境変数に API キーを設定しないようにする
2. **定期的に確認**：競合の警告に注意し、速やかに対処
3. **重要な変数のバックアップ**：削除前にバックアップを確認
## 削除した変数の復元
環境変数を誤って削除した場合：
1. バックアップファイルを見つける：`~/.cc-switch/env-backups/`
2. 対応する JSON ファイルを開く
3. システム環境に手動で変数を復元

111
docs/user-manual/ja/README.md Normal file
View File

@@ -0,0 +1,111 @@
# CC Switch ユーザーマニュアル
> Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw オールインワンアシスタント
## 目次構成
```
CC Switch ユーザーマニュアル
│
├── 1. はじめに
│ ├── 1.1 ソフトウェア紹介
│ ├── 1.2 インストールガイド
│ ├── 1.3 インターフェース概要
│ ├── 1.4 クイックスタート
│ └── 1.5 個人設定
│
├── 2. プロバイダー管理
│ ├── 2.1 プロバイダーの追加
│ ├── 2.2 プロバイダーの切り替え
│ ├── 2.3 プロバイダーの編集
│ ├── 2.4 並べ替えと複製
│ └── 2.5 使用量クエリ
│
├── 3. 拡張機能
│ ├── 3.1 MCP サーバー管理
│ ├── 3.2 Prompts プロンプト管理
│ └── 3.3 Skills スキル管理
│
├── 4. プロキシと高可用性
│ ├── 4.1 プロキシサービス
│ ├── 4.2 アプリケーション接管
│ ├── 4.3 フェイルオーバー
│ ├── 4.4 使用量統計
│ └── 4.5 モデルテスト
│
└── 5. よくある質問
├── 5.1 設定ファイルの説明
├── 5.2 FAQ
├── 5.3 ディープリンクプロトコル
└── 5.4 環境変数の競合
```
## ファイル一覧
### 1. はじめに
| ファイル | 内容 |
|------|------|
| [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.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5 分でできるクイックスタートチュートリアル |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 言語、テーマ、ディレクトリ、クラウド同期の設定 |
### 2. プロバイダー管理
| ファイル | 内容 |
|------|------|
| [2.1-add.md](./2-providers/2.1-add.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) | 使用量クエリ、残額表示、複数プラン表示 |
### 3. 拡張機能
| ファイル | 内容 |
|------|------|
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP プロトコル、サーバーの追加、アプリバインド |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | プリセットの作成、有効化の切り替え、スマートバックフィル |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | スキルの発見、インストール・アンインストール、リポジトリ管理 |
### 4. プロキシと高可用性
| ファイル | 内容 |
|------|------|
| [4.1-service.md](./4-proxy/4.1-service.md) | プロキシの起動、設定項目、実行状態 |
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | アプリケーション接管、設定変更、ステータス表示 |
| [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) | モデルテスト、ヘルスチェック、レイテンシテスト |
### 5. よくある質問
| ファイル | 内容 |
|------|------|
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch のストレージ、CLI 設定ファイル形式 |
| [5.2-questions.md](./5-faq/5.2-questions.md) | よくある質問と回答 |
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | ディープリンクプロトコル、生成と使用方法 |
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | 環境変数の競合検出と対処 |
## クイックリンク
- **初めての方**：[1.1 ソフトウェア紹介](./1-getting-started/1.1-introduction.md) からお読みください
- **インストールの問題**：[1.2 インストールガイド](./1-getting-started/1.2-installation.md) をご確認ください
- **プロバイダーの設定**：[2.1 プロバイダーの追加](./2-providers/2.1-add.md) をご確認ください
- **プロキシの使用**：[4.1 プロキシサービス](./4-proxy/4.1-service.md) をご確認ください
- **お困りの方**：[5.2 FAQ](./5-faq/5.2-questions.md) をご確認ください
## バージョン情報
- ドキュメントバージョン：v3.11.1
- 最終更新：2026-03-02
- CC Switch v3.11.1+ 対応
## コントリビュート
Issue や PR でドキュメントの改善にご協力ください：
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
- [GitHub Repository](https://github.com/farion1231/cc-switch)

0
docs/user-manual/1-getting-started/1.1-introduction.md → docs/user-manual/zh/1-getting-started/1.1-introduction.md
View File

0
docs/user-manual/1-getting-started/1.2-installation.md → docs/user-manual/zh/1-getting-started/1.2-installation.md
View File

4
docs/user-manual/1-getting-started/1.3-interface.md → docs/user-manual/zh/1-getting-started/1.3-interface.md
View File

@@ -2,7 +2,7 @@
## 主界面布局
![image-20260108001629138](../assets/image-20260108001629138.png)
![image-20260108001629138](../../assets/image-20260108001629138.png)
## 顶部导航栏
@@ -93,7 +93,7 @@ CC Switch 在系统托盘显示图标，提供快速操作入口。
### 托盘菜单结构
![image-20260108002153668](../assets/image-20260108002153668.png)
![image-20260108002153668](../../assets/image-20260108002153668.png)
### 菜单功能

4
docs/user-manual/1-getting-started/1.4-quickstart.md → docs/user-manual/zh/1-getting-started/1.4-quickstart.md
View File

@@ -11,7 +11,7 @@
3. 填写 **API Key**
4. 点击「添加」
![image-20260108002807657](../assets/image-20260108002807657.png)
![image-20260108002807657](../../assets/image-20260108002807657.png)
> 💡 **提示**：预设会自动填充端点地址，你只需要填写 API Key。
@@ -44,7 +44,7 @@
2. 开启「跳过 Claude Code 初次安装确认」开关
3. 重新启动 Claude Code
![image-20260108002626389](../assets/image-20260108002626389.png)
![image-20260108002626389](../../assets/image-20260108002626389.png)
> ⚠️ **注意**：此选项会写入 `~/.claude/settings.json` 的 `skipIntroduction` 字段，跳过官方的新手引导流程。

0
docs/user-manual/1-getting-started/1.5-settings.md → docs/user-manual/zh/1-getting-started/1.5-settings.md
View File

2
docs/user-manual/2-providers/2.1-add.md → docs/user-manual/zh/2-providers/2.1-add.md
View File

@@ -351,5 +351,5 @@ CC Switch 支持两种方式导入供应商配置：
- 🟡 黄色：延迟 500-1000ms（一般）
- 🔴 红色：延迟 > 1000ms（较慢）
![image-20260108005327817](../assets/image-20260108005327817.png)
![image-20260108005327817](../../assets/image-20260108005327817.png)

2
docs/user-manual/2-providers/2.2-switch.md → docs/user-manual/zh/2-providers/2.2-switch.md
View File

@@ -32,7 +32,7 @@
### 托盘菜单结构
![image-20260108004348993](../assets/image-20260108004348993.png)
![image-20260108004348993](../../assets/image-20260108004348993.png)
## 生效方式

2
docs/user-manual/2-providers/2.3-edit.md → docs/user-manual/zh/2-providers/2.3-edit.md
View File

@@ -32,7 +32,7 @@ CC Switch 提供丰富的图标自定义功能：
- 显示图标名称提示
- 实时预览选中效果
![image-20260108004734882](../assets/image-20260108004734882.png)
![image-20260108004734882](../../assets/image-20260108004734882.png)
### 配置信息

2
docs/user-manual/2-providers/2.4-sort-duplicate.md → docs/user-manual/zh/2-providers/2.4-sort-duplicate.md
View File

@@ -73,4 +73,4 @@
- **当前启用的供应商**：可以删除，但建议先切换到其他供应商
- **统一供应商**：删除后，关联的应用配置也会被删除
![image-20260108004946288](../assets/image-20260108004946288.png)
![image-20260108004946288](../../assets/image-20260108004946288.png)

0
docs/user-manual/2-providers/2.5-usage-query.md → docs/user-manual/zh/2-providers/2.5-usage-query.md
View File

4
docs/user-manual/3-extensions/3.1-mcp.md → docs/user-manual/zh/3-extensions/3.1-mcp.md
View File

@@ -15,7 +15,7 @@ MCP (Model Context Protocol) 是一种协议，允许 AI 工具访问外部数
## 面板概览
![image-20260108005723522](../assets/image-20260108005723522.png)
![image-20260108005723522](../../assets/image-20260108005723522.png)
## 添加 MCP 服务器
@@ -26,7 +26,7 @@ MCP (Model Context Protocol) 是一种协议，允许 AI 工具访问外部数
3. 根据需要修改配置
4. 点击「保存」
![image-20260108005739731](../assets/image-20260108005739731.png)
![image-20260108005739731](../../assets/image-20260108005739731.png)
### 常用预设

2
docs/user-manual/3-extensions/3.2-prompts.md → docs/user-manual/zh/3-extensions/3.2-prompts.md
View File

@@ -16,7 +16,7 @@ Prompts 功能用于管理系统提示词预设。系统提示词会影响 AI
## 面板概览
![image-20260108010110382](../assets/image-20260108010110382.png)
![image-20260108010110382](../../assets/image-20260108010110382.png)
## 创建预设

6
docs/user-manual/3-extensions/3.3-skills.md → docs/user-manual/zh/3-extensions/3.3-skills.md
View File

@@ -27,7 +27,7 @@ Skills 功能支持所有四种应用：
## 页面概览
![image-20260108010253926](../assets/image-20260108010253926.png)
![image-20260108010253926](../../assets/image-20260108010253926.png)
## 发现技能
@@ -41,7 +41,7 @@ CC Switch 预配置了以下 GitHub 仓库：
| ComposioHQ | 社区维护的技能集合 |
| 社区精选 | 精选的高质量技能 |
![image-20260108010308060](../assets/image-20260108010308060.png)
![image-20260108010308060](../../assets/image-20260108010308060.png)
### 搜索过滤
@@ -64,7 +64,7 @@ CC Switch 提供强大的搜索和过滤功能：
| 已安装 | 仅显示已安装的技能 |
| 未安装 | 仅显示未安装的技能 |
![image-20260108010324583](../assets/image-20260108010324583.png)
![image-20260108010324583](../../assets/image-20260108010324583.png)
#### 组合使用

4
docs/user-manual/4-proxy/4.1-service.md → docs/user-manual/zh/4-proxy/4.1-service.md
View File

@@ -20,14 +20,14 @@
- 🔴 白色：代理未运行
- 🟢 绿色：代理运行中
![image-20260108011353927](../assets/image-20260108011353927.png)
![image-20260108011353927](../../assets/image-20260108011353927.png)
### 方式二：设置页面
1. 打开「设置 → 高级 → 代理服务」
2. 点击右上角的开关
![image-20260108011338922](../assets/image-20260108011338922.png)
![image-20260108011338922](../../assets/image-20260108011338922.png)
## 代理配置

0
docs/user-manual/4-proxy/4.2-takeover.md → docs/user-manual/zh/4-proxy/4.2-takeover.md
View File

0
docs/user-manual/4-proxy/4.3-failover.md → docs/user-manual/zh/4-proxy/4.3-failover.md
View File

12
docs/user-manual/4-proxy/4.4-usage.md → docs/user-manual/zh/4-proxy/4.4-usage.md
View File

@@ -44,7 +44,7 @@
| 最近 7 天 | 过去 7 天 |
| 最近 30 天 | 过去 30 天 |
![image-20260108011730105](../assets/image-20260108011730105.png)
![image-20260108011730105](../../assets/image-20260108011730105.png)
## 趋势图表
@@ -76,7 +76,7 @@
![image-20260108011742847](../assets/image-20260108011742847.png)
![image-20260108011742847](../../assets/image-20260108011742847.png)
## 详细数据
@@ -134,7 +134,7 @@
- **重置**：恢复默认（过去 24 小时）
- **刷新**：重新加载数据
![image-20260108011859974](../assets/image-20260108011859974.png)
![image-20260108011859974](../../assets/image-20260108011859974.png)
### 供应商统计
@@ -150,7 +150,7 @@
| 总 Token | Token 使用总量 |
| 估算费用 | 该供应商的费用 |
![image-20260108011907928](../assets/image-20260108011907928.png)
![image-20260108011907928](../../assets/image-20260108011907928.png)
### 模型统计
@@ -165,7 +165,7 @@
| 平均延迟 | 平均响应时间 |
| 估算费用 | 该模型的费用 |
![image-20260108011915381](../assets/image-20260108011915381.png)
![image-20260108011915381](../../assets/image-20260108011915381.png)
## 定价配置
@@ -192,7 +192,7 @@
- **编辑**：点击行末的编辑图标修改
- **删除**：点击行末的删除图标移除
![image-20260108011933565](../assets/image-20260108011933565.png)
![image-20260108011933565](../../assets/image-20260108011933565.png)
### 预设价格

0
docs/user-manual/4-proxy/4.5-model-test.md → docs/user-manual/zh/4-proxy/4.5-model-test.md
View File

0
docs/user-manual/5-faq/5.1-config-files.md → docs/user-manual/zh/5-faq/5.1-config-files.md
View File

0
docs/user-manual/5-faq/5.2-questions.md → docs/user-manual/zh/5-faq/5.2-questions.md
View File

0
docs/user-manual/5-faq/5.3-deeplink.md → docs/user-manual/zh/5-faq/5.3-deeplink.md
View File

0
docs/user-manual/5-faq/5.4-env-conflict.md → docs/user-manual/zh/5-faq/5.4-env-conflict.md
View File

111
docs/user-manual/zh/README.md Normal file
View File

@@ -0,0 +1,111 @@
# CC Switch 用户手册
> Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw 全方位辅助工具
## 目录结构
```
📚 CC Switch 用户手册
│
├── 1. 快速入门
│ ├── 1.1 软件介绍
│ ├── 1.2 安装指南
│ ├── 1.3 界面概览
│ ├── 1.4 快速上手
│ └── 1.5 个性化配置
│
├── 2. 供应商管理
│ ├── 2.1 添加供应商
│ ├── 2.2 切换供应商
│ ├── 2.3 编辑供应商
│ ├── 2.4 排序与复制
│ └── 2.5 用量查询
│
├── 3. 扩展功能
│ ├── 3.1 MCP 服务器管理
│ ├── 3.2 Prompts 提示词管理
│ └── 3.3 Skills 技能管理
│
├── 4. 代理与高可用
│ ├── 4.1 代理服务
│ ├── 4.2 应用接管
│ ├── 4.3 故障转移
│ ├── 4.4 用量统计
│ └── 4.5 模型检查
│
└── 5. 常见问题
├── 5.1 配置文件说明
├── 5.2 FAQ
├── 5.3 深度链接协议
└── 5.4 环境变量冲突
```
## 文件列表
### 1. 快速入门
| 文件 | 内容 |
|------|------|
| [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.4-quickstart.md](./1-getting-started/1.4-quickstart.md) | 5 分钟快速上手教程 |
| [1.5-settings.md](./1-getting-started/1.5-settings.md) | 语言、主题、目录、云同步配置 |
### 2. 供应商管理
| 文件 | 内容 |
|------|------|
| [2.1-add.md](./2-providers/2.1-add.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) | 用量查询、剩余额度、多套餐显示 |
### 3. 扩展功能
| 文件 | 内容 |
|------|------|
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP 协议、添加服务器、应用绑定 |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | 创建预设、激活切换、智能回填 |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | 发现技能、安装卸载、仓库管理 |
### 4. 代理与高可用
| 文件 | 内容 |
|------|------|
| [4.1-service.md](./4-proxy/4.1-service.md) | 启动代理、配置项、运行状态 |
| [4.2-takeover.md](./4-proxy/4.2-takeover.md) | 应用接管、配置修改、状态指示 |
| [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) | 模型检查、健康检测、延迟测试 |
### 5. 常见问题
| 文件 | 内容 |
|------|------|
| [5.1-config-files.md](./5-faq/5.1-config-files.md) | CC Switch 存储、CLI 配置文件格式 |
| [5.2-questions.md](./5-faq/5.2-questions.md) | 常见问题解答 |
| [5.3-deeplink.md](./5-faq/5.3-deeplink.md) | 深度链接协议、生成和使用方法 |
| [5.4-env-conflict.md](./5-faq/5.4-env-conflict.md) | 环境变量冲突检测与处理 |
## 快速链接
- **新用户**：从 [1.1 软件介绍](./1-getting-started/1.1-introduction.md) 开始
- **安装问题**：查看 [1.2 安装指南](./1-getting-started/1.2-installation.md)
- **配置供应商**：查看 [2.1 添加供应商](./2-providers/2.1-add.md)
- **使用代理**：查看 [4.1 代理服务](./4-proxy/4.1-service.md)
- **遇到问题**：查看 [5.2 FAQ](./5-faq/5.2-questions.md)
## 版本信息
- 文档版本：v3.11.1
- 最后更新：2026-02-28
- 适用于 CC Switch v3.11.1+
## 贡献
欢迎提交 Issue 或 PR 改进文档：
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
- [GitHub Repository](https://github.com/farion1231/cc-switch)