AI摘要：高性能 HTTP 代理，支持各应用独立接管 🧩 MCP 服务器管理 - 统一管理 Claude/Codex/Gemini 的 MCP 服务器 💾 Skills 管理系统 - 从 GitHub 仓库一键安装/卸载 Claude Skills 📝🤯 配置混乱 - 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% | |:
Arch Linux (paru):
AppImage（通用）:
Flatpak:
🎯 基础使用 1. 添加提供商
启动 CC-Switch
点击主界面右上角 "Add Provider"
选择预设或创建自定义配置
填写 API Key、Base URL 等信息
保存后即可使用
主界面: 选择提供商 → 点击 "Enable"
系统托盘: 直接点击提供商名称（即时生效）
3.
12.4K⭐ GitHub 热榜工具，一键切换 Claude Code/Codex/Gemini 配置，效率提升 300%
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 双层架构，为云同步奠定基础
作为开发者，你是否也遇到过这些烦恼？
🤯 配置混乱 - 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 |
方式一：MSI 安装器（推荐）
下载 CC-Switch-v3.9.1-Windows.msi
CC-Switch-v3.9.1-Windows.msi
双击运行安装程序
按提示完成安装
方式二：便携版本
下载 CC-Switch-v3.9.1-Windows-Portable.zip，解压后直接使用
CC-Switch-v3.9.1-Windows-Portable.zip
方式一：Homebrew（推荐）
方式二：手动安装
下载 CC-Switch-v3.9.1-macOS.zip
CC-Switch-v3.9.1-macOS.zip
解压并拖动到「应用程序」文件夹
首次运行若提示"无法验证开发者"，前往「系统设置」→「隐私与安全性」点击"仍要打开"
Debian/Ubuntu:
Fedora/RHEL:
重启你的终端或 Claude Code / Codex / Gemini 客户端以应用更改。
选择 "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 | 通用 | 月之暗面模型 |
假设你有三个项目，分别使用不同的 API 提供商：
CC-Switch 方式：
每个切换耗时不超过 2 秒！
MCP（Model Context Protocol）服务器管理是 CC-Switch 的重要功能。
点击主界面右上角 "MCP" 按钮
方式一：使用内置模板
mcp-fetch - 网页抓取
mcp-fetch
mcp-filesystem - 文件系统操作
mcp-filesystem
mcp-github - GitHub 集成
mcp-github
等多种预置模板
方式二：自定义配置
| 类型 | 说明 |
| stdio | 标准输入/输出 |
| http | HTTP 传输 |
| SSE | Server-Sent Events |
使用开关控制哪些服务器同步到实时配置文件
启用的服务器会自动同步到对应应用的配置文件中
点击 "MCP" 按钮
选择内置模板 mcp-filesystem
设置目录路径
勾选需要同步的应用
保存，自动同步到三个工具
优势：
无需手动编辑 JSON/TOML 文件
自动同步到 Claude/Codex/Gemini
支持多种传输类型
v3.7.0 引入的 Claude Skills 管理功能。
点击主界面右上角 "Skills" 按钮
预配置仓库（自动扫描）:
Anthropic 官方仓库
ComposioHQ 仓库
社区仓库
自定义仓库:
添加自己的 GitHub 仓库
支持子目录扫描
安装: 点击 "Install" 一键安装到 ~/.claude/skills/
~/.claude/skills/
卸载: 点击 "Uninstall" 安全移除并清理状态
v3.9.0 开始支持 Claude Code 和 Codex 的多应用 Skills：
点击 "Skills" 按钮
自动扫描预配置仓库
找到 GitHub Integration Skill
GitHub Integration
点击 "Install"
自动安装到对应目录
自动更新检查
版本管理
一键卸载
支持自定义仓库
v3.7.0 引入的提示词管理功能。
点击主界面右上角 "Prompts" 按钮
点击 "New Preset"
使用 Markdown 编辑器编写提示词
语法高亮 + 实时预览
保存预设
| 应用 | 配置文件 |
|------|----------|
| Claude Code | ~/.claude/CLAUDE.md |
~/.claude/CLAUDE.md
| Codex | ~/.codex/AGENTS.md |
~/.codex/AGENTS.md
| Gemini | ~/.gemini/GEMINI.md |
~/.gemini/GEMINI.md
切换预设时自动保存当前提示词内容，防止手动修改丢失。
不同项目需要不同的系统提示词：
功能特性：
Markdown 编辑器 - 语法高亮 + 实时预览
多预设管理 - 无数量限制，快速切换
自动同步 - 切换预设时自动写入对应文件
保护机制 - 手动修改会被自动保存，不会丢失
CC-Switch v3.9.0 带来了强大的本地 API 代理功能。
高性能 HTTP 代理 - 基于 Axum 框架
统一代理 - 同时支持 Claude Code/Codex/Gemini
按应用接管 - 独立控制每个应用的代理路由
实时监控 - 请求日志和用量统计
错误日志 - 详细记录失败的代理请求
进入设置 → "Proxy" 标签
启用 "Enable Proxy"
选择需要代理的应用
代理自动接管选定应用的配置
⚠️ 注意: 代理接管会修改 CLI 实时配置，CC-Switch 会自动备份原配置
需求：公司要求所有 API 请求必须通过内网代理，Claude Code 走代理，Codex 直连
配置步骤：
在 "Per App Takeover" 中：
✅ Claude Code - 开启
❌ Codex - 关闭
❌ Gemini - 关闭
效果：
代理启用后，可以看到：
实时请求流量
响应延迟统计
错误请求日志
按模型分类的用量
断路器机制的自动故障转移功能。
健康检测 - 实时监控提供商状态
故障检测 - 自动识别提供商故障
自动切换 - 切换到备用提供商
独立队列 - 每个应用维护独立的故障转移队列
进入设置 → "Failover" 标签
启用 "Enable Auto Failover"
设置故障检测超时
配置备用提供商列表
场景：某个 API 提供商突然宕机或限流
传统方式：
至少浪费 5-10 分钟
几乎无感知！
单一配置可同步到多个应用。
适用于 API 网关（如 NewAPI）支持多协议的场景。
创建提供商时选择 "Universal" 类型
设置各应用的默认模型映射
启用需要同步的应用
测试 API 端点延迟和可用性。
选择要测试的提供商
点击 "Speed Test"
查看延迟和质量指标
| 指标 | 说明 |
| Latency | API 响应延迟 |
| Quality | 连接质量评级 |
| Availability | 可用性状态 |
根据结果：
急用项目 → Claude 官方
成本敏感 → DeepSeek
模型丰富 → OpenRouter
进入设置 → "Import/Export"
点击 "Export"
选择导出格式（JSON/SQL）
保存备份文件
点击 "Import"
选择备份文件
确认导入
自动轮转备份，保留最近 10 个备份
备份位置: ~/.cc-switch/backups/
~/.cc-switch/backups/
| 文件 | 说明 |
| ~/.claude/settings.json | 实时配置 |
~/.claude/settings.json
| ~/.claude.json | MCP 服务器配置 |
~/.claude.json
| ~/.claude/skills/ | Skills 目录 |
API Key 字段:
| ~/.codex/auth.json | 认证配置（必需） |
~/.codex/auth.json
| ~/.codex/config.toml | MCP 服务器配置（可选） |
~/.codex/config.toml
API Key 字段 (auth.json):
auth.json
| ~/.gemini/.env | API Key |
~/.gemini/.env
| ~/.gemini/settings.json | 认证模式和 MCP 服务器 |
~/.gemini/settings.json
API Key 字段 (.env):
.env
| 选项 | 说明 |
| 开机自启 | 开机自动运行 CC-Switch |
| 语言 | 中文/English/日本语 |
| 主题 | 深色/浅色/跟随系统 |
| 系统托盘 | 显示/隐藏托盘图标 |
| 启用代理 | 启动本地 API 代理 |
| 代理端口 | 默认 15721 |
| 按应用接管 | 独立控制每个应用 |
| 请求日志 | 记录代理请求 |
| 错误日志 | 记录失败请求 |
| 启用故障转移 | 开启自动故障切换 |
| 超时时间 | 检测超时时间 |
| 重试次数 | 故障时重试次数 |
| 备用列表 | 备用提供商优先级 |
维护可复用的配置片段，自动合并到提供商配置中。
进入 Provider 编辑页面
点击 "Extract Common Snippet"
选择从编辑器内容或当前提供商提取
保存为共用片段
Claude: 合并到 settings.json
settings.json
Codex: 移除 provider-specific 字段后合并
Gemini: 合并到 .env 和 settings.json
跟踪 API 使用情况和费用。
主界面 → "Usage" 按钮
自动刷新 - 定时更新用量数据
模型统计 - 按模型分类统计
缓存指标 - 显示缓存命中/创建情况
时区处理 - 正确处理夏令时
进入设置 → "Advanced"
点击 "Custom Configuration Directory"
选择云同步文件夹（Dropbox/OneDrive/iCloud 等）
重启应用生效
| 数据类型 | 同步方式 |
|----------|----------|
| Providers | SQLite 数据库 |
| MCP | SQLite 数据库 |
| Prompts | SQLite 数据库 |
| Skills | SQLite 数据库 |
| 窗口状态 | 本地 JSON |
| 快捷键 | 功能 |
|--------|------|
| Cmd/Ctrl + , | 打开设置 |
Cmd/Ctrl + ,
| Esc | 关闭模态框 |
Esc
macOS / Windows / Linux 都支持系统托盘图标：
场景：正在编码，突然需要切换提供商
传统方式：打开 CC-Switch → 找到提供商 → 点击 Enable
快捷方式：点击托盘图标 → 选择提供商 → 立即切换
提供商多了之后如何快速找到？
点击搜索框
输入关键词（如 "deepseek"、"aigocode"）
实时过滤，支持模糊匹配
为不同类别的提供商设置不同颜色：
视觉识别速度提升 200%！
进入提供商编辑页面
点击图标颜色选择器
选择你喜欢的颜色
保存生效
Claude Code 首次运行需要确认对话框，嫌烦？
进入设置 → "General"
启用 "Skip Claude Code First Run"
问题: macOS 12+ 上 AirPlay Receiver 占用 5000 端口
解决: CC-Switch v3.9.1 默认端口已改为 15721，如需手动修改：
解决:
关闭弹窗
前往「系统设置」→「隐私与安全性」
点击「仍要打开」
v3.9.1 已修复多字节字符（中文、Emoji）导致的崩溃问题。
出于安全考虑，SQL 导入仅支持 CC-Switch 导出的备份文件。
检查清单：
API Key 是否正确（不要有多余空格）
Base URL 是否完整（末尾不要有斜杠）
模型名称是否准确（区分大小写）
是否重启了对应的 AI 助手客户端
| 系统 | 日志位置 |
| macOS | ~/Library/Logs/com.ccswitch.desktop/ |
~/Library/Logs/com.ccswitch.desktop/
| Linux | ~/.local/share/cc-switch/logs/ |
~/.local/share/cc-switch/logs/
| Windows | %LOCALAPPDATA%\cc-switch\logs\ |
%LOCALAPPDATA%\cc-switch\logs\
重要: 运行新版本前请备份数据
Bug 修复:
修复代理端口冲突（5000 → 15721）
修复 UTF-8 边界崩溃（中文、Emoji 处理）
修复 unwrap/expect 导致的 panic
添加 SOCKS 代理支持
Windows 窗口标题修复
新功能:
添加崩溃日志功能
添加 AiGoCode 图标和合作伙伴推广
主要特性:
本地 API 代理（Axum-based）
自动故障转移（断路器机制）
通用提供商支持
Skills 多应用支持
共用配置片段
MCP 从已安装应用导入
UX 改进:
提供商搜索过滤
提供商图标颜色自定义
Cmd/Ctrl + , 打开设置
面板切换淡入淡出动画
架构升级:
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/…
点击阅读原文
Arch Linux (paru):
AppImage（通用）:
Flatpak:
🎯 基础使用 1. 添加提供商
启动 CC-Switch
点击主界面右上角 "Add Provider"
选择预设或创建自定义配置
填写 API Key、Base URL 等信息
保存后即可使用
主界面: 选择提供商 → 点击 "Enable"
系统托盘: 直接点击提供商名称（即时生效）
3.
CC-Switch：AI 编程助手配置管理完全指南
一、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 安装器（推荐）
下载
CC-Switch-v3.9.1-Windows.msi双击运行安装程序
按提示完成安装
方式二：便携版本
下载
CC-Switch-v3.9.1-Windows-Portable.zip，解压后直接使用macOS
方式一：Homebrew（推荐）
方式二：手动安装
下载
CC-Switch-v3.9.1-macOS.zip解压并拖动到「应用程序」文件夹
首次运行若提示"无法验证开发者"，前往「系统设置」→「隐私与安全性」点击"仍要打开"
Linux
Debian/Ubuntu:
Fedora/RHEL:
Arch Linux (paru):
AppImage（通用）:
Flatpak:
🎯 基础使用
1. 添加提供商
启动 CC-Switch
点击主界面右上角 "Add Provider"
选择预设或创建自定义配置
填写 API Key、Base URL 等信息
保存后即可使用
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 | 通用 | 月之暗面模型 |
自定义提供商
实战案例：多项目多提供商
假设你有三个项目，分别使用不同的 API 提供商：
CC-Switch 方式：
每个切换耗时不超过 2 秒！
🧩 MCP 服务器管理
MCP（Model Context Protocol）服务器管理是 CC-Switch 的重要功能。
访问 MCP 管理
点击主界面右上角 "MCP" 按钮
添加 MCP 服务器
方式一：使用内置模板
mcp-fetch- 网页抓取mcp-filesystem- 文件系统操作mcp-github- GitHub 集成等多种预置模板
方式二：自定义配置
传输类型
| 类型 | 说明 |
|------|------|
| stdio | 标准输入/输出 |
| http | HTTP 传输 |
| SSE | Server-Sent Events |
启用/禁用服务器
使用开关控制哪些服务器同步到实时配置文件
启用的服务器会自动同步到对应应用的配置文件中
实战案例：配置文件系统 MCP
CC-Switch 方式：
点击 "MCP" 按钮
选择内置模板
mcp-filesystem设置目录路径
勾选需要同步的应用
保存，自动同步到三个工具
优势：
无需手动编辑 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：
实战案例：安装 GitHub 集成 Skill
点击 "Skills" 按钮
自动扫描预配置仓库
找到
GitHub IntegrationSkill点击 "Install"
自动安装到对应目录
优势：
自动更新检查
版本管理
一键卸载
支持自定义仓库
📝 Prompts 管理系统
v3.7.0 引入的提示词管理功能。
访问 Prompts 管理
点击主界面右上角 "Prompts" 按钮
创建预设
点击 "New Preset"
使用 Markdown 编辑器编写提示词
语法高亮 + 实时预览
保存预设
同步机制
| 应用 | 配置文件 |
|------|----------|
| 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
按应用接管 - 独立控制每个应用的代理路由
实时监控 - 请求日志和用量统计
错误日志 - 详细记录失败的代理请求
启用代理
进入设置 → "Proxy" 标签
启用 "Enable Proxy"
选择需要代理的应用
代理自动接管选定应用的配置
配置示例
实战案例：企业内网代理
需求：公司要求所有 API 请求必须通过内网代理，Claude Code 走代理，Codex 直连
配置步骤：
进入设置 → "Proxy" 标签
启用 "Enable Proxy"
在 "Per App Takeover" 中：
✅ Claude Code - 开启
❌ Codex - 关闭
❌ Gemini - 关闭
效果：
监控界面
代理启用后，可以看到：
实时请求流量
响应延迟统计
错误请求日志
按模型分类的用量
🛡️ 自动故障转移（v3.9.0 新功能）
断路器机制的自动故障转移功能。
工作原理
健康检测 - 实时监控提供商状态
故障检测 - 自动识别提供商故障
自动切换 - 切换到备用提供商
独立队列 - 每个应用维护独立的故障转移队列
配置故障转移
进入设置 → "Failover" 标签
启用 "Enable Auto Failover"
设置故障检测超时
配置备用提供商列表
配置示例
实战案例：API 故障自动切换
场景：某个 API 提供商突然宕机或限流
传统方式：
至少浪费 5-10 分钟
CC-Switch 方式：
几乎无感知！
🔗 通用提供商（v3.9.0 新功能）
单一配置可同步到多个应用。
使用场景
适用于 API 网关（如 NewAPI）支持多协议的场景。
配置方式
创建提供商时选择 "Universal" 类型
设置各应用的默认模型映射
启用需要同步的应用
实战案例：API 网关统一配置
传统方式：
CC-Switch 方式：
📊 速度测试
测试 API 端点延迟和可用性。
使用方法
选择要测试的提供商
点击 "Speed Test"
查看延迟和质量指标
指标说明
| 指标 | 说明 |
|------|------|
| Latency | API 响应延迟 |
| Quality | 连接质量评级 |
| Availability | 可用性状态 |
实战案例：三个提供商对比
根据结果：
急用项目 → Claude 官方
成本敏感 → DeepSeek
模型丰富 → OpenRouter
📦 导入/导出
导出配置
进入设置 → "Import/Export"
点击 "Export"
选择导出格式（JSON/SQL）
保存备份文件
导入配置
进入设置 → "Import/Export"
点击 "Import"
选择备份文件
确认导入
自动备份
自动轮转备份，保留最近 10 个备份
备份位置:
~/.cc-switch/backups/四、配置详解
📁 配置文件位置
CC-Switch 存储（v3.8.0 新架构）
Claude Code 配置
| 文件 | 说明 |
|------|------|
|
~/.claude/settings.json| 实时配置 ||
~/.claude.json| MCP 服务器配置 ||
~/.claude/skills/| Skills 目录 |API Key 字段:
Codex 配置
| 文件 | 说明 |
|------|------|
|
~/.codex/auth.json| 认证配置（必需） ||
~/.codex/config.toml| MCP 服务器配置（可选） |API Key 字段 (
auth.json):Gemini 配置
| 文件 | 说明 |
|------|------|
|
~/.gemini/.env| API Key ||
~/.gemini/settings.json| 认证模式和 MCP 服务器 |API Key 字段 (
.env):⚙️ 设置选项
基础设置
| 选项 | 说明 |
|------|------|
| 开机自启 | 开机自动运行 CC-Switch |
| 语言 | 中文/English/日本语 |
| 主题 | 深色/浅色/跟随系统 |
| 系统托盘 | 显示/隐藏托盘图标 |
代理设置
| 选项 | 说明 |
|------|------|
| 启用代理 | 启动本地 API 代理 |
| 代理端口 | 默认 15721 |
| 按应用接管 | 独立控制每个应用 |
| 请求日志 | 记录代理请求 |
| 错误日志 | 记录失败请求 |
故障转移设置
| 选项 | 说明 |
|------|------|
| 启用故障转移 | 开启自动故障切换 |
| 超时时间 | 检测超时时间 |
| 重试次数 | 故障时重试次数 |
| 备用列表 | 备用提供商优先级 |
五、进阶功能
🔧 共用配置片段（v3.9.0 新功能）
维护可复用的配置片段，自动合并到提供商配置中。
创建共用片段
进入 Provider 编辑页面
点击 "Extract Common Snippet"
选择从编辑器内容或当前提供商提取
保存为共用片段
合并规则
Claude: 合并到
settings.jsonCodex: 移除 provider-specific 字段后合并
Gemini: 合并到
.env和settings.json💰 用量统计
跟踪 API 使用情况和费用。
访问用量面板
主界面 → "Usage" 按钮
功能特性
自动刷新 - 定时更新用量数据
模型统计 - 按模型分类统计
缓存指标 - 显示缓存命中/创建情况
时区处理 - 正确处理夏令时
配置用量查询
☁️ 云同步设置
设置步骤
进入设置 → "Advanced"
点击 "Custom Configuration Directory"
选择云同步文件夹（Dropbox/OneDrive/iCloud 等）
重启应用生效
数据同步
| 数据类型 | 同步方式 |
|----------|----------|
| Providers | SQLite 数据库 |
| MCP | SQLite 数据库 |
| Prompts | SQLite 数据库 |
| Skills | SQLite 数据库 |
| 窗口状态 | 本地 JSON |
⌨️ 快捷键
| 快捷键 | 功能 |
|--------|------|
|
Cmd/Ctrl + ,| 打开设置 ||
Esc| 关闭模态框 |六、实用技巧
💡 技巧一：使用系统托盘快速切换
macOS / Windows / Linux 都支持系统托盘图标：
场景：正在编码，突然需要切换提供商
传统方式：打开 CC-Switch → 找到提供商 → 点击 Enable
快捷方式：点击托盘图标 → 选择提供商 → 立即切换
💡 技巧二：提供商搜索过滤
提供商多了之后如何快速找到？
点击搜索框
输入关键词（如 "deepseek"、"aigocode"）
实时过滤，支持模糊匹配
💡 技巧三：自定义图标颜色
为不同类别的提供商设置不同颜色：
视觉识别速度提升 200%！
💡 技巧四：自定义图标颜色配置
进入提供商编辑页面
点击图标颜色选择器
选择你喜欢的颜色
保存生效
💡 技巧五：跳过首次运行确认
Claude Code 首次运行需要确认对话框，嫌烦？
进入设置 → "General"
启用 "Skip Claude Code First Run"
七、故障排除
❓ 常见问题
1. 代理端口冲突
问题: macOS 12+ 上 AirPlay Receiver 占用 5000 端口
解决: CC-Switch v3.9.1 默认端口已改为 15721，如需手动修改：
2. macOS "无法验证开发者"警告
解决:
关闭弹窗
前往「系统设置」→「隐私与安全性」
点击「仍要打开」
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\|🔄 数据备份
重要: 运行新版本前请备份数据
八、更新日志
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/…
点击阅读原文