2026-06-09

CC Switch 怎么安装和配置：给 Claude Code、Codex 新手的入门教程

CC Switch 不是模型，也不是中转站，它更像一个 AI 编程工具配置面板，用来统一管理 Claude Code、Codex、Gemini CLI 等工具的供应商、MCP 和提示词。

9 分钟choose / workflow

先说清楚：这里讲的是 farion1231/cc-switch

网上叫 ccswitch、CC Switch、cc-switch 的东西不止一个。本文讲的是这个开源桌面应用：

它的用途不是直接聊天，也不是卖模型额度，而是帮你管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等 AI 编程工具的配置。

CC Switch 适合解决什么问题

你不需要一开始就装 CC Switch。它主要解决的是“工具和供应商多了以后，配置很乱”的问题。

比如你已经遇到这些情况：

  • Claude Code、Codex、Gemini CLI 都在用
  • 既有官方账号，也有 API key 或企业网关
  • 不想反复手改 settings.json、config.toml、.env
  • 想统一管理 MCP、Skills、提示词和供应商配置
  • 想在不同供应商之间切换，但又怕覆盖掉原来的配置

这时 CC Switch 才有价值。

它不适合谁

如果你只是普通 ChatGPT / Claude 用户，不写代码，不用终端，也不切 API 供应商，那不用装。

如果你刚开始用 Claude Code，建议先把 Claude Code 官方安装和登录跑通，再考虑 CC Switch。否则你会分不清到底是 Claude Code 没装好，还是 CC Switch 配置没生效。

下载前先确认官方渠道

CC Switch 官方仓库的 Releases 页明确写了唯一官方渠道：

类型官方入口
官网ccswitch.io
源码github.com/farion1231/cc-switch
下载GitHub Releases
作者@farion1231

如果某个页面要求你给 CC Switch 充值、购买授权、输入 Claude / OpenAI 账号密码，先不要继续。

安装前先准备好这些工具

CC Switch 是配置管理器，不是替你安装所有 AI 编程工具的魔法按钮。安装它之前，最好先确认你要管理的工具本身能运行。

至少准备其中一个：

  • Claude Code：先按 Claude Code 官方文档 安装，并确认终端里能运行 claude
  • Codex：先按 Codex CLI 官方文档 安装，并确认终端里能运行 codex
  • Gemini CLI：如果你要管理 Gemini CLI，也先确认它本身已经能启动

如果基础工具还没跑通，不要急着导入到 CC Switch。

第一步：从 GitHub Releases 下载

进入 GitHub Releases，选择最新版本，再按系统下载：

  • Windows：通常选 .msi 或 .exe
  • macOS：通常选 .dmg
  • Linux：按发行版选择 .deb、.rpm 或 AppImage

如果你不确定自己的电脑架构，Windows 用户一般先看 x64，Apple Silicon Mac 一般看 arm64 / Apple Silicon。

第二步：先导入现有配置

新手最容易犯的错，是一打开 CC Switch 就直接新建一个空供应商，然后发现原来的 MCP、Skills、提示词全不见了。

更稳的顺序是：

  • 先打开 CC Switch
  • 找到导入现有配置的入口
  • 让它读取你已经跑通的 Claude Code / Codex / Gemini CLI 配置
  • 确认默认配置存在后，再新增供应商

这样就算你后面配错了，也能切回原来的官方登录或默认配置。

第三步：新增一个供应商

如果你朋友做的是中转站或企业网关，通常会给用户这几类信息：

  • Provider 名称
  • Base URL
  • API Key
  • 兼容格式，比如 Anthropic 兼容、OpenAI 兼容、Gemini 兼容
  • 推荐模型名

在 CC Switch 里新增供应商时，不要只看“能不能保存”，还要确认这个供应商是给哪个工具用的。

工具常见配置方向
Claude CodeAnthropic 格式端点、Claude 模型名、~/.claude 配置
CodexOpenAI 兼容端点、Codex / GPT 模型名、~/.codex/config.toml 配置
Gemini CLIGemini 兼容端点、Gemini 模型名、~/.gemini 配置

同一个 API key 不一定适合所有工具。中转站如果同时支持多种协议，也要分别确认每个工具该填哪种格式。

第四步：启用后重启对应工具

配置启用后，不要在旧终端里继续测试。更稳的做法是：

  • 先在 CC Switch 里启用目标供应商
  • 关闭已经打开的 Claude Code / Codex 终端会话
  • 重新打开终端
  • 在项目目录里重新运行 claude 或 codex

如果工具支持热切换，实际体验会更顺；但新手排错时，重启终端最不容易误判。

第五步：用一个小任务测试

不要一上来就让 agent 改真实项目的大功能。先用一个小任务确认链路：

  • 让 Claude Code 解释当前目录结构
  • 让 Codex 读取一个 README 并总结
  • 让 agent 只改一个无关紧要的测试文件
  • 看它是否能正常返回、是否报鉴权错误、是否模型名不识别

确认这一层没问题，再交给它真实任务。

常见问题 1：启用后还是走官方账号

可能原因：

  • 旧终端没有重启
  • 工具本身有环境变量覆盖了配置文件
  • CC Switch 改的是另一个工具的配置
  • 你导入的是默认配置，但没有启用新供应商

先重启终端，再检查当前工具到底读取哪个配置目录。

常见问题 2：报模型不存在

这通常不是 CC Switch 坏了，而是供应商给的模型名和工具请求的模型名对不上。

处理顺序：

  • 先确认供应商支持 Anthropic、OpenAI 还是 Gemini 格式
  • 再确认模型名是否完全一致
  • 如果是中转站，问清楚它是否做了模型别名映射
  • 不要自己猜模型名

Claude Code、Codex、Gemini CLI 对模型列表和响应格式的要求不完全一样，能在一个工具里跑通，不代表另一个工具一定能跑通。

常见问题 3：MCP 或 Skills 不见了

通常是因为你直接新建了空配置，没有先导入原来的配置。

处理方式：

  • 切回默认配置，看原来的 MCP / Skills 是否还在
  • 如果还在，重新用“导入现有配置”的方式建供应商
  • 如果已经覆盖，先找 CC Switch 的备份 / 云同步 / 历史配置
  • 不要继续反复新建供应商，否则更难判断哪份配置是对的

给中转站用户的说明模板

如果你要给小白用户发说明，可以直接改这段：

先从 github.com/farion1231/cc-switch/releases 下载 CC Switch，不要从搜索结果里的第三方下载站安装。安装后先导入你现有的 Claude Code / Codex 配置，再新增我们提供的供应商。启用后重启终端，再运行 claude 或 codex 测试。不要把 Claude、OpenAI、Google 账号密码填到任何非官方页面。

这段比单纯丢一个下载链接更安全，因为它告诉用户不要跳过“导入现有配置”和“重启终端”。

一句话建议

CC Switch 的价值不是“让 AI 变强”，而是把多个 AI 编程工具、多个供应商、多套 MCP / Skills 配置收在一个面板里管理。先把 Claude Code 或 Codex 官方安装跑通，再用 CC Switch 做配置切换，会比一开始就把所有东西都塞进去更稳。

继续看