1. 这个 15MB 小工具到底解决了什么问题第一次看到一个 15MB 的小工具让 Codex 和 Claude Code 随便换模型这个标题我脑子里蹦出来的第一个念头是终于有人把这件事做成一个独立小工具了。因为在这之前我自己维护过一套用脚本切换配置的方案改环境变量、改配置文件、重启终端一套流程下来少说两分钟多的时候还会因为某个变量没清干净导致请求打到错误的端点排查半天。这个工具的核心价值说白了就一句话它把切换模型供应商这件事从手动改配置变成了点一下按钮。Codex 和 Claude Code 这两类命令行 AI 编程助手默认都绑定自家的模型服务但实际用起来很多人会想接第三方兼容端点比如接 DeepSeek、Qwen、GLM 这类提供 OpenAI 兼容接口的服务。问题在于这两套工具的配置格式不一样、环境变量名不一样、认证方式也不完全一样手动切换非常容易出错。15MB 这个体积很关键。它不是 Electron 套壳不是带一堆运行时的大块头而是一个轻量的本地代理加配置管理器。它做的事情是在本地起一个转发层把 Codex 和 Claude Code 发出的请求按你当前选中的供应商配置转发到对应的真实端点同时把认证头、模型名、路径这些细节做转换。这样一来你不需要去动工具本身的安装目录也不需要反复改全局环境变量切换只发生在代理层。适合谁用三类人最需要。第一类是同时用 Codex 和 Claude Code 的开发者两边都想接同一个第三方模型不想维护两套配置。第二类是经常在不同模型之间横跳做对比的人比如同一个 bug 分别让 DeepSeek 和 Qwen 试一遍看谁修得准。第三类是网络环境或账号条件受限、需要走自建或第三方兼容端点的用户。如果你只用官方默认模型、从不切换那这个工具对你意义不大。我先把结论放前面这类工具真正的难点不在转发本身而在配置隔离、端点兼容、错误可观测这三件事。下面我会把它拆开讲透包括我实际踩过的坑。2. 核心原理拆解本地代理为什么是正解2.1 为什么不做成改配置文件而是本地代理最朴素的想法是写个脚本切换的时候直接改 Codex 和 Claude Code 的配置文件。我早期就是这么干的结论是能用但脆。原因有三个。第一配置文件格式和位置会随版本变。Codex 的配置在~/.codex/下Claude Code 在~/.claude/或项目级.claude/下字段名、层级结构在不同版本里调整过。你写死的脚本升级一次就可能失效而且失效的时候往往不报错只是静默地用了默认配置你以为切成功了其实没有。第二环境变量优先级混乱。很多工具同时支持配置文件和环境变量环境变量优先级通常更高。你改了配置文件但 shell 里还残留着上一次export的OPENAI_API_KEY或ANTHROPIC_BASE_URL结果请求还是打到旧端点。这种问题最难查因为配置文件看起来完全正确。第三切换需要重启进程。改完配置正在跑的会话不会自动生效你得退出重进。做模型对比的时候这个中断非常打断思路。本地代理方案把这些问题一次性绕开了。它的结构是这样的Codex / Claude Code | | 请求发到 127.0.0.1:某端口 v 本地代理15MB 小工具 | | 按当前选中配置改写后转发 v 真实端点DeepSeek / Qwen / GLM / 官方 ...工具本身只做一件事监听本地端口收到请求后根据当前激活的供应商配置把请求的 base URL、认证头、模型名替换掉再转发出去。Codex 和 Claude Code 那边你只需要把它们的 base URL 指向本地代理配置一次之后永远不用再动。2.2 请求改写到底改了哪些字段这是整个工具的技术核心也是最容易出兼容问题的地方。我按实际抓包看到的字段逐个说。Base URL 替换。Codex 走的是 OpenAI 风格的/responses或/chat/completionsClaude Code 走的是 Anthropic 风格的/v1/messages。代理需要识别进来的路径映射到目标供应商对应的路径。有些第三方端点只实现了/chat/completions没有/responses这时候代理要做路径降级转换否则就会报你热搜里那个cc switch local proxy failed while handling codex endpoint /responses的错误。认证头转换。OpenAI 风格用Authorization: Bearer sk-xxxAnthropic 风格用x-api-key: sk-xxx加anthropic-version头。代理要在两种风格之间做双向转换。如果目标端点只认 Bearer而进来的请求带的是 x-api-key代理就得把它翻译过去。模型名映射。这是最实用的一点。你可以在配置里写当请求模型是 gpt-5.6-sol 时实际转发成 deepseek-chat。这样 Codex 内部写死的模型名不用改代理层帮你换掉。热搜里那个the gpt-5.6-sol model is not supported when using codex with a...的报错本质就是模型名没做映射直接透传给了不认识的端点。流式响应透传。AI 编程助手大量依赖 SSE 流式输出代理必须原样透传text/event-stream不能缓冲整个响应再返回否则你会看到光标卡半天然后一次性刷出一大段。这一点对代理的实现质量要求很高。2.3 配置隔离为什么每个供应商要独立存我见过不少人把所有供应商的 key 塞在一个配置文件里靠注释切换。这在小规模下能用但一旦你要同时跑两个会话一个用 DeepSeek 调 bug一个用 Qwen 写测试就会互相干扰。好的做法是每个供应商一份独立配置包含名称、base URL、API key、模型映射表、额外请求头、超时设置。代理启动时加载全部配置运行时只激活其中一份。切换就是改一个当前激活项的指针不涉及重启。这种设计还有个好处配置可以版本化管理。你可以把不含 key 的配置模板提交到 gitkey 单独放本地团队协作时共享模板即可。3. 实操从零把 Codex 和 Claude Code 接到同一个代理3.1 安装与首次启动工具本身是单文件或极简安装包15MB 的体积意味着它大概率是 Go 或 Rust 编译的静态二进制没有运行时依赖。安装步骤通常是# 以实际发布形式为准这里演示通用流程 # 下载对应平台的可执行文件后 chmod x cc-switch ./cc-switch --version首次启动会生成默认配置目录一般在~/.cc-switch/或类似路径下。启动后它会在本地监听一个端口默认常见的是127.0.0.1:8787这类。你要做的是确认端口没被占用# Linux / macOS 检查端口占用 lsof -i :8787 # Windows netstat -ano | findstr 8787注意端口选择尽量避开常用开发端口3000、5000、8000、8080这些端口冲突概率极高。我一般会选 8787、9788 这种不常见的。3.2 配置一个第三方供应商配置项的核心字段我列成表方便对照填写字段说明示例name供应商显示名deepseekbase_url目标端点根地址https://api.deepseek.comapi_key认证密钥sk-xxxxxxxxmodel_map模型名映射gpt-5.6-sol - deepseek-chatextra_headers额外请求头视端点要求timeout超时秒数120模型映射这块我要多讲一句。Codex 内部会用一个默认模型名发请求Claude Code 也会用它的默认模型名。你在映射表里把这两个名字都指向目标端点的真实模型名代理收到后自动替换。比如gpt-5.6-sol - deepseek-chat claude-sonnet-4 - deepseek-chat这样无论哪个工具发请求最终都落到deepseek-chat上。做对比测试时你只要改映射表的目标值就能让两个工具同时切到新模型。3.3 让 Codex 指向本地代理Codex 的配置在~/.codex/config.toml或对应版本的文件里。关键是把 base URL 指向本地代理# ~/.codex/config.toml 示例 model_provider local-proxy [model_providers.local-proxy] name Local Proxy base_url http://127.0.0.1:8787/v1 wire_api responses同时确保环境变量里没有残留的旧配置# 检查是否有残留 env | grep -i -E openai|anthropic|codex # 如果有清掉 unset OPENAI_API_KEY unset OPENAI_BASE_URL这一步是踩坑重灾区。我遇到过配置文件明明指向代理但请求还是打到官方端点查了半小时才发现是 shell 里一个旧的OPENAI_BASE_URL在作祟。环境变量优先级高于配置文件务必先清干净。3.4 让 Claude Code 指向本地代理Claude Code 走 Anthropic 协议配置方式不同。它主要认环境变量export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 export ANTHROPIC_API_KEY任意占位值这里的 API key 填占位值就行因为真正的认证由代理层替换。代理收到请求后把x-api-key换成目标供应商的真实 key再转发出去。如果你用 VS Code 里的 Claude Code 插件环境变量要在插件启动的终端里设置或者写进 shell 的 profile 文件.bashrc/.zshrc确保插件继承到。3.5 验证链路是否打通配置完别急着写代码先用最小请求验证# 直接打代理的健康检查或模型列表 curl -s http://127.0.0.1:8787/v1/models | head -c 500如果返回模型列表说明代理活着。然后跑一个真实对话请求curl -s http://127.0.0.1:8787/v1/chat/completions \ -H Content-Type: application/json \ -d {model:gpt-5.6-sol,messages:[{role:user,content:hi}]}能正常返回内容说明映射和转发都通了。这一步通了再去 Codex 和 Claude Code 里实测。4. 常见报错与排查速查表这部分是我花时间最多的地方也是这类工具真正拉开差距的地方。我把热搜里出现的报错和实际遇到的整理成表。报错关键词根因解决方向local proxy failed while handling codex endpoint /responses目标端点不支持 responses 路径在代理里开启路径降级转成 chat/completionsmodel is not supported when using codex模型名未映射直接透传补全 model_map 映射表模型繁忙请稍后目标端点限流或过载换供应商或加重试退避无法加载组织设置认证头格式不对检查 Bearer 与 x-api-key 转换登录不上 / 登录失败代理端口未启动或端口冲突检查进程与端口占用自定义模型配置不生效环境变量残留覆盖清理 shell 环境变量4.1 路径不兼容responses 与 chat/completions 的坑Codex 新版默认走/responses接口这是 OpenAI 较新的 API 形态。但大量第三方兼容端点只实现了/chat/completions。代理如果原样转发/responses目标端点直接 404 或 400就出现failed while handling codex endpoint /responses。解决办法是在代理配置里开启协议降级把 responses 格式的请求体转换成 chat/completions 格式响应再转回来。这个转换不是简单改路径请求体结构不同——responses 用的是input字段chat/completions 用的是messages。好的代理会帮你做这层转换配置里通常有个开关叫compat_mode或responses_fallback。实操心得如果你的代理不支持自动降级可以在 Codex 配置里把wire_api改成chat强制它走 chat/completions。这是最省事的绕法。4.2 模型名透传导致的 400the gpt-5.6-sol model is not supported这个报错非常典型。Codex 内部硬编码了一个模型名你接的端点不认识这个名字直接拒绝。代理的模型映射就是干这个的。配置映射时要注意映射是双向生效的。请求出去时把 Codex 的模型名换成目标名响应回来时如果端点返回的模型名和请求的不一致有些工具会校验并报错代理需要把响应里的模型名再换回去。这一点很多简易代理没做导致请求成功但工具报错。4.3 流式输出卡顿或截断如果你发现 AI 回复是憋很久然后一次性刷出来而不是逐字输出说明代理缓冲了 SSE。检查代理配置里有没有flush_interval或stream_buffer之类的参数把它设成 0 或最小。SSE 必须边收边转任何缓冲都会破坏体验。另一个可能是超时设置太短。长回复生成时间可能超过 60 秒如果代理超时是 60 秒会在中途断开。把 timeout 调到 120 到 300 秒比较稳妥。4.4 切换后不生效最常见的原因是进程没重载配置。有些代理支持热重载改完配置自动生效有些不支持需要重启代理进程。如果你切换后行为没变先重启代理再重启 Codex / Claude Code 会话。还有一个隐蔽原因多个代理实例。你可能之前启动过一个忘了关新启动的因为端口被占用起在了别的端口但工具还指向旧端口。用lsof -i :8787确认只有一个实例。5. 我的实操心得与进阶玩法5.1 用代理做模型 A/B 对比这是我觉得这个工具最被低估的用法。因为切换成本几乎为零你可以这样玩同一个 bug先让 Codex 用 DeepSeek 修一遍记下结果切到 Qwen再修一遍切到 GLM再来一遍。三次结果摆一起对比谁修得准、谁废话少一目了然。具体操作上我建议给每个供应商配一个独立的映射目标然后用一个脚本快速切换激活项# 假设工具有 CLI 切换命令 cc-switch use deepseek # 跑测试 # ... cc-switch use qwen # 再跑测试对比的时候要注意控制变量同一个 prompt、同一份代码、同样的上下文长度。否则你比的是 prompt 差异不是模型差异。5.2 给代理加日志排查快十倍默认情况下代理可能不打日志出问题只能靠猜。我强烈建议开启请求日志至少记录时间、进来的路径、映射后的目标 URL、目标模型名、响应状态码、耗时。有了这份日志模型繁忙你能看出是 429 还是 503登录不上你能看出是 401 还是连不上排查效率完全不是一个量级。日志里注意不要记录 API key 和完整请求体避免泄露敏感信息。5.3 配置模板化团队共享如果你在团队里推广这套方案把不含 key 的配置模板提交到仓库# providers.template.yaml providers: - name: deepseek base_url: https://api.deepseek.com api_key: ${DEEPSEEK_KEY} model_map: gpt-5.6-sol: deepseek-chatkey 用环境变量占位每个人本地设置自己的。这样新人入职拉下模板、填个 key、启动代理五分钟就能跑起来不用挨个问配置怎么填。5.4 几个容易忽略的细节超时和重试要配套。只设超时不设重试遇到偶发 503 就直接失败只设重试不设退避会把限流的端点打得更死。建议指数退避首次重试等 1 秒之后翻倍最多重试 3 次。注意请求体大小限制。AI 编程助手经常带很长的上下文请求体可能几 MB。代理如果有 body size 限制大请求会被截断。检查配置里有没有max_body_size之类的项调大一些。HTTPS 与 HTTP 别搞混。本地代理是 HTTP目标端点是 HTTPS。代理转发时要正确发起 TLS 连接。如果目标端点证书有问题代理可能报证书错误这时候要么修证书要么在代理里显式信任仅限你信任的端点。版本升级后重新验证。Codex 和 Claude Code 更新频繁接口形态可能变。每次升级后跑一遍第 3.5 节的验证请求确认链路还通。我吃过一次亏工具升级后默认模型名变了映射表没更新结果所有请求都 400查了半天才发现。5.5 关于随便换模型的边界最后说点实在的。这个工具能让你随便换模型但换过去的模型能力差异是真实存在的。同一个复杂重构任务不同模型的表现可能天差地别。工具解决的是切换成本不解决模型选型。我的建议是日常简单任务用便宜快的模型复杂架构设计用能力强的模型通过代理快速切换把成本和质量平衡好。另外第三方端点的稳定性和官方不完全一样高峰期限流、偶发超时都正常。代理层做好重试和降级比什么都强。我现在的配置是主供应商加一个备用供应商主的不通自动切备用的基本不会因为端点抖动中断工作。这套方案我用了几个月最大的感受是把配置这件事从每次都要想变成一次配好再也不用管省下的心智负担远超工具本身的 15MB。如果你也在 Codex 和 Claude Code 之间反复横跳或者想接第三方模型又嫌配置麻烦这个思路值得试一遍。