Codex CLI 我大概从它刚出命令行版本就在折腾了。用过的人应该都有同感这玩意儿本质上是一个把大模型编程能力直接拉进终端的 agent 工具你给它一句自然语言任务它能自己翻项目、改文件、跑命令、查报错一路干到最后。但真把它用到工作流里之后最大的困扰反而不是“会不会用”而是“该喂它哪个模型”。我平时接的是中转 API 环境也就是第三方提供的、协议兼容 OpenAI 接口的聚合服务。这类环境里能选的模型特别多从各种开源权重模型到各家闭源旗舰都有。问题随之而来不同模型在代码场景里的差距非常大有的擅长重构有的适合解释报错有的写测试特别稳还有的便宜到可以随便挥霍。如果每次切换模型都要去改配置、重启会话、重新验证连通性那效率就废了。所以我花了不少时间把 Codex CLI 的多模型切换摸了个透这篇就完整复盘一下包含配置、原理、踩坑和实测结论。这篇文章适合这几类人正在用中转 API 接 Codex CLI、但对配置不熟的新手已经在用但觉得“一个模型走天下”不够用的人以及想在自己的脚本或自动化流程里动态切换模型的人。全文不涉及复杂前置知识基本照着做就能跑通。1. Codex CLI 和中转 API 的适配逻辑1.1 Codex CLI 到底是个什么东西先把这个工具的本质说清楚。Codex CLI 是 OpenAI 推出的命令行编程代理它的核心能力不是简单的“问答”而是以 agent 的方式直接操作你的本地项目。你给它一个任务它会自主决定看哪些文件、跑什么命令、改哪里然后循环执行直到任务完成。这个过程中它需要持续调用大模型所以模型的能力直接决定了它的上限。Codex CLI 和各种第三方模型服务能搭起来关键在于它的配置是开放式的。它不像某些工具把模型服务写死在代码里而是通过一个config.toml配置文件来声明“模型服务商”。你可以在里面自定义 provider指定base_url、api_key的环境变量名、以及使用的接口协议。换句话说只要对方提供的是 OpenAI 兼容接口你就能把 Codex CLI 接到任意模型服务上。中转 API 平台恰好就是这样一类服务它们通常会在一个统一的地址下聚合多家上游模型的调用能力这就为多模型切换提供了天然的土壤。1.2 中转 API 环境的特殊之处中转 API 平台的核心逻辑很简单它给你一个统一的 base_url 和一把 api_key你请求它它再转发到真正的模型厂商。这种模式下你不需要分别去各个模型厂商的官网注册账号、绑定支付方式只需要在中转平台里充值然后通过模型名来指定你要用哪个模型。这个模式给 Codex CLI 带来的好处是极其明显的。你在本机只需要维护一个 provider 配置然后把模型名当作一个可变参数。想用开源模型微调出来的专用模型也行想切到闭源顶级模型跑一次高难度重构也行只要中转平台支持Codex CLI 这边只需要换一个--model参数或者改一行配置。成本、速度、能力范围全都可以在中转平台上统一管理。要注意的是中转 API 的路径格式通常和官方不完全一样。大多数平台要求你把 base_url 配置到/v1这一级但也有的平台提供了自定义路径转发。后面我会专门讲这一块的坑。1.3 为什么多模型切换是刚需可能有人会问我认准一个好模型不就行了我实测下来真不是这样。首要原因是成本。旗舰编程模型的输入输出定价都不便宜如果你所有的操作——包括让 AI 生成一句 commit message、给变量重命名——都走最贵的模型那每个月的账单会很酸爽。而很多中等规模的模型在简单任务上表现完全够用价格却可能差一个数量级。其次是能力差异。不同模型在代码生成上的主观感受差异很大。有的模型在“理解整个项目结构、跨文件重构”这种复杂场景里明显更强有的模型在“给一大段晦涩代码写注释”时反而表现得更好还有的模型没有那么强的推理能力但你拿它做文本规范化、生成格式化输出速度和稳定性都很好。把这些模型全部接进来按任务类型分配才是效率最大化的玩法。还有一类需求来自模型评测和迁移测试。比如你正在评估一个新出的开源模型能不能替代当前主力模型或者想验证某个模型中转平台是否真的转到了上游而不是偷偷降级。这时候你就需要一个能快速在多个模型间切换的环境并且能明确看到实际调用的是哪个模型。2. 环境准备从安装到跑通第一句对话2.1 安装 Codex CLI 的几种方式Codex CLI 官方提供了多种安装方式但我实测最省事的是 npm 安装。只要你的机器上有 Node.js并且版本在 18 以上一条命令就能装完npm install -g openai/codex如果你不想依赖 Node.js 环境官方也提供了原生二进制安装方式一个 curl 脚本就能完成。不过在 Windows 上我更推荐 npm 方式原因是原生二进制的依赖项和 PATH 配置在 Windows 上问题更多一些。装完之后可以在终端里验证一下codex --version如果能看到版本号输出说明安装这步已经过了。这一步看似平平无奇但实际上有大量用户卡在下面这个报错上。2.2 高概率踩坑unable to locate the codex cli binary最近网上这类报错的讨论很多典型信息是chatgpt failed to start. unable to locate the codex cli binary or required runtime components.这个报错看起来很唬人其实说白了就是系统找不到codex这个可执行文件或者找到的路径不对。我从 Windows 和 macOS 两个平台分别排查过绝大多数原因都一样PATH 环境变量没有刷新。npm 全局安装后可执行文件会被放到 npm 的全局 bin 目录下。在 Windows 上通常是这样几个路径之一%APPDATA%\npm C:\Users\你的用户名\AppData\Roaming\npm但问题是很多 Windows 终端尤其是已经开着的 Windows Terminal、PowerShell 窗口在你安装完 npm 包之后不会自动刷新 PATH。你在这个旧窗口里执行codex系统自然找不到。解决办法很简单关掉当前终端窗口重新开一个新的。如果新窗口还是报同样的问题那就需要手动检查 PATH。检查方法是在终端里执行npm prefix -g拿到全局根目录后把%APPDATA%\npm或者对应的 bin 路径加到系统环境变量 PATH 里。具体操作是Windows 设置里搜“编辑系统环境变量”在“环境变量”面板中找到 Path新增一条路径确定后重开终端。macOS 上也有一种同类情况就是 npm 把可执行文件装到了/opt/homebrew/bin或~/.npm-global/bin但你的 shell 配置文件.zshrc里没有把它加进 PATH。修改完.zshrc后记得执行source ~/.zshrc或者直接重开终端。还有一个容易忽略的坑如果你装过旧版 codex新版安装后 PATH 中残留了旧路径。建议先执行一次which codexWindows 上是where codex看看实际指向的是不是新版安装位置。我遇到过 PATH 前面的旧目录里有一个损坏的 codex 文件导致总是报错删掉旧文件后才正常。2.3 跳过官方登录直接跑通本地配置Codex CLI 官方流程通常建议你执行codex login来登录账号。但如果你用的是中转 API这一步其实可以完全跳过。你需要的只是在中转平台注册并创建一把 API Key然后把 Key 配置到 Codex CLI 的配置里就能直接跑通。我推荐的验证方式是先建一个临时目录在目录里执行一条最简单的命令codex exec hello如果配置正确Codex CLI 会调用你配置好的模型返回一句问候或者其他回复如果配置有问题报错信息会直接告诉你哪一步不对。后面第三节我会给出完整的配置内容这里先建立一个基本认知中转环境下配置文件的优先级高于官方登录状态你完全可以做一个“永不登录”的 Codex CLI。3. 中转 API 的接入与核心配置3.1 一个能用的 config.toml 长什么样Codex CLI 启动时会读取用户目录下的~/.codex/config.tomlWindows 上是C:\Users\你的用户名\.codex\config.toml。这个文件是 TOML 格式所有核心配置都在这里。下面是我实际在用的一个中转 API 配置模板你可以直接抄作业model gpt-5-codex-medium model_provider my_aggregator model_providers: my_aggregator: name My Aggregator base_url https://api.example.com/v1 env_key AGGREGATOR_API_KEY wire_api chat这里解释一下每项的用途model默认启用的模型名。它会出现在每次 Codex CLI 调用的请求体里中转平台根据这个名字路由到实际模型。model_provider指定走哪个 provider。这个字段很重要即使你只配了一个 provider也建议显式写出来避免 Codex CLI 因为找不到默认 provider 而报错。model_providers自定义服务商的列表。base_url是中转平台的接口地址env_key指定从哪个环境变量读取 API Key。wire_api接口协议类型。绝大多数中转平台兼容 OpenAI 的 chat 协议所以填chat如果你的上游是 responses API 风格再选择对应取值。env_key对应的环境变量需要在终端里提前设置好。比如在 macOS/Linux 上export AGGREGATOR_API_KEYsk-你的中转密钥Windows PowerShell 上是$env:AGGREGATOR_API_KEYsk-你的中转密钥强烈建议不要直接把 Key 明文写进 config.toml因为配置文件很有可能会被同步到 Git 仓库或者分享给别人。用环境变量引用既能保证配置文件的通用性又能降低密钥泄露风险。3.2 环境变量覆盖与定时切换的巧用除了配置文件Codex CLI 也支持一些环境变量来覆盖默认行为。这个特性在“多模型切换”场景里非常实用。比如你把默认模型配置成便宜型号但在执行某个高难度任务时想临时切到旗舰模型又不想改文件可以直接在启动时用--model参数codex --model gpt-5-codex如果你的中转平台里每个模型对应不同的 API Key比如不同资源池你甚至可以在同一终端会话里先重设环境变量再启动 codexexport AGGREGATOR_API_KEYsk-高权限池密钥 codex --model expensive-model这种方式适合在自动化脚本里做定时或条件切换后面第四节我会给出一套完整的 shell 封装方案。3.3 Base URL 的路径陷阱与连通性验证中转 API 接入时最容易翻车的就是base_url的路径层级。有的平台给你的是根域名比如https://api.example.com但 OpenAI 兼容接口的真实路径是https://api.example.com/v1。如果你只填根域名Codex CLI 会向https://api.example.com/chat/completions发请求而不是https://api.example.com/v1/chat/completions结果就是 404。反过来有些平台在控制台里给你的是一个完整的/v1地址你自己又额外拼了一个/v1变成/v1/v1同样会报错。一个可靠的验证方法是先用通用 HTTP 客户端测试连通性比如 curlcurl https://api.example.com/v1/models \ -H Authorization: Bearer $AGGREGATOR_API_KEY如果返回模型列表说明地址和 Key 都没问题如果返回 404 或者 401优先检查路径层级和 Key 前缀。这里多说一句很多中转平台的 Key 以sk-开头但不是所有平台都这样千万不要写死判断逻辑。4. 多模型切换的实战玩法4.1 方案一同一个 Provider 下切换 model 名最基础的多模型切换就是让所有模型走同一个中转入口只改变model字段的取值。这种方式的优点是配置最简单你只需要记住中转平台支持的模型名列表启动时用--model指定即可。我可以直接给你几个示例命令# 用开源中等模型处理日常问题 codex --model qwen3-coder-30b # 用旗舰模型做跨文件重构 codex --model gpt-5-codex-medium # 用轻量模型快速生成 commit message codex exec --model deepseek-v3 根据 git diff 生成简洁的 commit message这里要注意一个细节中转平台上的模型名可能和模型厂商官方名字不完全一致。有的平台会加前缀或后缀比如gpt-5-codex-202505XX有的平台对开源模型做了量化版本名字里带-q4之类的标识。最稳妥的办法是调用中转平台提供的/v1/models接口把返回的模型名列表存下来切换时从中选而不是凭记忆手敲。4.2 方案二配置多个 Provider按服务商切换如果你同时使用多个中转平台或者一个中转平台下分了多个资源组那么可以考虑在 config.toml 里配置多个 provider。下面是一个双 provider 的示例model_provider agg_a model_providers: agg_a: name Aggregator A base_url https://api-a.example.com/v1 env_key AGG_A_API_KEY wire_api chat agg_b: name Aggregator B base_url https://api-b.example.com/v1 env_key AGG_B_API_KEY wire_api chat切换 provider 时在启动命令里加上--model-provider参数codex --model-provider agg_b --model claude-sonnet-4这种多 provider 方案适合什么场景呢通常是模型货源隔离。A 平台在某类模型上速度更快、更稳定B 平台在另一类模型上价格更低。把它们都配置好你在一个终端里就能随时比价、比速度、比效果不需要改动配置文件。4.3 方案三Shell 函数一键切换体验最顺手前面两种方案都要手敲--model参数参数一长就烦人。我个人最推荐的方式是把模型切换封装成 shell 函数用一个短语就能唤起特定模型组合。举个例子在~/.bashrc或~/.zshrc里加入这样一段cx() { local provider${CODEX_DEFAULT_PROVIDER:-my_aggregator} local model${1:-gpt-5-codex-medium} shift 2/dev/null codex --model-provider $provider --model $model $ }然后你在终端里就能这样用# 默认模型 cx 帮我看一下这个项目结构 # 临时切换到指定模型 cx qwen3-coder-30b 这个函数哪里性能有问题如果你想给特定任务绑定固定模型可以再封装一层migrate() { codex --model gpt-5-codex-medium 分析这个仓库并帮我完成数据库迁移脚本 } fix() { codex --model qwen3-coder-30b 修复当前分支的编译错误不要改动业务逻辑 }Windows 用户可以在 PowerShell 里做同样的事定义一个函数function cx { param( [string]$Model gpt-5-codex-medium, [string]$Prompt ) codex --model $Model $Prompt }这种封装的意义不只是少敲几个字更重要的是它把“模型选择”和“任务类型”做了语义绑定。时间一长你的肌肉记忆会变成“提交代码前用 cx commit、重构用 cx refactor”效率提升非常明显。4.4 非交互模式在自动化流水线里动态选模型Codex CLI 不只是交互式工具它还提供了非交互模式codex exec适合在脚本里调用。先指定模型再传入任务描述命令执行完就退出非常适合接入 CI/CD 或定时任务。我在实际项目里用过两个典型场景。第一个是自动生成 commit messagegit diff --staged | codex exec --model cheap-model \ 根据以下 git diff 生成一个符合 conventional commits 规范的 commit message第二个是自动代码审查codex exec --model review-model \ 审查当前分支相对 main 分支的改动重点关注潜在的并发安全问题和边界条件处理codex exec的优势是它可以非交互地执行完整 agent 流程也就是不仅回答问题还会实际读文件、跑命令、改代码。这使得你可以在批处理脚本里对多个仓库执行同样的任务再根据任务难度动态决定用哪个模型。构建脚本时建议把模型名抽成环境变量由上层调度器统一控制而不是硬编码在脚本里。5. 模型选择的思路与实测对比5.1 不同任务该选什么模型一份实测参考我断断续续在中转 API 环境里试过好几类模型下面这些结论带有主观色彩但至少能作为一个初始参考。需要先说明的是具体的模型名和版本会随时代变化我更想传达的是“分类匹配”的思路。任务类型推荐模型档位参考性价比我的实测感受跨文件重构、整体架构分析旗舰代码模型贵对项目上下文理解深能在多个文件之间做一致性修改解释报错、单函数修复中端代码模型适中速度更快普通 bug 没必要上旗舰生成单测、重复性编码开源中等模型便宜只要 prompt 写清楚测试生成质量完全可用生成 commit message、格式化轻量模型很便宜主打省 token输出稳定就够复杂算法题、逻辑推理推理增强模型贵推理链路长适合用带思维链的模型文档撰写、注释补全任意模型按需对模型能力要求不高上下文长度更重要我个人的习惯是“默认用中端模型复杂任务手动切旗舰”。一开始我想着“反正都接上了全用最强的”结果账单数字很难看。后来改成这种策略一个月下来成本降到原来的三分之一不到而任务完成质量基本没下降因为真正需要旗舰模型的场景其实没有想象中那么多。5.2 别忽略上下文窗口和 max_tokensCodex CLI 是 agent 模式它每次执行任务都会携带你已经展开的对话记录、当前文件内容、命令输出等上下文。上下文窗口小的模型可能任务进行到一半就“忘记了”前面的信息表现非常不稳定。所以选模型时优先看上下文窗口能不能覆盖工程项目会话的典型大小再比较单价。另一个隐蔽的参数是max_tokens。Codex CLI 在一些配置场景里会限制输出 token 数如果设得太小模型可能写到一半就被截断表面现象是“代码不完整”或者“生成结果突然中断”。如果你发现模型频繁在长输出时截断优先检查是不是 max_tokens 设置问题。在多模型切换时不同模型对 max_tokens 的支持也有差异有的中转平台对单次输出的上限有硬限制模型再强也无济于事。5.3 token 用量追踪与成本控制技巧Codex CLI 在会话结束时会显示本次会话的 token 消耗和费用估算。但这个统计只针对当前会话长期汇总还得靠中转平台的控制台。你可以定期把各模型的花销导出来按任务类型归类就知道钱花在哪了。我在成本控制上的三个实用技巧第一个是“默认便宜手动昂贵”。顶层配置里的model字段永远填便宜模型只有在需要时用--model临时覆盖。这样即使你忘了指定模型跑出来的账单也不会离谱。第二个是“给高成本模型加护栏”。把旗舰模型的使用场景封装成独立 shell 函数只在关键操作时调用。比如只有migrate、refactor这种高风险任务才用旗舰日常问答一律走中端模型。第三个是“长对话及时止损”。agent 模式下对话越长上下文越大单次调用的钱越多。发现任务目标已经偏离或者上下文已经很长但还没有解决方向果断开启新会话重新描述问题往往比继续硬推更省钱。6. 常见问题与排查技巧实录6.1 认证报错401 和 403这类报错的含义是认证失败或权限不足。排查顺序如下先确认环境变量是否真的被 Codex CLI 读取到了。有时你在.zshrc里设置了变量但当前终端会话是在修改之前启动的变量尚未生效。执行echo $AGGREGATOR_API_KEYWindows 上是echo $env:AGGREGATOR_API_KEY看看输出是否为空为空就是没读到。再确认 config.toml 里的env_key拼写是否和环境变量完全一致。大小写错误、多了下划线都可能导致 Codex CLI 读取到空 Key。然后到中转平台的控制台看看 Key 是否过期、是否被限流。有的平台对同一 Key 的并发数有要求短时间大量请求也会触发临时封禁。6.2 模型不存在404 model_not_found报文里如果明确告诉你 model 不存在最可能的原因是模型名和中转平台实际的命名对不上。不要猜测直接调用中转平台的模型列接口curl https://api.example.com/v1/models \ -H Authorization: Bearer $AGGREGATOR_API_KEY把返回结果里的 id 字段抄下来再去 config.toml 或启动命令里使用。千万注意有的平台对模型名大小写敏感GPT-5和gpt-5可能完全是两个结果。6.3 一直在转圈 / 请求超时如果 Codex CLI 发出请求后长时间无响应先确认网络到中转平台的连通性。用 curl 请求一个极小的模型接口如果能顺畅返回说明网络没问题如果卡住大概率是中转平台的线路在特定时段不稳定或者你的出口网络到该平台的路由质量差。这时可以考虑换一个中转平台的备用域名、切换 provider或者设置更长的超时时间。另外有些模型本身推理速度就慢比如带深度思考模式的推理模型响应时间几十秒是常态。建议给这类模型单独配置一个 provider避免和快速模型的超时设置混在一起。6.4 模型“变笨”了可能根本没切换成功这是非常隐蔽的一个问题。有时候你明明在命令行传了--model结果 Codex CLI 还是用的默认模型。原因往往是 Codex CLI 的配置加载顺序问题默认值、配置文件、环境变量、命令行参数不同来源的优先级不同。如果你同时在配置文件里写了model A在环境变量里设了CODEX_MODELB又通过命令行传了--model C最终生效的可能不是你想的那个。我的排查方法是在启动 Codex CLI 之前先显式声明当前环境变量echo $CODEX_MODEL有值就先清掉避免干扰。然后路径收敛为两种日常用 shell 函数固定模型临时用--model覆盖。不要同时维护多套配置来源否则迟早被优先级问题坑到。6.5 报错速查表报错信息主要原因解决建议unable to locate the codex cli binaryPATH 未生效或安装路径异常重开终端、检查 npm 全局 bin 路径401 unauthorizedAPI Key 缺失或错误检查 env_key 命名、环境变量值404 model_not_found模型名不被平台支持调用 /v1/models 查真实模型名请求超时网络到中转平台不稳定换备用域名、调整超时、换 provider输出截断max_tokens 过小或平台上限调大输出限制、换支持更长输出的模型模型名没生效配置来源优先级冲突清除 CODEX_MODEL 环境变量统一入口6.6 最后再分享一个小技巧如果你经常在“多模型对比”场景下工作可以给每个模型单独起一个 shell 别名比如cgpt、cqwen、csonnet每个别名内部写死 provider 和 model。这样做的直观好处是你不需要记住模型名甚至不需要记住它们的价格档位。看到别名就知道自己要用什么。我实际用下来还有一个体会不要一开始就把所有模型堆进 config.toml而是先选两三个覆盖面足够广的模型用一周摸清它们在你项目里的真实表现再逐步扩充。模型不是越多越好真正顺手的那两三个才是你日常效率的支柱。