CC-Switch 教程:一个桌面 App 管理所有 AI 编程工具

Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 五大 AI 编程工具，配置各不相同，切换 Provider 要手动改 JSON、TOML、.env……CC-Switch 一个桌面应用全搞定。

CC-Switch 是什么？

CC-Switch 是一款开源、跨平台（Windows / macOS / Linux）的桌面应用，专为统一管理和切换 AI 编程工具的接入配置而设计。

简单来说，它解决了这些痛点：

• • 手动改配置文件太麻烦：每个 CLI 工具配置格式不同，切个 Provider 要翻半天文件
• • 多工具配置不统一：Claude Code 用 JSON，Codex 用 TOML，Gemini CLI 又是另一套
• • MCP / Skills 管理分散：不同工具的 MCP 服务器、Prompt、Skill 各管各的

CC-Switch 把这些全部收归一个界面管理，一键切换，即时生效。

GitHub 仓库：https://github.com/farion1231/cc-switch

核心功能一览

安装

macOS（推荐 Homebrew）

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

也可以直接下载 .dmg 安装包，macOS 版本已通过 Apple 公证签名，双击即可安装。

Windows

从 GitHub Releases 页面下载 .msi 安装包或 .zip 便携版。

Linux

# Debian / Ubuntu
sudo dpkg -i CC-Switch-v*-Linux.deb

# Fedora / RHEL
sudo rpm -i CC-Switch-v*-Linux.rpm

# 通用（所有发行版）
chmod +x CC-Switch-v*-Linux.AppImage
./CC-Switch-v*-Linux.AppImage

Arch Linux 用户：

paru -S cc-switch-bin

无头服务器 / SSH 环境（Web 版）

如果你在远程服务器上使用，可以跑 Web 版：

wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch-web-linux-x64.tar.gz
tar -xzf cc-switch-web-linux-x64.tar.gz
cd cc-switch-web/
./cc-switch-web

默认端口 17666，浏览器访问 http://localhost:17666。

快速上手：5 步搞定

第 1 步：首次启动

打开 CC-Switch，首次启动会提示你导入已有的 CLI 工具配置。如果你之前已经配置过 Claude Code 或其他工具，选择导入即可，所有配置会被保存为默认 Provider。

第 2 步：添加 Provider

点击 "Add Provider"（添加 Provider）：

1. 1. 从预设列表选择一个 Provider（内置了 AWS Bedrock、NVIDIA NIM、各种中转服务等 50+ 预设）
2. 2. 填入你的 API Key
3. 3. 选择模型（支持 Haiku / Sonnet / Opus / Custom 四档模型配置）
4. 4. 点击确认，Provider 就添加好了

也可以选择自定义配置，手动填入 API Endpoint 和 Key。

第 3 步：切换 Provider

两种方式：

• • 主界面切换：选中 Provider → 点击 "Enable"
• • 系统托盘切换：点击托盘图标 → 直接选 Provider 名称

Claude Code 热切换：切换后 Claude Code 不需要重启终端，即时生效。其他工具需要重启终端或 CLI。

第 4 步：管理 MCP 服务器

点击 "MCP" 按钮：

1. 1. 选择模板或自定义配置添加 MCP 服务器
2. 2. 支持三种传输方式：stdio、HTTP、SSE
3. 3. 开启对应工具的同步开关，一键同步到 Claude Code / Codex / Gemini CLI

第 5 步：管理 Prompts 和 Skills

Prompts：点击 "Prompts" → 用内置 Markdown 编辑器编写系统提示词 → 激活后自动同步到对应的配置文件（CLAUDE.md / AGENTS.md / GEMINI.md）。

Skills：点击 "Skills" → 浏览 GitHub 仓库 → 一键安装到所有工具。

进阶用法

本地代理模式

CC-Switch 内置了本地代理功能，支持：

• • 热切换：不中断会话直接切换 Provider
• • 自动故障转移：当前 Provider 挂了自动切到备用的
• • 熔断器：连续失败自动暂停，恢复后自动重试
• • 请求修正：自动适配不同 Provider 的格式差异

启用方式：设置 → 代理模式 → 开启。

Deep Link 一键导入

CC-Switch 支持 ccswitch:// 协议，你可以从网页一键导入 Provider 配置。

例如，很多 API 中转服务平台（如 SiliconFlow、AiHubMix 等）在 Token 管理页面集成了 CC-Switch 的 Deep Link，点击即可自动填入配置。

共享配置片段

如果你在多个 Provider 之间切换时不想丢失插件配置，可以使用"共享配置片段"功能：

1. 1. 编辑 Provider → 共享配置面板 → 点击 "从当前 Provider 提取"
2. 2. 新建 Provider 时默认勾选 "写入共享配置"
3. 3. 所有通用配置（除 API Key 和 Endpoint 外）都会被保留

用量与成本追踪

CC-Switch 内置了用量仪表盘：

• • Token 消耗统计和趋势图表
• • 每个请求的详细日志
• • 自定义每模型定价，精确计算费用

这对于控制成本非常有用，尤其是使用多个中转服务时。

云端同步

如果你在多台设备上工作，可以把 CC-Switch 的数据目录设到云同步盘：

• • 支持 Dropbox、OneDrive、iCloud
• • 也支持 WebDAV 服务器（适合 NAS 用户）
• • 设置 → 配置目录 → 选择你的云同步路径

切回官方登录

如果你想切回官方 API：

1. 1. 从预设列表添加一个 "Official Login" Provider
2. 2. 切换到该 Provider
3. 3. 重启 CLI 工具（Claude Code 不需要）
4. 4. 按照官方的登录 / OAuth 流程操作

之后就可以在官方和第三方 Provider 之间自由切换了。

数据存储位置

CC-Switch 采用"最小侵入"设计原则——即使卸载应用，你的 CLI 工具配置也不会丢失，一切照常运行。

常见问题

Q：切换后需要重启终端吗？

A：Claude Code 不需要，其他工具需要重启终端或 CLI 才能生效。

Q：为什么不能删除当前活跃的 Provider？

A：CC-Switch 始终保留一个活跃配置，因为删除所有配置会导致对应的 CLI 工具无法使用。如果你不想用某个工具，可以在设置中隐藏它。

Q：切换 Provider 后插件配置没了？

A：使用"共享配置片段"功能，可以把通用配置在 Provider 之间传递。

Q：支持哪些系统？

A：Windows 10+、macOS 12 (Monterey)+、Ubuntu 22.04+ / Debian 11+ / Fedora 34+。

总结

CC-Switch 是目前最全面的 AI 编程工具管理器。如果你同时在用 Claude Code、Codex、Gemini CLI 等多个工具，或者频繁在不同 API Provider 之间切换，CC-Switch 能帮你省下大量配置管理的时间。

一句话总结：一个 App 管五个工具，一键切换，告别手动改配置。

下载方式

CC-Switch 支持 Windows、macOS、Linux 三大平台。

关注公众号 「光核 AI 记」，发送关键词 「CC-Switch」，即可获取最新版下载链接。