很多人天天用 Codex 和 Claude Code但都被同一个问题卡住官方默认只让用自家那几个模型想换个模型试试要么改环境变量改到头晕要么直接报model not supported。我最近一直在捣鼓一个只有 15MB 的小工具它能把 Codex 和 Claude Code 的模型请求拦下来再乖乖转发到你想用的任何模型上实测下来非常顺手。这篇文章就把我从安装到排错的全过程写出来包括那个让不少人头疼的local proxy failed while handling codex endpoint /responses报错以及切换模型后对话不断跳闪的问题一次性讲透。这个小工具适合谁如果你是 Codex 或 Claude Code 的用户觉得官方模型不够用、想接入本地模型或第三方自定义模型或者只是想在不同模型之间快速横跳对比效果这篇文章就是给你的。我会从原理讲起再给完整操作步骤最后把踩过的坑挨个复盘。1. 先说说我为什么会盯上这个 15MB 的小工具1.1 Codex 和 Claude Code 的模型锁定问题用过 Codex 的朋友都知道它默认走的是 OpenAI 的接口模型基本固定在 GPT-5 系列上你在配置文件里写model gpt-5.x未必管用因为客户端会在请求里强制带上它认识的模型名。你硬塞一个不认识的模型名大概率会得到类似这样的报错The gpt-5.6-sol model is not supported when using Codex with a...Claude Code 那边也差不多它默认绑定 Anthropic 的 Claude 系列虽然可以通过环境变量ANTHROPIC_BASE_URL改接口地址但改了之后模型名、请求格式还得自己适配。说穿了这两个工具表面上开放了配置入口实际上内部做了不少限制真想随便换模型靠常规手段很麻烦。我最初试过直接在配置里改model参数结果要么不生效要么客户端直接报错。后来试过在系统层面 mock 域名指向本地服务稍微能通但一旦涉及到不同模型的接口格式差异又得写一堆胶水代码维护成本太高。1.2 换模型的主流方案为什么都要绕远路圈子里换模型的主流办法大概有这么几种改环境变量指向兼容接口比如把 Codex 的请求指向一个兼容 OpenAI 格式的本地服务。用系统级网络重定向工具拦截请求再手工改写请求体。直接修改客户端源码或插件重新编译。这些方案各有各的坑。改环境变量只解决了地址变了的问题没解决格式不对的问题网络重定向工具通常是通用型的对 Codex 这种带流式输出和复杂错误结构的客户端处理得不好改源码就更累了客户端一更新就白改。所以当我看到这个 15MB 的小工具时第一反应是它凭什么这么小看完原理才明白它只做了一件事——在本地起一个轻量的 HTTP 转发服务专门接收 Codex 和 Claude Code 发来的请求然后按照目标模型的接口规范改写请求体再转发出去最后把响应原样传回来。这个思路非常聪明它不需要侵入客户端也不需要在系统层面做全局重定向只在你需要的时候让 Codex 或 Claude Code 指向这个本地端口就行。2. 这个小工具到底做了什么把 API 请求导流到任意模型2.1 一个本地转发层的完整工作流程要理解这个小工具的运行逻辑可以把它想象成一个翻译官。Codex 客户端在发起请求时会按照 OpenAI 的格式构造一个完整的 HTTP 请求包括请求头、模型名、消息列表、温度参数、流式标记等等。这个小工具在本地监听一个端口比如127.0.0.1:8080你通过配置文件把 Codex 的接口地址指到这个端口。Codex 的请求到了这里小工具会做四件事解析原始请求提取模型名、消息内容、参数。根据你当前选定的目标模型把请求体转换成目标模型 API 需要的格式。把转换后的请求发送给目标模型的真实接口地址。接收目标模型的响应如果需要再转换回 Codex 能识别的格式原样返回。这整个过程对 Codex 来说几乎是透明的它以为自己一直在跟官方接口说话实际上背后已经换了一套模型。Claude Code 那边的流程类似区别在于它原生走的是 Anthropic 的消息格式/v1/messages这个工具也要做一套对应的格式转换。因为两个客户端的请求结构差异很大所以这个小工具内部其实维护了好几套翻译规则这也是它最核心的价值所在。2.2 为什么 15MB 就能实现这么大的自由度很多人会怀疑15MB 能干什么做不做得好其实这类工具不需要安装 Python 运行时也不依赖大型框架它本身就是一个静态编译的二进制文件逻辑集中在请求解析、格式映射、转发这三个模块上压缩完自然很小。类比一下一个只做菜单翻译的服务员只需要一张翻译对照表就能上岗不需要会做满汉全席。小工具也同理它不承载任何模型的计算能力只负责把话传明白所以体积可以做得非常克制。更重要的是它把可自定义这件事简化成了改一个配置文件。你不需要懂 HTTP 协议不需要会写代码只要在配置文件里填上目标模型的 API 地址、API Key、模型名它就能帮你把请求转换过去。2.3 它和改配置文件、改环境变量的本质区别我之前也以为改环境变量指向一个兼容接口就够了实际跑起来才知道区别有多大。改环境变量只解决把请求发到哪不解决请求格式是否兼容。如果目标模型接口格式和客户端原生的格式不同照样报错。改客户端源码能解决格式问题但每次客户端更新都要重新适配维护成本极高。这个小工具把格式兼容和地址指向分开处理。格式转换逻辑全部由工具负责客户端配置只需要改一个端口地址改配置的工作量几乎为零。也就是说这个小工具等于在客户端和模型之间加了一个可编程的转换层。你把转换规则写在配置文件里工具帮你执行改模型只是改一行配置的事。3. 安装与接入实操三分钟让 Codex 用上自定义模型3.1 检查环境和前置依赖这个小工具对系统要求很低Windows、macOS、Linux 都可以跑。我的开发机是 macOS不过下面的操作在 Windows 上也大同小异。你需要准备的是一个小工具的可执行文件15MB 左右我把它放在~/tools/cc-switch目录下。一个终端工具。目标模型的 API 地址和 Key。如果你用的是本地模型服务比如 LM Studio 或者 Ollama那只需要确认它们已经在本地端口上跑起来。安装前先确认一下系统架构避免下错版本。在终端里跑一下uname -m如果是x86_64就选 amd64 版本如果是arm64Apple Silicon 或部分 ARM 服务器就选 arm64 版本。下错了文件一般是直接打不开或者报 exec format error。3.2 安装并启动本地转发服务拿到可执行文件之后先给它加执行权限再启动。以 macOS 为例chmod x cc-switch ./cc-switch --port 8080正常情况下终端会输出一行监听日志类似Local proxy listening on 127.0.0.1:8080这个8080就是后面要给 Codex 用的地址。如果你想换端口启动参数里改一下就行。我建议第一次启动先不要急着接 Codex先在浏览器或者终端里用 curl 试探一下转发服务是否正常响应curl http://127.0.0.1:8080/health如果返回ok之类的状态说明服务已经活了。这一步能帮你把服务没起来和配置有问题两种状况先区分开。3.3 把 Codex 和 Claude Code 指到这个转发层启动转发服务之后最关键的一步就是让 Codex 和 Claude Code 把请求发到127.0.0.1:8080。对 Codex 来说通常需要设置两个环境变量一个是接口地址一个是模型名称。在终端里这样写export OPENAI_BASE_URLhttp://127.0.0.1:8080/v1 export OPENAI_MODELmy-custom-model这里my-custom-model并不是真实模型名而是你在这个小工具配置里定义的别名。真正要用的目标模型写在工具的配置文件里比如models: - name: my-custom-model provider: openai-compatible api_base: http://localhost:1234/v1 # 本地模型服务地址 api_key: local-key model_name: qwen2.5-coder-32b # 实际请求时使用的模型名启动 Codex 的时候它会向127.0.0.1:8080/v1发请求工具收到后发现模型名是my-custom-model就从配置里找到对应的真实模型服务把请求转过去然后把模型名替换成qwen2.5-coder-32b再发给本地模型服务。这样客户端看到的还是它认识的模型名服务端收到的却是真正的模型名。Claude Code 的接法类似它一般认ANTHROPIC_BASE_URL和ANTHROPIC_MODEL这两个环境变量export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_MODELmy-claude-alias配置文件的写法跟上面大同小异只是 provider 要换成 anthropic-compatible。提示很多人在这一步图省事只设置了ANTHROPIC_BASE_URL结果发现模型根本没变。原因是 Claude Code 会优先读取它内置的模型列表只有当配置里的模型名不在它认识的列表里时它才会走自定义请求。这时候把ANTHROPIC_MODEL设成一个工具自定义的别名就能绕过这个问题。3.4 验证是否成功切换配置好之后别急着进入对话先用一个最简单的请求验证链路是否通。我习惯在终端里跑一次codex exec 你好用一句话介绍你自己如果配置成功Codex 会把请求发给本地转发服务转发服务再发给目标模型然后返回结果。你可以在终端里看到小工具打印的日志里面会显示[forward] request model alias: my-custom-model [forward] target: http://localhost:1234/v1, model: qwen2.5-coder-32b [response] status: 200, tokens: 87看到这样的日志就说明整条链路已经通了。如果只看到请求进来没有响应那大概率是目标模型的接口地址或 Key 填错了后面排查章节会细说。Claude Code 的验证类似直接运行claude -p 你好就能测。同样看转发日志确认请求是不是真的被导流到了目标模型。4. 实测体验不同模型下的表现差异与切换技巧4.1 切换速度和稳定性实测我用这个小工具在同一台机器上连续切换了几个模型包括远程 API 模型和本地模型整体感受是切换延迟很低。切换模型时的生效时间主要分两块一是改配置文件后重启转发服务的耗时几乎可以忽略二是 Codex 或 Claude Code 重新发起连接的时间一般在 1 秒以内。也就是说你改完模型配置重启转发服务再重新打开 Codex基本可以立刻用上新模型。稳定性方面连续跑了一下午的代码生成任务只有一次因为本地模型服务内存占用过高导致响应超时转发工具本身没有崩过。它只做转发不缓存状态所以只要目标模型接口稳定这条链路就是稳的。4.2 不同场景下的模型选型建议有了随时切换的能力之后反而要克制一点不是所有任务都适合同一个模型。我这几天的经验是任务类型推荐模型类型原因代码生成、函数补全代码专用的大模型指令遵循能力强生成格式稳定长文档总结、逻辑推理强调上下文理解的模型长文本处理更少出现遗忘开头内容快速试错、临时问话本地小模型延迟低成本为零写单元测试、改 bug代码能力均衡的模型需要同时理解旧代码和测试框架当然这只是基于我自己的任务类型做的粗略分类你也可以根据自己的项目特点灵活调整。4.3 会话上下文的处理避免跳闪和中断切换模型之后最容易遇到的一个问题是原对话里已经积累了不少上下文但新模型对这些上下文的处理能力不同。具体表现就是客户端界面不断跳闪或者消息刷出来一半又缩回去。我遇到过一次用 A 模型聊了十几轮切到 B 模型后Codex 界面上原来的消息列表开始不停重新渲染就像在反复刷新。排查了一圈发现是因为 A 模型的输出里包含了某些特殊格式的 markdown而 B 模型在处理这些上下文时生成的内容流式输出不稳定导致客户端以为是增量更新于是反复拉取历史消息。解决办法有两个切换模型后新建一个会话不要沿用旧会话。如果一定要沿用旧会话先执行一次对话清理把历史消息压缩到系统提示词里减少上下文长度。我个人更推荐第一种。换模型就跟换人讨论问题一样把一个不同背景的人拉进你和前任的聊天记录里他反而容易误读之前的内容不如把需求背景重新说清楚。5. 踩坑记录我从转发失败到稳定运行的过程5.1 local proxy failed while handling /responses 的根因分析这是我在刚开始使用时遇到的第一个大坑。Codex 报错信息是这样的cc switch local proxy failed while handling codex endpoint /responses. provided...第一次看到这个报错时我以为是工具本身的问题后来仔细看了小工具打印的完整日志发现它卡在解析 Codex 发来的 /responses 请求这一步。Codex 在流式对话时不只是发一个请求就完事它还会在生成过程中持续向/responses这个路径发送继续生成的控制请求比如要求服务端取消、刷新、追加内容。这个小工具在最初版本里只处理了首次请求的格式转换没有处理好后续的/responses控制请求导致客户端以为转发失败。这个问题的根源在于一部分 Codex 版本的/responses请求里带了stream: true参数并且使用 SSEServer-Sent Events格式返回数据而转发工具默认把响应当成普通 JSON 处理流式数据没被正确透传。解决办法其实不复杂升级小工具到最新版本或者手动在配置里打开流式透传开关类似server: stream_mode: passthrough打开之后转发工具会把从目标模型收到的 SSE 数据块逐字转发给 Codex不再尝试解析内容。这样/responses的控制请求就能正常往返了。重要如果你用的 Codex 版本比较新遇到这个报错优先检查stream_mode是否开启。99% 的/responses转发失败都是没开启流式透传导致的。5.2 切换后原对话不停跳闪 的解决办法前面提到过跳闪问题这里再展开说一下为什么会出现这种情况。Codex 的界面会根据 SSE 事件流刷新消息内容。当目标模型返回的内容包含不完整的 markdown 代码块、异常缩进或非常规字符时Codex 的前端解析器可能产生歧义于是反复对比当前消息和增量内容导致渲染循环。如果你也遇到跳闪先别急着换工具尝试按下面顺序排查停掉正在进行的对话先确认是历史消息跳闪还是新消息跳闪。历史消息跳闪通常是切换前模型写入的旧内容无法被新模型继续处理新消息跳闪则是当前模型生成的格式有问题。在转发工具的配置里关闭流式输出改回普通 JSON 模式。这样 Codex 只能拿到完整响应不能做增量渲染。代价是响应速度会变慢但能确认是不是流式解析的问题。如果关了流式之后跳闪消失那基本可以断定是模型输出的格式和 Codex 的 SSE 解析器不兼容。这时候要么换一个输出格式更稳定的模型要么在转发工具里加一层输出清洗规则把异常的空白字符和重复的代码块标记去掉。我自己最终的做法是把跳闪的那个模型在配置文件里单独加了一条清洗规则只保留代码块和普通文本删掉所有控制字符。之后再没出现过跳闪。5.3 最容易忽略的端口和鉴权配置很多人配置完之后连不上多半是栽在这两个细节上。第一个是端口冲突。Codex 或 Claude Code 可能自己也在监听某个端口如果转发工具监听的端口正好和系统服务冲突启动时不会报错但请求根本到不了转发工具。建议换一个不常用的高位端口比如18080并且在配置里确认指向的是这个端口。第二个是目标模型的鉴权方式。不同模型服务的鉴权头不一样有的是Authorization: Bearer xxx有的用自定义头有的干脆不需要鉴权。这个小工具的默认配置里通常会给你一个模板但你得根据目标模型的文档去填。比如本地 LM Studio 默认不需要鉴权但代码云厂的 API 需要带api-key头。填错了转发工具会收到 401 错误然后返回给 CodexCodex 就会显示认证失败。我的习惯是先在转发工具里把目标模型地址配成 curl 直接能访问的版本测试通了再让 Codex 走转发。这样能精准确定问题出在转发工具和目标模型之间还是Codex 和转发工具之间。5.4 值得养成的三个使用习惯最后分享三个我体验下来非常有用的习惯能帮你减少很多无谓的折腾。第一个改配置之前先备份一份当前配置。这个工具最大的卖点是切换模型方便但也正因为方便你可能会频繁改配置。改出问题找不到原配置的时候备份就是救命稻草。第二个定期更新工具的二进制版本。这类小工具迭代很快尤其是对 Codex 这种客户端版本更新频繁的工具不及时升级很容易遇到客户端新版接口变化导致转发失败的问题。我都是每个月更新一次顺便看一眼 changelog 里有没有针对新客户端版本的兼容性修复。第三个把启动命令写成一个可复用的脚本。比如我在~/.zshrc里加了一个别名每次打开终端直接敲csw就能启动转发服务并加载常用配置。你不用记端口也不用每次手动输入启动参数。alias csw~/tools/cc-switch --config ~/.cc-switch/config.yaml --port 18080配合 Codex 的启动脚本我可以在项目目录里一键切换模型比如csw codex就是带自定义模型启动claude --model aliases就是带自定义模型启动 Claude Code。我实际用下来最深的感受是工具本身很小但它解决的不是能跑不能跑的问题而是想换谁就换谁的自由度。过去我为了对比不同模型的代码能力要分别配置好多套环境现在只要改一行配置、重启一次服务就能在模型之间横跳。虽然偶尔还会遇到一些兼容性小坑但比起过去那种手动改源码再编译的方式已经舒服太多了。如果你也在用 Codex 或 Claude Code想试试别的模型这个 15MB 的小工具确实值得装一个。