最近在折腾 Claude Code 的时候发现身边不少朋友还在手动改settings.json来切换模型文件改得乱七八糟换一次模型要翻半天文档稍不留神就把生产环境的配置给覆盖了。其实社区早就有了一个叫CC Switch的开源命令行工具专门解决“把自定义模型接进 Claude Code”这件事。它做的事情很简单用交互式界面帮你管理多套模型配置一键切换不用再碰配置文件。这篇文章我会从配置痛点讲起把 CC Switch 的安装、目录结构、核心命令、自定义模型接入的完整流程全部拆开讲最后附上我实际使用中踩过的坑。无论你是刚开始接触 Claude Code 的新手还是已经在多模型之间来回切换的老手这份实操笔记应该都能帮到你。1. 为什么要用 CC Switch手改配置到底有多痛1.1 官方配置的限制和日常痛点Claude Code 默认情况下只认官方接口也就是你必须在环境变量里配置好官方 API Key它才愿意干活。而要把自定义模型接进去核心手段就是设置几个环境变量ANTHROPIC_BASE_URL指向你的模型网关地址ANTHROPIC_AUTH_TOKEN填你的 API KeyANTHROPIC_MODEL指定模型名称。听起来挺简单问题是一旦你同时有几个模型源要切换事情就开始失控了。比如你本地跑了一个基于开源模型的推理服务想拿 Claude Code 当终端来用公司内部又有一个统一网关接了商业大模型个人开发机上还有一套走第三方兼容接口的配置。这三个场景的 base URL、token、模型名全都不一样。你总不能每次使用前都去编辑~/.claude/settings.json把env里的字段改一遍吧实际手改配置的痛点非常具体每次切换至少要改三四个字段漏改一个就报错而且报错信息不一定能直接指向问题根源你根本分不清是 URL 写错还是 token 失效。配置没有版本概念改坏了想回退只能靠记忆或备份文件体验极差。同时有全局配置和项目级配置时优先级互相覆盖排查起来极其痛苦。团队协作时因为缺少统一配置管理每个人机器上的配置都不一样。你在这个机器上能跑通的命令到同事那边就变成connection error。1.2 CC Switch 是什么它解决了哪一类问题CC Switch 的本质是一个配置切换器它把你所有模型提供方的配置集中存放在自己的配置文件里然后在需要的时候把选中的配置写入 Claude Code 实际读取的位置。换句话说它把“编辑配置文件”这个动作替换成了“选择配置项”这个动作。你只需要在终端里执行一个命令在弹出的交互界面里选择要用哪套模型它就自动帮你把ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、模型名等参数写入 Claude Code 的配置文件。你根本不需要关心文件具体长什么样。它的工作方式可以类比成一个“遥控器”每个模型提供方就是一台电视CC Switch 帮你把频道记忆好按一下就能切台而不是每次都要蹲在电视背后手动拧旋钮。1.3 适用人群和典型场景结合我自己和周围同行的使用情况CC Switch 特别适合这几类人经常在不同大模型 API 之间切换的开发者比如白天用商业模型写代码晚上用本地私有模型做测试。接了多个第三方模型网关的团队需要统一维护一套模型配置避免每个人各自维护一套互相打架的 settings.json。需要把 Claude Code 接入内部模型服务的公司用户通过 CC Switch 可以快速在官方模型和内部模型之间切换不干扰已有配置。喜欢折腾终端工具链的人。它本身就是命令行交互式界面和 Claude Code 的使用习惯一致没有额外的学习成本。2. 工欲善其事安装、目录与核心概念2.1 安装 CC Switch 的几种方式CC Switch 是开源项目安装方式很灵活主流有三种。方式一Homebrew 安装如果你用的是 macOS 或 Linux并且装了 Homebrew直接执行brew install cc-switch这条命令会自动下载预编译的二进制文件并放到 PATH 里之后直接执行cc-switch就能启动。方式二安装脚本项目文档里提供了一键安装脚本适合不想用 Homebrew 或者想装最新版的人curl -fsSL https://example.com/install.sh | bash提示执行任何从网络下载的安装脚本前建议先打开脚本看一眼内容确认没有做额外动作。这是基本的安全习惯跟工具本身无关。方式三源码构建如果你喜欢自己动手或者想改点源码可以克隆仓库后用构建命令编译。这种方式适合要对工具二次开发的用户git clone https://example.com/cc-switch.git cd cc-switch go build -o cc-switch ./cmd/cc-switch我个人的建议是平时用只要装 Homebrew 版本就够源码构建除非有特殊需求否则没必要折腾。2.2 配置目录结构搞清楚状态实际存在哪里刚开始用 CC Switch 的时候我对它的“配置层级”犯过迷糊。它实际上涉及两个不同的配置目录先搞清楚这一点后面所有操作都顺了。第一个目录是 CC Switch 自己的数据目录默认在~/.cc-switch/。里面最重要的文件是config.json记录了你添加过的所有模型提供方。大致结构长这样{ providers: [ { name: local-model, baseURL: http://127.0.0.1:8080, apiKey: local-key-not-required, models: [qwen2.5-coder:7b] }, { name: company-gateway, baseURL: https://api.example.com/v1, apiKey: sk-xxxxxxxx, models: [claude-sonnet-default] } ], current: company-gateway }第二个目录是 Claude Code 自己的配置目录默认在~/.claude/其中settings.json是 CC Switch 真正写入的目标文件。你执行切换后CC Switch 会把选中 provider 的环境变量写进这个文件的env字段。注意Claude Code 还支持项目级的.claude/settings.json它会覆盖全局配置。如果你在某个项目里也配了env那切换可能看起来“没生效”后面我会专门讲这个问题。这两套文件的关系是~/.cc-switch/config.json是“源”~/.claude/settings.json是“目标”。CC Switch 做的事就是把源里的某一条配置同步成目标里的当前配置。2.3 核心命令速览CC Switch 的命令不多来回就那么几个练一遍就能记住命令作用cc-switch直接启动交互式 TUI 界面用方向键选择 provider 并回车切换cc-switch list列出所有已配置的 provider标注当前使用哪一个cc-switch use provider名非交互式切换适合写进脚本cc-switch add添加新的 provider 配置可以交互输入或指定参数cc-switch delete provider名删除某个 provider 配置我在实际使用中最常用的是cc-switch use加 Tab 补全切模型几乎不需要打开完整交互界面。3. 把自定义模型接进 Claude Code 的完整实操3.1 准备一个兼容接口模型源怎么选在动手配置之前先回答一个问题你的自定义模型是怎么暴露出来的Claude Code 走的是 Anthropic 的 Messages API 协议请求格式、响应格式都是固定的。如果你的模型服务原生支持这个协议那直接填 base URL 和 token 就能用。但现实中大部分本地模型服务或第三方网关并不原生支持 Anthropic 格式它们更多是 OpenAI 兼容的/v1/chat/completions接口。那怎么办两个思路找一个适配层把 Anthropic 格式的请求转发成目标模型的格式这类工具在社区里很常见比如各种协议转换代理。直接用支持 Anthropic 格式的网关服务现在有不少商业网关同时兼容多种协议你只需要在网关上配置好模型路由然后把网关的地址填给 CC Switch。以本地起一个兼容服务为例假设你已经在127.0.0.1:8080上跑好了服务并且它支持 Anthropic 格式那么 provider 的baseURL就填http://127.0.0.1:8080。如果你的 baseURL 填到了http://127.0.0.1:8080/v1而网关实际路径是/v1/messages最后拼出来的地址可能对不上服务会报 404这个细节要格外留意。3.2 添加 provider 配置的完整步骤添加一个 provider最直接的方式是执行cc-switch add它会进入交互式引导一步步让你输入名称、baseURL、API Key 和模型列表。但我个人更喜欢直接编辑~/.cc-switch/config.json因为一次可以完整看到所有字段还能顺带检查旧配置有没有问题。下面是我给一个虚构的“内部网关”添加配置时的文件内容{ providers: [ { name: internal-gw, baseURL: https://gateway.example.com/anthropic, apiKey: sk-internal-key-123456, models: [ model-alpha, model-beta ], extraHeaders: { X-Project-ID: dev-ops } } ] }字段含义如下name显示名在切换时用要起得简短好记。baseURLClaude Code 实际请求的接口地址。注意它不要以/messages结尾Claude Code 会自己拼接路径。apiKey放在Authorization: Bearer头里传给服务端。models该 provider 下可选的模型名列表。切到该配置后Claude Code 里可以通过/model命令看模型列表。extraHeaders额外请求头。如果你需要给内部网关传项目 ID 或组织 ID这个字段就派上用场了。保存文件后执行cc-switch list确认列表里能看到internal-gw。然后执行cc-switch use internal-gw工具会提示切换成功。此时打开 Claude Code 的配置文件看一眼cat ~/.claude/settings.json你会看到类似这样的内容{ env: { ANTHROPIC_BASE_URL: https://gateway.example.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-internal-key-123456, ANTHROPIC_MODEL: model-alpha, ANTHROPIC_SMALL_FAST_MODEL: model-alpha } }这就说明配置已经写进去了。3.3 环境变量映射关系Claude Code 到底读了哪些变量这里值得花点篇幅搞清楚环境变量的映射关系因为很多人配置失败问题就出在不知道该填哪些变量。CC Switch 帮你写的是下面这组变量环境变量作用对应 CC Switch 字段ANTHROPIC_BASE_URL自定义接口地址baseURLANTHROPIC_AUTH_TOKEN接口鉴权令牌apiKeyANTHROPIC_MODEL默认使用的主模型models第一个ANTHROPIC_SMALL_FAST_MODEL轻量任务使用的模型models第一个或第二个ANTHROPIC_CUSTOM_HEADERS附加请求头JSON 字符串extraHeaders关键点在于ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL是必须同时给的。Claude Code 在处理轻量任务比如标题生成、短文本总结时会调用SMALL_FAST_MODEL。如果你只设置了ANTHROPIC_MODEL忽略SMALL_FAST_MODEL大概率会在一些后台任务上报模型不存在。实际操作中我给每个 provider 都会配两个模型一个主力模型一个快速小模型。如果只有一个模型那SMALL_FAST_MODEL也填同一个名字至少能保证不报错。3.4 切换验证与持久化别信提示要信实际效果执行完切换后别马上就觉得“搞定了”我建议按下面三步做验证第一步验证配置是否已经写盘。cat ~/.claude/settings.json | grep -A 10 env确认ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN已经变成你选中 provider 的值。第二步在 Claude Code 里确认当前模型。启动 Claude Code 后输入/status它会打印当前环境的模型信息和 API 地址。对比一下和你预期值是否一致。第三步发一条实际请求。随便让它写个函数或者解释一段代码如果它能正常返回说明全链路是通的。这一步很重要——有时候配置看着没问题但实际请求会报错比如接口格式不兼容。如果报错看下报错信息是 4xx 还是 5xx后面我会讲分别怎么查。4. 典型问题排查与避坑经验4.1 模型连上了但响应异常请求格式和参数问题如果你的配置看起来都对了网络也通但 Claude Code 报错说“响应格式不正确”或者直接超时多数情况是请求协议和模型服务不匹配。Claude Code 调用自定义接口时会发送 Anthropic 格式的消息体里面包含messages、max_tokens、temperature、stream等字段。如果你的后端服务是 OpenAI 格式的直接收到这样的请求会解析失败。解决办法是在前面加一个协议转换层把 Anthropic 请求转成 OpenAI 格式再把响应转回去。另外要留意max_tokens参数。有些模型服务对单次生成的最大 token 数有限制Claude Code 默认请求可能会超过这个限制服务会返回错误。我遇到过几次最后在网关侧改了模型配置把输出上限调大才解决。这类问题不属于 CC Switch 本身的问题但很多人误以为是切换工具有 bug所以排查的时候要先分清楚报错发生在 HTTP 请求之前还是之后。如果 CC Switch 已经明确提示“切换成功”而后续请求出错那问题基本出在模型服务那侧。4.2 配置不生效环境变量优先级和缓存问题这是被问得最多的一个问题明明切到 provider A 了进去一看还是 provider B 的模型。首先要检查的是你的 shell 环境变量。如果你在.bashrc或.zshrc里export ANTHROPIC_BASE_URLxxx那这个值的优先级很高Claude Code 会优先读环境变量而不是settings.json里的env。CC Switch 写配置后被环境变量覆盖看起来就像“没生效”。排查命令env | grep ANTHROPIC如果输出里有相关变量先把你 shell 配置里的 export 行删掉再重新开一个终端重新执行cc-switch use provider。其次要检查项目级配置。Claude Code 允许每个项目有独立的.claude/settings.json项目级配置的优先级高于全局配置。如果你在某个仓库里执行 Claude Code发现模型没切换成功去项目目录下看一眼cat .claude/settings.json如果有env配置它会盖掉全局的。团队协作时模板仓库里经常带着一份项目级配置这常常是配置不生效的罪魁祸首。4.3 401 鉴权错误token 格式与请求头细节自定义模型服务返回 401说明鉴权没过。常见原因有三个apiKey填错了。服务端要求的鉴权头不是Authorization: Bearer xxx格式。apiKey里带了多余的空格或换行。CC Switch 写入配置时会把apiKey原样放进ANTHROPIC_AUTH_TOKENClaude Code 通常会用Authorization: Bearer token发送。如果你的网关要求自定义的头部比如X-API-Key那光填apiKey是不够的。解决办法是使用extraHeaders字段比如{ name: gw-with-custom-auth, baseURL: https://gateway.example.com/anthropic, apiKey: ignored-not-used, extraHeaders: { X-API-Key: real-key-here } }但注意这种做法要求网关允许同时传两套头一般内部网关才会这样设计。如果你自己写网关建议直接兼容Authorization: Bearer这样 CC Switch 的标准配置就能全面覆盖。4.4 多项目隔离与团队协作的配置管理建议最后聊一下配置管理层面的经验。CC Switch 虽然方便但它默认只管理全局的~/.claude/settings.json。如果你的团队同时维护多个项目每个项目用的模型不一样怎么组织我的建议是全局配置文件里只保留基础模型源比如官方接口避免默认配置影响别人。需要特定模型的项目在项目级.claude/settings.json里单独设置。这时候项目级配置优先级高于全局行为容易理解。对于团队协作千万不要把~/.claude/settings.json放进版本库也别把个人 token 提交到任何共享文件里。更稳妥的做法是在项目模板里放一个settings.json.example里面用占位符代替真实 key新成员复制成自己的配置后再用 CC Switch 把全局配置切到工作需要的 provider。我现在的习惯是在~/.cc-switch/config.json里维护三套配置——官方 API、内部网关、本地模型服务。日常默认切到官方 API调试本地模型时再切到本地配置。整个过程几秒钟完成比手改文件高效太多也基本没有再出现过把配置搞坏的情况。最后分享一个小技巧CC Switch 的use命令可以直接带参数执行不需要进入交互界面。你可以给自己加一个 shell 别名比如alias tothesiscc-switch use internal-gw切换时就是一个单词的事。配合 Claude Code 启动时读取最新的全局配置整个链路非常顺滑。