说实话，Claude Code 用到现在，最让我崩溃的不是 Agent 能力不行，也不是上下文不够长，而是来回改配置这件事。今天用官方 Anthropic API，明天想接一下第三方兼容网关，后天又想切到本地 Ollama 跑一下模型，每次都得打开config.toml手改ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN，一不小心改错一个斜杠，整个会话就报废了。我一直在找一个能一键切换的工具，直到用上 cc-switch，这个问题才算彻底解决。如果你也经常在多套 Claude Code 环境之间来回横跳，那这篇实操笔记你应该用得上。
cc-switch 本质上是一个管理 Claude Code 供应商（Supplier）配置的小工具，它把那些散落在配置文件里的 api_base_url、api_key、model 命名全部抽出来，做成一套套独立配置，然后通过一个交互式菜单，一键激活、一键覆盖。它支持直接在 Home 目录下安装使用，也支持跨平台（macOS / Windows / Linux）。特别适合以下几类人：长期在官方 API 和第三方网关之间切换的开发者、需要同时管理本地 Ollama 和云端模型的玩家、以及团队里有多套企业级端点的配置管理员。
下面我把完整的安装流程、配置方法和踩坑记录都整理出来，尽量做到读完就能直接上手。
1. 整体设计与思路拆解
1.1 为什么需要 cc-switch
先搞清楚 Claude Code 的配置机制，这个很关键。
Claude Code 在启动时会自动加载一份config.toml，文件里通过[env]字段注入各种环境变量。你平时在终端里设置的那些ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL，其实都可以写进这个文件里。也就是说，Claude Code 的"行为"完全由这一份配置文件决定。
问题就出在这里：当你需要切换不同的 API 供应商时，本质上是让config.toml里的三四个关键字段变成另一套值。手动改吧，每次都要小心翼翼，改完还要重启 Claude Code 让它重新读取配置。改错一个字母、多带一个空格、URL 漏掉/v1后缀，那这次会话基本就废了。更麻烦的是，来回切换的次数一多，你根本想不起来上一次用的是什么组合，全靠记忆硬撑。
cc-switch 的思路很朴素：把每套供应商配置做成一个"模板"，里面存好 base_url、api_key、model 等完整信息。你需要用哪一套，就在菜单里选中它，工具会自动把这些字段写入 Claude Code 的配置文件，并做一次备份。这就好比你手机里的 Wi-Fi 列表，连接哪台路由器只需要点一下，而不是每次都手动输入 SSID 和密码。
这里还要说一个细节：cc-switch 本身也会把自己的配置保存在一个独立的config.json里，它只是"负责写" Claude Code 的config.toml，两者是分离的。所以即使你把 cc-switch 卸载了，Claude Code 也能正常用，只不过失去了快速切换能力而已。这个设计我给好评，依赖不纠缠，干干净净。
1.2 cc-switch 官方版与社区版的选择
现在你在网上搜 cc-switch，可能会看到两个版本。一个是较早的 Node.js 版本，安装方式基本是npm i -g cc-switch，它提供了一个菜单式的交互界面，功能简单直接，就是管理供应商配置、激活配置、查看当前配置。我最早用的就是这个版本，稳定，够用，唯一的槽点是界面有点粗糙，但你只是切换配置，也不指望它多花哨。
后来社区里出了一个用 Rust 重写的版本，仓库一般叫cc-switch，看 README 里写的是用cargo或者源码编译安装，编译出来的二进制文件性能更好、启动更快，而且界面也做得更像一个正经 TUI（终端交互界面）。如果你电脑上本来就有 Rust 工具链，我建议直接上 Rust 版本；如果你只是想要一个开箱即用的工具，Node.js 版也挺好。
两个版本的核心逻辑完全一致，基本不挑操作系统，macOS 和 Windows 都没有问题。唯一的差别在于安装方式，下面一节我会分开讲。
2. 安装与核心配置要点
2.1 安装前的环境确认
在安装 cc-switch 之前，有个前置条件你得确认一下：Claude Code 本身已经正常工作。如果你还没装 Claude Code，或者装完以后连/status命令都跑不出来，那先用官方安装文档把 CLI 装好，再来折腾切换工具。
macOS 和 Linux 下的安装很简单，终端执行官方安装命令，然后重启终端让claude命令生效。Windows 下稍微特殊点，你大概率得用 PowerShell 执行安装命令，而且安装完必须手动关掉 PowerShell 再重新打开，否则 PATH 不会刷新，claude命令找不到。这个坑我后来查了很多帖子才明白，不是命令装坏了，纯粹是 Windows 的 PATH 缓存机制在作怪。
装好 Claude Code 之后，再来确认 Node.js 环境。Node.js 版的 cc-switch 依赖 npm，所以你需要先保证node -v和npm -v能正常输出版本号。如果发现 npm 命令不可用，大概率是 Node.js 没有正确加到 PATH 里，建议先把这个解决掉再继续。
2.2 两种安装方式实操
Node.js 版的安装命令非常简单，一条npm install -g cc-switch就搞定。全局安装之后，终端里直接输入cc-switch就能进入交互界面。我遇到过一种情况：npm 安装过程没有任何报错，但执行cc-switch时提示找不到命令。这种问题多半是 npm 全局安装目录没有加进 PATH，你可以用npm prefix -g查一下全局目录，把它塞进 PATH 再去试试。
Rust 版的安装，如果你用的是 macOS 并且装了 Homebrew，可以先试一下 brew 安装，没有就按我下面这条路径来。
# 克隆仓库（以 CC Switch 官方/社区仓库为例） git clone https://github.com/farion1231/cc-switch.git cd cc-switch # 如果你习惯用 Cargo 安装二进制方式 cargo install --path .如果编译时间太长，可以给 cargo 配置国内镜像源，提前把依赖拉下来，不然等起来确实磨人。不过说实话，现在 GitHub Release 页面基本都直接提供了编译好的可执行文件，Windows 用户下载.exe，macOS 用户下载对应架构的二进制包，这比本地编译省事太多了。
2.3 配置供应商（Supplier）的手法
进入 cc-switch 主界面后，核心操作就集中在 Supplier 管理这一块。选择 Add 新建一套供应商配置，然后按提示挨个填写字段。这里我重点讲几个容易填错的地方：
name字段，随便起，能认出来就行，比如official-anthropic、local-ollama、company-gateway。注意这个 name 最好只用字母、数字、连字符和下划线，有些版本对中文支持不友好，用中文命名可能导致切换后配置文件解析出错。
api_base_url字段，是问题高发区。Claude Code 对端点后缀非常敏感，官方 API 要填https://api.anthropic.com，一般不需要手动加/v1，因为 Claude Code 内部会自动拼接。但很多第三方兼容网关要求你明确写上/v1后缀，不写就报 404。而且有些自建网关是基于/anthropic或/claude这样的路径做路由的，你必须照着服务商文档写完整路径。我的建议是：填完后先用 curl 手动请求一下这个地址，确认能通，再填进 cc-switch。
api_key字段，官方 key 是sk-ant-开头的一长串；第三方网关的 key 则五花八门，有的直接填 token，有的要求填网关分配的密钥。格式无所谓，但千万别带额外的引号、换行符或空格，这些隐蔽字符会让 HTTP 请求直接 401。
model字段，Claude Code 默认走的是claude-sonnet-4-5或者claude-opus-4-1这类模型名。第三方网关可能要用他们自己的命名，比如claude-3-5-sonnet-20241022或者claude-2，这个字段直接决定请求体里model参数的值。拿不准的时候，先看看 API 文档里给的模型 ID 列表，别凭感觉填。
填完之后保存，cc-switch 会在主界面列出你这套配置。此时按 Activate 激活，它会立刻把这份配置写入 Claude Code 的config.toml。之后再启动 Claude Code，就已经默认使用这套供应商了。
3. 实操过程与核心场景切换
3.1 场景一：官方 API 与第三方网关互切
这个场景应该是最常见的。我平时写代码主要用官方 API，但官方 API 在某些时候并发限制比较严格，为了不影响工作效率，我会切到一个第三方网关去跑一些批量任务。以前全靠手动改config.toml，每次都要经历"打开文件→找到 env 块→改三行→保存→重启"这一套流程。用 cc-switch 之后就简单多了：
- 启动 cc-switch，进入 Supplier 列表。
- 看到两套配置，一套叫
official，一套叫thirdparty-gw。 - 直接方向键选到你想用的那套，回车激活。
- 回到终端，重新运行
claude，用/status查看当前连接的 API base 和模型 ID。
这里有个细节值得注意：cc-switch 在激活新配置之前，会先备份当前的config.toml，备份文件名通常带时间戳。这意味着你可以在任意时刻一键回滚到上一个可用状态。我实测过它的回滚逻辑，非常稳，几乎不会出现改坏配置文件后只能手动恢复的尴尬情况。
另外，如果你是在配置完一套网关后发现 Claude Code 报 404 或者 401，别急着在 cc-switch 里反复切换，先回去检查 api_base_url 是否有/v1后缀、api_key 是否有隐藏字符。同一个报错，原因可能差很多。
3.2 场景二：切换本地 Ollama 模型
这个场景这两年越来越多人在玩，Claude Code 配合 Ollama 跑本地大模型，等于把全部上下文都放在自己电脑上，数据完全本地化。cc-switch 同样可以管理本地 Ollama 端点，无非是在 Supplier 里把 api_base_url 指向http://localhost:11434，api_key 随便填一个占位符，model 填 Ollama 上已经拉下来的模型 ID。
我第一次这么干的时候，遇到了一个非常隐性的问题：Claude Code 算是 Anthropic API 的原生客户端，它的请求协议是为 Anthropic 格式设计的。Ollama 默认提供的却是 OpenAI 兼容协议，两端协议对不上，根本没法直接连通。当时我一度以为是切换工具有 bug，后来才知道需要在 Ollama 和 Claude Code 之间再架一层协议转换，比如用 LiteLLM 启一个本地代理容器，把 OpenAI 协议转成 Anthropic 协议。
cc-switch 在这个场景里的角色是"最后一步的开关"，也就是把 Claude Code 指向http://localhost:4000这样的本地代理地址。你在外面把 LiteLLM 跑起来、模型加载好，cc-switch 负责让 Claude Code 连上这个地址。用这套组合拳，我实现了从云端 API 到本地模型的秒级切换，而且两边互不干扰。
3.3 场景三：多套远程配置协同管理
还有一种使用场景容易被人忽略：同一个开发机需要对应多个开发环境，比如一个项目走公司内网网关，另一个开源项目走公共 API。这在团队协作里非常常见。cc-switch 对这种场景的处理方式，是把每套配置独立管理，切换时只影响 Claude Code 自身，不影响系统环境变量和 Shell profile。
我自己的习惯是，在 cc-switch 里建三套配置：work-gw、personal、local-test。开工之前花 3 秒钟选中work-gw，下班写开源项目就切到personal，想本地验证就选local-test。以前这个流程我用的是手写脚本，现在有了现成的工具，省心多了。
还有一个小细节，cc-switch 也支持在 Git 仓库里做 Provider 级别的自动切换，这个属于进阶功能。如果你经常在多仓库之间切换，可以让 cc-switch 跟随当前仓库目录自动选择合适的供应商配置，省掉了手动切换的心智负担。
4. 常见问题与排查技巧实录
4.1 配置不生效，Claude Code 还是用旧的端点
这个问题在新手群里出现频率最高。明明在 cc-switch 里激活了新配置，进去 Claude Code 一看/status还是旧的 API base。大多数情况下，问题出在缓存上。Claude Code 在启动时会读取一份本地缓存，你需要完全退出进程，再重新进入，才能拿到最新配置。如果是通过 Tmux 或 screen 维护的长驻会话，那重启的意义不大，得先 kill 掉旧进程。
我的排查清单是固定的：先claude --version确认 CLI 正常；然后打开config.toml看ANTHROPIC_BASE_URL的值是否真的被改掉了；最后再重启 Claude Code 看/status。如果config.toml是对的但/status不对，那就要检查进程是不是没杀干净了。
4.2 切换后再也打不开历史对话
我在网上看到有用户反馈过，cc-switch 切换配置后，Codex 的历史对话无法打开，报错内容是model provider \custo...`` 之类。这个问题的本质，通常是切换后的配置里没有正确设置 model 字段，或者自定义 provider 名称里带了非法字符，导致 Claude Code 在反序列化对话记录时无法匹配对应的模型。
面对这种问题，我建议先查一下 Claude Code 的会话存储目录，看看那个报错里提到的 provider 名称是不是和 config.toml 里的某个字段对不上。如果对不上，八成是因为你在 cc-switch 里自定义的 name 太奇怪了，比如包含了点号、中文或空格。把这些特殊字符去掉，重新激活，一般就能解决。
4.3 本地 Ollama 连接失败
本地模型场景下的报错很多，但九成以上都不是 cc-switch 的责任。如果你切换完 Ollama 端点后 Claude Code 一直转圈或者直接 timeout，先用curl http://localhost:11434/api/tags确认 Ollama 服务本身是活的，再确认模型 ID 是否真的存在。如果服务正常、模型存在，那问题基本就是协议转换层没配好，回到 LiteLLM 那边去排查，而不是反复动 cc-switch 的配置。这个排查思路能节省大量时间。
4.4 忘了当前用哪套配置
cc-switch 虽然切换快，但如果你建了五六套配置，过两天再回头可能就忘了当前哪套是活跃的。我在实践中找到一个比较稳的办法：给供应商命名时带上明确的业务含义，比如work-internal-gw-opus、personal-official-kimi、local-ollama-test。这样就算切换后忘了，打开配置文件的注释项也能一眼分辨。另外，cc-switch 的主界面通常会对当前激活的供应商做一些标识（比如高亮或者星标），注意看界面的状态提示就不会乱。
注意：在你切换配置后，最好立刻用
/status看一眼当前连接信息。这一步虽然多花几秒钟，但能避免你在环境错误的状态下启动一大轮 Agent 任务，尤其是批量跑代码任务的时候。
4.5 配置备份与回滚机制
最后说一个我觉得很好用的点：cc-switch 会在每次激活新配置时自动备份旧配置。也就是说，你完全可以把它当成一个"Claude Code 配置文件快照工具"。就算你切错了供应商、配错了 URL，只要切回来点一下恢复，一切都安然无恙。
我自己现在的工作习惯是：每个月定期用 cc-switch 导出一次全部供应商配置，存到一个私有的 Git 仓库里。这样即使换电脑，也可以直接导入配置继续干活，不需要重新输入一大串 API key 和 endpoint。这个操作听起来很简单，但真的能帮你省掉很多重复劳动。
我在实际操作中最大的感受是：cc-switch 这类工具的价值，不在于它有多少炫酷功能，而在于它把你每天都要重复做的那些一秒钟动作压缩到了零操作。以前我可能每天要切换两三次配置，每次花五到十分钟改文件、排查错误；现在十秒钟之内就完成了，而且出错概率几乎为零。如果你也是一个 Claude Code 重度用户，一定要把 cc-switch 装起来试试，配置完的那一瞬间，你会回来感谢我的。
