CC Switch教程,一个工具统一管理 12 款 AI 编程助手

导语：CC Switch 是一款免费开源的桌面端 AI 编程工具管理器，能在一个界面里统一管理 Claude Code、Codex、Gemini CLI 等 12 款 AI 编程工具的 API 提供商、MCP、Skills 和 Prompts，一键切换，彻底告别手动改配置文件的痛苦。本文是面向零基础读者的超详细教程，从”它是什么”讲到”每一步怎么点”，看完你就能独立上手。

项目地址：https://github.com/farion1231/cc-switch（唯一官网：ccswitch.io）

一、CC Switch 是什么？（先搞懂它解决什么问题）

CC Switch 是一个跨平台的桌面端 AI 编程工具管理器。简单说，它是一个”总控制台”，把你电脑上安装的各种 AI 编程工具（比如 Claude Code、Codex、Gemini CLI 等，一共 12 款）的”设置”全部集中到一个图形界面里，让你用鼠标点点就能完成切换，不用再去碰那些又乱又容易出错的配置文件。

它到底解决什么痛点？

要理解它的价值，得先知道一个小背景。现在很多开发者都在用”AI 编程工具”——这些工具让你在终端或编辑器里用自然语言让 AI 帮你写代码、改代码、解释代码。最流行的几款有：

• Claude Code：Anthropic 公司出的命令行 AI 编程工具
• Codex：OpenAI 出的命令行 AI 编程工具
• Gemini CLI：Google 出的命令行 AI 编程工具
• Grok Build：xAI（马斯克的公司）出的 AI 编程工具
• 以及其他若干款（OpenCode、OpenClaw、Hermes、Pi、MiniMax Code、Kimi Code、Oh My Pi）

这些工具都有一个共同点：它们要调用”大模型”，而大模型来自”API 提供商”。你可以用官方 API（Anthropic、OpenAI、Google），也可以用第三方中转服务，还可以用本地模型。

问题来了：每一款工具的配置格式都不一样——

• Claude Code 用 JSON 配置文件
• Codex 用 TOML 配置文件
• Gemini CLI 用 YAML 配置
• 有的还用 .env 环境变量

如果你想从”官方 API”切换到”第三方中转服务”，或者想换成本地模型，就得手动找到对应的配置文件，小心翼翼地改端点、改密钥、改模型名。改错一个字符，工具就可能启动不了；而且每换一个工具，就要重复一遍这个痛苦的过程。

CC Switch 就是来解决这个问题的：你只要在它的界面上”选好提供商 → 填入密钥 → 点一下切换”，它就会自动帮你改好所有工具的配置文件。而且它切换时只替换”连接信息”（端点、密钥、模型），你自己加的插件、hooks、MCP、环境变量、注释统统原样保留，不会弄丢。

一个形象的比喻

如果把每一款 AI 编程工具比作一台”用电器”，它们各自有五花八门的插头和开关，那么 CC Switch 就是一个”智能配电箱”——你在配电箱上操作一次，就能统一控制 12 台电器的供电切换，再也不用钻到每台电器后面去手动接线了。

二、它到底有多火？（数据说话）

CC Switch 是一个增长极其迅猛的开源项目（以下数据来自 GitHub 仓库实时统计，截至 2026 年 11 月 2 日）：

• Star 数：约 15.1 万，位列 GitHub 全站最热门的开源项目之一。star 可以理解为”收藏/点赞”，15 万意味着有 15 万人主动收藏了它。
• Fork 数：约 9900。fork 是”复制到自己账号”，代表有近万名开发者在它基础上做二次开发。
• 诞生与更新：仓库创建于 2025 年 8 月，最近一次推送就在 2026 年 11 月 2 日。一年多时间突破 15 万 star，总提交数超过 3400 次，更新频率极高。
• 主要语言：Rust，配合 Tauri 2 框架构建，所以它轻量、启动快、内存占用低，不像 Electron 应用那么吃资源。

这个体量的 star 数，本身就说明它精准命中了大量开发者的真实需求——”管理多个 AI 工具和多个 API 提供商”这件事，确实是很多人的刚需。

三、核心功能有哪些？（逐条大白话解释）

CC Switch 的功能非常丰富，下面逐条拆解，每一条都附上大白话解释。

1. 一个应用管理 12 款工具

Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code、Kimi Code、Oh My Pi——这 12 款 AI 编程工具，都可以在 CC Switch 这一个界面里管理。不用每个工具装一个管理器，一个就够。

2. 90+ 提供商预设

内置了 AWS Bedrock、NVIDIA NIM 以及大量社区中转服务的预设。国内开发者常用的 Kimi、DeepSeek、GLM（智谱）、硅基流动等都能轻松接入。添加提供商时可以按名称（含中文名）和域名搜索，同一个供应商的不同套餐会自动合并成一行，方便对比。

3. 三种连接模式（重点，下面会详细讲）

• Direct（直连）：工具直接连到提供商，中间不经过任何中转。
• Routing（本地路由）：请求先经过你本机的 CC Switch，由它做格式转换和故障转移。
• Aggregation（聚合）：把多个提供商的模型合并成一个列表，你在工具里随意挑选。

4. 用量与费用追踪

自动扫描各工具的本地会话日志，统计你用了多少次请求、消耗了多少 token、命中缓存的比例、输出速度，以及按提供商/模型花了多少钱。还能显示订阅配额的剩余量和重置倒计时（比如”还剩 5 小时，94%”）。对需要控制成本的人来说非常实用。

5. MCP / Skills / Prompts 统一管理

• MCP：MCP 服务器（给 AI 工具扩展能力的小插件）在一处管理，选择同步到哪些工具。
• Skills：从 skills.sh 或 GitHub 仓库一键安装技能。
• Prompts：用 Markdown 编辑器维护提示词，自动写入对应工具的文件。

6. 云同步

支持 WebDAV（坚果云、Nextcloud、群晖 NAS 等）和 S3 兼容存储（AWS S3、Cloudflare R2、阿里云 OSS、腾讯云 COS 等），实现多台电脑之间的配置同步。

7. 其他实用功能

• 会话管理器：把各工具的对话历史解析成结构化视图，支持搜索、恢复会话。
• 项目切换器：一键保存/切换整套配置（提供商 + MCP + Skills + Prompts）。
• 账户管理：登录 GitHub Copilot、ChatGPT、xAI、Kimi Code 等订阅账户，把订阅当提供商用。
• CLI 工具管理：查看、安装、升级 Claude Code、Codex 等命令行工具本身。

四、安装教程（三种系统都讲）

CC Switch 支持 Windows、macOS、Linux 三大平台，安装都很简单。下面按系统分开讲，你只挑自己用的系统看即可。

Windows 安装

1. 打开 GitHub Releases 页面（或官网 ccswitch.io 的下载页）。
2. 下载 CC-Switch-v{版本号}-Windows.msi（这是安装版，双击就能装）。
3. 如果你不想安装、想即开即用，下载 -Windows-Portable.zip 便携版，解压后双击 exe 即可。
4. 如果你用的是 ARM 架构设备（比如部分骁龙笔记本），下载 -Windows-arm64.msi 版本。

macOS 安装（推荐用 Homebrew）

如果你装了 Homebrew（Mac 上的软件包管理工具），打开”终端”，输入：

brew install --cask cc-switch

以后想更新，输入：

brew upgrade --cask cc-switch

如果没装 Homebrew，也可以直接去下载页下载 -macOS.dmg 安装包（Universal 构建，苹果芯片和 Intel 芯片都能用），双击拖进”应用程序”即可。macOS 版本已通过苹果官方签名和公证，可以直接安装，不会被系统拦截。

Linux 安装

• Arch Linux：用 paru -S cc-switch-bin 安装。
• Debian / Ubuntu：下载 .deb 包，双击或用 dpkg -i 安装。
• Fedora 等 RPM 发行版：下载 .rpm 包安装。
• 其他发行版：下载 .AppImage，加执行权限后直接运行。

注意：Linux 需要系统满足 x86_64 或 ARM64 架构、glibc 2.35+、WebKitGTK 4.1（如 Ubuntu 22.04+、Debian 12+、较新的 Fedora）。RHEL / Rocky / Alma 8–9 目前暂不支持。

五、第一次使用：三步上手

装好后，打开 CC Switch，你会看到一个带侧边栏的桌面界面。整个上手流程可以概括为三步：① 确认工具 → ② 添加提供商 → ③ 一键切换。

第 1 步：确认要管理的工具

左侧边栏会列出那些 AI 编程工具。点击某个工具（比如 Claude Code），就进入它的管理页面。如果你某个工具没装，侧边栏的”Apps”页面还能帮你一键安装或升级这些命令行工具。

首次启动的贴心设计：CC Switch 会自动把你已有的 Claude Code、Codex、Gemini CLI、Grok Build 配置导入为一个名为 default 的提供商，并为每款工具添加官方提供商。也就是说，你之前辛辛苦苦配好的东西不会丢，全都被自动接管了。

第 2 步：添加提供商

在某个工具的管理页面，点击右上角的 「+」 按钮，会弹出提供商选择界面：

• 可以从 90+ 预设里选一个（支持按中文名和域名搜索）。
• 也可以选择”自定义”，手动填入提供商信息。
• 选好后填入对应的 API Key（密钥），保存即可。

第 3 步：一键切换

添加好多个提供商后，切换就很简单了：

• 主界面切换：选中某个提供商，点击 Enable 按钮（共存模式的工具是 Add 按钮）。
• 系统托盘切换：右下角的托盘图标，每行显示一个工具，格式是”工具名 · 模式 · 提供商 · 配额”，点一下子菜单里的提供商名就能切换，不用打开主界面。

切换后什么时候生效？这取决于工具，很重要，务必记住：

• Claude Code：无需重启，热切换，立刻生效。
• Codex / Gemini CLI / Grok Build：需要重启终端或 CLI 工具。
• Claude Desktop：需要完全退出并重新打开。

想恢复官方登录？切换到内置的官方提供商（如 “Claude Official”），重启工具，然后走工具自己的登录流程（Claude Code 用 /login，Codex 用 codex login）即可。

六、三种连接模式详解（核心章节）

这是 CC Switch 最核心也最容易搞混的部分，我用大白话把它讲透。

模式一：Direct（直连）

含义：工具直接连到提供商，请求不经过任何中转。

什么时候用：这是默认模式，也是大多数人的日常选择。只要你的提供商本身就兼容该工具的 API 格式（比如 Claude Code 用 Anthropic 格式的提供商），直接用直连就行。

怎么用：添加提供商后直接点 Enable，就是直连模式，不用做任何额外设置。

模式二：Routing（本地路由）

含义：请求先经过你本机的 CC Switch，由它负责转换 API 格式、自动故障转移。

什么时候用：这是 Routing 模式的杀手锏——跨格式使用。比如你想在 Claude Code 里用 OpenAI 的模型（GPT），或者在 Codex 里用 Anthropic 的模型（Claude），正常情况下格式不兼容、用不了，但 Routing 模式可以把请求格式自动转换，让你”跨家使用”。它还支持自动故障转移（一个提供商挂了自动切下一个）。

怎么用：

1. 进入 Claude Code / Codex / Gemini CLI / Grok Build 页面。
2. 点击顶部的 Routing 标签页。
3. 点击 Start routing 按钮。
4. 在提供商的”Advanced Options”里设置 Upstream Format，选择该提供商实际的 API 格式（OpenAI Chat Completions / OpenAI Responses / Gemini Native / Anthropic Messages）。
5. 想退出时，点击 Back to direct 返回直连。

注意：启用 Routing 后，你工具的配置文件会指向 127.0.0.1（本机），真实的提供商地址和密钥都存在 CC Switch 里。官方提供商（如 Claude Official）不能走本地路由（Codex 的 OpenAI Official 除外）。

模式三：Aggregation（聚合）

含义：把多个提供商的模型合并成一个列表，你在工具里可以直接挑选不同提供商的模型。

什么时候用：当你想同时使用多个提供商的模型、随时切换时。比如既想用 Claude 又想用 GPT，聚合模式下它们会出现在同一个模型列表里。

怎么用：

1. 在 Claude Code 或 Codex 页面，切换到 Aggregation 标签。
2. 点击 Switch to Aggregation。
3. 在提供商卡片上点 Add，添加多个提供商。
4. 选一个提供商作为默认（没指定聚合模型的请求会发给它）。
5. 返回时点击 Back to direct。

限制：聚合模式目前只支持 Claude Code 和 Codex，且不提供故障转移。Claude Code 需要 v2.1.243 以上版本；Codex 改聚合模型列表后要完全重启（包括后台 daemon）。

三种模式速查表

下面帮你快速对比：

• Direct：工具 → 提供商，直连；不转换格式、不故障转移；所有工具都支持。
• Routing：工具 → CC Switch → 提供商；支持格式转换和故障转移；支持 Claude Code、Codex、Gemini CLI、Grok Build。
• Aggregation：工具 → 对应提供商（按模型选）；多提供商模型合并；仅支持 Claude Code 和 Codex。

七、高级功能：MCP、Skills、Prompts 怎么管

除了切换提供商，CC Switch 还能统一管理三类”扩展资源”，这里简单讲一下各自的入口和用途。

MCP 管理

MCP（Model Context Protocol）是给 AI 工具”外挂能力”的标准，比如让 AI 能读文件、查数据库、联网搜索。在 CC Switch 左侧点 MCP，可以：通过模板或自定义配置添加 MCP 服务器、从各工具导入现有配置、为每个工具单独开关同步。一处配置，同步到多个工具。

Skills 管理

Skills（技能）是一些预制的功能包。点侧边栏 Skills → Discover Skills，可以从 skills.sh 搜索、浏览 GitHub 仓库、或从 ZIP 文件安装。安装后自动同步到你的工具里。

Prompts 管理

Prompts（提示词）是你想让 AI 遵循的规则或背景设定。点侧边栏 Prompts，用 Markdown 编辑器写好，启用后会自动写入对应工具的文件（Claude Code 是 CLAUDE.md，Codex 是 AGENTS.md，Gemini CLI 是 GEMINI.md）。

八、常见问题排查（新手必看）

下面整理了几个新手最容易遇到的问题和解决办法。

问题 1：切换提供商后，工具没变化 / 没生效

原因：不同工具的热切换能力不同。

解决：Claude Code 可热切换；Codex、Gemini CLI、Grok Build 需重启终端；Claude Desktop 需完全退出重开。

问题 2：我想在 Claude Code 里用 GPT，却报 404 或 405 错误

原因：Claude Code 默认只认 Anthropic 格式，直接用 OpenAI 格式的提供商会报错。

解决：用 Routing 模式，并在提供商的 Advanced Options 里把 Upstream Format 设成 OpenAI Chat Completions（或 Responses）。

问题 3：连接性检查通过，但请求还是失败

原因：连接性检查只测”地址能不能连上”，不验证 API Key 和模型名对不对。

解决：检查 API Key 是否正确、模型名是否填对、Upstream Format 是否选对。具体错误可以在”Usage”的请求日志里查看。

问题 4：为什么我在工具里改的模型，切换后又变回去了？

原因：模型属于”关键字段”，由提供商决定。切换时配置里的模型会被替换成目标提供商的模型。

解决：想长期用某个模型，就在 CC Switch 里编辑那个提供商，把模型写进去；而不是在工具里临时改。

问题 5：为什么删不掉当前正在用的提供商？

原因：CC Switch 遵循”最小侵入”原则，始终保留一个可用配置，防止你删完后工具没法用。

解决：先切换到另一个提供商，再回来删除原来那个。（共存模式的工具没这个限制。）

问题 6：数据都存在哪？

默认在 ~/.cc-switch 目录（Windows 是 C:\Users\你的用户名\.cc-switch）：

• cc-switch.db：主数据库（提供商、MCP、提示词等）
• settings.json：本地设置
• backups/：自动备份（每 24 小时一次，保留最近 10 个）
• skills/：Skills 存储
• logs/：日志

改配置前它会自动备份，所以万一出问题，可以去 backups 目录找回。

九、哪些人适合用？哪些人不适合？

适合用的人

• AI 编程工具的重度用户：经常在 Claude Code、Codex、Gemini CLI 等工具之间切换的人。
• 使用多个 API 提供商的人：需要在官方 API、第三方中转、本地模型之间灵活切换的人。
• 国内开发者：想接入 Kimi、DeepSeek、GLM、硅基流动等国内服务、无需特殊网络就能用的人。
• 需要控制成本的人：想看清每个模型、每个提供商花了多少钱的人。
• 被配置文件折磨过的人：不想再手动改 JSON/TOML/YAML 的人。

不适合用的人

• 完全不用 AI 编程工具的人：如果你根本不碰 Claude Code、Codex 这类工具，就完全用不上它。
• Linux 特定发行版用户：RHEL / Rocky / Alma 8–9 暂不支持，需先确认系统满足要求。
• 对”第三方中转”有顾虑的人：在官方客户端之外使用订阅，可能违反供应商的服务条款，需自行评估风险。

十、总结

CC Switch 是目前最火的开源 AI 编程工具管理器之一。它把 Claude Code、Codex、Gemini CLI 等 12 款工具的 API 提供商、MCP、Skills、Prompts 全部统一到一个桌面界面里，支持直连、本地路由、聚合三种模式，一键切换、自动备份、用量追踪、云同步，能极大减少开发者维护配置文件的成本。

如果你平时会用到多款 AI 编程工具、或者需要在多个 API 提供商之间切换，CC Switch 几乎是”用了就回不去”的效率工具。它的上手门槛也不高——装好、添加提供商、点一下切换，三步就能开始用。

如果你对 AI 相关的开源工具也感兴趣，可以看看本站之前介绍的《REA 教程》等更多项目。最后提醒：使用第三方中转服务时，请注意遵守各供应商的服务条款。