CC-Switch 超详细入门教程附安装包（Windows/macOS/Linux）
前言
在使用 Claude Code、Codex、Gemini CLI 等 AI 编程 CLI 工具时，你是否遇到过这些痛点：
- 频繁切换 API 供应商，手动修改 JSON、TOML、.env 配置文件，繁琐又易出错；
- 多个工具配置分散，无法统一管理，同步配置耗时费力；
- 担心配置文件损坏，没有可靠的备份与恢复方式；
- 新手对配置语法不熟悉，上手难度大，效率低下。
今天给大家推荐一款开源跨平台神器——CC-Switch，它能一站式解决以上问题，让 AI 编程工具的配置管理变得简单高效。本文专为 Windows 平台新手打造，全程图文讲解，零基础也能快速上手！
一、前置认知：CC-Switch 核心定位与适用场景
1. 核心定位
CC-Switch 是一款AI CLI 工具配置管理器，基于 Rust + Tauri 2 + React/TypeScript 开发，所有配置本地存储于 SQLite 数据库，采用原子写入机制，避免配置文件损坏。软件启动快、占用内存小，专注于统一管理主流 AI 编程 CLI 工具的 API 配置，实现供应商一键切换、全局配置同步。
2. 核心功能
| 功能 | 说明 |
|---|---|
| 供应商管理 | 内置 50+ 供应商预设，支持自定义配置，一键切换 |
| 快捷切换 | 主界面/系统托盘快切，Claude Code 支持热切换无需重启终端 |
| 配置同步 | 统一管理多 CLI 工具配置，一次设置全局生效 |
| 辅助能力 | MCP 服务器管理、Skills 一键安装、Prompts 管理、用量追踪 |
3. 适用人群与环境
- 适用人群：使用 AI 编程 CLI 工具、需频繁切换 API 供应商、不想手动改配置的 Windows 开发者与新手用户；
- 适用系统：Windows 10 及以上 64 位系统，推荐 Windows 11。
二、第一步：下载与安装
CC-Switch下载地址：
📌 备用下载（夸克网盘）：
https://pan.quark.cn/s/ce7ed4e4acd5
推荐版本：v3.13.0 及以上，修复多项兼容问题，运行更稳定。
方式一：MSI 安装器（新手首选）
- 下载后缀为
.msi的安装包（如 CC-Switch-v3.13.0-Windows-x64.msi）； - 双击安装包，跟随向导点击「下一步」，接受协议，选择安装路径（默认即可）；
- 点击「安装」，等待 1-2 分钟完成，勾选「启动 CC-Switch」，点击「完成」；
- 若遇 Windows SmartScreen 提示，点击「更多信息」→「仍要运行」，开源软件安全无风险。
安装验证
启动后看到主界面（顶部工具标签页、中间供应商列表、右上角「+」添加按钮），无报错即安装成功。首次启动会自动扫描并导入本地已有 CLI 配置，直接点击「导入」即可。
三、第二步：核心配置（5 分钟快速上手）
核心操作只有两步：添加供应商 → 切换供应商，以小麦 API 为例演示。
1. 核心概念：供应商（Provider）
一套完整 API 配置，包含：供应商名称、API 端点（Base URL）、API 密钥（API Key）、模型，切换即自动写入对应 CLI 配置文件。
2. 添加供应商（两种方式）
方式一：预设供应商（推荐，零手动填地址）
- 点击主界面右上角「+」（添加供应商）；
- 「预设（Preset）」下拉选择目标供应商（如 Zhipu GLM、DeepSeek、Kimi 等），自动填充 API 端点；
- 填入自己的 API Key，自定义供应商名称（如「小麦 API - Claude」）；
- 点击「添加（Add）」，完成配置。
方式二：自定义供应商（无预设时使用）
- 点击「+」→ 选择「自定义（Custom）」；
- 填写信息（以小麦 API 为例）：
- 供应商名称：自定义（如「小麦 API - Codex」）；
- API 端点：
https://xiaomai.win（末尾禁止加斜杠，否则请求失败）； - API 密钥：你的 sk-xxxx 密钥；
- 模型：按需选择（如 claude-sonnet-4-20250514）；
- 点击「添加」，完成自定义配置。
3. 切换供应商
在供应商列表中，找到目标配置，点击右侧「启用（Enable）」，状态变为Active（活跃）即切换成功。
4. 配置生效验证
- Claude Code：无需重启终端，直接输入测试指令（如
hello），正常响应即生效； - Codex/Gemini CLI：关闭终端重新打开，输入指令验证生效。
新手必看注意事项
- API Key 妥善保管，严禁泄露；
- Base URL 末尾不要加斜杠，避免路径拼接错误；
- 非 Claude Code 工具，切换后必须重启终端；
- Windows 用户名含中文，优先使用便携版，避免路径兼容问题。
四、第三步：进阶常用功能（按需学习）
1. 多工具独立配置
顶部切换 Claude、Codex、Gemini 等标签页，可为每个工具单独添加供应商，互不冲突，无需重复设置。
2. Skills 一键安装（Claude Code 专属）
- 切换到「Skills」标签页；
- 软件自动扫描 GitHub 公开 Skills 仓库；
- 勾选需要的 Skills（代码审查、规范化提交等），点击「安装」，自动同步到 Claude Code Skills 目录。
3. MCP 服务器统一管理
MCP（Model Context Protocol）用于扩展 AI 工具功能（文件读取、网页搜索等），CC-Switch 支持统一配置：
- 进入「MCP」标签页；
- 点击「导入已有」或「添加」，支持 stdio/HTTP/SSE 三种协议；
- 支持 ccswitch:// 开头的 Deep Link 一键导入，无需手动填写。
五、常见问题排查（Windows 新手避坑）
问题 1：切换供应商后配置不生效
- 检查是否重启对应 CLI 工具（Claude Code 除外）；
- 核对 Base URL 正确，末尾无多余斜杠；
- Git Bash 执行：
unset ANTHROPIC_AUTH_TOKEN、unset ANTHROPIC_BASE_URL，清除冲突环境变量。
问题 2：找不到需要的供应商预设
选择「自定义（Custom）」，手动填写 API 端点、Key 等信息，参考供应商官方文档配置格式。
问题 3：软件启动失败、报错、白屏
- 用户名含中文：用便携版，解压到纯英文路径；
- 配置损坏：删除
C:\Users\你的用户名\.cc-switch\cc-switch.db，重启软件重新配置； - 缺失 DLL：安装微软 VC++ 2019 运行库，重启电脑重试。
六、新手总结与后续学习
1. 核心流程回顾
Windows 新手上手 CC-Switch，只需 3 步：
安装软件 → 添加供应商 → 切换供应商，5 分钟完成基础配置，彻底告别手动改配置文件。
2. 后续进阶方向
- 进阶功能：学习本地代理、故障转移，实现自动切换与格式转换；
- 配置备份：定期备份
cc-switch.db文件，防止配置丢失； - 版本更新：关注 GitHub Releases，及时更新获取新功能与 bug 修复；
- 合规提醒：CC-Switch 为社区开源工具，非官方出品，使用第三方 API 需确认兼容对应 CLI 格式。
七、参考资料
- CC-Switch 官方下载与更新：https://github.com/farion1231/cc-switch/releases
结语
CC-Switch 凭借简洁的界面、强大的配置管理能力，成为 AI 开发者的必备辅助工具。按照本文教程操作，新手也能快速掌握核心用法，大幅提升 AI 编程工具的使用效率。如果教程对你有帮助，欢迎点赞、收藏、转发～