CC-Switch 快速入门教程：AI工具使用指南

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

说到日常折腾 AI 编程工具这件事，最让人头疼的往往不是写代码本身，而是配置管理这事儿——今天换 API 供应商了，明天调个模型了，都得手动去翻 JSON、TOML、.env 这些配置文件，一不小心就写错，问题排查起来又是半天。CC-Switch 就是专门解决这个痛点的工具。

它的核心角色，说白了一句话：跨平台的开源桌面工具，统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 这些主流 AI 编程 CLI 的 API 供应商配置。供应商一键切换、全局配置同步，这些听起来繁琐的操作，在它这儿就是点几下鼠标的事。

目前 GitHub 上已经收获了 44000+ Star，对于开发者社区来说，这个数字本身就是一种背书。本教程专为 Windows 平台的新手准备，不需要复杂的技术基础，全程跟着截图走就行。目标是帮助大家从“零认知”快速上手，掌握核心操作，顺带绕开那些常见的坑。

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 页面。Windows 平台提供了两种安装方式，新手可以根据自己的需求选。下面是最直接的步骤，照着操作就行了。

1. 方法一：MSI 安装器（推荐）

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

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

1. 在 GitHub Releases 页面下载后缀为 .zip 的便携版压缩包；
2. 解压到任意目录，建议选无中文、无空格的路径，避免兼容问题；
3. 找到解压目录里的 cc-switch.exe，双击运行，不需要安装。想卸载？把解压目录删掉就行了，干干净净。

3. 安装验证

启动 CC-Switch 后，如果能看到主界面——顶部是工具标签页，中间是供应商列表，右上角是「+」添加按钮——并且没有任何报错提示，就说明安装成功了。首次启动时，软件会自动扫描你本地已有的 CLI 工具配置，如果有，会提示是否导入，新手直接点「导入」就行，不需要额外操作。

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

CC-Switch 的核心操作其实就两个：添加供应商和切换供应商。下面用“添加小麦 API 供应商”作为例子来演示，其他供应商的配置流程完全一样。

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

所谓供应商，就是一套完整的 API 配置，包含四个信息：供应商名称、API 端点（Base URL）、API 密钥（API Key）、模型。切换供应商，本质上就是把这套配置自动写入对应 CLI 工具的配置文件，你不需要手动去改任何东西。

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

方式一：使用预设供应商（推荐）

1. 启动 CC-Switch，点击主界面右上角的「+」按钮（添加供应商）；
2. 在弹出的窗口中，点击「预设」下拉框，选择你需要的供应商，比如 Zhipu GLM、Deep Seek、Kimi 等。预设会自动填充 API 端点，省掉了手动输入这一步；
3. 在「API Key」输入框中，填入你从对应供应商平台获取的密钥；
4. 自定义供应商名称，方便后续识别。点击「添加」，供应商就会出现在主界面列表中。

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

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

3. 切换供应商

主界面切换

在主界面的供应商列表中，找到需要启用的供应商，点击它右侧的「启用」按钮。当供应商状态变成「Active」时，就说明切换成功了。

4. 配置验证（关键步骤）

切换供应商后，最好验证一下配置是否真的生效。不同 CLI 工具的验证方式有点差异：

• Claude Code：不需要重启终端，直接启动 Claude Code，输入一个简单指令，如果能正常响应，就说明配置成功了。Claude Code 支持热重载，体验最好；
• Codex：需要关闭终端，重新打开，再输入测试指令；
• Gemini CLI：也不需要重启终端，每次请求都会重新读取配置，输入测试指令验证就好。

5. 新手注意事项

• API 密钥要妥善保管，不要泄露给他人；
• 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 是 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 端点末尾是不是多了斜杠；
• 清除可能冲突的环境变量，比如 Anthropic 官方的环境变量。在 Git Bash 中输入命令：unset ANTHROPIC_AUTH_TOKEN、unset ANTHROPIC_BASE_URL（注意，普通 Windows 终端不支持这个命令，需要安装 Git 并打开 Git Bash 执行）。

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

解决方案：直接用「自定义」方式，手动填写 API 端点、API Key 等信息。具体配置格式可以参照对应供应商的官方文档。

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

解决方案：

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

六、新手总结与后续学习

1. 核心流程回顾

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

2. 后续学习方向

• 进阶功能：学习使用本地袋里与故障转移，重度用户必备，可以实现自动故障切换和格式转换；
• 配置备份：定期备份 C:\Users\你的用户名\.cc-switch\cc-switch.db 文件，避免重装软件后丢失配置；
• 版本更新：关注 GitHub Releases 页面，及时更新到最新版本，修复已知 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

来源：互联网