Claude Code 这工具用久了你会发现一个刚需多个 API 节点来回切换。今天要用官方 Anthropic 的额度做代码审查明天想切到 DeepSeek 兼容接口省点成本后天又得走公司内部网关——每换一次就要去改一遍 BaseURL 和 APIKey。这种手动操作真的烦改错一个字符、多带一个斜杠整个会话就废了。这篇文章就从我这个重度使用者的视角把一套“节点清单 切换脚本”的方案完整拆开让你像切换 Git 分支一样切换 Claude Code 的后端节点。文章适合三类人一是把 Claude Code 当日常主力工具、但经常在不同模型服务间横跳的开发者二是团队里要给不同成员配不同 API 网关的管理员三是刚接触 Claude Code、被各种配置教程绕晕的新手。我会把配置加载原理、脚本实现、实测记录、避坑清单全部交代清楚你拿过去就能直接用。1. 多 API 节点到底解决什么问题高频场景与手动修改的三大痛点1.1 一个实际问题你的 Claude Code 不只接一个后端先聊聊为什么会有人需要“多 API 节点”。Claude Code 的架构很清晰它是一个 CLI 前端真正干活的是背后的大模型推理服务。只要接口协议兼容 Anthropic 的 Messages API理论上谁都可以当它的后端。于是就有了几种常见组合官方 Anthropic API延迟低、稳定性好但是配额要省着用尤其做批量代码审查的时候消耗很快。DeepSeek 等第三方模型的 Anthropic 兼容接口成本低适合长会话、跑批任务。DeepSeek 官方就提供了兼容 Anthropic API 的接入点把 BaseURL 指过去、换一个 APIKey 就能用。企业内部网关或聚合层很多公司会在内网搭一个统一的模型网关统一记账、统一鉴权Claude Code 在其中只是其中一个客户端。坦白说大多数人一开始只接一个节点直到某天发现“官方 key 额度见底了”或者“这个任务没必要用那么贵的模型”才开始琢磨怎么一键切换。我也不例外。最早我是手动改环境变量的每次都要翻终端历史找上次填的地址体验极差于是才决定做一套切换方案。1.2 手动切换的三大痛点手动改 BaseURL 和 APIKey听起来就是“打开配置文件、替换两行、保存”实际上坑比想象中多容易填错参数。BaseURL 这东西多一个/、少一个/v1结果完全不同。Anthropic 协议要求固定的/v1/messages路径但你接不同网关时有的网关要求 BaseURL 写到根路径有的又要带版本路径手工复制粘贴特别容易错。混淆全局与项目配置。Claude Code 启动时会从多个位置读取环境变量全局的~/.claude/.env.local、当前项目目录下的.env.local、还有 shell 里已经 export 的变量。你改了全局结果当前项目里有个旧的.env.local把配置覆盖了你以为切了一半实际还走老节点。验证成本高。切换完不是马上能确认结果得退出会话重新启动发一条消息试试看模型回复的风格和速度才能间接判断走的是哪个后端。如果切换时手滑把 key 中间截断了还要花时间排查。这三个痛点叠加就很需要一个“把配置当成可选项来管理”的工具。手动改配置本质上是在“编辑文件”而我们要的是“选择后端”前者是过程导向后者是结果导向。1.3 Claude Code 配置加载的秘密它不是从提示符里读的很多人第一次接触配置时有个误解以为 Claude Code 会在交互界面里提供一个设置菜单让你填 BaseURL 和 APIKey。实际上它走的是标准的环境变量机制。核心只有两个变量ANTHROPIC_BASE_URL指定 API 服务地址。ANTHROPIC_API_KEY指定调用凭证。它启动时会读取这些变量的值然后拼接出完整的请求地址。还有几个辅助变量比如ANTHROPIC_MODEL可以指定默认模型ANTHROPIC_SMALL_FAST_MODEL指定后台轻量任务用的模型这些在切换节点时也很重要因为不同后端支持的模型名不一样。Claude Code 的环境变量加载顺序大概是这样的当前 shell 里已经存在的环境变量优先级最高其次是项目目录下的.env.local最后才是全局的~/.claude/.env.local。理解了这个顺序后面排查“为什么改了不生效”就会非常有方向感。2. 切换方案的选型思路为什么我坚持用脚本管理配置2.1 三个落点三种做法的取舍知道了配置加载原理切换方案其实就有三个落点可以选改 shell 环境变量在.bashrc或者.zshrc里写死一组变量然后source一下。缺点是要维护两份配置换节点等于重新 export 再 source会话里已有的环境变量还容易残留。改.env.local文件Claude Code 每次启动时读取改了之后重开会话即可生效不需要管 shell 生命周期。而且~/.claude/.env.local是全局生效的切换一次影响所有项目非常符合“换后端”的语义。改settings.json里的 env 块新版 Claude Code 支持在~/.claude/settings.json中写env字段效果类似。但它是 JSON 格式用脚本改起来比较啰嗦除非你引入jq否则还是文本文件更顺手。我最终选择改全局.env.local。原因很简单它是最接近“配置唯一入口”的地方脚本处理极其方便而且不会和 shell 生命周期纠缠。2.2 方案选型自己写脚本而不是用现成工具社区里已经有几款 Claude Code 切换工具有些做得还蛮精致的有图形界面能管理多套配置甚至还能监控当前会话走的哪个节点。为什么我还要自己写脚本第一是可控性。图形工具本质上也是改配置但它在“改哪些文件、按什么优先级改”这件事上经常是黑盒。自己写的脚本每一步做了什么都能看得见出了问题知道去哪里查。第二是灵活性。我自己的脚本里可以随时加逻辑比如切换同时更新ANTHROPIC_MODEL、切换后自动记录日志、甚至切换后验证节点连通性。第三是依赖最少。一个 bash 脚本任何 Linux 和 macOS 机器上都能跑不需要装额外的运行时。当然如果你手头已经有顺手的图形化切换工具也完全可以用。我只是提供一个更透明、更适合二次改造的路径。工具选型没有绝对的对错关键是你自己清楚“切换”的本质只是改两个环境变量理解了这一点用什么工具都是锦上添花。2.3 设计目标像切换 Git 分支一样切换节点我给自己定的设计目标很直接一次切换只花一秒而且不会改错。具体拆开是这样的cc-switch add 名称 BaseURL APIKey # 注册一个节点以后不用再输入这串长参数 cc-switch ls # 查看已注册的所有节点 cc-switch use 名称 # 切换当前会话使用的节点 cc-switch rm 名称 # 删除一个不再使用的节点 cc-switch status # 查看当前生效的配置这套命令设计参考了git branch和nvm use的交互方式节点有名字切换靠名字而不是靠粘贴一长串 URL。注册一次后面每次切换都只输入一个短名字彻底告别反复复制粘贴。3. 动手实现写一个 120 行的 cc-switch 多节点切换脚本3.1 节点清单格式先用文本定义数据任何工具的第一步都是定义数据。我把节点清单放在~/.claude/endpoints.conf每行一条用|分隔四个字段节点名称|BaseURL|APIKey|备注举个例子official|https://api.anthropic.com|sk-ant-api03-xxxx|官方主账号 deepseek|https://api.deepseek.com/anthropic|sk-xxxx|DeepSeek 兼容接口 localgw|http://127.0.0.1:8080|local-key|本机网关测试选择纯文本而不是 JSON是因为 bash 处理文本最顺手cut -d|就能拆字段不需要依赖jq。节点名称不允许包含|这是唯一约束。endpoints.conf和.env.local都是敏感文件保存后我会立刻chmod 600避免其他用户读到 APIKey。3.2 核心函数解析upsert 的跨平台细节脚本里最重要的函数是upsert_env它负责把ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY写入.env.local。这里有个细节必须处理如果文件里已经有这两行不能盲目 append否则会留下两个同名变量后加载的还是旧值。我的实现思路是先用grep判断 key 是否存在存在就用sed原地替换不存在才 append。sed的原地替换参数在 macOS 和 Linux 上不一样macOS 要写sed -i Linux 直接写sed -i。这个坑我踩过一次第一次写完脚本在 macOS 上跑直接报错后来加了一个uname判断才解决。另一个细节是替换格式。sed命令里用|作为分隔符替换因为 BaseURL 本身包含https://如果还用/分隔会跟替换字符串里的斜杠冲突。upsert_env() { local key$1 value$2 file$3 if grep -q ^${key} $file; then if [[ $(uname) Darwin ]]; then sed -i s|^${key}.*|${key}${value}| $file else sed -i s|^${key}.*|${key}${value}| $file fi else echo ${key}${value} $file fi }3.3 完整脚本cc-switch 的参考实现下面是我实际在用的脚本去掉了跟具体密钥相关的部分结构保持完整。你可以直接保存为~/.claude/bin/cc-switch.sh加执行权限然后软链到 PATH 里。#!/usr/bin/env bash # 文件: ~/.claude/bin/cc-switch.sh # 说明: Claude Code 多 API 节点切换工具 set -euo pipefail CC_HOME${CC_HOME:-$HOME/.claude} CONF_FILE${CC_HOME}/endpoints.conf ENV_FILE${CC_HOME}/.env.local HISTORY${CC_HOME}/switch.log ensure_file() { touch $CONF_FILE $ENV_FILE chmod 600 $CONF_FILE $ENV_FILE } list_nodes() { ensure_file if [[ ! -s $CONF_FILE ]]; then echo 还没有注册任何节点先运行 cc-switch add return fi echo 已注册节点: while IFS| read -r name base key comment; do printf %-12s base%-40s key%s... %s\n $name $base ${key:0:6} $comment done $CONF_FILE } add_node() { ensure_file local name$1 base$2 key$3 comment${4:-} if grep -qE ^${name}\| $CONF_FILE; then echo 节点 $name 已存在先 cc-switch rm $name 再添加 exit 1 fi echo $name|$base|$key|$comment $CONF_FILE echo 已添加节点: $name } remove_node() { ensure_file local name$1 grep -vE ^${name}\| $CONF_FILE ${CONF_FILE}.tmp mv ${CONF_FILE}.tmp $CONF_FILE echo 已移除节点: $name } upsert_env() { local key$1 value$2 file$3 if grep -q ^${key} $file; then if [[ $(uname) Darwin ]]; then sed -i s|^${key}.*|${key}${value}| $file else sed -i s|^${key}.*|${key}${value}| $file fi else echo ${key}${value} $file fi } use_node() { ensure_file local name$1 local line line$(grep -E ^${name}\| $CONF_FILE || true) if [[ -z $line ]]; then echo 找不到节点: $name先 cc-switch add 注册 exit 1 fi local base key base$(echo $line | cut -d| -f2) key$(echo $line | cut -d| -f3) umask 077 upsert_env ANTHROPIC_BASE_URL $base $ENV_FILE upsert_env ANTHROPIC_API_KEY $key $ENV_FILE echo $(date %Y-%m-%d %H:%M:%S) switch - $name ($base) $HISTORY echo 已切换到: $name echo 当前生效: ANTHROPIC_BASE_URL$base echo 注意: 请退出当前 claude 会话重新启动才会加载最新配置 } show_status() { ensure_file echo 配置清单: $CONF_FILE echo 环境文件: $ENV_FILE echo --- if [[ -f $ENV_FILE ]]; then sed s/\(ANTHROPIC_API_KEY\).*/\1****已隐藏****/ $ENV_FILE else echo (无环境文件) fi echo --- echo 当前 shell 中的 ANTHROPIC_ 变量: env | grep ^ANTHROPIC_ || echo (无) } cmd${1:-status} shift || true case $cmd in add) add_node $ ;; rm) remove_node $ ;; use) use_node $ ;; ls) list_nodes ;; status) show_status ;; *) echo 用法: cc-switch {add|rm|use|ls|status} exit 1 ;; esac脚本逻辑不复杂核心是use_node这个函数先从配置文件里按名称捞出节点信息然后拆出 BaseURL 和 APIKey最后调用upsert_env写入.env.local。整个切换过程没有手动复制粘贴没有编辑器操作出错概率大幅下降。3.4 接入新节点的配置要点以 DeepSeek 兼容接口为例很多朋友第一次用这个脚本就是为了接 DeepSeek。DeepSeek 的 Anthropic 兼容接口有它自己的路径约定BaseURL 要写https://api.deepseek.com/anthropic这只是根路径协议层会自动拼/v1/messages。也就是说你不需要也不应该自己再加/v1否则最终请求会变成/anthropic/v1/v1/messages之类直接 404。注册 DeepSeek 节点时我是这样操作的cc-switch add deepseek https://api.deepseek.com/anthropic sk-你的deepseek密钥 DeepSeek兼容接口 cc-switch use deepseek切换后建议顺手在.env.local里加一行默认模型因为不同后端支持的模型名各不相同。DeepSeek 的模型名是deepseek-chat或deepseek-reasoner不会认claude-sonnet-4-5这种东西。upsert_env ANTHROPIC_MODEL deepseek-chat $HOME/.claude/.env.local这里有个小技巧在cc-switch use之后很多人的第一反应是直接发消息测试但我会先跑一次cc-switch status确认当前环境文件里的值然后再开新的会话。这样能区分“配置没写对”和“模型没加载对”两类问题。4. 实测记录DeepSeek 与官方节点之间无缝来回切换4.1 一次完整切换的演示过程我以自己电脑上的实际操作记录来演示。注册两个节点之后先看一眼清单$ cc-switch ls 已注册节点: official basehttps://api.anthropic.com keysk-ant... 官方主账号 deepseek basehttps://api.deepseek.com/anthropic keysk-... DeepSeek兼容接口切换到 DeepSeek$ cc-switch use deepseek 已切换到: deepseek 当前生效: ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic 注意: 请退出当前 claude 会话重新启动才会加载最新配置然后退出当前 claude 会话重新输入claude启动。此时如果在会话里问一句“你是什么模型”大概率会得到 DeepSeek 的自我介绍说明节点切换成功。切换回官方节点也完全对称$ cc-switch use official 已切换到: official 当前生效: ANTHROPIC_BASE_URLhttps://api.anthropic.com整个过程不到三秒而且不需要打开任何编辑器。4.2 验证切换是否真正生效的三种方法光看脚本输出还不算数关键是确认 claude 会话里实际走的节点。我总结了三种验证方式按可靠性从低到高排列问模型身份直接问“你的模型版本是什么”这个方法在模型输出比较诚实的时候有效但如果模型被提示词包装过可能答非所问只能作为辅助判断。看请求路径日志如果你的 API 网关或者服务提供商有控制台切完之后立刻触发一次请求然后去控制台看最近的调用记录里 base 域名是什么。这是最硬的证据。观察错误特征不同后端对同一个请求的处理不完全一样。比如 DeepSeek 不支持的某些参数会返回特定的错误码官方 API 对超长上下文的处理更宽松。从错误信息反推当前节点也是一种实用技巧。我最常用的是第二种因为公司网关控制台里能看到实时的请求域名和延迟一目了然。个人开发者在没有控制台的情况下把cc-switch status和模型身份问答结合基本够用。4.3 我遇到的三个隐蔽问题帮你提前避坑实测过程中踩了几个比较隐蔽的坑这里单独拿出来讲。第一个坑是shell 环境变量的残留覆盖。有段时间我在.zshrc里 export 过ANTHROPIC_BASE_URL导致cc-switch use改了.env.local之后完全不生效我还以为是脚本有 bug。排查了一圈才发现shell 里已有的变量优先级高于.env.localclaude 启动时直接用了 shell 里的值。解决办法是把.zshrc里的相关 export 删干净只保留.env.local这一处配置源。第二个坑是项目目录里的本地.env.local覆盖全局配置。你在某个项目里跑过claude并手写了一个项目级.env.local那么在这个目录下切节点就会失效。因为项目级配置的加载顺序在全局之前。我一劳永逸的办法是在项目根目录的.gitignore里加上.env.local同时养成习惯不在项目里放第二份环境文件。第三个坑是BaseURL 结尾的斜杠位置。DeepSeek 官方文档给的路径是/anthropic有些教程里写成https://api.deepseek.com/anthropic/多一个斜杠看起来差不多但某些网关实现会对路径做严格拼接最终请求路径多出一个//触发 404 或者 CORS 错误。我的建议是严格按照官方文档的地址写不带多余斜杠做到“文档给啥就填啥”。5. 常见问题速查表与安全避坑清单5.1 切换过程中的常见问题速查表我把自己和身边同事遇到的高频问题整理成了一张表排错的时候直接对着看现象常见原因快速解法切换后没有生效还是走旧节点shell 环境变量残留或项目目录存在.env.local检查env | grep ANTHROPIC_清理.zshrc中的 export检查项目目录是否有本地环境文件新会话连接报 404BaseURL 多写或少写路径如多加了/v1对照官方文档确保 BaseURL 不带多余斜杠和路径切换后报 401 认证失败APIKey 粘贴不完整或复制时带了空格在endpoints.conf里重新 add 一次确认 key 前后无空格模型名不存在不同后端的模型命名差异比如从 Claude 切到 DeepSeek 后还让它加载claude-sonnet在.env.local中设置ANTHROPIC_MODEL为当前后端支持的模型名sed: 1: ... invalid command codemacOS 和 Linux 的sed -i参数差异参考脚本里的uname分支macOS 写成sed -i 无法连接 API 地址服务商临时故障或网关地址变更用curl -v手动请求 BaseURL 根路径看 DNS 和 TLS 握手是否正常再确认节点地址是否有更新这个表的核心逻辑是先分清“配置层面”和“网络层面”。凡是配置问题用cc-switch status和env就能兜底凡是网络问题用curl就能验证。两级排查基本覆盖所有情况。5.2 别把 tsconfig 的 baseUrl 和 Claude Code 混为一谈网上搜“Claude Code baseurl 配置”的时候经常会混进来一条看起来很唬人的报错选项“baseurl”已弃用,并将停止在 typescript 7.0 中运行。注意这条消息不是 Claude Code 输出的它是 TypeScript 编译器在提示 tsconfig 里的baseUrl选项过时。这俩只是同名完全是两码事。Claude Code 的环境变量叫ANTHROPIC_BASE_URL藏在.env.local里TypeScript 的baseUrl是编译选项写在项目根目录的tsconfig.json里。如果你在给 Claude Code 调配置时看到 TS 的报错大概率是编辑器把两个配置文件的语义搞混了或者你打开的文档本身就跑偏了。这也是我一直推荐用脚本管理的原因之一把配置入口收敛到一个地方减少人工识别的机会。5.3 安全与工程化的十条建议最后分享几条我在实际使用中沉淀的安全与维护建议每一条都是拿教训换来的密钥文件的权限endpoints.conf和.env.local保存后立即chmod 600防止其他用户读取明文 APIKey。不要提交仓库项目里哪怕只放了一个.env.local也请确保它被.gitignore覆盖否则一个git push就把密钥泄露出去了。定期轮换密钥如果怀疑某个节点的 APIKey 泄露第一时间在服务商后台吊销然后cc-switch rm旧节点、cc-switch add新密钥。保留切换日志脚本里已经写了switch.log切换历史对排查配额异常很有用哪天发现消耗暴涨翻日志能定位是哪天切到哪个节点出的事。切换前确认业务语义不同节点可能有完全不同的模型能力和计费标准批处理任务切换到便宜节点没问题但涉及线上调试、敏感代码时务必确认当前节点是企业认可的网关。不要迷信任何中转服务接第三方聚合层之前先确认对方资质、数据留存策略和可用性承诺省钱的优先级永远排在安全之后。定期测试节点连通性可以用curl -sS -o /dev/null -w %{http_code} $BASE_URL快速探测地址是否可达我把它写成一个 cron 脚本每天早上自动检查异常时邮件提醒。新增节点先小流量验证新接一个节点先用一条普通问题测试不要上来就跑大任务避免因为模型行为差异造成意外开销。保持脚本单一职责cc-switch 只负责切换配置不要往里面加太多业务逻辑出问题时定位范围越小越好。备份配置文件endpoints.conf里存的都是敏感信息不适合直接备份到网盘我一般用本地的加密归档工具每月手动备份一次。这套脚本我实际用了将近两个月最大的感受不是每次省下的那几秒钟而是切换时的那份确定性。以前每次手动改配置心里总会嘀咕“这次改对了没有”现在一个cc-switch use下去配置文件、日志、当前状态全部明明白白彻底治好了我的配置焦虑。最后再分享一个小技巧如果你也经常在多个项目之间来回跑可以在cc-switch use成功之后顺手加一条命令把当前节点名写到一个.claude-current-node文件然后在 shell 的 Prompt 里显示出来。这样每次打开终端一眼就能看到当前 Claude Code 走的是哪个后端再也不会出现“我以为切了实际没切”的乌龙。 Claude Code多API节点切换：cc-switch脚本实战指南
Claude Code 这工具用久了你会发现一个刚需多个 API 节点来回切换。今天要用官方 Anthropic 的额度做代码审查明天想切到 DeepSeek 兼容接口省点成本后天又得走公司内部网关——每换一次就要去改一遍 BaseURL 和 APIKey。这种手动操作真的烦改错一个字符、多带一个斜杠整个会话就废了。这篇文章就从我这个重度使用者的视角把一套“节点清单 切换脚本”的方案完整拆开让你像切换 Git 分支一样切换 Claude Code 的后端节点。文章适合三类人一是把 Claude Code 当日常主力工具、但经常在不同模型服务间横跳的开发者二是团队里要给不同成员配不同 API 网关的管理员三是刚接触 Claude Code、被各种配置教程绕晕的新手。我会把配置加载原理、脚本实现、实测记录、避坑清单全部交代清楚你拿过去就能直接用。1. 多 API 节点到底解决什么问题高频场景与手动修改的三大痛点1.1 一个实际问题你的 Claude Code 不只接一个后端先聊聊为什么会有人需要“多 API 节点”。Claude Code 的架构很清晰它是一个 CLI 前端真正干活的是背后的大模型推理服务。只要接口协议兼容 Anthropic 的 Messages API理论上谁都可以当它的后端。于是就有了几种常见组合官方 Anthropic API延迟低、稳定性好但是配额要省着用尤其做批量代码审查的时候消耗很快。DeepSeek 等第三方模型的 Anthropic 兼容接口成本低适合长会话、跑批任务。DeepSeek 官方就提供了兼容 Anthropic API 的接入点把 BaseURL 指过去、换一个 APIKey 就能用。企业内部网关或聚合层很多公司会在内网搭一个统一的模型网关统一记账、统一鉴权Claude Code 在其中只是其中一个客户端。坦白说大多数人一开始只接一个节点直到某天发现“官方 key 额度见底了”或者“这个任务没必要用那么贵的模型”才开始琢磨怎么一键切换。我也不例外。最早我是手动改环境变量的每次都要翻终端历史找上次填的地址体验极差于是才决定做一套切换方案。1.2 手动切换的三大痛点手动改 BaseURL 和 APIKey听起来就是“打开配置文件、替换两行、保存”实际上坑比想象中多容易填错参数。BaseURL 这东西多一个/、少一个/v1结果完全不同。Anthropic 协议要求固定的/v1/messages路径但你接不同网关时有的网关要求 BaseURL 写到根路径有的又要带版本路径手工复制粘贴特别容易错。混淆全局与项目配置。Claude Code 启动时会从多个位置读取环境变量全局的~/.claude/.env.local、当前项目目录下的.env.local、还有 shell 里已经 export 的变量。你改了全局结果当前项目里有个旧的.env.local把配置覆盖了你以为切了一半实际还走老节点。验证成本高。切换完不是马上能确认结果得退出会话重新启动发一条消息试试看模型回复的风格和速度才能间接判断走的是哪个后端。如果切换时手滑把 key 中间截断了还要花时间排查。这三个痛点叠加就很需要一个“把配置当成可选项来管理”的工具。手动改配置本质上是在“编辑文件”而我们要的是“选择后端”前者是过程导向后者是结果导向。1.3 Claude Code 配置加载的秘密它不是从提示符里读的很多人第一次接触配置时有个误解以为 Claude Code 会在交互界面里提供一个设置菜单让你填 BaseURL 和 APIKey。实际上它走的是标准的环境变量机制。核心只有两个变量ANTHROPIC_BASE_URL指定 API 服务地址。ANTHROPIC_API_KEY指定调用凭证。它启动时会读取这些变量的值然后拼接出完整的请求地址。还有几个辅助变量比如ANTHROPIC_MODEL可以指定默认模型ANTHROPIC_SMALL_FAST_MODEL指定后台轻量任务用的模型这些在切换节点时也很重要因为不同后端支持的模型名不一样。Claude Code 的环境变量加载顺序大概是这样的当前 shell 里已经存在的环境变量优先级最高其次是项目目录下的.env.local最后才是全局的~/.claude/.env.local。理解了这个顺序后面排查“为什么改了不生效”就会非常有方向感。2. 切换方案的选型思路为什么我坚持用脚本管理配置2.1 三个落点三种做法的取舍知道了配置加载原理切换方案其实就有三个落点可以选改 shell 环境变量在.bashrc或者.zshrc里写死一组变量然后source一下。缺点是要维护两份配置换节点等于重新 export 再 source会话里已有的环境变量还容易残留。改.env.local文件Claude Code 每次启动时读取改了之后重开会话即可生效不需要管 shell 生命周期。而且~/.claude/.env.local是全局生效的切换一次影响所有项目非常符合“换后端”的语义。改settings.json里的 env 块新版 Claude Code 支持在~/.claude/settings.json中写env字段效果类似。但它是 JSON 格式用脚本改起来比较啰嗦除非你引入jq否则还是文本文件更顺手。我最终选择改全局.env.local。原因很简单它是最接近“配置唯一入口”的地方脚本处理极其方便而且不会和 shell 生命周期纠缠。2.2 方案选型自己写脚本而不是用现成工具社区里已经有几款 Claude Code 切换工具有些做得还蛮精致的有图形界面能管理多套配置甚至还能监控当前会话走的哪个节点。为什么我还要自己写脚本第一是可控性。图形工具本质上也是改配置但它在“改哪些文件、按什么优先级改”这件事上经常是黑盒。自己写的脚本每一步做了什么都能看得见出了问题知道去哪里查。第二是灵活性。我自己的脚本里可以随时加逻辑比如切换同时更新ANTHROPIC_MODEL、切换后自动记录日志、甚至切换后验证节点连通性。第三是依赖最少。一个 bash 脚本任何 Linux 和 macOS 机器上都能跑不需要装额外的运行时。当然如果你手头已经有顺手的图形化切换工具也完全可以用。我只是提供一个更透明、更适合二次改造的路径。工具选型没有绝对的对错关键是你自己清楚“切换”的本质只是改两个环境变量理解了这一点用什么工具都是锦上添花。2.3 设计目标像切换 Git 分支一样切换节点我给自己定的设计目标很直接一次切换只花一秒而且不会改错。具体拆开是这样的cc-switch add 名称 BaseURL APIKey # 注册一个节点以后不用再输入这串长参数 cc-switch ls # 查看已注册的所有节点 cc-switch use 名称 # 切换当前会话使用的节点 cc-switch rm 名称 # 删除一个不再使用的节点 cc-switch status # 查看当前生效的配置这套命令设计参考了git branch和nvm use的交互方式节点有名字切换靠名字而不是靠粘贴一长串 URL。注册一次后面每次切换都只输入一个短名字彻底告别反复复制粘贴。3. 动手实现写一个 120 行的 cc-switch 多节点切换脚本3.1 节点清单格式先用文本定义数据任何工具的第一步都是定义数据。我把节点清单放在~/.claude/endpoints.conf每行一条用|分隔四个字段节点名称|BaseURL|APIKey|备注举个例子official|https://api.anthropic.com|sk-ant-api03-xxxx|官方主账号 deepseek|https://api.deepseek.com/anthropic|sk-xxxx|DeepSeek 兼容接口 localgw|http://127.0.0.1:8080|local-key|本机网关测试选择纯文本而不是 JSON是因为 bash 处理文本最顺手cut -d|就能拆字段不需要依赖jq。节点名称不允许包含|这是唯一约束。endpoints.conf和.env.local都是敏感文件保存后我会立刻chmod 600避免其他用户读到 APIKey。3.2 核心函数解析upsert 的跨平台细节脚本里最重要的函数是upsert_env它负责把ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY写入.env.local。这里有个细节必须处理如果文件里已经有这两行不能盲目 append否则会留下两个同名变量后加载的还是旧值。我的实现思路是先用grep判断 key 是否存在存在就用sed原地替换不存在才 append。sed的原地替换参数在 macOS 和 Linux 上不一样macOS 要写sed -i Linux 直接写sed -i。这个坑我踩过一次第一次写完脚本在 macOS 上跑直接报错后来加了一个uname判断才解决。另一个细节是替换格式。sed命令里用|作为分隔符替换因为 BaseURL 本身包含https://如果还用/分隔会跟替换字符串里的斜杠冲突。upsert_env() { local key$1 value$2 file$3 if grep -q ^${key} $file; then if [[ $(uname) Darwin ]]; then sed -i s|^${key}.*|${key}${value}| $file else sed -i s|^${key}.*|${key}${value}| $file fi else echo ${key}${value} $file fi }3.3 完整脚本cc-switch 的参考实现下面是我实际在用的脚本去掉了跟具体密钥相关的部分结构保持完整。你可以直接保存为~/.claude/bin/cc-switch.sh加执行权限然后软链到 PATH 里。#!/usr/bin/env bash # 文件: ~/.claude/bin/cc-switch.sh # 说明: Claude Code 多 API 节点切换工具 set -euo pipefail CC_HOME${CC_HOME:-$HOME/.claude} CONF_FILE${CC_HOME}/endpoints.conf ENV_FILE${CC_HOME}/.env.local HISTORY${CC_HOME}/switch.log ensure_file() { touch $CONF_FILE $ENV_FILE chmod 600 $CONF_FILE $ENV_FILE } list_nodes() { ensure_file if [[ ! -s $CONF_FILE ]]; then echo 还没有注册任何节点先运行 cc-switch add return fi echo 已注册节点: while IFS| read -r name base key comment; do printf %-12s base%-40s key%s... %s\n $name $base ${key:0:6} $comment done $CONF_FILE } add_node() { ensure_file local name$1 base$2 key$3 comment${4:-} if grep -qE ^${name}\| $CONF_FILE; then echo 节点 $name 已存在先 cc-switch rm $name 再添加 exit 1 fi echo $name|$base|$key|$comment $CONF_FILE echo 已添加节点: $name } remove_node() { ensure_file local name$1 grep -vE ^${name}\| $CONF_FILE ${CONF_FILE}.tmp mv ${CONF_FILE}.tmp $CONF_FILE echo 已移除节点: $name } upsert_env() { local key$1 value$2 file$3 if grep -q ^${key} $file; then if [[ $(uname) Darwin ]]; then sed -i s|^${key}.*|${key}${value}| $file else sed -i s|^${key}.*|${key}${value}| $file fi else echo ${key}${value} $file fi } use_node() { ensure_file local name$1 local line line$(grep -E ^${name}\| $CONF_FILE || true) if [[ -z $line ]]; then echo 找不到节点: $name先 cc-switch add 注册 exit 1 fi local base key base$(echo $line | cut -d| -f2) key$(echo $line | cut -d| -f3) umask 077 upsert_env ANTHROPIC_BASE_URL $base $ENV_FILE upsert_env ANTHROPIC_API_KEY $key $ENV_FILE echo $(date %Y-%m-%d %H:%M:%S) switch - $name ($base) $HISTORY echo 已切换到: $name echo 当前生效: ANTHROPIC_BASE_URL$base echo 注意: 请退出当前 claude 会话重新启动才会加载最新配置 } show_status() { ensure_file echo 配置清单: $CONF_FILE echo 环境文件: $ENV_FILE echo --- if [[ -f $ENV_FILE ]]; then sed s/\(ANTHROPIC_API_KEY\).*/\1****已隐藏****/ $ENV_FILE else echo (无环境文件) fi echo --- echo 当前 shell 中的 ANTHROPIC_ 变量: env | grep ^ANTHROPIC_ || echo (无) } cmd${1:-status} shift || true case $cmd in add) add_node $ ;; rm) remove_node $ ;; use) use_node $ ;; ls) list_nodes ;; status) show_status ;; *) echo 用法: cc-switch {add|rm|use|ls|status} exit 1 ;; esac脚本逻辑不复杂核心是use_node这个函数先从配置文件里按名称捞出节点信息然后拆出 BaseURL 和 APIKey最后调用upsert_env写入.env.local。整个切换过程没有手动复制粘贴没有编辑器操作出错概率大幅下降。3.4 接入新节点的配置要点以 DeepSeek 兼容接口为例很多朋友第一次用这个脚本就是为了接 DeepSeek。DeepSeek 的 Anthropic 兼容接口有它自己的路径约定BaseURL 要写https://api.deepseek.com/anthropic这只是根路径协议层会自动拼/v1/messages。也就是说你不需要也不应该自己再加/v1否则最终请求会变成/anthropic/v1/v1/messages之类直接 404。注册 DeepSeek 节点时我是这样操作的cc-switch add deepseek https://api.deepseek.com/anthropic sk-你的deepseek密钥 DeepSeek兼容接口 cc-switch use deepseek切换后建议顺手在.env.local里加一行默认模型因为不同后端支持的模型名各不相同。DeepSeek 的模型名是deepseek-chat或deepseek-reasoner不会认claude-sonnet-4-5这种东西。upsert_env ANTHROPIC_MODEL deepseek-chat $HOME/.claude/.env.local这里有个小技巧在cc-switch use之后很多人的第一反应是直接发消息测试但我会先跑一次cc-switch status确认当前环境文件里的值然后再开新的会话。这样能区分“配置没写对”和“模型没加载对”两类问题。4. 实测记录DeepSeek 与官方节点之间无缝来回切换4.1 一次完整切换的演示过程我以自己电脑上的实际操作记录来演示。注册两个节点之后先看一眼清单$ cc-switch ls 已注册节点: official basehttps://api.anthropic.com keysk-ant... 官方主账号 deepseek basehttps://api.deepseek.com/anthropic keysk-... DeepSeek兼容接口切换到 DeepSeek$ cc-switch use deepseek 已切换到: deepseek 当前生效: ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic 注意: 请退出当前 claude 会话重新启动才会加载最新配置然后退出当前 claude 会话重新输入claude启动。此时如果在会话里问一句“你是什么模型”大概率会得到 DeepSeek 的自我介绍说明节点切换成功。切换回官方节点也完全对称$ cc-switch use official 已切换到: official 当前生效: ANTHROPIC_BASE_URLhttps://api.anthropic.com整个过程不到三秒而且不需要打开任何编辑器。4.2 验证切换是否真正生效的三种方法光看脚本输出还不算数关键是确认 claude 会话里实际走的节点。我总结了三种验证方式按可靠性从低到高排列问模型身份直接问“你的模型版本是什么”这个方法在模型输出比较诚实的时候有效但如果模型被提示词包装过可能答非所问只能作为辅助判断。看请求路径日志如果你的 API 网关或者服务提供商有控制台切完之后立刻触发一次请求然后去控制台看最近的调用记录里 base 域名是什么。这是最硬的证据。观察错误特征不同后端对同一个请求的处理不完全一样。比如 DeepSeek 不支持的某些参数会返回特定的错误码官方 API 对超长上下文的处理更宽松。从错误信息反推当前节点也是一种实用技巧。我最常用的是第二种因为公司网关控制台里能看到实时的请求域名和延迟一目了然。个人开发者在没有控制台的情况下把cc-switch status和模型身份问答结合基本够用。4.3 我遇到的三个隐蔽问题帮你提前避坑实测过程中踩了几个比较隐蔽的坑这里单独拿出来讲。第一个坑是shell 环境变量的残留覆盖。有段时间我在.zshrc里 export 过ANTHROPIC_BASE_URL导致cc-switch use改了.env.local之后完全不生效我还以为是脚本有 bug。排查了一圈才发现shell 里已有的变量优先级高于.env.localclaude 启动时直接用了 shell 里的值。解决办法是把.zshrc里的相关 export 删干净只保留.env.local这一处配置源。第二个坑是项目目录里的本地.env.local覆盖全局配置。你在某个项目里跑过claude并手写了一个项目级.env.local那么在这个目录下切节点就会失效。因为项目级配置的加载顺序在全局之前。我一劳永逸的办法是在项目根目录的.gitignore里加上.env.local同时养成习惯不在项目里放第二份环境文件。第三个坑是BaseURL 结尾的斜杠位置。DeepSeek 官方文档给的路径是/anthropic有些教程里写成https://api.deepseek.com/anthropic/多一个斜杠看起来差不多但某些网关实现会对路径做严格拼接最终请求路径多出一个//触发 404 或者 CORS 错误。我的建议是严格按照官方文档的地址写不带多余斜杠做到“文档给啥就填啥”。5. 常见问题速查表与安全避坑清单5.1 切换过程中的常见问题速查表我把自己和身边同事遇到的高频问题整理成了一张表排错的时候直接对着看现象常见原因快速解法切换后没有生效还是走旧节点shell 环境变量残留或项目目录存在.env.local检查env | grep ANTHROPIC_清理.zshrc中的 export检查项目目录是否有本地环境文件新会话连接报 404BaseURL 多写或少写路径如多加了/v1对照官方文档确保 BaseURL 不带多余斜杠和路径切换后报 401 认证失败APIKey 粘贴不完整或复制时带了空格在endpoints.conf里重新 add 一次确认 key 前后无空格模型名不存在不同后端的模型命名差异比如从 Claude 切到 DeepSeek 后还让它加载claude-sonnet在.env.local中设置ANTHROPIC_MODEL为当前后端支持的模型名sed: 1: ... invalid command codemacOS 和 Linux 的sed -i参数差异参考脚本里的uname分支macOS 写成sed -i 无法连接 API 地址服务商临时故障或网关地址变更用curl -v手动请求 BaseURL 根路径看 DNS 和 TLS 握手是否正常再确认节点地址是否有更新这个表的核心逻辑是先分清“配置层面”和“网络层面”。凡是配置问题用cc-switch status和env就能兜底凡是网络问题用curl就能验证。两级排查基本覆盖所有情况。5.2 别把 tsconfig 的 baseUrl 和 Claude Code 混为一谈网上搜“Claude Code baseurl 配置”的时候经常会混进来一条看起来很唬人的报错选项“baseurl”已弃用,并将停止在 typescript 7.0 中运行。注意这条消息不是 Claude Code 输出的它是 TypeScript 编译器在提示 tsconfig 里的baseUrl选项过时。这俩只是同名完全是两码事。Claude Code 的环境变量叫ANTHROPIC_BASE_URL藏在.env.local里TypeScript 的baseUrl是编译选项写在项目根目录的tsconfig.json里。如果你在给 Claude Code 调配置时看到 TS 的报错大概率是编辑器把两个配置文件的语义搞混了或者你打开的文档本身就跑偏了。这也是我一直推荐用脚本管理的原因之一把配置入口收敛到一个地方减少人工识别的机会。5.3 安全与工程化的十条建议最后分享几条我在实际使用中沉淀的安全与维护建议每一条都是拿教训换来的密钥文件的权限endpoints.conf和.env.local保存后立即chmod 600防止其他用户读取明文 APIKey。不要提交仓库项目里哪怕只放了一个.env.local也请确保它被.gitignore覆盖否则一个git push就把密钥泄露出去了。定期轮换密钥如果怀疑某个节点的 APIKey 泄露第一时间在服务商后台吊销然后cc-switch rm旧节点、cc-switch add新密钥。保留切换日志脚本里已经写了switch.log切换历史对排查配额异常很有用哪天发现消耗暴涨翻日志能定位是哪天切到哪个节点出的事。切换前确认业务语义不同节点可能有完全不同的模型能力和计费标准批处理任务切换到便宜节点没问题但涉及线上调试、敏感代码时务必确认当前节点是企业认可的网关。不要迷信任何中转服务接第三方聚合层之前先确认对方资质、数据留存策略和可用性承诺省钱的优先级永远排在安全之后。定期测试节点连通性可以用curl -sS -o /dev/null -w %{http_code} $BASE_URL快速探测地址是否可达我把它写成一个 cron 脚本每天早上自动检查异常时邮件提醒。新增节点先小流量验证新接一个节点先用一条普通问题测试不要上来就跑大任务避免因为模型行为差异造成意外开销。保持脚本单一职责cc-switch 只负责切换配置不要往里面加太多业务逻辑出问题时定位范围越小越好。备份配置文件endpoints.conf里存的都是敏感信息不适合直接备份到网盘我一般用本地的加密归档工具每月手动备份一次。这套脚本我实际用了将近两个月最大的感受不是每次省下的那几秒钟而是切换时的那份确定性。以前每次手动改配置心里总会嘀咕“这次改对了没有”现在一个cc-switch use下去配置文件、日志、当前状态全部明明白白彻底治好了我的配置焦虑。最后再分享一个小技巧如果你也经常在多个项目之间来回跑可以在cc-switch use成功之后顺手加一条命令把当前节点名写到一个.claude-current-node文件然后在 shell 的 Prompt 里显示出来。这样每次打开终端一眼就能看到当前 Claude Code 走的是哪个后端再也不会出现“我以为切了实际没切”的乌龙。