说实话Claude Code 的自定义模型接入对我这种喜欢折腾的人来说一直是个“又爱又恨”的话题。爱的是它确实能把我平时用的顺手模型、内部服务、各种实验性模型全部统一到一个交互界面里恨的是每次切换我都要跟那一堆 JSON 配置和环境变量搏斗。改来改去改错一个引号整个启动直接报错真的很耗耐心。用 CC Switch 之前我一直以为这就是命直到我把它装上才发现以前那种“手改配置”的日子完全可以彻底翻篇。CC Switch 这个工具简单说就是一个专门给 Claude Code 用的配置切换器。它把每一套自定义模型接入方案包括接口地址、鉴权信息、模型名、附带的环境变量打成一个“配置档”需要哪个就一键切到哪个。对于频繁切换不同模型、不同服务端点的开发者和团队来说它能省掉大部分琐碎的手工编辑同时避免很多低级错误。这篇文章我就把我从安装到日常使用、踩坑、最后形成一套稳定用法的心得全部写出来希望能帮你少走弯路。1. 手改配置这件事到底麻烦在哪儿1.1 Claude Code 自定义模型接入的基本机制要理解 CC Switch 的价值得先搞清楚 Claude Code 是怎么让用户接自定义模型的。我知道很多新朋友第一次听说这个概念时会以为要改源码或者搞插件其实不用。Claude Code 在启动时会读取一套配置这套配置里最核心的是几个环境变量ANTHROPIC_BASE_URL指向你真正要请求的模型接口地址Claude Code 会把所有标准请求发到这个地址。ANTHROPIC_AUTH_TOKEN访问这个接口时用的鉴权令牌。ANTHROPIC_MODEL告诉 Claude Code 默认用哪个模型标识去请求。一些更细的场景还会涉及ANTHROPIC_MODEL_PARAMS比如 temperature 等采样参数、ANTHROPIC_HEADERS附加请求头这些。换句话说Claude Code 本身是个非常标准的客户端它只认这几个配置项。你只要把配置指到“一个兼容 API 格式的服务端点”就能让 Claude Code 跑在你想要的模型上。这种方式本来是为了灵活但对使用者极其不友好。因为配置项是全局的你在一台机器上同时有工作项目、个人实验、客户环境时就得反复修改同一套全局配置。今天给 A 项目用方案一明天切回方案二后天又需要临时用一个测试模型整个流程就是打开配置文件改 baseURL改 token改模型名保存重启 Claude Code然后默默祈祷自己没把 JSON 的逗号写漏。1.2 手改配置时那些让人抓狂的瞬间我自己手改配置时踩过的坑基本上可以分为几类。第一类是格式错误配置文件是 JSON 或类 JSON 格式多一个逗号、少一个引号、注释格式不对Claude Code 启动时要么直接报错要么行为诡异。有一次我在 token 值里不小心留下了一个换行符结果所有请求都 401我愣是排查了半小时才发现是粘贴密钥时格式出了问题。第二类是维护多套配置的痛苦。我手头常备三四个不同服务端点的配置为了不反复修改我曾经用一个“配置模板文件”加脚本去替换脚本本身倒是能跑但扩展性很差。今天想加一个 header脚本逻辑就得更复杂明天想给不同项目用不同模型脚本已经成了一坨补丁叠补丁的产物。第三类是环境变量污染。Claude Code 和终端共享环境变量有时候我在某个终端会话里 export 了配置切个目录、开个新窗口环境就变了同一套代码有时候能连上模型有时候不能非常玄学。项目里的同事还会互相影响A 同学在自己的终端里改了全局配置B 同学一启动发现自己之前的配置全没了。这些痛点总结起来就是配置本身不难难的是“切换”这个动作在长期使用中反复发生而手改这个动作既不安全、也不可重复、更没法版本化。2. CC Switch 的核心设计把配置做成“档位”2.1 配置档Profile到底是什么CC Switch 的思路其实特别朴素你把它想象成“手机里的声音模式切换”就行。你不会每次想静音就去系统里翻设置而是直接拨动侧边键从“响铃”切到“静音”。CC Switch 就是把“响铃配置”和“静音配置”各自存成一个档位切换时一键拨过去。具体到 Claude Code 里每个配置档就是一套独立的完整接入方案通常包含配置名称比如“内部测试模型”、“客户环境”、“实验性应用模型”接口基础地址baseURL鉴权信息token 或 API key默认模型标识需要的附加环境变量或请求头备注信息比如这个配置是谁维护的、后端是什么服务、有什么使用限制。这些配置档会保存在 CC Switch 自己的管理存储里而不是散落在你的 shell 脚本、终端历史、便利贴和微信聊天记录中。用的时候你只需要说“切到配置 A”CC Switch 会把对应配置写入 Claude Code 实际读取的位置然后你就可以正常启动了。2.2 为什么“切换配置”比“手改环境变量”更可靠有人可能会问CC Switch 背后不就是帮你写了几个环境变量吗我自己写脚本不也一样吗表面上确实都是“改配置”但差异在于管理和校验机制。手写脚本时你大概率不会对每套配置做有效性检查改坏了就是坏了只能自己去试错。CC Switch 这类工具在保存配置时会做基础的格式整理比如保证 token 不带意外空白、baseURL 不以斜杠结尾、模型名符合常见命名规则切换时会先把旧配置完整替换不会出现新旧配置残留的“奶油夹心”状态。更关键的是它把“如何写”和“写到哪”从你的记忆里剥离了。Claude Code 的配置可能分布在用户级、项目级、环境变量三个层级手改时经常出现“改了 A 层但 B 层优先级更高根本没生效”的情况。CC Switch 会明确告诉你它写入的是哪一层并且切换后可以让你确认当前生效配置。对我这种要同时管多个项目的人来说这种确定性让整个人都安心了不少。2.3 它能给谁带来价值先说结论CC Switch 不是所有人的必需品。如果你只是安装了一个 Claude Code默认设置从来不用自定义模型那这个工具对你没有意义。如果你被薄薄一两套配置缠住了每次切换需要一两条命令那你的投入产出比也还好。真正适合的人群是第一手上同时有多个模型服务端点的使用者比如工作用内部网关、个人用兼容接口服务、临时测试用一个实验性模型几个档位来回切是常规操作。第二团队里多人协作使用 Claude Code 的场景配置可以通过配置文件分发新人不用知道每一个环境变量的含义直接用“档位”就能上手。第三对配置正确性有高要求的场景比如生产环境需要稳定复现某一套模型参数不能容忍“上次能连这次不行”的玄学。3. 实操从零开始把自定义模型接进 Claude Code3.1 安装 CC SwitchCC Switch 的安装方式跟着版本迭代有所变化不同系统也略有差异最稳妥的方式永远是看官方仓库或发布页的 README。我自己常用的安装方式是使用 npm 全局安装npm install -g cc-switch如果你是在 macOS 上且装了 Homebrew也可以留意是否有对应的 brew 包或者按官方建议下载对应平台的二进制文件。装好之后命令行里敲cc-switch --version能正常输出版本号就说明装好了。这个工具本质上是命令行工具不需要常驻后台也不需要在 Claude Code 里额外装插件用的时候呼出来即可。3.2 创建一个自定义模型的配置档我先说我的一次完整操作记录。当时我要把一个内部测试模型服务接入 Claude Code这个接口兼容标准请求格式接口地址是https://gateway.example.internal/v1鉴权 token 是一长串字符串模型标识是my-custom-model。第一步我把 CC Switch 的配置档列表打开确认初始状态cc-switch list它返回一个空列表因为还没有任何配置档。然后执行cc-switch add my-test-env工具会进入一个交互式录入流程询问接口地址、token、模型名等信息。我依次填入baseURLhttps://gateway.example.internal/v1token粘贴那一长串密钥modelmy-custom-model可选参数我加了一个自定义请求头X-Tenant-ID: tenant-001因为后端要求标识租户录入完成后工具会把配置保存成名为my-test-env的配置档。这时再执行cc-switch list就能看到这个档位及它的摘要信息。3.3 切换到配置档并验证生效配置档建好后切换到它的命令非常直接cc-switch use my-test-env执行时CC Switch 会把配置写入 Claude Code 的配置层可能是用户级配置文件常见路径是~/.claude/settings.json也可能是环境变量文件具体取决于你所在环境。切换成功后工具会提示当前生效的配置档名称。然后我启动 Claude Codeclaude启动后在对话中输入/status就能看到当前使用的模型标识和连接的相关信息。如果显示的是my-custom-model说明切换成功。我在实际操作中还习惯再发一条非常简单的消息给模型比如“回复一个‘好’字”通过响应速度、回复风格、模型自我介绍来判断自己连的是不是预期的那一个。这一步建议不要省因为配置文件和实际请求链路之间可能存在你意想不到的中间层。3.4 多配置切换与临时覆盖参数日常使用中最频繁的操作其实是“来回切”。我又建了一个配置档命名为gpu-lab指向另一套算力服务。现在两个配置档就在我手边我想用哪个就是一句cc-switch use xxx的事然后开一个新的 Claude Code 会话。旧会话可能还保留着旧配置的进程所以切换后建议关闭已打开的 Claude Code 会话再重新启动否则有可能仍在读取旧环境变量。有时候我不想为“临时换一个模型参数”专门建一个配置档而是想基于当前配置微调。比如我还是连内部网关但这轮任务想用更大容量的模型标识。这时 CC Switch 有没有提供临时覆盖功能要看版本老版本不一定有。有的版本支持在 use 命令后追加临时环境变量参数形如cc-switch use my-test-env --set ANTHROPIC_MODELmy-custom-model-large如果支持它会基于基础配置生成一个临时的生效环境不影响已保存的配置档。如果不支持我自己习惯的做法是直接复制一份配置档改个名字存成“变体”也不费事。用命名规范来区分比如my-test-env-large。4. 常见的翻车场景与排查心得4.1 问题速查表遇到这些现象该往哪想这个节目我喜欢用表格来总结方便你哪天遇到问题快速对号入座。现象可能原因排查思路启动 Claude Code 后仍用默认模型配置没写入生效层或有更高优先级配置检查项目级.claude/settings.json看它是否覆盖用户级确认 CC Switch 写入路径报 401 鉴权失败token 有误或 token 尾部有空白字符删除配置档重新粘贴 token确认接口服务的鉴权方式报 404 请求地址不存在baseURL 路径不对确认 baseURL 是否包含/v1等前缀试着在 curl 里请求一下接口文档路径连接超时接口地址不可达或客户端网络受限先用 curl 测 baseURL 连通性检查是否需要配置请求头请求成功但返回内容很奇怪模型标识与后端服务不匹配用/status查看实际 model对照服务端文档确认正确模型名切换配置后旧配置仍生效环境变量残留检查当前 shell 是否 export 过相关变量开新的终端窗口再试其他同事的配置被覆盖多人共用一台机器的同一用户目录优先使用项目级配置隔离或让 CC Switch 写入项目配置层这里要特别强调一下 t_token 粘贴时的格式问题。很多 token 在复制时会带上前导或尾随空白字符尤其是从网页或者聊天工具里复制时你可能肉眼看不出来。CC Switch 在保存时如果做得严谨会帮你 trim 掉但如果你遇到随机 401第一件事是重新粘贴一遍 token不要急着怀疑后端。4.2 避坑经验切换之后不要忘记“会话边界”我第一次用 CC Switch 时犯过一个很低级的错误在 Claude Code 运行中执行了切换命令然后回到原会话继续使用结果发现这个会话的模型没变。这是因为 Claude Code 进程启动时已经读取了配置CC Switch 修改的是磁盘上的配置但当前进程的内存环境没有被刷新。所以要记住一个原则CC Switch 负责“切换”你需要负责“重启会话”。另外还有一个比较容易忽略的点某些项目内部会有自己的.claude目录里面也有settings.json或本地配置。Claude Code 的配置优先级是“项目级 用户级”如果你在某个项目目录下启动了 Claude Code而这个项目里已经存在配置文件那么它可能覆盖掉 CC Switch 写入的用户级配置。遇到这种情况不要觉得是 CC Switch 没生效而是要看是不是被项目级配置拦截了。解决办法要么是调整项目级文件要么是把 CC Switch 的配置也写入到项目层如果工具支持的话或者干脆保证项目目录干净不用项目级配置。4.3 排查实操记录一个 401 问题的完整追踪我再分享一次完整的排查过程方便你建立思路。某天我发现gpu-lab这个配置档切过去之后Claude Code 里所有请求都返回 401 Unauthorized。我第一反应是密钥到期了于是去服务管理页面重新生成了一份。重新粘贴进 CC Switch 配置档再次切换还是 401。我做了三件事。第一用 curl 直接请求接口地址带上同样的 tokencurl -s -X POST https://gateway.example.internal/v1/chat/completions \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d {model:my-custom-model,messages:[{role:user,content:ping}]}结果 curl 正常返回。这至少说明接口地址、token、模型名本身没问题。第二我怀疑 Claude Code 发出的请求格式与 curl 有差异。但是等等如果格式不对应该报 400 而不是 401。于是考虑鉴权信息是否在请求头里正确传递。我开始怀疑 Claude Code 读取的不是 CC Switch 写入的 token而是环境变量里残留的旧 token。我在终端里执行env | grep -i anthropic果然看到一个旧的ANTHROPIC_AUTH_TOKEN还挂在环境里。因为环境变量优先级高于配置文件所以无论配置档怎么切Claude Code 用的都是环境变量里的旧值。第三解决办法很简单我unset ANTHROPIC_AUTH_TOKEN把脏环境清掉然后再启动 Claude Code马上就好了。后来我养成了一个习惯切换配置档后在新窗口启动前先看一眼env | grep -i anthropic确认没有脏变量。这个习惯帮我省了很多莫名其妙的排查时间。5. 进阶用法让配置管理进入团队协作轨道5.1 用配置档模板统一团队认知如果你是一个小团队的维护者或者经常帮同事配置环境你会发现 CC Switch 不只是自己的效率工具还可以成为团队内部的配置分发方式。你可以把一套配置档整理成模板命名带上清晰的业务含义比如prod-main-model、staging-test-model、local-compat-mode等。然后在团队文档里写清楚什么场景用哪个档位谁来维护 token 更新。这一点的价值在于它把“接入自定义模型”这个本来需要理解概念的知识降维成了“选一个档位”的操作。新同学来了不需要理解ANTHROPIC_BASE_URL是什么只需要知道“连不上就问运维要最新的配置档”。老同学也不需要在本地维护一个自己的私有配置文件因为档位是共享的、一致的。5.2 配置档的版本管理思路CC Switch 的配置档本质上就是文本数据所以你也可以考虑把它纳入版本管理。当然这里有一个大坑token 和密钥不能直接提交到仓库里。我自己用过的方式是配置档模板进仓库token 用占位符表示然后在一个独立的加密存储或团队密钥管理服务里保存真实值。使用时在本地把占位符替换成真实值再导入 CC Switch。如果你是一个人用那简单得多直接把 CC Switch 的配置存储目录纳入你自己的备份体系就行。定期备份这个目录换机器时拷贝过去再执行一下导入或重新注册整套配置就迁移过去了。我用这个办法在新电脑上恢复配置只花了两分钟比重新录入一遍高效得多。另外我建议在配置档的“备注”字段里写清楚这个接口对应的文档地址、维护人、注意事项。因为时间一长你一定会忘记某个配置档的详细背景有备注的话三个月后再回来看依然能快速理解。5.3 自动化脚本中的配置切换我平时还会写一些自动化脚本来调用 Claude Code。以前的写法是脚本里 export 各种环境变量再跑 Claude Code 命令每次都要小心变量之间的影响。用了 CC Switch 之后脚本变成这样cc-switch use prod-main-model claude --print 帮我生成某个任务的报告 output.txt脚本里再也不用维护一长串环境变量定义了可读性和稳定性都提高了。如果你的 CI 环境也跑 Claude Code你也可以在 CI 脚本第一步调用cc-switch指定配置档保证流水线里用的是预期的模型。当然CI 环境里要预装 CC Switch 并配置好 token 管理这属于团队基建层面的工作了。最后分享一个小技巧用 CC Switch 时间长了我最大的感受是“确定性”带来的安心感。以前切一次配置要心惊胆战地改文件现在只是敲一条命令切完看一眼/status就完事。不过我还是建议大家真正重要的生产环境切换后不要立刻投入大批量任务先发一条小消息验证一下链路再开始正式用。这个习惯帮我避过几次“看似连上、实际上配置被缓存坑了”的情况。最后再分享一个小技巧如果你发现某个配置档平时用得最多可以给 CC Switch 设置一个默认档让它在没有显式指定时自动使用这个档位。这样你打开新终端时不用每次手动切换默认就是你最常用的环境。省一步是一步把时间留给真正需要思考的事情上这才是我折腾这些工具的本心。 
长河君 · 2026/10/20 5:59:25 · 阅读 1.2k CC Switch：一键切换Claude Code自定义模型配置
说实话Claude Code 的自定义模型接入对我这种喜欢折腾的人来说一直是个“又爱又恨”的话题。爱的是它确实能把我平时用的顺手模型、内部服务、各种实验性模型全部统一到一个交互界面里恨的是每次切换我都要跟那一堆 JSON 配置和环境变量搏斗。改来改去改错一个引号整个启动直接报错真的很耗耐心。用 CC Switch 之前我一直以为这就是命直到我把它装上才发现以前那种“手改配置”的日子完全可以彻底翻篇。CC Switch 这个工具简单说就是一个专门给 Claude Code 用的配置切换器。它把每一套自定义模型接入方案包括接口地址、鉴权信息、模型名、附带的环境变量打成一个“配置档”需要哪个就一键切到哪个。对于频繁切换不同模型、不同服务端点的开发者和团队来说它能省掉大部分琐碎的手工编辑同时避免很多低级错误。这篇文章我就把我从安装到日常使用、踩坑、最后形成一套稳定用法的心得全部写出来希望能帮你少走弯路。1. 手改配置这件事到底麻烦在哪儿1.1 Claude Code 自定义模型接入的基本机制要理解 CC Switch 的价值得先搞清楚 Claude Code 是怎么让用户接自定义模型的。我知道很多新朋友第一次听说这个概念时会以为要改源码或者搞插件其实不用。Claude Code 在启动时会读取一套配置这套配置里最核心的是几个环境变量ANTHROPIC_BASE_URL指向你真正要请求的模型接口地址Claude Code 会把所有标准请求发到这个地址。ANTHROPIC_AUTH_TOKEN访问这个接口时用的鉴权令牌。ANTHROPIC_MODEL告诉 Claude Code 默认用哪个模型标识去请求。一些更细的场景还会涉及ANTHROPIC_MODEL_PARAMS比如 temperature 等采样参数、ANTHROPIC_HEADERS附加请求头这些。换句话说Claude Code 本身是个非常标准的客户端它只认这几个配置项。你只要把配置指到“一个兼容 API 格式的服务端点”就能让 Claude Code 跑在你想要的模型上。这种方式本来是为了灵活但对使用者极其不友好。因为配置项是全局的你在一台机器上同时有工作项目、个人实验、客户环境时就得反复修改同一套全局配置。今天给 A 项目用方案一明天切回方案二后天又需要临时用一个测试模型整个流程就是打开配置文件改 baseURL改 token改模型名保存重启 Claude Code然后默默祈祷自己没把 JSON 的逗号写漏。1.2 手改配置时那些让人抓狂的瞬间我自己手改配置时踩过的坑基本上可以分为几类。第一类是格式错误配置文件是 JSON 或类 JSON 格式多一个逗号、少一个引号、注释格式不对Claude Code 启动时要么直接报错要么行为诡异。有一次我在 token 值里不小心留下了一个换行符结果所有请求都 401我愣是排查了半小时才发现是粘贴密钥时格式出了问题。第二类是维护多套配置的痛苦。我手头常备三四个不同服务端点的配置为了不反复修改我曾经用一个“配置模板文件”加脚本去替换脚本本身倒是能跑但扩展性很差。今天想加一个 header脚本逻辑就得更复杂明天想给不同项目用不同模型脚本已经成了一坨补丁叠补丁的产物。第三类是环境变量污染。Claude Code 和终端共享环境变量有时候我在某个终端会话里 export 了配置切个目录、开个新窗口环境就变了同一套代码有时候能连上模型有时候不能非常玄学。项目里的同事还会互相影响A 同学在自己的终端里改了全局配置B 同学一启动发现自己之前的配置全没了。这些痛点总结起来就是配置本身不难难的是“切换”这个动作在长期使用中反复发生而手改这个动作既不安全、也不可重复、更没法版本化。2. CC Switch 的核心设计把配置做成“档位”2.1 配置档Profile到底是什么CC Switch 的思路其实特别朴素你把它想象成“手机里的声音模式切换”就行。你不会每次想静音就去系统里翻设置而是直接拨动侧边键从“响铃”切到“静音”。CC Switch 就是把“响铃配置”和“静音配置”各自存成一个档位切换时一键拨过去。具体到 Claude Code 里每个配置档就是一套独立的完整接入方案通常包含配置名称比如“内部测试模型”、“客户环境”、“实验性应用模型”接口基础地址baseURL鉴权信息token 或 API key默认模型标识需要的附加环境变量或请求头备注信息比如这个配置是谁维护的、后端是什么服务、有什么使用限制。这些配置档会保存在 CC Switch 自己的管理存储里而不是散落在你的 shell 脚本、终端历史、便利贴和微信聊天记录中。用的时候你只需要说“切到配置 A”CC Switch 会把对应配置写入 Claude Code 实际读取的位置然后你就可以正常启动了。2.2 为什么“切换配置”比“手改环境变量”更可靠有人可能会问CC Switch 背后不就是帮你写了几个环境变量吗我自己写脚本不也一样吗表面上确实都是“改配置”但差异在于管理和校验机制。手写脚本时你大概率不会对每套配置做有效性检查改坏了就是坏了只能自己去试错。CC Switch 这类工具在保存配置时会做基础的格式整理比如保证 token 不带意外空白、baseURL 不以斜杠结尾、模型名符合常见命名规则切换时会先把旧配置完整替换不会出现新旧配置残留的“奶油夹心”状态。更关键的是它把“如何写”和“写到哪”从你的记忆里剥离了。Claude Code 的配置可能分布在用户级、项目级、环境变量三个层级手改时经常出现“改了 A 层但 B 层优先级更高根本没生效”的情况。CC Switch 会明确告诉你它写入的是哪一层并且切换后可以让你确认当前生效配置。对我这种要同时管多个项目的人来说这种确定性让整个人都安心了不少。2.3 它能给谁带来价值先说结论CC Switch 不是所有人的必需品。如果你只是安装了一个 Claude Code默认设置从来不用自定义模型那这个工具对你没有意义。如果你被薄薄一两套配置缠住了每次切换需要一两条命令那你的投入产出比也还好。真正适合的人群是第一手上同时有多个模型服务端点的使用者比如工作用内部网关、个人用兼容接口服务、临时测试用一个实验性模型几个档位来回切是常规操作。第二团队里多人协作使用 Claude Code 的场景配置可以通过配置文件分发新人不用知道每一个环境变量的含义直接用“档位”就能上手。第三对配置正确性有高要求的场景比如生产环境需要稳定复现某一套模型参数不能容忍“上次能连这次不行”的玄学。3. 实操从零开始把自定义模型接进 Claude Code3.1 安装 CC SwitchCC Switch 的安装方式跟着版本迭代有所变化不同系统也略有差异最稳妥的方式永远是看官方仓库或发布页的 README。我自己常用的安装方式是使用 npm 全局安装npm install -g cc-switch如果你是在 macOS 上且装了 Homebrew也可以留意是否有对应的 brew 包或者按官方建议下载对应平台的二进制文件。装好之后命令行里敲cc-switch --version能正常输出版本号就说明装好了。这个工具本质上是命令行工具不需要常驻后台也不需要在 Claude Code 里额外装插件用的时候呼出来即可。3.2 创建一个自定义模型的配置档我先说我的一次完整操作记录。当时我要把一个内部测试模型服务接入 Claude Code这个接口兼容标准请求格式接口地址是https://gateway.example.internal/v1鉴权 token 是一长串字符串模型标识是my-custom-model。第一步我把 CC Switch 的配置档列表打开确认初始状态cc-switch list它返回一个空列表因为还没有任何配置档。然后执行cc-switch add my-test-env工具会进入一个交互式录入流程询问接口地址、token、模型名等信息。我依次填入baseURLhttps://gateway.example.internal/v1token粘贴那一长串密钥modelmy-custom-model可选参数我加了一个自定义请求头X-Tenant-ID: tenant-001因为后端要求标识租户录入完成后工具会把配置保存成名为my-test-env的配置档。这时再执行cc-switch list就能看到这个档位及它的摘要信息。3.3 切换到配置档并验证生效配置档建好后切换到它的命令非常直接cc-switch use my-test-env执行时CC Switch 会把配置写入 Claude Code 的配置层可能是用户级配置文件常见路径是~/.claude/settings.json也可能是环境变量文件具体取决于你所在环境。切换成功后工具会提示当前生效的配置档名称。然后我启动 Claude Codeclaude启动后在对话中输入/status就能看到当前使用的模型标识和连接的相关信息。如果显示的是my-custom-model说明切换成功。我在实际操作中还习惯再发一条非常简单的消息给模型比如“回复一个‘好’字”通过响应速度、回复风格、模型自我介绍来判断自己连的是不是预期的那一个。这一步建议不要省因为配置文件和实际请求链路之间可能存在你意想不到的中间层。3.4 多配置切换与临时覆盖参数日常使用中最频繁的操作其实是“来回切”。我又建了一个配置档命名为gpu-lab指向另一套算力服务。现在两个配置档就在我手边我想用哪个就是一句cc-switch use xxx的事然后开一个新的 Claude Code 会话。旧会话可能还保留着旧配置的进程所以切换后建议关闭已打开的 Claude Code 会话再重新启动否则有可能仍在读取旧环境变量。有时候我不想为“临时换一个模型参数”专门建一个配置档而是想基于当前配置微调。比如我还是连内部网关但这轮任务想用更大容量的模型标识。这时 CC Switch 有没有提供临时覆盖功能要看版本老版本不一定有。有的版本支持在 use 命令后追加临时环境变量参数形如cc-switch use my-test-env --set ANTHROPIC_MODELmy-custom-model-large如果支持它会基于基础配置生成一个临时的生效环境不影响已保存的配置档。如果不支持我自己习惯的做法是直接复制一份配置档改个名字存成“变体”也不费事。用命名规范来区分比如my-test-env-large。4. 常见的翻车场景与排查心得4.1 问题速查表遇到这些现象该往哪想这个节目我喜欢用表格来总结方便你哪天遇到问题快速对号入座。现象可能原因排查思路启动 Claude Code 后仍用默认模型配置没写入生效层或有更高优先级配置检查项目级.claude/settings.json看它是否覆盖用户级确认 CC Switch 写入路径报 401 鉴权失败token 有误或 token 尾部有空白字符删除配置档重新粘贴 token确认接口服务的鉴权方式报 404 请求地址不存在baseURL 路径不对确认 baseURL 是否包含/v1等前缀试着在 curl 里请求一下接口文档路径连接超时接口地址不可达或客户端网络受限先用 curl 测 baseURL 连通性检查是否需要配置请求头请求成功但返回内容很奇怪模型标识与后端服务不匹配用/status查看实际 model对照服务端文档确认正确模型名切换配置后旧配置仍生效环境变量残留检查当前 shell 是否 export 过相关变量开新的终端窗口再试其他同事的配置被覆盖多人共用一台机器的同一用户目录优先使用项目级配置隔离或让 CC Switch 写入项目配置层这里要特别强调一下 t_token 粘贴时的格式问题。很多 token 在复制时会带上前导或尾随空白字符尤其是从网页或者聊天工具里复制时你可能肉眼看不出来。CC Switch 在保存时如果做得严谨会帮你 trim 掉但如果你遇到随机 401第一件事是重新粘贴一遍 token不要急着怀疑后端。4.2 避坑经验切换之后不要忘记“会话边界”我第一次用 CC Switch 时犯过一个很低级的错误在 Claude Code 运行中执行了切换命令然后回到原会话继续使用结果发现这个会话的模型没变。这是因为 Claude Code 进程启动时已经读取了配置CC Switch 修改的是磁盘上的配置但当前进程的内存环境没有被刷新。所以要记住一个原则CC Switch 负责“切换”你需要负责“重启会话”。另外还有一个比较容易忽略的点某些项目内部会有自己的.claude目录里面也有settings.json或本地配置。Claude Code 的配置优先级是“项目级 用户级”如果你在某个项目目录下启动了 Claude Code而这个项目里已经存在配置文件那么它可能覆盖掉 CC Switch 写入的用户级配置。遇到这种情况不要觉得是 CC Switch 没生效而是要看是不是被项目级配置拦截了。解决办法要么是调整项目级文件要么是把 CC Switch 的配置也写入到项目层如果工具支持的话或者干脆保证项目目录干净不用项目级配置。4.3 排查实操记录一个 401 问题的完整追踪我再分享一次完整的排查过程方便你建立思路。某天我发现gpu-lab这个配置档切过去之后Claude Code 里所有请求都返回 401 Unauthorized。我第一反应是密钥到期了于是去服务管理页面重新生成了一份。重新粘贴进 CC Switch 配置档再次切换还是 401。我做了三件事。第一用 curl 直接请求接口地址带上同样的 tokencurl -s -X POST https://gateway.example.internal/v1/chat/completions \ -H Authorization: Bearer token \ -H Content-Type: application/json \ -d {model:my-custom-model,messages:[{role:user,content:ping}]}结果 curl 正常返回。这至少说明接口地址、token、模型名本身没问题。第二我怀疑 Claude Code 发出的请求格式与 curl 有差异。但是等等如果格式不对应该报 400 而不是 401。于是考虑鉴权信息是否在请求头里正确传递。我开始怀疑 Claude Code 读取的不是 CC Switch 写入的 token而是环境变量里残留的旧 token。我在终端里执行env | grep -i anthropic果然看到一个旧的ANTHROPIC_AUTH_TOKEN还挂在环境里。因为环境变量优先级高于配置文件所以无论配置档怎么切Claude Code 用的都是环境变量里的旧值。第三解决办法很简单我unset ANTHROPIC_AUTH_TOKEN把脏环境清掉然后再启动 Claude Code马上就好了。后来我养成了一个习惯切换配置档后在新窗口启动前先看一眼env | grep -i anthropic确认没有脏变量。这个习惯帮我省了很多莫名其妙的排查时间。5. 进阶用法让配置管理进入团队协作轨道5.1 用配置档模板统一团队认知如果你是一个小团队的维护者或者经常帮同事配置环境你会发现 CC Switch 不只是自己的效率工具还可以成为团队内部的配置分发方式。你可以把一套配置档整理成模板命名带上清晰的业务含义比如prod-main-model、staging-test-model、local-compat-mode等。然后在团队文档里写清楚什么场景用哪个档位谁来维护 token 更新。这一点的价值在于它把“接入自定义模型”这个本来需要理解概念的知识降维成了“选一个档位”的操作。新同学来了不需要理解ANTHROPIC_BASE_URL是什么只需要知道“连不上就问运维要最新的配置档”。老同学也不需要在本地维护一个自己的私有配置文件因为档位是共享的、一致的。5.2 配置档的版本管理思路CC Switch 的配置档本质上就是文本数据所以你也可以考虑把它纳入版本管理。当然这里有一个大坑token 和密钥不能直接提交到仓库里。我自己用过的方式是配置档模板进仓库token 用占位符表示然后在一个独立的加密存储或团队密钥管理服务里保存真实值。使用时在本地把占位符替换成真实值再导入 CC Switch。如果你是一个人用那简单得多直接把 CC Switch 的配置存储目录纳入你自己的备份体系就行。定期备份这个目录换机器时拷贝过去再执行一下导入或重新注册整套配置就迁移过去了。我用这个办法在新电脑上恢复配置只花了两分钟比重新录入一遍高效得多。另外我建议在配置档的“备注”字段里写清楚这个接口对应的文档地址、维护人、注意事项。因为时间一长你一定会忘记某个配置档的详细背景有备注的话三个月后再回来看依然能快速理解。5.3 自动化脚本中的配置切换我平时还会写一些自动化脚本来调用 Claude Code。以前的写法是脚本里 export 各种环境变量再跑 Claude Code 命令每次都要小心变量之间的影响。用了 CC Switch 之后脚本变成这样cc-switch use prod-main-model claude --print 帮我生成某个任务的报告 output.txt脚本里再也不用维护一长串环境变量定义了可读性和稳定性都提高了。如果你的 CI 环境也跑 Claude Code你也可以在 CI 脚本第一步调用cc-switch指定配置档保证流水线里用的是预期的模型。当然CI 环境里要预装 CC Switch 并配置好 token 管理这属于团队基建层面的工作了。最后分享一个小技巧用 CC Switch 时间长了我最大的感受是“确定性”带来的安心感。以前切一次配置要心惊胆战地改文件现在只是敲一条命令切完看一眼/status就完事。不过我还是建议大家真正重要的生产环境切换后不要立刻投入大批量任务先发一条小消息验证一下链路再开始正式用。这个习惯帮我避过几次“看似连上、实际上配置被缓存坑了”的情况。最后再分享一个小技巧如果你发现某个配置档平时用得最多可以给 CC Switch 设置一个默认档让它在没有显式指定时自动使用这个档位。这样你打开新终端时不用每次手动切换默认就是你最常用的环境。省一步是一步把时间留给真正需要思考的事情上这才是我折腾这些工具的本心。