【AI工具】CC-Switch 入门教程

一、前置认知：CC-Switch 核心定位与适用场景

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

本教程专为 Windows 平台新手设计，无需复杂技术基础，全程图文化逻辑，带你从“零认知”快速上手 CC-Switch，掌握核心操作，解决使用中的常见问题。

一、前置认知：CC-Switch 核心定位与适用场景

1. 核心定位

CC-Switch 本质是「AI CLI 工具配置管理器」，基于 Rust + Tauri 2 + React/TypeScript 开发，所有配置本地存储（SQLite 数据库），采用原子写入方式（临时文件+重命名），避免配置文件写坏的问题，支持 Windows 系统使用，启动快、占用内存小。

2. 适用人群

• 使用 Claude Code、Codex 等 AI 编程 CLI 工具的 Windows 平台开发者；
• 需要频繁切换 API 供应商（如官方渠道、中转服务）的 Windows 用户；
• 不想手动编辑配置文件、怕出错的 Windows 新手；
• 需要统一管理 MCP 服务器、Skills 扩展、系统提示词的 Windows 重度用户。

3. 核心功能（新手必知）

• 供应商管理：内置 50+ 供应商预设（含官方渠道、云厂商、国内中转服务），支持自定义配置，一键切换；
• 快捷切换：支持主界面切换和系统托盘快切，Claude Code 支持热切换（无需重启终端），其他工具重启后生效；
• 配置同步：统一管理多个 CLI 工具的配置，一次设置可同步到所有支持的工具，无需重复操作；
• 辅助功能：支持 MCP 服务器统一管理、Skills 一键安装、系统提示词（Prompts）管理、用量追踪等。

4. 适用环境

• Windows：10 及以上版本（64位，推荐 Windows 11 以获得更流畅体验）。

二、第一步：下载与安装（Windows 平台详细步骤）

CC-Switch 官方下载渠道为 GitHub Releases 页面（https://github.com/farion1231/cc-switch/releases），Windows 平台提供两种安装方式，新手可根据需求选择，以下是详细步骤，直接跟着操作即可。

1. 方法一：MSI 安装器（推荐，无需手动配置）

1. 打开 GitHub Releases 页面，找到最新版本（推荐 v3.13.0 及以上，修复多项兼容问题），下载后缀为.msi的安装包（如 CC-Switch-v3.13.0-Windows-x64.msi）；
2. 双击下载后的安装包，弹出安装向导，点击「下一步」，接受许可协议，选择安装路径（默认路径即可，无需修改）；
3. 点击「安装」，等待安装完成（约1-2分钟），勾选「启动 CC-Switch」，点击「完成」，即可自动启动软件；
4. 若遇到 SmartScreen 提示“无法验证发行者”，点击「更多信息」，再点击「仍要运行」，即可正常启动（该提示为 Windows 安全验证，软件开源无风险）。

2. 方法二：便携版（无需安装，适合临时使用）

1. 在 GitHub Releases 页面下载后缀为.zip的便携版压缩包（如 CC-Switch-v3.13.0-Windows-Portable.zip）；
2. 将压缩包解压到任意目录（如桌面、D 盘，建议选择无中文、无空格的路径，避免兼容问题）；
3. 找到解压目录中的cc-switch.exe，双击即可运行，无需安装，关闭软件后删除解压目录即可彻底卸载。

3. 安装验证

启动 CC-Switch 后，若能看到主界面（顶部为工具标签页，中间为供应商列表，右上角为「+」添加按钮），且无报错提示，说明安装成功。首次启动时，软件会自动扫描本地已有的 CLI 工具配置，若有则会提示导入，新手可直接点击「导入」，无需手动操作。

三、第二步：核心配置（新手必学，5分钟搞定）

CC-Switch 的核心操作是「添加供应商」和「切换供应商」，以下以“添加小麦 API 供应商”为例（新手易上手），带你完成核心配置，其他供应商配置流程完全一致。

1. 核心概念：供应商（Provider）

供应商是一套完整的 API 配置，包含「供应商名称、API 端点（Base URL）、API 密钥（API Key）、模型」四部分，切换供应商本质就是将这套配置自动写入对应 CLI 工具的配置文件，无需手动修改。

2. 添加供应商（两种方式）

方式一：使用预设供应商（推荐，无需手动填 API 端点）

1. 启动 CC-Switch，点击主界面右上角的「+」按钮（添加供应商）；
2. 在弹出的窗口中，点击「预设（Preset）」下拉框，选择你需要的供应商（如 Zhipu GLM、Deep Seek、Kimi 等），预设会自动填充 API 端点，无需手动输入；
3. 在「API Key」输入框中，填入你的对应供应商 API 密钥（密钥需从对应供应商平台获取，如小麦 API 需在其控制台创建令牌）；
4. 自定义供应商名称（如“小麦 API- Claude”），方便后续识别，点击「添加（Add）」，即可完成供应商添加，此时供应商会出现在主界面列表中。

方式二：自定义供应商（适合预设中没有的供应商）

1. 点击主界面右上角的「+」按钮，选择「自定义（Custom）」；
2. 填写以下信息（以小麦 API 为例）：
3. 供应商名称：自定义（如“小麦 API- Codex”）；
4. API 端点（Base URL）：https://xiaomai.win（末尾不要加斜杠，否则会导致 API 请求失败）；
5. API 密钥：你的小麦 API Key（格式通常为 sk-xxxx）；
6. 模型：根据需求选择（如 claude-sonnet-4-20250514）。
7. 点击「添加」，完成自定义供应商配置，注意：官方预设的 API 端点是锁定的，若需修改为第三方 API 地址，必须选择「自定义」方式。

3. 切换供应商

主界面切换

在主界面的供应商列表中，找到需要启用的供应商，点击其右侧的「启用（Enable）」按钮，当供应商状态变为「Active」（活跃），说明切换成功。

4. 配置验证（关键步骤，避免配置失败）

切换供应商后，需验证配置是否生效，不同 CLI 工具的验证方式略有差异：

• Claude Code：无需重启终端，直接启动 Claude Code，输入简单指令（如“hello, please briefly introduce yourself”），若能正常响应，说明配置成功（支持热重载）；
• Codex：需关闭终端，重新打开，输入测试指令，正常响应即生效；
• Gemini CLI：无需重启终端，每次请求会重新读取配置，输入测试指令即可验证。

5. 新手注意事项

• API 密钥需妥善保管，不要泄露给他人；
• API 端点（Base URL）末尾不要加斜杠，否则会导致 API 路径拼接错误；
• 切换供应商后，若配置不生效，大概率是未重启对应 CLI 工具（Claude Code 除外）；
• 若之前手动配置过 CLI 工具，CC-Switch 首次启动会自动检测并导入，无需重复添加；
• Windows 用户名含中文时，建议使用便携版，绕开安装路径限制，避免软件启动失败。

四、第三步：新手常用功能（进阶操作，按需学习）

完成核心配置后，可根据自身需求，学习以下常用功能，进一步提升使用效率。

1. 多工具独立配置

CC-Switch 顶部有对应 CLI 工具的标签页（如 Claude、Codex、Gemini），切换到对应标签页，可为每个工具单独添加供应商，避免配置冲突。例如，为 Claude Code 添加小麦 API，为 Codex 添加 Kimi API，各自独立生效，无需重复设置。

2. Skills 一键安装（Claude Code 专属）

1. 点击主界面顶部的「Skills」标签页；
2. 软件会自动扫描 GitHub 上的公开 Skills 仓库（含官方、社区资源）；
3. 找到需要的 Skills（如代码审查、规范化提交），勾选后点击「安装」，即可自动同步到 Claude Code 的 Skills 目录，无需手动下载配置。

3. MCP 服务器统一管理

MCP（Model Context Protocol）是 AI CLI 工具的扩展协议，用于扩展工具功能（如文件读取、网页搜索）。CC-Switch 提供统一的 MCP 管理面板，一次配置可同步到所有支持的 CLI 工具，无需分别设置：

1. 点击主界面顶部的「MCP」标签页；
2. 点击「导入已有」，可导入已配置的 MCP 服务器；或点击「添加」，新建 MCP 服务器（支持 stdio、HTTP、SSE 三种协议）；
3. 若有 MCP 服务器的 Deep Link（ccswitch:// 开头），点击即可自动导入，无需手动填写配置。

五、常见问题排查（Windows 新手必看，避坑指南）

Windows 新手使用过程中，可能会遇到一些小问题，以下是高频问题及解决方案，无需复杂排查，直接对照操作即可。

1. 切换供应商后，配置不生效

解决方案：

• 确认是否重启了对应 CLI 工具（Claude Code 除外，支持热切换），Codex、Gemini CLI 等必须关闭终端后重新打开；
• 检查 API 端点（Base URL）是否正确，末尾是否多了斜杠；
• 清除可能冲突的环境变量（如 Anthropic 官方环境变量），在 Git Bash 中输入命令：unset ANTHROPIC_AUTH_TOKEN、unset ANTHROPIC_BASE_URL（普通 Windows 终端不支持该命令，需安装 Git 并打开 Git Bash 执行）。

2. 无法找到需要的供应商预设

解决方案：选择「自定义（Custom）」方式，手动填写 API 端点、API Key 等信息，具体配置格式可参考对应供应商的官方文档。

3. 软件启动失败（报错、白屏）

解决方案：

• Windows 用户名含中文：使用便携版（.zip），解压到无中文、无空格的路径，重新运行；
• 配置文件损坏：删除C:\Users\你的用户名\.cc-switch\目录下的 cc-switch.db 文件（需替换“你的用户名”为实际 Windows 用户名），重启软件，重新添加供应商（建议提前备份该文件）；
• 启动提示“缺失.dll文件”：安装微软常用运行库（如 VC++ 2019 运行库），重启电脑后再启动软件。

六、新手总结与后续学习

1. 核心流程回顾

Windows 新手上手 CC-Switch，只需掌握 3 个核心步骤：安装软件 → 添加供应商 → 切换供应商，5 分钟即可完成基础配置，告别手动编辑配置文件的繁琐。

2. 后续学习方向

• 进阶功能：学习使用本地代理与故障转移（重度用户必备，可实现自动故障切换、格式转换）；
• 配置备份：定期备份C:\Users\你的用户名\.cc-switch\cc-switch.db文件，避免重装软件后丢失配置；
• 版本更新：关注 GitHub Releases 页面，及时更新 CC-Switch 到最新版本，修复已知 bug，获得新功能；

3. 注意事项

CC-Switch 是社区开源工具，非 Anthropic、OpenAI 等官方出品，仅用于配置管理，不负责 API 供应商的服务质量；使用第三方 API 供应商时，需确认其支持对应 CLI 工具的 API 格式（如 Claude Code 需 Anthropic 兼容格式，Codex 需 OpenAI 兼容格式）。

据说，Claude Code会检测是否开启cc-switch，进行风控，请谨慎慎用。

七、参考资料

以下为教程相关参考资源，可用于获取最新版本、解决进阶问题及了解软件更新动态，均为官方或权威渠道，适合Windows平台用户查阅：

• CC-Switch 官方下载与版本更新：https://github.com/farion1231/cc-switch/releases
• CC Switch v3.10.3 - 安装与使用详细教程： https://zhuanlan.zhihu.com/p/2010439384097367984。