api.foo
api.foo / 文档 / CC Switch 安装与配置

CC Switch 下载安装与配置教程（2026 v4 最新）：一键切换 Claude Code、Codex 的 API

更新于
本页目录

一句话说清：CC Switch 是一个免费开源的桌面软件，帮你管理 Claude Code、Codex、Gemini CLI 等 AI 编程工具用哪家的 API。把服务商的地址和密钥存进去，点一下「启用」就切换过去，不用再手动改配置文件。

下载地址：唯一官网 ccswitch.io，或 GitHub 上的 farion1231/cc-switch。Mac 用户可以直接 brew install --cask cc-switch。本文按 2026 年 10 月的最新版 v4.0.12 写。v4 的界面和 v3 差别很大，网上不少教程截图还是旧版。

CC Switch 是什么，能帮你做什么

用 Claude Code、Codex 这类工具时，换一家 API 服务商就要手动改它们的配置文件：Claude Code 是 JSON，Codex 是 TOML，Gemini CLI 是 .env，改错一个字符就用不了。CC Switch 把这件事做成了图形界面：

  • 一键切换服务商：每家服务商是一张卡片，点「启用」就切过去。
  • 只改关键几项：切换时只替换地址、密钥、模型这几项，你自己装的插件、Hooks、MCP、权限设置都原样保留。第一次改写某个配置文件之前，它会先把原文件备份一份。
  • 管 10 种工具：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code。
  • 顺手的功能：统一管理 MCP、Skills 和提示词，在供应商卡片上显示余额，统计用量，浏览历史会话，在「应用」页一键安装和升级上面这些命令行工具。

v4 里有三种连接方式，理解了它们，后面的设置就都看得懂：

模式 怎么工作 什么时候用
直连 把服务商的地址和密钥直接写进工具的配置文件，工具自己去连 默认就是这个，大多数情况够用
路由 工具先连到 CC Switch 在你电脑上开的本地服务，CC Switch 再转发给服务商，中途可以转换接口格式、失败自动换下一家 服务商的接口格式和工具对不上（卡片上标着「需要路由」），或者想要自动故障转移
聚合 把好几家服务商的模型放进同一个模型列表，选哪个模型就发给哪一家 想在 Claude Code 或 Codex 里混用多家的模型

下载和安装

系统要求：Windows 10 及以上；macOS 12 及以上（Apple 芯片和 Intel 通用）；Linux 需要 glibc 2.35+ 和 WebKitGTK 4.1，比如 Ubuntu 22.04+、Debian 12+。

只从 ccswitch.io 或 GitHub 的 farion1231/cc-switch 下载。CC Switch 是免费软件，要你付费、充值或者索要登录信息的「CC Switch」网站和安装包都是假的。

Windows：下载 CC-Switch-v版本号-Windows.msi，双击安装；不想安装就下 Windows-Portable.zip 绿色版，解压后运行 CC-Switch.exe。ARM 电脑选带 arm64 的。双击安装包没反应时，右键 →「属性」→「常规」，勾选「解除锁定」再试。

Mac：推荐用 Homebrew：

brew install --cask cc-switch

也可以下载 CC-Switch-v版本号-macOS.dmg，把 CC Switch 拖进「应用程序」。Mac 版经过苹果签名和公证，能直接打开。

Linux：Ubuntu / Debian 下载 .deb，用 sudo dpkg -i 安装（缺依赖再运行 sudo apt-get install -f）；Fedora 用 .rpm；其他发行版用 .AppImage；Arch 用户 paru -S cc-switch-bin。

CC Switch 本身不需要装 Node.js。它管理的 Claude Code、Codex 这些工具要另外装，可以在 CC Switch 侧栏底部的「应用」页里一键安装，也可以按各自的教程装：Claude Code、Codex。

第一次打开：不会弄丢你原来的配置

第一次启动时，CC Switch 会做两件事：

  1. 把 Claude Code、Codex、Gemini CLI、Grok Build 现有的配置导入成一个叫 default 的供应商。
  2. 给每个工具加一个官方供应商，比如 Claude Official、OpenAI Official，以后想切回官方登录就点它。

所以装上 CC Switch 不会让你原来能用的配置失效，随时可以切回 default。

添加服务商：三种方法

先在左侧栏选中要配置的工具（比如 Claude Code），再点页面右上角的「+」（添加供应商）。

方法一：从服务商的控制台一键导入（最省事）

很多 API 平台的控制台有「导入到 CC Switch」按钮，点一下就能把地址、密钥、模型一起带进 CC Switch，不用手动复制。以 api.foo 为例：

  1. 登录 api.foo，进入 控制台 → API 密钥。
  2. 在要用的那把密钥右边点「⋯」，选「CC Switch」。
  3. 在弹出的「填入 CC Switch」窗口里：
    • 应用：选 Claude、Codex 或 Gemini。
    • 名称：卡片上显示的名字，可以自己改。
    • 主模型：必选。
    • Haiku、Sonnet、Opus 模型：选 Claude 时还可以分别指定。
  4. 点「打开 CC Switch」，浏览器会问是否打开 CC Switch，允许即可。
  5. CC Switch 弹出导入确认框，显示地址、打了码的密钥和模型。底部有个「导入后立即切换」开关，默认是关的；想马上用就打开，然后点「导入」。

导入时，地址会按工具自动填好：Claude 和 Gemini 是 https://api.foo，Codex 是 https://api.foo/v1。

方法二：用内置预设

CC Switch 内置了 90 多家服务商的预设。在添加页的搜索框输入名字（比如 kimi、智谱、openrouter），选中后地址自动填好，你只要填 API Key，点「添加」。

方法三：自定义配置

列表里没有你的服务商，就选最上面的「自定义配置」，自己填地址和密钥。不同工具的地址写法不一样，以 api.foo 为例：

工具 请求地址 说明
Claude Code https://api.foo 不带 /v1，Claude Code 会自己拼路径
Codex https://api.foo/v1 带 /v1；服务商要支持 OpenAI 的 Responses 接口
Gemini CLI https://api.foo

模型名可以点模型输入框旁边的「获取模型列表」按钮自动拉取。它调用的是服务商的 /v1/models 接口，报 401 是密钥不对，报 404 说明这家服务商不提供模型列表，就手动填。

切换和生效

在供应商卡片上点「启用」就切换过去了，也可以在系统托盘（Mac 右上角菜单栏）的 CC Switch 菜单里直接点服务商名字。

切换后什么时候生效，看工具：

工具 生效方式
Claude Code 立即生效，不用重启
Codex、Gemini CLI 关掉终端或工具，重新打开
Claude Desktop 完全退出再打开
OpenCode 等「共存式」工具 点「添加」后，在工具里自己选模型

想切回官方登录：启用列表里的官方供应商（如 Claude Official、OpenAI Official），重启工具后按它自己的流程登录：Claude Code 里输入 /login，Codex 运行 codex login。

配置 Codex 要注意的几点

  • 服务商要支持 Responses 接口。新版 Codex 只走 OpenAI 的 Responses 接口。只提供 Chat Completions 的服务商，卡片上会标「需要路由」，得开路由转换格式才能用。
  • 切换后要重启 Codex。
  • 密钥写在哪：切到第三方服务商时，CC Switch 把密钥写进 ~/.codex/config.toml 里那个服务商的 experimental_bearer_token，不会动 ~/.codex/auth.json（那是 ChatGPT 登录用的）。切回 OpenAI Official 时，原来的 ChatGPT 登录还在。

手动配置 Codex 的写法，见 Codex 安装与使用教程。

「需要路由」是什么意思

有的预设后面带一个「需要路由」标签，意思是：这家服务商的接口格式和你要用的工具对不上。比如 Claude Code 只会说 Anthropic 格式，而有的服务只提供 OpenAI 格式。

这时 CC Switch 的「路由」模式可以在你电脑上做翻译：

  1. 在工具页面顶部点「路由」标签，再点「开始路由」。
  2. 工具的配置文件会被改成指向本机地址（默认 http://127.0.0.1:15721），密钥一栏写的是占位符 PROXY_MANAGED。真正的地址和密钥保存在 CC Switch 里。
  3. 使用期间 CC Switch 必须开着。退出 CC Switch 时它会自动把配置写回直连。
  4. 不用了就点「回到直连」。

路由模式还能配故障转移队列：一家服务商请求失败，自动换到下一家。

服务商本来就支持你工具的格式时（比如 api.foo 同时提供 Claude 原生接口和 OpenAI Responses 接口），用直连就行，不需要开路由。少一层转发，也少一个出问题的地方。

常见问题与解决办法

1. 切换了，工具里还是旧的

  • Codex、Gemini CLI 关掉终端重新打开再试；Claude Code 一般立即生效，不行就重开终端或编辑器。
  • 看 CC Switch 顶部有没有黄色的「检测到系统环境变量冲突」提示。你自己在系统或 ~/.zshrc 里设置过 ANTHROPIC_BASE_URL、OPENAI_API_KEY 这类变量的话，它们的优先级比配置文件高，CC Switch 怎么切都会被盖掉。点「查看详情」，勾选后删除，CC Switch 会先自动备份，然后重启终端。

2. 「检测连通」通过了，请求还是失败

供应商卡片上的连通检测只检查地址能不能连上，不验证密钥和模型名。请求失败时，重点检查密钥有没有复制完整、模型名和服务商的列表是否一致、地址该不该带 /v1（见上面的表）。用路由模式的话，侧栏「用量」里的请求日志能看到具体报错。

3. 配置文件里的地址变成了 127.0.0.1

说明开着路由或聚合模式，这是正常的，见上文「需要路由」一节。想恢复成服务商的真实地址，点「回到直连」。

4. 正在用的供应商删不掉

CC Switch 规定每个工具始终要有一个在用的配置，这样即使卸载了 CC Switch，工具也还能用。先切到别的供应商，再删除。

5. Windows 上打不开、闪退

最常见的原因是缺少 WebView2 运行时，或者被杀毒软件拦了。从微软官网安装 Microsoft Edge WebView2，把 CC Switch 加进杀毒软件白名单，再打开。

6. Linux 上 AppImage 打不开

  1. 先加执行权限：chmod +x CC-Switch-*.AppImage。
  2. 提示 GLIBC_2.xx not found 说明系统太旧，CC Switch 需要 glibc 2.35+（RHEL / Rocky / Alma 8–9 暂不支持）。
  3. 报 FUSE 相关错误，装 libfuse2，或者改用 .deb / .rpm 包。

卸载

系统 卸载方法
Windows 「设置 → 应用」里卸载，或运行安装目录下的卸载程序
Mac（Homebrew 装的） brew uninstall --cask cc-switch，加 --zap 连配置数据一起删
Mac（手动装的） 把「应用程序」里的 CC Switch 拖进废纸篓
Ubuntu / Debian sudo apt remove cc-switch
Fedora sudo dnf remove cc-switch
Arch paru -R cc-switch-bin

卸载 CC Switch 不影响 Claude Code、Codex 这些工具，它们会继续用卸载前最后一次切换的配置。CC Switch 自己的数据（供应商列表、备份、日志）在用户目录的 .cc-switch 文件夹里，不要了可以手动删掉。

相关阅读

常见问题

CC Switch 官网是哪个？

唯一官方网站是 ccswitch.io，安装包也可以从 GitHub 上的 farion1231/cc-switch 项目的 Releases 页面下载，两处文件相同。CC Switch 是免费开源软件，任何要你付费、充值或者索要账号密码的「CC Switch」都不是官方的。

CC Switch 是干什么的？

它是一个桌面软件，帮你管理 Claude Code、Codex、Gemini CLI、OpenCode 等 AI 编程工具的 API 配置。把各家服务商的地址和密钥存进去，点一下就能切换，不用手动改 JSON、TOML 配置文件；还能统一管理 MCP、Skills 和提示词。

CC Switch 里的「需要路由」是什么意思？

表示这个服务商的接口格式和你要用的工具不一致，比如在 Claude Code 里用只支持 OpenAI 格式的服务。这时要在 CC Switch 里开启本地路由，由它在你电脑上做格式转换后再转发，并且使用期间 CC Switch 要保持运行。

CC Switch 切换供应商后不生效怎么办？

Claude Code 支持热切换，一般不用重启；Codex、Gemini CLI 要关掉终端或工具重新打开才生效。如果还是不对，看看 CC Switch 顶部有没有「检测到系统环境变量冲突」的提示，系统里设置的 ANTHROPIC_ 或 OPENAI_ 开头的环境变量会盖掉 CC Switch 写的配置。

卸载 CC Switch 会影响 Claude Code、Codex 吗？

不会。CC Switch 只是改写各个工具的配置文件，卸载后工具会继续使用卸载前最后一次切换的配置。CC Switch 自己的数据在用户目录的 .cc-switch 文件夹里，想彻底清除可以手动删掉。

CC Switch 要钱吗？

不要钱，它是 MIT 协议的开源软件。你在里面配置的模型服务各自收费。

发现内容有误？发邮件到 [email protected] 告诉我们。