ZT-006教程READY

CC-Switch 完整教程：AI CLI 多配置管理与一键切换

如果你同时用多个 AI CLI，或者同一个客户端有几套 API 配置，CC-Switch 可以把反复改配置文件的动作集中到一个界面里。

作者
AI折腾所
发布
更新
阅读
约 8 分钟
  • CC-Switch
  • AI CLI
  • Claude Code
  • Codex
CC-Switch 完整教程封面，展示安装、启用、禁用与配置切换主题

如果你同时在用 Claude Code、Codex、Gemini CLI，或者同一个客户端有多个 API / Provider 配置，最烦的事情之一就是来回改配置文件。改完还要记得改对地址、模型和密钥，偶尔还会忘记自己当前用的是哪一套。

CC-Switch 做的事情其实很简单：把这些配置集中到一个界面里，让你保存多套配置，再点一下启用、禁用或切换。

这篇只带你跑通一条主线：安装 CC-Switch → 优先一键导入配置 → 确认并启用 → 重启对应的 AI CLI / 客户端 → 开始使用 → 需要时切换或禁用。如果服务商没有一键导入，再手动添加。先会用，再看它背后怎么管理配置。

如果你用的是国内常见中转站，先别急着手填配置。现在很多服务商后台已经提供“一键导入 CC-Switch”“导入到 CC-Switch”或“一键配置”之类入口，点一下导进去、启用，再把对应的 AI CLI 或客户端完全退出重开，通常就能用了。

CC-Switch 是什么

CC-Switch 本质上是一个 AI CLI / AI 客户端配置管理工具。它不是模型服务，也不是新的 AI 客户端，而是帮你整理和切换现有客户端配置的桌面工具。

如果你只有一套固定配置，手动配置完全够用。如果你有多套配置，或者经常在不同客户端之间切换，集中管理会轻松很多。

它支持哪些客户端

当前项目 README 和我这台 macOS 上的 CC-Switch v3.20.3 界面列出了这些入口：

  • Claude Code
  • Claude Desktop
  • Codex
  • Gemini CLI
  • Grok Build
  • OpenCode
  • OpenClaw
  • Hermes Agent

界面里还可以看到其他应用入口（例如 Pi），具体以你安装的版本为准。不同客户端底层配置不一样，但在 CC-Switch 里的操作逻辑基本相同：先选客户端，再管理它的配置。

先把 CC-Switch 装上

最简单的路线是打开项目的 GitHub Releases，下载与你系统对应的安装包。

  • macOS：下载 macOS 安装包，打开后把 CC-Switch 拖进应用程序，或按安装器提示完成安装。
  • Windows：下载 Windows 安装包，按安装向导完成安装。
  • Linux：项目提供 Linux 发布包；选择对应发行版和架构的包，按项目 README 的说明安装。

第一次安装时，优先用 Releases 里的正式包，不要从搜索结果里的第三方下载站获取。版本更新很快，安装包名称和格式以发布页当前内容为准。

安装完成后打开 CC-Switch。你不需要先打开 Claude Code 或 Codex，先在 CC-Switch 里选好要管理的客户端即可。

第一次打开，先看这几个位置

打开后，顶部通常是客户端选择区，下面是当前客户端的配置列表。你马上会用到的只有几处：

  • 客户端选择：切换 Claude Code、Codex、Gemini CLI 等管理对象。
  • 配置列表：查看已经保存的配置。
  • 当前启用项：看哪一套配置正在生效。
  • 添加 / 新建：增加一套配置。
  • 编辑、启用、禁用和删除：管理已有配置。

不用一开始把每个按钮都研究一遍。先选一个你已经在使用的客户端，看看服务商后台有没有现成的导入入口。

CC-Switch 主界面显示客户端选择、多个配置和启用入口
主界面里先选要管理的 AI 客户端，再从配置列表里完成启用、禁用和切换。

最省事的方式：直接一键导入 CC-Switch

如果你的服务商后台提供“一键导入 CC-Switch”“导入到 CC-Switch”“一键配置”或类似入口，直接用这个就行，没必要先研究一堆配置字段。

  1. 打开服务商后台。
  2. 找到一键导入 CC-Switch 或类似入口并点击。
  3. 按提示打开 CC-Switch。
  4. 检查配置名称、地址和其他信息是否符合预期。
  5. 保存并启用这套配置。
  6. 完全退出正在运行的 AI CLI 或客户端。
  7. 重新打开它。

导入成功不等于正在运行的客户端立刻切换。很多客户端启动时才读取配置，所以导进去以后别忘了点启用，然后把对应客户端关掉再开一次。

没有一键导入？再手动添加

只有服务商没提供一键导入时，再按下面的方式手动添加：

  1. 在顶部选择目标客户端。
  2. 点击“添加新供应商”或“新建配置”。
  3. 填一个容易认出的配置名称，例如“公司 API”或“个人测试”。
  4. 按界面提示填写服务地址 / API 地址。
  5. 填 API Key 或 Token。
  6. 如果这套服务需要，再选择或填写模型。
  7. 保存。

不同客户端和不同 Provider 显示的字段可能不一样。地址、模型和鉴权信息怎么填，以 CC-Switch 当前表单和服务商文档为准，不要把 Claude Code 的字段照搬到 Codex，也不要把一个服务的模型名猜着填到另一个服务里。

API Key、Token 和 Cookie 都是秘密。不要把它们贴进文章、截图、聊天记录或 Git；截图前也要确认输入框没有显示真实值。

CC-Switch 编辑供应商表单显示名称、地址、API Key 和模型字段
新增配置时，把服务商给你的地址、凭据和客户端所需字段填进去即可；不同客户端显示的字段可能不同。

导入或添加以后，还要点启用

这里最容易漏一步：无论是一键导入还是手动添加，保存只是把配置存起来。还要在配置列表中选中这套配置并点击“启用”，看到当前启用项已经换成它，再进行下一步。

切换后为什么要重启客户端

这一点很容易漏。CC-Switch 改的是配置，但你正在运行的 Claude Code、Codex、Gemini CLI 或其他客户端，可能早就把旧配置读进内存了。

所以最稳妥的做法是：

  1. 完全退出正在运行的 AI CLI 或客户端。
  2. 确认终端或桌面客户端没有留下旧进程。
  3. 重新打开它。

默认建议切完以后直接重启；除非某个客户端明确支持实时刷新。把正在跑的 AI 客户端关掉再开一次，通常是最省心的做法。

切换到另一套配置

假设列表里有配置 A 和配置 B，操作就是：

选中配置 B
→ 点击启用
→ 完全退出对应 AI CLI / 客户端
→ 重新打开

想切回来时再对配置 A 做同样的操作。CC-Switch 的价值就在这里：不用每次打开 JSON、TOML 或环境变量文件找同一行配置。

禁用配置

暂时不用某个配置，直接禁用就行，不用删。禁用是让它当前不生效，配置本身还会留在列表里，之后可以再次启用。

禁用和删除不是一回事：

  • 禁用：暂时不用，之后还能恢复。
  • 删除：把这套配置从列表中移除，删除前先确认以后不再需要。

如果禁用后客户端看起来还在工作，先把客户端完全退出再打开。旧进程还活着时，它可能继续使用之前读到的配置。

编辑和删除配置

选中配置后，可以按需要编辑：

  • 改一个更容易识别的名称；
  • 更新服务地址；
  • 更换 API Key / Token；
  • 修改模型；
  • 删除已经不用的配置。

换了 Key 或地址后，保存、重新启用当前配置，再重启对应客户端。只改完表单但没有启用，或者客户端还没重启，看到旧结果并不奇怪。

导入、导出和备份怎么处理

CC-Switch 的版本更新较快，导入、导出、备份等入口可能随客户端和版本变化。当前主界面最稳定、最通用的操作是添加、编辑、复制、启用、检测和删除；如果你的版本提供单独的导入或备份入口，按界面提示使用即可。

第一次让 CC-Switch 管理重要配置前，建议先保留原配置文件的备份。备份不要和 API Key 一起发给别人，也不要提交到 Git。找不到恢复入口时，可以先禁用当前配置、恢复原文件，再重启客户端。

CC-Switch 背后做了什么

它没有替你创造一套新的 Provider 协议。Claude Code、Codex、Gemini CLI 各自有自己的配置方式，CC-Switch 只是把这些原本需要手动维护的配置集中到 UI 里，并在你启用时写回客户端能读取的位置。

因此它不是魔法：客户端本身能不能连接、服务地址是否正确、模型是否存在，仍然由对应客户端和服务决定。CC-Switch 负责的是“选哪套配置”和“把它放到正确位置”。

手动配置还是 CC-Switch

只有一个固定配置、而且你熟悉配置文件时，手动配置完全可以。它的好处是简单、透明，不依赖额外桌面工具。

如果你同时用多个客户端、同一个客户端有多套 Provider，或者经常切换，CC-Switch 更省事。它把重复的编辑、保存和切换动作放到一个地方，减少手改 JSON、TOML 或环境变量时的出错机会。

不要和 codex-switch 混淆

CC-Switch 是第三方开源的图形化配置管理工具，面向多个 AI CLI / 客户端。

codex-switch 则是 Codex 如何切换 OpenAI Compatible API 里介绍的用户自建 shell 脚本，专门围绕 Codex 的独立 Profile 和 Provider 切换。两者解决的问题有点像，但不是同一个项目，也不能把一个工具的配置方式直接套到另一个工具上。

常见问题

切换以后为什么没变化？

先把对应的 AI CLI / 客户端完全退出，再重新打开。很多程序只在启动时读取配置。

保存了为什么没生效？

你可能只保存了配置，还没有点“启用”。保存是存起来，启用才是让它成为当前配置。

禁用了为什么还能用？

旧进程可能还在运行。退出客户端和相关终端进程，再重新打开看看。

换了 Key 还是旧 Key？

确认改的是当前启用的配置，保存后重新启用，并重启客户端。不要只改列表里另一套没有启用的配置。

删除和禁用有什么区别？

禁用是暂时不用，配置还在；删除是移除配置，之后需要重新添加才能使用。

CC-Switch 会自动修改原配置吗？

它的工作就是把配置写到对应客户端会读取的位置。不同客户端的具体文件和行为可能随版本变化，遇到异常时先看 CC-Switch 当前提示，再检查客户端自己的配置和启动状态。

记住这一条主线

有一键导入时，从服务商后台导入 CC-Switch，确认后点启用并重启对应客户端；没有一键导入时，再手动添加、保存、启用并重启。要换配置，就启用另一套并重启；暂时不用就禁用，不确定时先保留备份。

如果你还没装 Claude Code，可以先看 Claude Code 从零开始；如果你主要想解决 Codex 的 Provider 和独立 Profile，再看上面的 codex-switch 教程。