夜雨聆风❝适合人群：正在用 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等 AI 编程工具，但被 API Key、Base URL、模型名、配置文件折腾到头大的新手
很多人第一次用 AI 编程 CLI 工具时，都会卡在同一个地方：
工具本身能装，但供应商怎么填？API Key 放哪里？Base URL 是什么？模型名写错了会怎样？想从官方切到第三方 API，又怕把配置文件改坏。
CC Switch 就是为这类场景准备的桌面工具。它把一堆原本需要手动改配置文件的操作，做成了一个可视化界面：添加供应商、切换供应商、管理模型、查看用量、管理 MCP、Skills、Prompt、会话等，都可以在一个应用里完成。
一句话讲清楚：
CC Switch 不是 AI 模型，也不是替你写代码的工具。它更像 AI 编程 CLI 的“配置总控台”。
一、先搞懂：CC Switch 到底帮你省了什么事？
如果你只用一个工具、一个官方账号、一个模型，也许暂时不需要它。
但只要你遇到下面任意一种情况，CC Switch 就很有价值：
想在 Claude Code、Codex、Gemini CLI 等工具之间统一管理配置。 想把官方供应商和第三方 API 分开管理。 想快速切换不同模型，比如日常用便宜模型，复杂任务再换强模型。 想给 Codex、Claude Code 这类工具接入第三方兼容接口。 不想每次都手动改 JSON、TOML、环境变量。 想看用量、余额、会话记录，方便控制成本。 想管理 MCP、Skills、Prompt、Agents、Output Styles 等高级配置。
对小白来说，它最实用的点不是“功能很多”，而是：
你终于不用靠记路径、改配置文件、重启命令行来试错了。
二、使用前先认识 4 个词
第一次打开 CC Switch，不要急着乱填。先把这 4 个词搞懂，后面就顺了。
1. App
这里的 App 指的是你要管理的 AI CLI 工具。
常见包括：
Claude Code Codex Gemini CLI OpenCode OpenClaw
你可以把它理解成“我要给哪个工具换供应商”。
2. Provider
Provider 就是供应商。
它可以是官方服务，也可以是第三方 API 服务。比如你给 Codex 添加一个 DeepSeek、Kimi、GLM、MiniMax 等兼容上游，本质上就是新增一个 Provider。
3. API Key
API Key 就像一把钥匙，用来证明“你有权限调用这个供应商的模型”。
小白一定要记住：
API Key 不要发给别人。 不要把 API Key 截图发到群里。 不要从来路不明的网站复制配置。 不要把 API Key 写进公开仓库。
4. Base URL
Base URL 可以理解成“请求发到哪里”。
官方供应商和第三方供应商的 Base URL 往往不同。很多配置失败，本质就是 Base URL 填错、结尾路径不对，或者模型名和接口协议不匹配。
三、下载安装：先认准官方渠道
CC Switch 是免费、开源的桌面应用。项目 Release 页面特别提醒：只应通过官方渠道获取软件，不要相信收费、充值、索取登录凭据的山寨网站。
安装时按系统选择：
Windows 用户
推荐下载 MSI 安装包。如果你只是想试一下，也可以下载 Portable 便携版，解压后运行。
适合小白的选择：
优先选 Windows.msiWindows 安装向导一般就是一路下一步。真正要注意的是：安装包要来自官方 Release 页面，不要从陌生下载站拿“二次打包版”。
如果你想修改安装目录，可以在安装向导里选择目标文件夹；不确定就保持默认。
macOS 用户
推荐下载 DMG 安装包，打开后拖到 Applications。
如果你熟悉 Homebrew，也可以用 cask 安装和升级。
适合小白的选择：
优先选 macOS.dmgLinux 用户
Linux 会区分 x86_64 和 ARM64 架构，也会提供 AppImage、deb、rpm 等格式。
小白建议：
Ubuntu / Debian 选 .debFedora / RHEL 系选 .rpm不想安装到系统里，选 AppImage
不知道自己是什么架构时，可以在终端运行：
uname -m常见结果：
x86_64：选 x86_64aarch64：选 arm64
四、第一次打开：先别急着添加，先看主界面
打开 CC Switch 后，主界面会把不同 App 和供应商管理放在一起。你可以先切换语言为中文，再看自己要管理的是 Claude Code、Codex，还是其他 CLI 工具。
主界面建议先看 5 个地方：
当前管理的是哪个 App。 已经识别到哪些供应商。 当前正在使用哪个供应商。 是否有用量、余额、状态信息。 是否有 MCP、Skills、Prompt、Session 等配置入口。
如果你以前手动配置过 Claude Code 或 Codex，CC Switch 可能会读取现有配置。第一次使用时不要急着删除旧配置，先观察它识别出来的内容是否正确。
如果打开后是英文界面，也别慌
CC Switch 支持多语言。即使你第一次看到的是英文界面，布局也基本一致：左侧选 App，中间看 Provider，右侧管理用量、模型和相关配置。
小白最稳的做法是：先找语言设置切到中文，再继续添加供应商。不要一边看英文界面一边乱猜配置项，尤其不要把 API Key 填到错误位置。
五、添加第一个供应商：小白照这个顺序填
点击添加供应商后，会进入类似下面的表单页面。
如果你看到的是英文添加页面，也可以对照中文界面理解。核心字段无非是 App、Provider 名称、API Key、Base URL 和模型名。
小白不要被表单吓到，按这个顺序填就行。
第 1 步：选 App
先确认你要给哪个工具添加供应商。
例如：
想给 Codex 用第三方 API，就选 Codex。 想给 Claude Code 增加 Claude 兼容上游，就选 Claude Code。
不要把 App 选错。App 选错了，配置写到另一个工具里，自然不会生效。
第 2 步：取一个好懂的名字
建议不要只写“默认”“测试”“API1”。
更推荐这样命名：
DeepSeek-日常 Kimi-长文 GLM-便宜 Claude-官方 Codex-官方 OpenAI-备用
名字写清楚，后面切换时不会迷路。
第 3 步：选择供应商类型或预设
如果 CC Switch 里有对应预设，优先用预设。预设通常会帮你少填一些容易错的协议和接口信息。
如果没有预设，再选择自定义供应商。
第 4 步：填 API Key
API Key 从对应供应商后台获取。
这里最容易出错的是：
复制时多了空格。 复制了错误项目的 Key。 Key 已过期或额度不足。 使用了不支持当前接口的 Key。
填完后不要截图分享。
第 5 步：填 Base URL
Base URL 必须来自你正在使用的供应商文档。
这里不要凭感觉猜。不同供应商、不同兼容接口，路径可能不一样。看文档、复制官方示例，永远比自己手打稳。
第 6 步：填模型名
模型名也要以供应商文档为准。
很多人配置失败，不是 Key 错了，而是模型名写错了。
建议第一次不要选太冷门的模型，先选供应商文档里明确支持、最常用的那个。确认跑通后，再慢慢换高级模型。
下面两张第三方教程配置图可以帮助你理解：Claude Code 和 Codex 的配置项看起来不完全一样，但本质都绕不开供应商、密钥、接口地址和模型。
六、添加后怎么确认能不能用？
添加完供应商后，不要马上拿真实项目开干。先做一个最小测试。
推荐顺序：
在 CC Switch 里保存供应商。 切换到这个供应商。 如果界面提供检查或测试能力，先跑一次。 重启对应 CLI 工具。 在终端里发一个最简单的问题。
例如：
你好，请用一句话回复你当前可用。为什么要这么简单？因为第一次测试只验证“能不能连上”，不是验证模型聪不聪明。问题越简单，排错越快。
七、一键切换供应商：它真正好用的地方
配置好多个供应商后，CC Switch 的价值就出来了。
你可以按场景切换：
日常小任务
用便宜、响应快的模型。
适合：
改 README 写脚本 查报错 生成测试数据 简单解释代码
复杂代码任务
切到更强的模型。
适合：
大范围重构 分析复杂 bug 设计架构 写长上下文方案 多文件联动修改
备用线路
当某个供应商限流、网络不稳、额度不足时，切到备用供应商。
这对经常使用 CLI 写代码的人非常实用。以前你可能要手动改配置文件，现在直接在界面里切。
八、Codex 用户特别注意：改完供应商可能要重启 Codex
根据项目最新 Release 说明，Codex 的模型目录和部分配置会在客户端启动时读取。也就是说，切换供应商或修改模型映射后，可能需要重启 Codex，才能让菜单和模型目录刷新。
小白记住一句话就行：
Codex 配置改完不生效，先重启 Codex。
这一步很朴素，但能解决大量“我明明保存了，为什么没变化”的问题。
九、MCP、Skills、Prompt、Session：小白先怎么用？
CC Switch 不只管理供应商，还支持 MCP、Skills、Prompt、会话、用量等功能。
但我建议小白不要第一天就全部折腾。
更稳的路线是：
第一天
只做三件事：
安装 CC Switch 添加一个供应商 切换并跑通一次 CLI
第二天
再看：
用量和余额 模型价格 当前供应商是否稳定 是否需要备用供应商
第三天之后
再逐步研究：
MCP Skills Prompt Agents Output Styles Session 管理
这样不容易把自己绕晕。
十、一个小白可抄的配置策略
如果你还不知道怎么规划供应商，可以照这个来。
方案 A：最简单
只保留一个官方供应商。
适合：
刚开始使用 不想折腾第三方 API 预算可接受 只求稳定
优点是省心，缺点是成本和可选模型受限制。
方案 B：官方 + 一个第三方
保留官方供应商，再添加一个第三方备用。
适合：
想降低成本 想试试 DeepSeek、Kimi、GLM 等上游 希望官方服务不稳定时有备用
这是我最推荐小白尝试的路线。
方案 C：多个第三方分工
按任务类型分配供应商。
例如：
日常便宜模型 长上下文模型 代码能力强的模型 备用线路
这个方案更灵活，但也更考验你对模型、价格和稳定性的理解。
十一、常见问题排查
1. 保存了供应商，但 CLI 没变化
先重启对应 CLI 工具。尤其是 Codex，切换供应商或修改模型映射后，重启往往是必要的。
2. 提示认证失败
重点检查：
API Key 是否复制完整。 Key 是否过期。 当前账户是否有余额。 供应商是否要求特定接口或区域。
3. 提示模型不存在
大概率是模型名写错，或者这个 Key 没有权限访问该模型。
去供应商文档里复制模型名，不要手打。
4. 能连上，但回答很慢
可能原因：
供应商本身慢。 网络到该供应商不稳定。 模型太大。 任务上下文太长。 开启了复杂的工具调用或 MCP。
先用简单问题测试，再逐步增加复杂度。
5. 第三方 API 用在 Codex 里有异常
Codex 和部分第三方供应商的协议并不总是完全一致。CC Switch 的新版本加强了 Chat Completions 到 Responses 的路由转换，但不同供应商在工具调用、流式输出、推理内容、错误返回上仍可能有差异。
小白建议：
先用项目预设。 不要一开始就乱改模型映射。 出问题先换一个基础模型测试。 复杂功能跑不通时，先退回官方供应商确认工具本身正常。
6. 担心把原配置弄坏
第一次使用前，可以先备份对应工具的配置目录。如果你不知道配置在哪里，至少不要手动删除 CC Switch 识别出来的旧供应商。
更稳的习惯是：
先添加新供应商。 测试通过再切换。 不要直接覆盖唯一可用配置。 重要项目开工前，确认当前供应商没选错。
十二、安全提醒：不要被“山寨 CC Switch”骗了
项目 Release 明确提醒：CC Switch 是免费、开源的桌面应用。任何向你收费、要求充值、索取登录凭据的“CC Switch”网站或客户端，都要警惕。
小白尤其要记住：
只从官方渠道下载。 不要把 API Key 填到陌生网页。 不要购买所谓“CC Switch 激活码”。 不要相信别人发来的二次打包安装包。 如果安装包来源不确定，就不要运行。
这个提醒很现实。AI 工具越火，山寨下载站越多。
十三、最适合小白的上手路线
最后给一个不容易翻车的流程：
从官方 Release 下载并安装 CC Switch。 打开软件，切换中文界面。 先确认它识别到哪些 AI CLI 工具。 选一个你真正要用的 App，比如 Codex 或 Claude Code。 添加一个供应商，优先用预设。 填 API Key、Base URL、模型名。 保存。 切换到这个供应商。 重启对应 CLI 工具。 用一句简单问题测试。 跑通后，再添加备用供应商。 最后再研究 MCP、Skills、Prompt 和用量管理。
按这个顺序来，小白也能比较快跑通。
总结
CC Switch 的真正价值，是把 AI 编程工具里最容易劝退新手的配置工作，变成一个可视化流程。
它不替你选择模型，也不保证第三方供应商永远稳定。但它能让你更清楚地管理：
哪个 CLI 工具正在用哪个供应商 API Key 和 Base URL 填在哪里 模型如何切换 用量和余额怎么看 出问题该从哪里排查
如果你已经开始用 Claude Code、Codex、Gemini CLI 这类 AI 编程工具，CC Switch 值得装一个。哪怕你暂时只用一个供应商，它也能帮你把配置管得更清楚。
相关地址
CC Switch GitHub 仓库：https://github.com/farion1231/cc-switch
写在最后
如果你也在折腾 AI 编程工具、Claude Code、Codex、MCP、Skills 和各种第三方模型接入，欢迎关注本号。后面会继续分享更适合新手的实战教程：从安装、配置、避坑到真实项目工作流，一步一步把这些工具用顺
