CC-Switch：AI 编程助手配置管理完全指南

CC-Switch：AI 编程助手配置管理完全指南

12.4K⭐ GitHub 热榜工具，一键切换 Claude Code/Codex/Gemini 配置，效率提升 300%

一、CC-Switch 是什么？

CC-Switch 是一款跨平台的桌面应用程序，专门用于管理 Claude Code、Codex 和 Gemini CLI 的 API 配置。作为一个"All-in-One"助手工具，它可以帮助开发者轻松切换不同的 AI 服务提供商，管理 MCP 服务器，以及组织提示词和工作流。

📊 项目数据

| 指标 | 数据 |

|------|------|

| GitHub Stars | 12,400+ |

| Forks | 799 |

| Contributors | 35+ |

| 最新版本 | v3.9.1 |

| Release Date | 2026-01-09 |

🌟 核心特性

🔄 一键切换 - 快速在不同 API 提供商之间切换

⚡ 速度测试 - 测试 API 端点延迟，可视化质量指标

🛡️ 自动故障转移 - 断路器机制，自动切换到备用提供商

🌐 本地 API 代理 - 高性能 HTTP 代理，支持各应用独立接管

🧩 MCP 服务器管理 - 统一管理 Claude/Codex/Gemini 的 MCP 服务器

💾 Skills 管理系统 - 从 GitHub 仓库一键安装/卸载 Claude Skills

📝 Prompts 管理 - 多预设系统提示词管理

🔗 通用提供商 - 单一配置同步到多个应用

☁️ 云同步准备 - SQLite + JSON 双层架构，为云同步奠定基础

💡 为什么选择 CC-Switch？

作为开发者，你是否也遇到过这些烦恼？

🤯 配置混乱 - Claude Code、Codex、Gemini 三个工具的配置文件散落各处，每次切换都要手动修改

⏱️ 切换耗时 - 想换个 API 提供商，翻遍配置文件找半天

💸 成本失控 - 多个账号分散管理，用量和费用统计一团糟

🔧 MCP 繁琐 - 手动配置 MCP 服务器，每个工具都要重复一遍

CC-Switch 的核心价值：

✅ 统一管理 - Claude Code、Codex、Gemini 三个工具，一个界面搞定

✅ 一键切换 - 毫秒级切换 API 提供商，告别手动修改配置

✅ 智能代理 - 本地 API 代理 + 自动故障转移，保证服务稳定

✅ 专业功能 - MCP 管理、Skills 管理、Prompts 管理全覆盖

✅ 可视化监控 - 实时用量统计、延迟测试、日志追踪

✅ 安全可靠 - 自动备份、断路器保护、数据加密存储

📈 效率对比

| 场景 | 传统方式 | 使用 CC-Switch | 效率提升 |

|------|----------|---------------|----------|

| 切换 API 提供商 | 打开配置文件 → 修改 → 保存 → 重启 | 点击切换按钮 | 95% |

| 配置 MCP 服务器 | 手动编辑 JSON/TOML → 多文件同步 | 图形界面管理 | 80% |

| 查看用量统计 | 登录多个平台查看 | 统一面板查看 | 90% |

| 安装 Claude Skills | Git clone → 手动移动文件 | 一键安装/卸载 | 85% |

---

二、快速开始

📋 系统要求

| 系统 | 最低版本 | 架构 |

|------|----------|------|

| Windows | Windows 10 | x64 |

| macOS | macOS 10.15 (Catalina) | Intel/Apple Silicon |

| Linux | Ubuntu 22.04+ / Debian 11+ / Fedora 34+ | x64 |

🚀 安装方式

Windows

方式一：MSI 安装器（推荐）

1. 下载 CC-Switch-v3.9.1-Windows.msi

2. 双击运行安装程序

3. 按提示完成安装

方式二：便携版本

下载 CC-Switch-v3.9.1-Windows-Portable.zip，解压后直接使用

macOS

方式一：Homebrew（推荐）

# 添加 Tap

brew tap farion1231/ccswitch

# 安装

brew install --cask cc-switch

# 更新

brew upgrade --cask cc-switch

方式二：手动安装

1. 下载 CC-Switch-v3.9.1-macOS.zip

2. 解压并拖动到「应用程序」文件夹

3. 首次运行若提示"无法验证开发者"，前往「系统设置」→「隐私与安全性」点击"仍要打开"

Linux

Debian/Ubuntu:

sudo dpkg -i CC-Switch-v3.9.1-Linux.deb

# 或

sudo apt install ./CC-Switch-v3.9.1-Linux.deb

Fedora/RHEL:

sudo rpm -i CC-Switch-v3.9.1-Linux.rpm

# 或

sudo dnf install ./CC-Switch-v3.9.1-Linux.rpm

Arch Linux (paru):

paru -S cc-switch-bin

AppImage（通用）:

chmod +x CC-Switch-v3.9.1-Linux.AppImage

./CC-Switch-v3.9.1-Linux.AppImage

Flatpak:

flatpak install ./CC-Switch-v3.9.1-Linux.flatpak

flatpak run com.ccswitch.desktop

🎯 基础使用

1. 添加提供商

1. 启动 CC-Switch

2. 点击主界面右上角 "Add Provider"

3. 选择预设或创建自定义配置

4. 填写 API Key、Base URL 等信息

5. 保存后即可使用

2. 切换提供商

• 主界面: 选择提供商 → 点击 "Enable"

• 系统托盘: 直接点击提供商名称（即时生效）

3. 生效方式

重启你的终端或 Claude Code / Codex / Gemini 客户端以应用更改。

4. 返回官方登录

选择 "Official Login" 预设（Claude/Codex）或 "Google Official" 预设（Gemini），重启对应客户端，然后按照其登录/OAuth 流程操作即可。

---

三、核心功能详解

🏢 提供商管理

CC-Switch 的核心功能是管理多个 AI 服务提供商配置，支持一键切换。

预设提供商

内置多个预设配置，开箱即用：

| 提供商 | 类型 | 说明 |

|--------|------|------|

| Official Login | 官方 | Claude/Codex 官方登录 |

| OpenRouter | 第三方 | 多模型聚合平台 |

| AIGoCode | 合作伙伴 | 稳定高效的 AI 编码服务 |

| PackyCode | 合作伙伴 | API 中继服务 |

| DMXAPI | 合作伙伴 | 全球大模型 API 服务 |

| Cubence | 合作伙伴 | 灵活的 API 中继服务 |

| GLM (智谱) | 合作伙伴 | GLM-4.6 模型 |

| DeepSeek | 通用 | 国产大模型 |

| MiniMax | 合作伙伴 | AI 编码专用模型 |

| 通义千问 | 通用 | 阿里云模型 |

| Kimi | 通用 | 月之暗面模型 |

自定义提供商

{

"name": "My Provider",

"apiKey": "sk-...",

"baseUrl": "https://api.example.com/v1",

"model": "claude-sonnet-4-20250514",

"models": {

"haiku": "claude-haiku-3-20250520",

"sonnet": "claude-sonnet-4-20250514",

"opus": "claude-opus-4-20250520"

}

}

实战案例：多项目多提供商

假设你有三个项目，分别使用不同的 API 提供商：

项目 A（个人项目） → DeepSeek（便宜快速）

项目 B（企业项目） → OpenRouter（模型丰富）

项目 C（实验性质） → Claude 官方（稳定可靠）

CC-Switch 方式：

项目 A → 点击 DeepSeek 卡片 → Enable

项目 B → 点击 OpenRouter 卡片 → Enable

项目 C → 点击 Claude Official 卡片 → Enable

每个切换耗时不超过 2 秒！

🧩 MCP 服务器管理

MCP（Model Context Protocol）服务器管理是 CC-Switch 的重要功能。

访问 MCP 管理

点击主界面右上角 "MCP" 按钮

添加 MCP 服务器

方式一：使用内置模板

• mcp-fetch - 网页抓取

• mcp-filesystem - 文件系统操作

• mcp-github - GitHub 集成

• 等多种预置模板

方式二：自定义配置

{

"name": "custom-mcp",

"type": "stdio",

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],

"env": {}

}

传输类型

| 类型 | 说明 |

|------|------|

| stdio | 标准输入/输出 |

| http | HTTP 传输 |

| SSE | Server-Sent Events |

启用/禁用服务器

• 使用开关控制哪些服务器同步到实时配置文件

• 启用的服务器会自动同步到对应应用的配置文件中

实战案例：配置文件系统 MCP

CC-Switch 方式：

1. 点击 "MCP" 按钮

2. 选择内置模板 mcp-filesystem

3. 设置目录路径

4. 勾选需要同步的应用

5. 保存，自动同步到三个工具

优势：

• 无需手动编辑 JSON/TOML 文件

• 自动同步到 Claude/Codex/Gemini

• 支持多种传输类型

💾 Skills 管理系统

v3.7.0 引入的 Claude Skills 管理功能。

访问 Skills 管理

点击主界面右上角 "Skills" 按钮

发现 Skills

预配置仓库（自动扫描）:

• Anthropic 官方仓库

• ComposioHQ 仓库

• 社区仓库

自定义仓库:

• 添加自己的 GitHub 仓库

• 支持子目录扫描

安装/卸载 Skills

• 安装: 点击 "Install" 一键安装到 ~/.claude/skills/

• 卸载: 点击 "Uninstall" 安全移除并清理状态

多应用支持

v3.9.0 开始支持 Claude Code 和 Codex 的多应用 Skills：

~/.claude/

├── skills/ # Claude Code Skills

└── codex/

└── skills/ # Codex Skills

实战案例：安装 GitHub 集成 Skill

1. 点击 "Skills" 按钮

2. 自动扫描预配置仓库

3. 找到 GitHub Integration Skill

4. 点击 "Install"

5. 自动安装到对应目录

优势：

• 自动更新检查

• 版本管理

• 一键卸载

• 支持自定义仓库

📝 Prompts 管理系统

v3.7.0 引入的提示词管理功能。

访问 Prompts 管理

点击主界面右上角 "Prompts" 按钮

创建预设

1. 点击 "New Preset"

2. 使用 Markdown 编辑器编写提示词

3. 语法高亮 + 实时预览

4. 保存预设

同步机制

| 应用 | 配置文件 |

|------|----------|

| Claude Code | ~/.claude/CLAUDE.md |

| Codex | ~/.codex/AGENTS.md |

| Gemini | ~/.gemini/GEMINI.md |

保护机制

切换预设时自动保存当前提示词内容，防止手动修改丢失。

实战案例：多场景提示词切换

不同项目需要不同的系统提示词：

代码审查 → 严格模式，关注安全性

文档生成 → 详细模式，注重完整性

快速原型 → 简洁模式，关注效率

功能特性：

• Markdown 编辑器 - 语法高亮 + 实时预览

• 多预设管理 - 无数量限制，快速切换

• 自动同步 - 切换预设时自动写入对应文件

• 保护机制 - 手动修改会被自动保存，不会丢失

🌐 本地 API 代理（v3.9.0 新功能）

CC-Switch v3.9.0 带来了强大的本地 API 代理功能。

核心特性

• 高性能 HTTP 代理 - 基于 Axum 框架

• 统一代理 - 同时支持 Claude Code/Codex/Gemini

• 按应用接管 - 独立控制每个应用的代理路由

• 实时监控 - 请求日志和用量统计

• 错误日志 - 详细记录失败的代理请求

启用代理

1. 进入设置 → "Proxy" 标签

2. 启用 "Enable Proxy"

3. 选择需要代理的应用

4. 代理自动接管选定应用的配置

配置示例

{

"proxy": {

"enabled": true,

"port": 15721,

"perAppTakeover": {

"claudeCode": true,

"codex": false,

"gemini": false

},

"logging": {

"requests": true,

"errors": true

}

}

}

⚠️ 注意: 代理接管会修改 CLI 实时配置，CC-Switch 会自动备份原配置

实战案例：企业内网代理

需求：公司要求所有 API 请求必须通过内网代理，Claude Code 走代理，Codex 直连

配置步骤：

1. 进入设置 → "Proxy" 标签

2. 启用 "Enable Proxy"

3. 在 "Per App Takeover" 中：

• ✅ Claude Code - 开启

• ❌ Codex - 关闭

• ❌ Gemini - 关闭

4. 配置代理地址和端口

效果：

Claude Code 请求 → 本地代理(15721端口) → 内网代理 → API 提供商

Codex 请求 → 直连 API 提供商

监控界面

代理启用后，可以看到：

• 实时请求流量

• 响应延迟统计

• 错误请求日志

• 按模型分类的用量

🛡️ 自动故障转移（v3.9.0 新功能）

断路器机制的自动故障转移功能。

工作原理

1. 健康检测 - 实时监控提供商状态

2. 故障检测 - 自动识别提供商故障

3. 自动切换 - 切换到备用提供商

4. 独立队列 - 每个应用维护独立的故障转移队列

配置故障转移

1. 进入设置 → "Failover" 标签

2. 启用 "Enable Auto Failover"

3. 设置故障检测超时

4. 配置备用提供商列表

配置示例

{

"failover": {

"enabled": true,

"timeout": 5000, // 5秒超时

"retryCount": 3, // 重试3次

"providers": [ // 备用队列

"openrouter",

"deepseek",

"aigocode"

]

}

}

实战案例：API 故障自动切换

场景：某个 API 提供商突然宕机或限流

传统方式：

发现请求失败 → 切换到备用提供商 → 配置错误 → 再切换...

至少浪费 5-10 分钟

CC-Switch 方式：

检测到故障 → 自动切换到备用提供商 → 继续工作

几乎无感知！

🔗 通用提供商（v3.9.0 新功能）

单一配置可同步到多个应用。

使用场景

适用于 API 网关（如 NewAPI）支持多协议的场景。

配置方式

1. 创建提供商时选择 "Universal" 类型

2. 设置各应用的默认模型映射

3. 启用需要同步的应用

{

"type": "universal",

"name": "NewAPI Gateway",

"apiKey": "sk-xxx",

"baseUrl": "https://api.newapi.com/v1",

"models": {

"claudeCode": "claude-3.5-sonnet",

"codex": "gpt-4o",

"gemini": "gemini-2.0-pro"

}

}

实战案例：API 网关统一配置

传统方式：

创建 Provider A → 配置 API Key → 手动同步到 Claude

创建 Provider B → 配置 API Key → 手动同步到 Codex

创建 Provider C → 配置 API Key → 手动同步到 Gemini

CC-Switch 方式：

创建 Universal Provider → 配置一次 → 自动同步到所有应用

📊 速度测试

测试 API 端点延迟和可用性。

使用方法

1. 选择要测试的提供商

2. 点击 "Speed Test"

3. 查看延迟和质量指标

指标说明

| 指标 | 说明 |

|------|------|

| Latency | API 响应延迟 |

| Quality | 连接质量评级 |

| Availability | 可用性状态 |

实战案例：三个提供商对比

DeepSeek → Latency: 234ms Quality: A

OpenRouter → Latency: 512ms Quality: B

Claude 官方 → Latency: 89ms Quality: A

根据结果：

• 急用项目 → Claude 官方

• 成本敏感 → DeepSeek

• 模型丰富 → OpenRouter

📦 导入/导出

导出配置

1. 进入设置 → "Import/Export"

2. 点击 "Export"

3. 选择导出格式（JSON/SQL）

4. 保存备份文件

导入配置

1. 进入设置 → "Import/Export"

2. 点击 "Import"

3. 选择备份文件

4. 确认导入

自动备份

• 自动轮转备份，保留最近 10 个备份

• 备份位置: ~/.cc-switch/backups/

---

四、配置详解

📁 配置文件位置

CC-Switch 存储（v3.8.0 新架构）

~/.cc-switch/

├── cc-switch.db # SQLite 数据库（单一数据源）

├── settings.json # 本地设置（窗口状态、路径覆盖等）

└── backups/ # 自动备份目录

Claude Code 配置

| 文件 | 说明 |

|------|------|

| ~/.claude/settings.json | 实时配置 |

| ~/.claude.json | MCP 服务器配置 |

| ~/.claude/skills/ | Skills 目录 |

API Key 字段:

{

"env": {

"ANTHROPIC_AUTH_TOKEN": "sk-ant-...",

"ANTHROPIC_API_KEY": "sk-..."

}

}

Codex 配置

| 文件 | 说明 |

|------|------|

| ~/.codex/auth.json | 认证配置（必需） |

| ~/.codex/config.toml | MCP 服务器配置（可选） |

API Key 字段 (auth.json):

{

"OPENAI_API_KEY": "sk-..."

}

Gemini 配置

| 文件 | 说明 |

|------|------|

| ~/.gemini/.env | API Key |

| ~/.gemini/settings.json | 认证模式和 MCP 服务器 |

API Key 字段 (.env):

GEMINI_API_KEY=AI...

GOOGLE_GEMINI_API_KEY=AI...

⚙️ 设置选项

基础设置

| 选项 | 说明 |

|------|------|

| 开机自启 | 开机自动运行 CC-Switch |

| 语言 | 中文/English/日本語 |

| 主题 | 深色/浅色/跟随系统 |

| 系统托盘 | 显示/隐藏托盘图标 |

代理设置

| 选项 | 说明 |

|------|------|

| 启用代理 | 启动本地 API 代理 |

| 代理端口 | 默认 15721 |

| 按应用接管 | 独立控制每个应用 |

| 请求日志 | 记录代理请求 |

| 错误日志 | 记录失败请求 |

故障转移设置

| 选项 | 说明 |

|------|------|

| 启用故障转移 | 开启自动故障切换 |

| 超时时间 | 检测超时时间 |

| 重试次数 | 故障时重试次数 |

| 备用列表 | 备用提供商优先级 |

---

五、进阶功能

🔧 共用配置片段（v3.9.0 新功能）

维护可复用的配置片段，自动合并到提供商配置中。

创建共用片段

1. 进入 Provider 编辑页面

2. 点击 "Extract Common Snippet"

3. 选择从编辑器内容或当前提供商提取

4. 保存为共用片段

合并规则

• Claude: 合并到 settings.json

• Codex: 移除 provider-specific 字段后合并

• Gemini: 合并到 .env 和 settings.json

💰 用量统计

跟踪 API 使用情况和费用。

访问用量面板

主界面 → "Usage" 按钮

功能特性

• 自动刷新 - 定时更新用量数据

• 模型统计 - 按模型分类统计

• 缓存指标 - 显示缓存命中/创建情况

• 时区处理 - 正确处理夏令时

配置用量查询

{

"usage": {

"provider": "openrouter",

"apiKey": "sk-...",

"baseUrl": "https://openrouter.ai/api/v1"

}

}

☁️ 云同步设置

设置步骤

1. 进入设置 → "Advanced"

2. 点击 "Custom Configuration Directory"

3. 选择云同步文件夹（Dropbox/OneDrive/iCloud 等）

4. 重启应用生效

数据同步

| 数据类型 | 同步方式 |

|----------|----------|

| Providers | SQLite 数据库 |

| MCP | SQLite 数据库 |

| Prompts | SQLite 数据库 |

| Skills | SQLite 数据库 |

| 窗口状态 | 本地 JSON |

⌨️ 快捷键

| 快捷键 | 功能 |

|--------|------|

| Cmd/Ctrl + , | 打开设置 |

| Esc | 关闭模态框 |

---

六、实用技巧

💡 技巧一：使用系统托盘快速切换

macOS / Windows / Linux 都支持系统托盘图标：

场景：正在编码，突然需要切换提供商

传统方式：打开 CC-Switch → 找到提供商 → 点击 Enable

快捷方式：点击托盘图标 → 选择提供商 → 立即切换

💡 技巧二：提供商搜索过滤

提供商多了之后如何快速找到？

1. 点击搜索框

2. 输入关键词（如 "deepseek"、"aigocode"）

3. 实时过滤，支持模糊匹配

💡 技巧三：自定义图标颜色

为不同类别的提供商设置不同颜色：

官方提供商 → 蓝色

聚合平台 → 绿色

国产模型 → 红色

测试环境 → 灰色

视觉识别速度提升 200%！

💡 技巧四：自定义图标颜色配置

1. 进入提供商编辑页面

2. 点击图标颜色选择器

3. 选择你喜欢的颜色

4. 保存生效

💡 技巧五：跳过首次运行确认

Claude Code 首次运行需要确认对话框，嫌烦？

1. 进入设置 → "General"

2. 启用 "Skip Claude Code First Run"

---

七、故障排除

❓ 常见问题

1. 代理端口冲突

问题: macOS 12+ 上 AirPlay Receiver 占用 5000 端口

解决: CC-Switch v3.9.1 默认端口已改为 15721，如需手动修改：

{

"proxy": {

"port": 15721

}

}

2. macOS "无法验证开发者"警告

解决:

1. 关闭弹窗

2. 前往「系统设置」→「隐私与安全性」

3. 点击「仍要打开」

3. UTF-8 边界崩溃

v3.9.1 已修复多字节字符（中文、Emoji）导致的崩溃问题。

4. SQL 导入限制

出于安全考虑，SQL 导入仅支持 CC-Switch 导出的备份文件。

5. 配置文件不生效

检查清单：

• API Key 是否正确（不要有多余空格）

• Base URL 是否完整（末尾不要有斜杠）

• 模型名称是否准确（区分大小写）

• 是否重启了对应的 AI 助手客户端

🔧 日志位置

| 系统 | 日志位置 |

|------|----------|

| macOS | ~/Library/Logs/com.ccswitch.desktop/ |

| Linux | ~/.local/share/cc-switch/logs/ |

| Windows | %LOCALAPPDATA%\cc-switch\logs\ |

🔄 数据备份

重要: 运行新版本前请备份数据

# 备份数据库

cp ~/.cc-switch/cc-switch.db ~/.cc-switch/cc-switch.db.backup

# 备份配置

cp ~/.cc-switch/settings.json ~/.cc-switch/settings.json.backup

---

八、更新日志

v3.9.1（2026-01-09）

Bug 修复:

• 修复代理端口冲突（5000 → 15721）

• 修复 UTF-8 边界崩溃（中文、Emoji 处理）

• 修复 unwrap/expect 导致的 panic

• 添加 SOCKS 代理支持

• Windows 窗口标题修复

新功能:

• 添加崩溃日志功能

• 添加 AiGoCode 图标和合作伙伴推广

v3.9.0（2026-01-07）

主要特性:

• 本地 API 代理（Axum-based）

• 自动故障转移（断路器机制）

• 通用提供商支持

• Skills 多应用支持

• 共用配置片段

• MCP 从已安装应用导入

UX 改进:

• 提供商搜索过滤

• 提供商图标颜色自定义

• Cmd/Ctrl + , 打开设置

• 面板切换淡入淡出动画

v3.8.0（2025-11-28）

架构升级:

• SQLite + JSON 双层架构

• 为云同步奠定基础

• 数据库 Schema 版本管理

界面重构:

• 全新的用户界面

• 更流畅的动画效果

• 日语语言支持

新功能:

• Skills 递归扫描

• 开机自启

• 提供商图标配置

---

九、总结

CC-Switch 是一款功能强大的 AI 编程助手配置管理工具，其核心价值在于：

🎯 适用人群

• ✅ AI 助手重度用户 - Claude/Codex/Gemini 都在用

• ✅ 多项目开发者 - 不同项目用不同提供商

• ✅ 成本敏感型 - 需要用量统计和成本控制

• ✅ 配置管理困难户 - 讨厌手动编辑配置文件

• ✅ 追求效率者 - 希望减少重复操作

📈 效率提升数据

| 操作 | 传统方式 | CC-Switch | 提升 |

|------|----------|----------|------|

| 切换提供商 | 5-10 分钟 | 2 秒 | 150x |

| 配置 MCP | 15-30 分钟 | 3 分钟 | 5-10x |

| 查看用量 | 5-10 分钟 | 30 秒 | 10-20x |

| 安装 Skill | 10-20 分钟 | 1 分钟 | 10-20x |

💰 成本节省

• 避免因配置错误导致的 API 浪费

• 精准的用量统计帮助优化成本

• 合作伙伴折扣码直接省钱

🔒 安全可靠

• MIT 开源协议，代码透明

• 自动备份机制，防止数据丢失

• 严格的 SQL 导入限制

对于经常使用 AI 编程助手的开发者来说，CC-Switch 是提升工作效率的利器。

---

十、资源链接

📚 官方资源

| 资源 | 链接 |

|------|------|

| GitHub 仓库 | github.com/farion1231/… |

| 官方文档 | github.com/farion1231/… |

| 下载页面 | github.com/farion1231/… |

| 讨论社区 | github.com/farion1231/… |

| 问题反馈 | github.com/farion1231/…