CC Switch 使用教程

官方网站：ccswitch.io
GitHub：farion1231/cc-switch
当前版本：v3.10.3+
技术栈：Rust + Tauri 2 + React/TypeScript · 本地 SQLite 存储 · 开源免费

📋 目录

CC Switch 是什么

下载与安装

快速上手

添加与切换 Provider

内置代理模式（Proxy + Takeover）

一、CC Switch 是什么

CC Switch 就是解决手动修改配置文件痛点的桌面工具，它提供一个统一的图形界面，让你可以一键切换 Provider、多应用统一管理。

CC Switch 是一款跨平台开源桌面工具，核心作用是统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等主流 AI 编程 CLI 工具的 API 供应商配置，彻底告别手动编辑 JSON、TOML、.env 配置文件的繁琐操作，实现供应商一键切换、全局配置同步等功能，目前已收获 44000+ Star，是 AI 开发者必备的辅助工具之一。

核心功能一览

功能	说明
🔄 一键切换 Provider	保存多套 API 配置，点一下即可切换，无需手动编辑 JSON
🖥️ 多应用统一管理	同时管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw
🛡️ 本地 API 代理	内置高性能 HTTP 代理，支持自动故障转移与请求监控
🔌 MCP 服务器管理	可视化添加、编辑和同步 MCP 服务器配置
📊 用量统计	实时查看 Token 消耗与 API 费用
💾 备份与恢复	自动备份配置，防止误操作导致数据丢失
☁️ WebDAV 同步	多设备间同步配置（支持坚果云等）

支持管理的 CLI 工具

🤖 Claude Code（Anthropic）

⚡ Codex（OpenAI）

✨ Gemini CLI（Google）

🧩 OpenCode（开源）

🦅 OpenClaw（v3.11.0 新增）

二、下载与安装

前往 GitHub Releases 下载对应平台的安装包，拉到页面底部的 Assets 区域选择对应文件。

系统要求

系统	最低版本	架构
Windows	Windows 10 及以上	x64
macOS	macOS 10.15 Catalina 及以上	Intel (x64) / Apple Silicon (arm64)
Linux	Ubuntu 18.04+ / Fedora 33+ 等	x64 / arm64

🪟 Windows 安装

文件	说明
`CC-Switch-vX.X.X-Windows.msi`	✅ 推荐——MSI 安装包，支持自动更新
`CC-Switch-vX.X.X-Windows-Portable.zip`	便携版，解压即用，不写注册表

双击 .msi 文件，按向导完成安装后，在开始菜单搜索「CC Switch」启动即可。

🍎 macOS 安装

方式一：直接下载（推荐）

下载 CC-Switch-vX.X.X-macOS.zip

解压后将 CC Switch.app 拖入「应用程序」文件夹

首次启动：右键点击 → 打开，或前往「系统设置 → 隐私与安全性 → 仍要打开」

⚠️ 作者暂无 Apple 开发者证书，macOS 会提示「未知开发者」，按上述步骤绕过即可，之后每次正常启动。

方式二：Homebrew

🐧 Linux 安装

根据发行版选择对应格式：

发行版	推荐格式	安装命令
Ubuntu / Debian / Mint	`.deb`	`sudo apt install ./CC-Switch-*.deb`
Fedora / RHEL / Rocky	`.rpm`	`sudo dnf install ./CC-Switch-*.rpm`
openSUSE	`.rpm`	`sudo zypper install ./CC-Switch-*.rpm`
Arch / Manjaro / 其他	`.AppImage`	见下方

AppImage 通用方式：

三、快速上手

安装完成后，按以下流程完成首次配置：

① 启动 CC Switch
        ↓
② 自动检测已安装的 CLI 工具（导入现有配置）
        ↓
③ 顶部切换栏选择要管理的应用（Claude Code / Codex 等）
        ↓
④ 点击 「+」 添加第一个 Provider
        ↓
⑤ 点击目标 Provider → 「启用」
        ↓
⑥ 终端运行 claude / codex，即使用新配置
        ↓
⑦（可选）点击「健康检查」验证 API Key 是否可用

💡 首次启动时，系统托盘中会出现 CC Switch 图标，之后可从托盘快速切换 Provider，无需打开主界面。

四、添加与切换 Provider

添加 Provider

点击主界面右上角 「+」：

选择统一供应商，点击右下角添加统一供应商
按照下面图图片配置，apikey去自己的令牌管理那里去复制。
:::

字段	说明	是否必填
名称	便于区分的备注（如「余烬ApI-Claude」）	✅
API Key	服务商提供的密钥（`sk-xxx...`）	✅
Base URL	自定义代理地址（如 `https://api.yujingai.top`）	✅
模型	默认使用的模型名称（如 `claude-opus-4-8`）	可选

想用哪个模型去模型广场参考填入，codex，Claude code，Gemini CLI建议都开启。
保存配置
再次进入这个页面

点击

同步到所有应用

点击

可以测试是否成功，点击启用即可。

如果你添加供应商的时候没有选择统一供应商，而是选择了第一种供应模式。（按照上面配置的可以划走）

那么你需要注意在高级选项里面修改api格式并打开路由；如果你使用的是Anthropic的claude模型的话不用修改也行，修改也行。

路由开启方式：
点击首页

进入设置页面，按照下面图片配置保存即可。

| API 格式 | Anthropic 原生格式或 OpenAI 兼容格式 | ✅ |

切换 Provider

在 Provider 列表中点击目标 Provider

点击 「启用」

CC Switch 自动将配置写入对应 CLI 工具的配置文件

终端运行 claude 命令即使用新配置

✅ Claude Code 支持热切换，无需重启终端。其他工具切换后需重启终端生效。

健康检查

点击 Provider 旁的 「健康检查」 按钮，发送测试请求验证 API Key 和网络连通性，结果实时显示。

接入newapi的话到这里就Ok啦，想继续了解CC switch可以往下看。

五、内置代理模式（Proxy + Takeover）

CC Switch 在本地启动一个 HTTP 代理服务器，接管各 CLI 工具的配置文件（自动备份原始配置），将所有 API 请求通过本地代理路由。

开启方式

设置 → 代理 → 开启 Proxy + Takeover

代理模式的优势

功能	说明
🔀 自动故障转移	某个 Provider 不可用时自动切换到下一个
📋 请求日志	实时查看所有 API 请求记录，便于调试
🧠 Claude Rectifier	自动修复第三方 API 网关导致的 thinking block 格式不兼容问题
💰 用量统计	精确记录 Token 消耗和费用

💡 推荐开启：尤其是使用多个中转站的用户，故障转移功能可以大幅提升稳定性。

六、进阶功能

🔌 MCP 服务器管理

在 「MCP」 面板中，可视化添加、编辑和删除 MCP（Model Context Protocol）服务器。

配置自动同步到对应 CLI 工具

支持从已安装的应用一键导入现有 MCP 配置

若有 MCP 服务器的 Deep Link（ccswitch:// 开头），点击即可自动导入，无需手动填写

📚 Skills 管理

Skills 是 Claude Code / Codex 的提示词增强功能，CC Switch 支持：

从 GitHub 仓库安装（内置 baoyu-skills 等预设仓库）

从本地 ZIP 文件安装

统一管理 Claude Code 和 Codex 的 Skills

🗂️ 会话管理器

在 「会话」 页面，可浏览全部五个应用的历史对话记录：

支持目录导航和会话内搜索

自动按当前选中应用过滤显示

快速找回历史任务上下文

💾 备份管理

设置 → 备份管理 中可以：

查看所有自动备份记录

手动创建备份（升级前强烈建议）

重命名、删除旧备份

数据库迁移前自动备份（无需手动操作）

☁️ WebDAV 自动同步

支持将数据库同步到 WebDAV 服务（坚果云、Nextcloud 等），实现多设备间配置共享。

配置路径：设置 → 同步 → WebDAV

字段	说明
服务器地址	WebDAV 服务的 URL
用户名 / 密码	登录凭证
同步目录	远端存储路径

⚠️ 内置大文件保护机制，防止误传超大文件覆盖配置。

📊 用量统计与计费

「用量」 页面展示：

Token 消耗总量与趋势图

缓存命中率分析（节省多少费用）

按模型和 Provider 分类的费用明细

支持自动刷新

七、WSL 环境配置

Windows 环境下装个 exe 应用，就可以实现对 WSL 下的 Claude Code、Codex 的配置切换。使用方法也很简单，只需要在设置中配置 WSL 路径即可。

配置步骤

设置 → WSL 路径，填写以下路径（根据实际用户名修改）：

\\wsl$\Ubuntu\home\你的用户名\.claude
\\wsl$\Ubuntu\home\你的用户名\.codex

注意事项

⚠️ 配置完成后，若在未启动 WSL 时打开 CC Switch（包括未打开 VS Code 内的 WSL 终端），会自动唤醒 WSL。属于正常现象，无需担心。

八、常用快捷键

快捷键	功能
`Cmd/Ctrl + ,`	快速打开设置
`ESC`	关闭当前面板
系统托盘右键	快速切换 Provider（无需打开主界面）

九、常见问题 FAQ

Q：安装后找不到 CC Switch 在哪里？

Windows 用户在开始菜单搜索「CC Switch」；macOS 在「应用程序」文件夹；也可以在系统托盘（任务栏右下角）找到图标。

Q：macOS 提示「无法打开，因为它来自身份不明的开发者」？

右键点击应用 → 选择「打开」，或前往「系统设置 → 隐私与安全性」，找到相关提示点击「仍要打开」。之后每次均可正常启动。

Q：切换 Provider 后终端里还是用旧配置？

除 Claude Code 外，其他工具切换后需要重启终端（关闭并重新打开终端窗口）才能生效。Claude Code 支持热切换，无需重启。

Q：健康检查失败，怎么排查？

按以下顺序排查：
1.
确认 API Key 填写正确，无多余空格
2.
确认账户余额充足
3.
检查 Base URL 格式是否正确（一般为 https://xxx.xxx.xxx/v1 或不带 /v1）
4.
检查网络连通性（部分官方 API 需要代理）

Q：从旧版升级后 Provider 配置消失了？

这是从 v3.10.2 升级到 v3.10.3 后，当系统 HOME 路径与实际用户目录不一致时出现的问题。请使用 v3.10.3 的安装包重新安装。

Q：CC Switch 和 cockpit-tools 有什么区别？

维度	CC Switch	cockpit-tools
定位	API Provider 切换管理	AI IDE 账号管理
管理对象	API Key / Base URL	账号（用户名密码）
号池支持	❌	✅
配额监控	用量统计	实时配额监控
适合场景	中转站/多 Provider 切换	多账号轮换使用

Q：CC Switch 完全免费吗？

✅ 完全开源免费，MIT 许可证，代码托管在 GitHub，所有配置本地存储，无需注册账号。

🔗 相关链接

CC Switch 官方文档

GitHub 仓库

CC Switch 使用教程

📋 目录#

一、CC Switch 是什么#

核心功能一览#

支持管理的 CLI 工具#

二、下载与安装#

系统要求#

🪟 Windows 安装#

🍎 macOS 安装#

🐧 Linux 安装#

三、快速上手#

四、添加与切换 Provider#

添加 Provider#

如果你添加供应商的时候没有选择统一供应商，而是选择了第一种供应模式。 （按照上面配置的可以划走）#

切换 Provider#

健康检查#

五、内置代理模式（Proxy + Takeover）#

开启方式#

代理模式的优势#

六、进阶功能#

🔌 MCP 服务器管理#

📚 Skills 管理#

🗂️ 会话管理器#

💾 备份管理#

☁️ WebDAV 自动同步#

📊 用量统计与计费#

七、WSL 环境配置#

配置步骤#

注意事项#

八、常用快捷键#

九、常见问题 FAQ#

🔗 相关链接#