1. 聊聊为什么要做 cc-switch 这个工具说实话在接触 Claude Code 之前我一直觉得命令行工具配置一次就完事了。直到我同时接了三个项目——一个用官方 Anthropic API一个走公司内部的网关代理还有一个想折腾本地 Ollama 跑开源模型。这时候我才发现Claude Code 这套配置切换是真的能让人崩溃。每换一个项目我都要打开~/.claude/settings.json或者环境变量配置文件手改ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY改完还得重启终端、验证连通性。好几次我都是因为改完配置忘了恢复导致另外一个项目突然报 401 认证失败排查了半天才发现是配置串了。后来我想这种活儿应该是可以自动化的于是开始找现成的工具找来找去发现了 cc-switch。cc-switch 本质上就是一个 Claude Code 的配置管理工具它把不同供应商的 API 配置做成可视化列表点一下就能切换当前生效的配置。它的设计思路跟 IDE 里的多环境配置管理很像只不过它专注在 Claude Code 这一个场景上。解决了什么问题就是让你不再手动去改配置文件不再担心改坏、改乱、改忘。适合谁来用只要你的 Claude Code 需要在多个 API 供应商之间切换无论是官方、第三方代理还是本地模型这工具对你就有价值。这个工具的核心优势在于它把“配置文件编辑”这件事变成了“点选操作”降低出错的概率。而且它不只是改一个文件它会帮你处理好配置的持久化、备份和恢复这几点恰恰是手动操作时最容易被忽略的。如果你还没到多配置切换的需求那你可以先收藏等你的 Claude Code 用得更深入、涉及的项目更多之后你会发现这工具是真的香。2. Claude Code 配置管理的痛点到底在哪要理解 cc-switch 为什么出现你得先理解 Claude Code 配置管理到底烦在哪里。2.1 配置文件分散改起来要命Claude Code 的配置不是集中在一个地方的。有~/.claude/settings.json这种全局配置文件也有项目目录下的.claude/settings.local.json这类局部配置。环境变量也是配置的一部分包括ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL等。问题就出在“分散”上。你想切换一个供应商可能既要改环境变量又要改settings.json里的字段还要确保项目目录的局部配置不会被全局配置覆盖。有些时候你改了全局配置发现项目里的配置优先级更高你的修改根本没生效。这种问题排查起来最浪费时间因为你不知道到底是哪个配置在起作用。还有一个隐藏的坑是配置格式。不同版本的 Claude Code 对配置字段的解析可能不一样旧版本认apiKey新版本可能改成了api_key或者需要套一层env对象。你手动改的时候除非你密切关注更新日志否则很容易踩到格式兼容性的雷。2.2 手动切换操作繁琐容易出错手动切换配置的常规操作大概是这样的打开配置文件确认当前哪个字段是生效的注释掉不用的取消注释要用的保存关闭终端重新打开最后验证连接。这套流程听起来不复杂但实际操作的时候你很容易出现两个问题。第一个问题是遗漏。你改了环境变量忘了改settings.json的文件内容或者反过来。尤其是当配置里既有apiKey又有baseUrl时你必须确保它们匹配的是同一个供应商否则结果就是请求发错地址或者带了错误密钥。第二个问题是“改了但没生效”。Claude Code 在启动时读取配置如果你在启动之后改了配置当前会话里的环境变量是不会自动刷新的。很多人的反应是继续改配置而不是重启会话最后陷入“改了没用-继续改-还是没用”的死循环。这正是搜索引擎里出现一堆“claude code 配置不生效”相关问题的原因。这些痛点的本质是配置管理太依赖人肉操作。人一旦手动去做重复性高、细节多的事情就一定会出错。cc-switch 的存在意义是把这个过程简化成“选一个列表项”同时保证配置的一致性和可回滚性。3. cc-switch 的核心设计思路与整体架构我第一次看到 cc-switch 这个项目的时候第一反应是“这个作者肯定也被配置折磨过”。因为它针对的痛点非常明确整个工具的设计逻辑基本就是一个“配置切换器”没有拖泥带水的功能堆砌。下面我结合实际使用情况拆解一下它的设计思路和核心模块。3.1 供应商配置的抽象与建模cc-switch 的核心抽象是“供应商Provider配置”。每个供应商配置会记录以下最关键的信息供应商名称比如叫“官方”、“DeepSeek”、“Ollama”、API 地址Base URL、API 密钥API Key、默认模型名称Model以及一些可选的扩展字段。这个抽象非常关键。因为 Claude Code 原本的配置里这些参数是分散在环境变量和 JSON 文件里的cc-switch 把它们收纳为一个“配置对象”。你不再需要关心环境变量叫什么名字、配置文件里字段嵌套在哪一层只需要关心“我要连哪个供应商”就行。在数据存储上cc-switch 会把所有供应商配置保存到本地的配置文件中比如~/.cc-switch/config.json。每次切换时它会用当前激活的供应商配置去生成 Claude Code 实际需要的环境变量和配置文件内容。这套设计跟 Docker Compose 的 env 管理思路类似利用一个中间层屏蔽底层差异。3.2 配置写入机制的巧妙之处cc-switch 最核心的机制在于“如何写入配置”。我最初以为它只是简单地改一个 JSON 文件实际上它做了更多——它需要处理两种配置形式环境变量和配置文件。环境变量的处理方式比较直接。cc-switch 会把当前选中的配置转换成环境变量然后写入你的 shell 配置文件比如.bashrc或.zshrc或者直接在当前会话中导出。这里需要注意直接导出只对当前终端生效重启终端就失效了。而写入 shell 配置文件是持久的但需要重新加载才能生效。配置文件部分则稍微复杂一点。cc-switch 需要找到 Claude Code 的配置文件位置一般在~/.claude/settings.json然后修改或生成对应的配置字段。而且它要确保不会覆盖你原有的其他配置项所以会先读取现有文件合并配置后再写回而不是简单粗暴地整体覆盖。还有一个细节值得提cc-switch 在切换配置之前会做一次“当前配置备份”。这是为了防止你切换之后发现新配置不行想恢复到原来的配置却找不到原来的内容。这个细节看起来不起眼但在实际使用中非常救命尤其是当你正在用某个配置跑一些重要任务时。3.3 可视化界面与交互设计cc-switch 提供了图形界面这一点让它比纯命令行工具对普通用户友好得多。界面上是一个供应商列表每个列表项显示名称和当前状态旁边有“切换”按钮或者单选标识。你点击切换工具后台做配置写入然后提示你重启 Claude Code 会话即可生效。它不是简单的把选择结果写进一个独立配置文件就算完事而是会根据你选中的配置生成一份 Claude Code 能够识别的完整配置。这样做的好处非常明显对用户来说切配置变成一次点击对系统来说配置仍然符合 Claude Code 的预期格式不存在“工具自己一套、Claude Code 又一套”的割裂问题。我也用过一些类似的切换工具很多只是把历史命令封装了一下本质还是在“改文件”。cc-switch 的价值在于它真正理解了“配置切换”这个场景你就想换一个供应商别让我去研究环境变量、配置文件路径、字段名这些无关紧要的东西。3.4 多供应商与本地模型的支持cc-switch 不只是面向 Anthropic 官方或第三方代理它也支持本地模型比如 Ollama。这个支持在界面上可能只是多一个供应商配置项但在实际使用中意义很大。本地模型和云端 API 的配置差异不止是 Base URL 不同可能连认证方式都不同。Ollama 这种本地服务一般不需要 API Key或者用一个固定的占位符就行。cc-switch 在供应商配置里允许你留空或填写占位内容然后生成对应的配置这样你就不用为“本地模型要不要填 key”这种问题纠结了。再加上很多人会同时使用 DeepSeek、智谱、Kimi 这类国内模型的 API每个模型的 Base URL 和模型名都不同手动把这些参数管理好确实麻烦。有了 cc-switch 这类工具你需要维护的就只是“一条条清晰的供应商记录”而不是一堆需要记忆的配置值。4. 实操如何安装和使用 cc-switch下面进入正题讲一讲 cc-switch 从下载到日常使用的完整流程。这里我以最常见的桌面端安装为例。4.1 下载与安装cc-switch 的安装包发布在 GitHub Releases 页面你找到对应系统的安装包下载即可。Windows 用户一般是.exe或.msimacOS 用户是.dmg或.zipLinux 用户可能是.AppImage或.deb。下载完成之后按照系统的常规方式安装就行。macOS 用户可能会遇到“无法打开因为无法验证开发者”的提示这是因为应用没有经过 App Store 公证。解决办法是右键点击应用图标选择“打开”然后确认打开即可。安装完成后打开 cc-switch它会检测你当前已有的 Claude Code 配置。如果你是第一次使用界面会是空白的供应商列表需要手动添加。如果你之前配置过 Claude Code它也会尝试读取已有的配置信息作为默认展示。4.2 添加一个供应商配置添加供应商配置的入口一般是一个“新增”按钮。点击之后你需要填写这些字段字段说明示例名称这个配置的显示名称自己识别用的官方API、DeepSeek、OllamaAPI 地址接口的 Base URLhttps://api.anthropic.comAPI 密钥认证密钥本地模型可不填sk-ant-xxx模型名称默认使用的模型claude-sonnet-4-20250514这是我整理的最核心映射关系建议你按照这四类信息去整理手头的供应商参数。很多人第一次看到“API 地址”和“模型名称”不知道该填什么其实只要去看你买的服务商提供的文档就行。以 Ollama 为例API 地址一般是http://localhost:11434模型名称要填你本地拉取的具体模型名比如qwen2.5-coder:32bAPI 密钥可以留空。以 DeepSeek 为例API 地址是https://api.deepseek.com模型名称填deepseek-chatAPI 密钥填你在 DeepSeek 开放平台申请的 key。添加完成之后保存列表里就会多出一条配置。4.3 切换配置的正确姿势切换配置很简单选中你想要的供应商配置点击“切换”或者“启用”按钮。工具会提示你配置已经写入需要重启 Claude Code 才能生效。这里要强调一个关键点切换之后务必完全退出 Claude Code 的当前会话包括相关终端进程再重新启动。不要只关掉窗口就重开因为有些系统上进程还驻留在后台环境变量没有刷新你会误以为配置没生效。如果是用 VS Code 里集成的 Claude Code 插件也要重载窗口CtrlShiftP然后输入Reload Window才能确保新的环境变量被加载。这个问题我在实际使用中踩过几次坑后来养成了“切换之后必然全重启”的习惯基本没再出过配置不生效的问题。4.4 备份与恢复配置的细节cc-switch 在切换时是会自动备份当前配置的这一点你可以在它的配置目录中看得到。备份文件的命名一般会带上时间戳方便你回溯到指定时间的配置。万一你切换之后发现新配置完全不可用比如 API 地址填错、密钥失效你需要做的是回到 cc-switch选择之前的配置再切换回去。如果你是个喜欢手动折腾的人也可以直接打开备份文件把内容复制回原配置文件。我个人建议是养成定期导出一份 cc-switch 配置的习惯。备份的成本很低但如果你哪一天不小心删除了配置目录又记不清当初填的参数那真的只能欲哭无泪了。5. 常见问题与排查技巧实录我在使用 cc-switch 以及搜索相关热词时看到不少人遇到的问题都很有共性。这里整理几个典型场景以及对应的排查思路。5.1 切换了别的模型后选择列表里看不到新模型这个问题的表述是“cc-switch 切换了别的模型后选择模型里面还是看不到别的模型”。说实话这不是 cc-switch 的问题而是你对模型名称的理解有偏差。cc-switch 只负责切换“供应商配置”它会把模型名称写入配置让 Claude Code 启动时使用你指定的模型。但是在 Claude Code 的交互界面里如果你通过命令切换模型它通常只会列出当前供应商支持的模型而这些模型列表不是从 cc-switch 读取的是 Claude Code 自身从当前 API 的模型列表接口获取的。也就是说如果你切到了 OllamaClaude Code 当前连到的是本地 Ollama它能列举的模型只能来自 Ollama 的本地列表。如果你在 Ollama 里没拉取某个模型那 Claude Code 当然看不到。排查思路是确认 cc-switch 里的模型名称和实际存在的模型名称一致确认你已经完全重启了 Claude Code确认你在 Claude Code 里切换模型时选的是正确的供应商路径。5.2 切换配置导致 Codex 历史对话无法打开还有用户反馈“cc-switch 导致 codex 历史对话无法打开请修复 config.toml: model providercusto”。这个问题看起来吓人其实原因不复杂。Codex CLI 和 Claude Code 虽然都是命令行 AI 工具但它们的配置机制并不相同。cc-switch 不管理 Codex 的配置但它可能间接影响了环境变量或者公共配置目录里的某些文件。如果你遇到了这个问题排查步骤建议这样走先去查看 Codex 的配置文件一般路径是~/.codex/config.toml确认里面的model_provider字段是否完整再检查环境变量里是否有多余的ANTHROPIC_BASE_URL或ANTHROPIC_MODEL指向了当前正在使用的供应商最后检查 cc-switch 的切换操作是否在系统层面修改了你 shell 的公共配置。这种问题的出现本质上是因为多个工具共用了一套环境变量。cc-switch 本身没有直接改 Codex 的配置但它写入环境变量的行为影响了 Codex。了解了这一点你就知道排查方向了一切以环境变量的实际值为准不要只看具体某个工具的配置文件。5.3 提示“your organization has disabled claude subscription access”这个提示的意思是你所在的组织账号没有开启 Claude 订阅访问权限。这个和 cc-switch 完全无关纯粹是账号权限问题。遇到这个提示你要检查的是你登录 Claude Code 时用的是个人账号还是组织账号如果是组织账号是否在管理后台开启了 Claude Code 的使用权限你配置的 API Key 对应的组织是否有相应权限。cc-switch 只是把你填的 Key 传给 Claude Code它并不能绕过任何账号权限限制。5.4 切换之后原配置丢失如何找回这种情况通常是误操作导致。cc-switch 在切换时会备份当前配置但如果你自己手动删除了一些文件或者使用了“清理”功能配置可能就找不回来了。找回的思路有两个。第一个是从 cc-switch 的备份目录找看有没有自动生成的备份文件。第二个是从 Claude Code 自己的缓存或历史配置中找看~/.claude目录下有没有残留的配置片段。如果两者都没有那就只能靠你手动重新添加了。所以我强烈建议不要把配置的唯一副本放在 cc-switch 里至少在刚使用 cc-switch 的时候把你原来的手工配置完整保留在一个安全的位置。6. 扩展场景cc-switch 如何与本地大模型结合最近很多人在折腾“claude code cc switch ollama”的组合我现在也在用这套方案效果还不错这里分享一些我的实际体会。6.1 为什么要在 Claude Code 里用 OllamaClaude Code 默认连接的是 Anthropic 官方 API好处是模型能力强、响应稳定但代价是需要付费而且有些区域访问不太方便。如果你只是想在本地跑一些代码补全、简单问答或者实验性任务接一个本地大模型是性价比很高的选择。Ollama 是目前比较流行的本地模型运行工具安装简单支持的模型也不少比如 Qwen 系列、Llama 系列、DeepSeek 系列。它可以在本地起一个 API 服务地址是http://localhost:11434。通过 cc-switch你可以在“官方 API”和“Ollama 本地模型”之间一键切换。比如白天在公司用官方 API 跑正式任务晚上回家想省点额度切到 Ollama 用本地模型继续玩完全不需要改任何配置文件。6.2 配置 Ollama 到 cc-switch 的操作具体操作其实并不复杂。在 cc-switch 里新增一个供应商配置名称填OllamaAPI 地址填http://localhost:11434API 密钥留空模型名称填你本地的模型名。这里的模型名称比较关键很多人会填成llama3:8b或者qwen2.5:7b但实际上你首先要确认本地 Ollama 已经拉取了这个模型。你可以在终端里跑一句命令查看ollama list输出里会有模型名列表比如qwen2.5-coder:32b。把这个名字原样填到 cc-switch 的模型名称字段里就行。配置完成后切换到这个 Ollama 配置重启 Claude Code然后你在使用过程中就能感受到和官方 API 的差异了——响应速度跟你的机器性能直接相关模型能力上限也比较明显但本地部署的灵活性和零成本是真实存在的。6.3 本地模型使用中的注意事项用 Ollama 接 Claude Code 有几个体验上的问题需要提前有心理准备。第一个是上下文长度限制。本地模型能处理的上下文窗口通常没有官方模型那么大你粘贴一大段代码进去模型可能只能关注到前半段。第二个是并发能力差。官方 API 可以同时处理多个请求本地模型在单块 GPU 或 CPU 上跑并发能力非常有限追加问几个问题就会出现明显的排队延迟。第三个是代码能力上限。虽然 Qwen 系列、DeepSeek 系列在代码任务上表现不错但比起顶级的 Claude 系列还是有差距你要在“免费”和“效果”之间做权衡。对于只是想低成本试试 Claude Code 工作流的人来说cc-switch Ollama 是一条值得走的路。对于追求极致代码质量的场景我还是建议用官方模型或旗舰级第三方 API。7. 关于配置切换工具选型的个人经验前面说了这么多最后我想从个人使用经验的角度聊聊什么时候该用 cc-switch、什么时候不建议用。7.1 什么样的用户适合 cc-switch如果你符合下面这几条里的任意一条cc-switch 就值得一试你需要同时管理两个以上的 Claude Code 供应商配置。你经常在“AI 服务”和“本地模型”之间切换使用。你之前的配置串位过、失效过、找不到过不想再手动折腾这些事。7.2 什么样的用户不建议现在用如果你是 Claude Code 的新手连基本配置、API Key 申请、环境变量设置都还不太熟悉那我不建议你立刻上 cc-switch。原因很简单工具的抽象会让你跳过“理解配置”的过程一旦出现问题你反而更难排查。先用原生方式跑通一次官方配置再切换到 cc-switch这样遇到问题的时候你才知道它底层到底做了什么。7.3 多工具共存时的环境变量管理建议现在不少人的电脑上同时装了 Claude Code、Codex CLI、其他 AI 插件这些工具的环境变量会有冲突风险。cc-switch 的切换操作会影响 shell 的环境变量如果多个工具共用同一套变量名就可能导致一个工具正常而另一个报错。我的建议是尽量让 Claude Code 这类工具的配置通过各自的配置文件管理而不是依赖全局环境变量。如果 cc-switch 在切换时写入的是 shell 配置那你就要注意切换后可能影响其他工具的全局行为。遇到这种问题时先检查环境变量的实际值再判断是谁改动了它。8. 最后一个实用技巧手动管理配置的备选方案cc-switch 解决得很好的场景是多供应商切换但如果你只是临时想用一个不同的模型、不想安装任何额外工具我也可以提供一个纯手动的备选思路。你可以为不同的供应商各准备一个独立的配置文件比如settings-official.json、settings-deepseek.json、settings-ollama.json。平时把它们放在一个专门的目录里比如~/.claude-profiles/。每次要切换的时候只需要复制一个文件到 Claude Code 的配置目录再重新启动即可。具体命令类似cp ~/.claude-profiles/deepseek.json ~/.claude/settings.json这个方案比 cc-switch 原生的配置切换要原始但它有一个好处你能清楚地知道当前生效的配置是什么出了问题也能快速检查。对于只在少数配置文件之间切换、而且切换频率不高的用户这个方案可能比安装工具还简单。我自己是这么做的日常使用 cc-switch 来管理复杂的场景但手头永远保留一份纯手动的配置文件作为兜底。这套“工具为主、手动兜底”的组合拳让我在配置管理这件事上基本没遇到过无法解决的难题。你可以根据自己的使用频率和风险偏好选择适合自己的方式。 cc-switch：Claude Code 多供应商配置一键切换指南
1. 聊聊为什么要做 cc-switch 这个工具说实话在接触 Claude Code 之前我一直觉得命令行工具配置一次就完事了。直到我同时接了三个项目——一个用官方 Anthropic API一个走公司内部的网关代理还有一个想折腾本地 Ollama 跑开源模型。这时候我才发现Claude Code 这套配置切换是真的能让人崩溃。每换一个项目我都要打开~/.claude/settings.json或者环境变量配置文件手改ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY改完还得重启终端、验证连通性。好几次我都是因为改完配置忘了恢复导致另外一个项目突然报 401 认证失败排查了半天才发现是配置串了。后来我想这种活儿应该是可以自动化的于是开始找现成的工具找来找去发现了 cc-switch。cc-switch 本质上就是一个 Claude Code 的配置管理工具它把不同供应商的 API 配置做成可视化列表点一下就能切换当前生效的配置。它的设计思路跟 IDE 里的多环境配置管理很像只不过它专注在 Claude Code 这一个场景上。解决了什么问题就是让你不再手动去改配置文件不再担心改坏、改乱、改忘。适合谁来用只要你的 Claude Code 需要在多个 API 供应商之间切换无论是官方、第三方代理还是本地模型这工具对你就有价值。这个工具的核心优势在于它把“配置文件编辑”这件事变成了“点选操作”降低出错的概率。而且它不只是改一个文件它会帮你处理好配置的持久化、备份和恢复这几点恰恰是手动操作时最容易被忽略的。如果你还没到多配置切换的需求那你可以先收藏等你的 Claude Code 用得更深入、涉及的项目更多之后你会发现这工具是真的香。2. Claude Code 配置管理的痛点到底在哪要理解 cc-switch 为什么出现你得先理解 Claude Code 配置管理到底烦在哪里。2.1 配置文件分散改起来要命Claude Code 的配置不是集中在一个地方的。有~/.claude/settings.json这种全局配置文件也有项目目录下的.claude/settings.local.json这类局部配置。环境变量也是配置的一部分包括ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL等。问题就出在“分散”上。你想切换一个供应商可能既要改环境变量又要改settings.json里的字段还要确保项目目录的局部配置不会被全局配置覆盖。有些时候你改了全局配置发现项目里的配置优先级更高你的修改根本没生效。这种问题排查起来最浪费时间因为你不知道到底是哪个配置在起作用。还有一个隐藏的坑是配置格式。不同版本的 Claude Code 对配置字段的解析可能不一样旧版本认apiKey新版本可能改成了api_key或者需要套一层env对象。你手动改的时候除非你密切关注更新日志否则很容易踩到格式兼容性的雷。2.2 手动切换操作繁琐容易出错手动切换配置的常规操作大概是这样的打开配置文件确认当前哪个字段是生效的注释掉不用的取消注释要用的保存关闭终端重新打开最后验证连接。这套流程听起来不复杂但实际操作的时候你很容易出现两个问题。第一个问题是遗漏。你改了环境变量忘了改settings.json的文件内容或者反过来。尤其是当配置里既有apiKey又有baseUrl时你必须确保它们匹配的是同一个供应商否则结果就是请求发错地址或者带了错误密钥。第二个问题是“改了但没生效”。Claude Code 在启动时读取配置如果你在启动之后改了配置当前会话里的环境变量是不会自动刷新的。很多人的反应是继续改配置而不是重启会话最后陷入“改了没用-继续改-还是没用”的死循环。这正是搜索引擎里出现一堆“claude code 配置不生效”相关问题的原因。这些痛点的本质是配置管理太依赖人肉操作。人一旦手动去做重复性高、细节多的事情就一定会出错。cc-switch 的存在意义是把这个过程简化成“选一个列表项”同时保证配置的一致性和可回滚性。3. cc-switch 的核心设计思路与整体架构我第一次看到 cc-switch 这个项目的时候第一反应是“这个作者肯定也被配置折磨过”。因为它针对的痛点非常明确整个工具的设计逻辑基本就是一个“配置切换器”没有拖泥带水的功能堆砌。下面我结合实际使用情况拆解一下它的设计思路和核心模块。3.1 供应商配置的抽象与建模cc-switch 的核心抽象是“供应商Provider配置”。每个供应商配置会记录以下最关键的信息供应商名称比如叫“官方”、“DeepSeek”、“Ollama”、API 地址Base URL、API 密钥API Key、默认模型名称Model以及一些可选的扩展字段。这个抽象非常关键。因为 Claude Code 原本的配置里这些参数是分散在环境变量和 JSON 文件里的cc-switch 把它们收纳为一个“配置对象”。你不再需要关心环境变量叫什么名字、配置文件里字段嵌套在哪一层只需要关心“我要连哪个供应商”就行。在数据存储上cc-switch 会把所有供应商配置保存到本地的配置文件中比如~/.cc-switch/config.json。每次切换时它会用当前激活的供应商配置去生成 Claude Code 实际需要的环境变量和配置文件内容。这套设计跟 Docker Compose 的 env 管理思路类似利用一个中间层屏蔽底层差异。3.2 配置写入机制的巧妙之处cc-switch 最核心的机制在于“如何写入配置”。我最初以为它只是简单地改一个 JSON 文件实际上它做了更多——它需要处理两种配置形式环境变量和配置文件。环境变量的处理方式比较直接。cc-switch 会把当前选中的配置转换成环境变量然后写入你的 shell 配置文件比如.bashrc或.zshrc或者直接在当前会话中导出。这里需要注意直接导出只对当前终端生效重启终端就失效了。而写入 shell 配置文件是持久的但需要重新加载才能生效。配置文件部分则稍微复杂一点。cc-switch 需要找到 Claude Code 的配置文件位置一般在~/.claude/settings.json然后修改或生成对应的配置字段。而且它要确保不会覆盖你原有的其他配置项所以会先读取现有文件合并配置后再写回而不是简单粗暴地整体覆盖。还有一个细节值得提cc-switch 在切换配置之前会做一次“当前配置备份”。这是为了防止你切换之后发现新配置不行想恢复到原来的配置却找不到原来的内容。这个细节看起来不起眼但在实际使用中非常救命尤其是当你正在用某个配置跑一些重要任务时。3.3 可视化界面与交互设计cc-switch 提供了图形界面这一点让它比纯命令行工具对普通用户友好得多。界面上是一个供应商列表每个列表项显示名称和当前状态旁边有“切换”按钮或者单选标识。你点击切换工具后台做配置写入然后提示你重启 Claude Code 会话即可生效。它不是简单的把选择结果写进一个独立配置文件就算完事而是会根据你选中的配置生成一份 Claude Code 能够识别的完整配置。这样做的好处非常明显对用户来说切配置变成一次点击对系统来说配置仍然符合 Claude Code 的预期格式不存在“工具自己一套、Claude Code 又一套”的割裂问题。我也用过一些类似的切换工具很多只是把历史命令封装了一下本质还是在“改文件”。cc-switch 的价值在于它真正理解了“配置切换”这个场景你就想换一个供应商别让我去研究环境变量、配置文件路径、字段名这些无关紧要的东西。3.4 多供应商与本地模型的支持cc-switch 不只是面向 Anthropic 官方或第三方代理它也支持本地模型比如 Ollama。这个支持在界面上可能只是多一个供应商配置项但在实际使用中意义很大。本地模型和云端 API 的配置差异不止是 Base URL 不同可能连认证方式都不同。Ollama 这种本地服务一般不需要 API Key或者用一个固定的占位符就行。cc-switch 在供应商配置里允许你留空或填写占位内容然后生成对应的配置这样你就不用为“本地模型要不要填 key”这种问题纠结了。再加上很多人会同时使用 DeepSeek、智谱、Kimi 这类国内模型的 API每个模型的 Base URL 和模型名都不同手动把这些参数管理好确实麻烦。有了 cc-switch 这类工具你需要维护的就只是“一条条清晰的供应商记录”而不是一堆需要记忆的配置值。4. 实操如何安装和使用 cc-switch下面进入正题讲一讲 cc-switch 从下载到日常使用的完整流程。这里我以最常见的桌面端安装为例。4.1 下载与安装cc-switch 的安装包发布在 GitHub Releases 页面你找到对应系统的安装包下载即可。Windows 用户一般是.exe或.msimacOS 用户是.dmg或.zipLinux 用户可能是.AppImage或.deb。下载完成之后按照系统的常规方式安装就行。macOS 用户可能会遇到“无法打开因为无法验证开发者”的提示这是因为应用没有经过 App Store 公证。解决办法是右键点击应用图标选择“打开”然后确认打开即可。安装完成后打开 cc-switch它会检测你当前已有的 Claude Code 配置。如果你是第一次使用界面会是空白的供应商列表需要手动添加。如果你之前配置过 Claude Code它也会尝试读取已有的配置信息作为默认展示。4.2 添加一个供应商配置添加供应商配置的入口一般是一个“新增”按钮。点击之后你需要填写这些字段字段说明示例名称这个配置的显示名称自己识别用的官方API、DeepSeek、OllamaAPI 地址接口的 Base URLhttps://api.anthropic.comAPI 密钥认证密钥本地模型可不填sk-ant-xxx模型名称默认使用的模型claude-sonnet-4-20250514这是我整理的最核心映射关系建议你按照这四类信息去整理手头的供应商参数。很多人第一次看到“API 地址”和“模型名称”不知道该填什么其实只要去看你买的服务商提供的文档就行。以 Ollama 为例API 地址一般是http://localhost:11434模型名称要填你本地拉取的具体模型名比如qwen2.5-coder:32bAPI 密钥可以留空。以 DeepSeek 为例API 地址是https://api.deepseek.com模型名称填deepseek-chatAPI 密钥填你在 DeepSeek 开放平台申请的 key。添加完成之后保存列表里就会多出一条配置。4.3 切换配置的正确姿势切换配置很简单选中你想要的供应商配置点击“切换”或者“启用”按钮。工具会提示你配置已经写入需要重启 Claude Code 才能生效。这里要强调一个关键点切换之后务必完全退出 Claude Code 的当前会话包括相关终端进程再重新启动。不要只关掉窗口就重开因为有些系统上进程还驻留在后台环境变量没有刷新你会误以为配置没生效。如果是用 VS Code 里集成的 Claude Code 插件也要重载窗口CtrlShiftP然后输入Reload Window才能确保新的环境变量被加载。这个问题我在实际使用中踩过几次坑后来养成了“切换之后必然全重启”的习惯基本没再出过配置不生效的问题。4.4 备份与恢复配置的细节cc-switch 在切换时是会自动备份当前配置的这一点你可以在它的配置目录中看得到。备份文件的命名一般会带上时间戳方便你回溯到指定时间的配置。万一你切换之后发现新配置完全不可用比如 API 地址填错、密钥失效你需要做的是回到 cc-switch选择之前的配置再切换回去。如果你是个喜欢手动折腾的人也可以直接打开备份文件把内容复制回原配置文件。我个人建议是养成定期导出一份 cc-switch 配置的习惯。备份的成本很低但如果你哪一天不小心删除了配置目录又记不清当初填的参数那真的只能欲哭无泪了。5. 常见问题与排查技巧实录我在使用 cc-switch 以及搜索相关热词时看到不少人遇到的问题都很有共性。这里整理几个典型场景以及对应的排查思路。5.1 切换了别的模型后选择列表里看不到新模型这个问题的表述是“cc-switch 切换了别的模型后选择模型里面还是看不到别的模型”。说实话这不是 cc-switch 的问题而是你对模型名称的理解有偏差。cc-switch 只负责切换“供应商配置”它会把模型名称写入配置让 Claude Code 启动时使用你指定的模型。但是在 Claude Code 的交互界面里如果你通过命令切换模型它通常只会列出当前供应商支持的模型而这些模型列表不是从 cc-switch 读取的是 Claude Code 自身从当前 API 的模型列表接口获取的。也就是说如果你切到了 OllamaClaude Code 当前连到的是本地 Ollama它能列举的模型只能来自 Ollama 的本地列表。如果你在 Ollama 里没拉取某个模型那 Claude Code 当然看不到。排查思路是确认 cc-switch 里的模型名称和实际存在的模型名称一致确认你已经完全重启了 Claude Code确认你在 Claude Code 里切换模型时选的是正确的供应商路径。5.2 切换配置导致 Codex 历史对话无法打开还有用户反馈“cc-switch 导致 codex 历史对话无法打开请修复 config.toml: model providercusto”。这个问题看起来吓人其实原因不复杂。Codex CLI 和 Claude Code 虽然都是命令行 AI 工具但它们的配置机制并不相同。cc-switch 不管理 Codex 的配置但它可能间接影响了环境变量或者公共配置目录里的某些文件。如果你遇到了这个问题排查步骤建议这样走先去查看 Codex 的配置文件一般路径是~/.codex/config.toml确认里面的model_provider字段是否完整再检查环境变量里是否有多余的ANTHROPIC_BASE_URL或ANTHROPIC_MODEL指向了当前正在使用的供应商最后检查 cc-switch 的切换操作是否在系统层面修改了你 shell 的公共配置。这种问题的出现本质上是因为多个工具共用了一套环境变量。cc-switch 本身没有直接改 Codex 的配置但它写入环境变量的行为影响了 Codex。了解了这一点你就知道排查方向了一切以环境变量的实际值为准不要只看具体某个工具的配置文件。5.3 提示“your organization has disabled claude subscription access”这个提示的意思是你所在的组织账号没有开启 Claude 订阅访问权限。这个和 cc-switch 完全无关纯粹是账号权限问题。遇到这个提示你要检查的是你登录 Claude Code 时用的是个人账号还是组织账号如果是组织账号是否在管理后台开启了 Claude Code 的使用权限你配置的 API Key 对应的组织是否有相应权限。cc-switch 只是把你填的 Key 传给 Claude Code它并不能绕过任何账号权限限制。5.4 切换之后原配置丢失如何找回这种情况通常是误操作导致。cc-switch 在切换时会备份当前配置但如果你自己手动删除了一些文件或者使用了“清理”功能配置可能就找不回来了。找回的思路有两个。第一个是从 cc-switch 的备份目录找看有没有自动生成的备份文件。第二个是从 Claude Code 自己的缓存或历史配置中找看~/.claude目录下有没有残留的配置片段。如果两者都没有那就只能靠你手动重新添加了。所以我强烈建议不要把配置的唯一副本放在 cc-switch 里至少在刚使用 cc-switch 的时候把你原来的手工配置完整保留在一个安全的位置。6. 扩展场景cc-switch 如何与本地大模型结合最近很多人在折腾“claude code cc switch ollama”的组合我现在也在用这套方案效果还不错这里分享一些我的实际体会。6.1 为什么要在 Claude Code 里用 OllamaClaude Code 默认连接的是 Anthropic 官方 API好处是模型能力强、响应稳定但代价是需要付费而且有些区域访问不太方便。如果你只是想在本地跑一些代码补全、简单问答或者实验性任务接一个本地大模型是性价比很高的选择。Ollama 是目前比较流行的本地模型运行工具安装简单支持的模型也不少比如 Qwen 系列、Llama 系列、DeepSeek 系列。它可以在本地起一个 API 服务地址是http://localhost:11434。通过 cc-switch你可以在“官方 API”和“Ollama 本地模型”之间一键切换。比如白天在公司用官方 API 跑正式任务晚上回家想省点额度切到 Ollama 用本地模型继续玩完全不需要改任何配置文件。6.2 配置 Ollama 到 cc-switch 的操作具体操作其实并不复杂。在 cc-switch 里新增一个供应商配置名称填OllamaAPI 地址填http://localhost:11434API 密钥留空模型名称填你本地的模型名。这里的模型名称比较关键很多人会填成llama3:8b或者qwen2.5:7b但实际上你首先要确认本地 Ollama 已经拉取了这个模型。你可以在终端里跑一句命令查看ollama list输出里会有模型名列表比如qwen2.5-coder:32b。把这个名字原样填到 cc-switch 的模型名称字段里就行。配置完成后切换到这个 Ollama 配置重启 Claude Code然后你在使用过程中就能感受到和官方 API 的差异了——响应速度跟你的机器性能直接相关模型能力上限也比较明显但本地部署的灵活性和零成本是真实存在的。6.3 本地模型使用中的注意事项用 Ollama 接 Claude Code 有几个体验上的问题需要提前有心理准备。第一个是上下文长度限制。本地模型能处理的上下文窗口通常没有官方模型那么大你粘贴一大段代码进去模型可能只能关注到前半段。第二个是并发能力差。官方 API 可以同时处理多个请求本地模型在单块 GPU 或 CPU 上跑并发能力非常有限追加问几个问题就会出现明显的排队延迟。第三个是代码能力上限。虽然 Qwen 系列、DeepSeek 系列在代码任务上表现不错但比起顶级的 Claude 系列还是有差距你要在“免费”和“效果”之间做权衡。对于只是想低成本试试 Claude Code 工作流的人来说cc-switch Ollama 是一条值得走的路。对于追求极致代码质量的场景我还是建议用官方模型或旗舰级第三方 API。7. 关于配置切换工具选型的个人经验前面说了这么多最后我想从个人使用经验的角度聊聊什么时候该用 cc-switch、什么时候不建议用。7.1 什么样的用户适合 cc-switch如果你符合下面这几条里的任意一条cc-switch 就值得一试你需要同时管理两个以上的 Claude Code 供应商配置。你经常在“AI 服务”和“本地模型”之间切换使用。你之前的配置串位过、失效过、找不到过不想再手动折腾这些事。7.2 什么样的用户不建议现在用如果你是 Claude Code 的新手连基本配置、API Key 申请、环境变量设置都还不太熟悉那我不建议你立刻上 cc-switch。原因很简单工具的抽象会让你跳过“理解配置”的过程一旦出现问题你反而更难排查。先用原生方式跑通一次官方配置再切换到 cc-switch这样遇到问题的时候你才知道它底层到底做了什么。7.3 多工具共存时的环境变量管理建议现在不少人的电脑上同时装了 Claude Code、Codex CLI、其他 AI 插件这些工具的环境变量会有冲突风险。cc-switch 的切换操作会影响 shell 的环境变量如果多个工具共用同一套变量名就可能导致一个工具正常而另一个报错。我的建议是尽量让 Claude Code 这类工具的配置通过各自的配置文件管理而不是依赖全局环境变量。如果 cc-switch 在切换时写入的是 shell 配置那你就要注意切换后可能影响其他工具的全局行为。遇到这种问题时先检查环境变量的实际值再判断是谁改动了它。8. 最后一个实用技巧手动管理配置的备选方案cc-switch 解决得很好的场景是多供应商切换但如果你只是临时想用一个不同的模型、不想安装任何额外工具我也可以提供一个纯手动的备选思路。你可以为不同的供应商各准备一个独立的配置文件比如settings-official.json、settings-deepseek.json、settings-ollama.json。平时把它们放在一个专门的目录里比如~/.claude-profiles/。每次要切换的时候只需要复制一个文件到 Claude Code 的配置目录再重新启动即可。具体命令类似cp ~/.claude-profiles/deepseek.json ~/.claude/settings.json这个方案比 cc-switch 原生的配置切换要原始但它有一个好处你能清楚地知道当前生效的配置是什么出了问题也能快速检查。对于只在少数配置文件之间切换、而且切换频率不高的用户这个方案可能比安装工具还简单。我自己是这么做的日常使用 cc-switch 来管理复杂的场景但手头永远保留一份纯手动的配置文件作为兜底。这套“工具为主、手动兜底”的组合拳让我在配置管理这件事上基本没遇到过无法解决的难题。你可以根据自己的使用频率和风险偏好选择适合自己的方式。