最近升级了Codex客户端之后我一直想用最新发布的那个模型结果折腾了半天都选不上。命令行里明明指定了新的模型名回答却还是旧模型的风格想从配置文件里改改完重启还是老样子最气人的是它有时候直接甩给我一句“unknown model”不留一点线索。后来我发现身边好几个用Codex的同学都卡在这一步有人甚至直接把配置文件删了重装一遍也没解决。这篇就把我完整排查“Codex 新模型无法使用 / model选择问题”的过程写下来。从一条报错信息一路追到配置文件和环境变量再讲清楚“模型选择”的隐藏机制和常见误区。如果你正准备尝鲜新模型或者眼下正被“模型选不上”困扰这篇文章能帮你少走一大段弯路。1. 先把“新模型不可用”分分类别急着重装客户端很多人遇到新模型不可用的第一反应是删配置、重装客户端、重新登录。我这次也差点这么干后来发现这条路效率极低因为“不可用”这个说法太笼统了它至少包含三种完全不同的情况处理方式也完全不一样。1.1 三种“不可用”的症状与原因我把实际见到过的报错和现象归成了三类整理了一张对照表方便你先判断自己属于哪一种类型典型表现根源方向本地不认识模型名报错unknown model、model not found客户端的模型清单落后于官方发布配置没生效指定了模型但始终回退默认改配置文件无效环境变量或更高优先级配置覆盖服务端不放开请求能发出去但一直报权限、model not allowed或超时账号权限、灰度范围、网关侧未放量第一类最容易被误判成“客户端坏了”。实际上客户端的可用模型并不是每次运行时从服务端实时拉取的它内部很可能维护了一张静态模型清单。新模型发布之后你还是旧版本的话本地就不认这个名字你指定一百遍也没用。第二类最隐蔽。表面看是配置问题但你把配置文件翻来覆去改了好几轮它还是回退到默认模型。这种时候十有八九是环境变量的优先级把配置文件压住了。第三类属于“有劲儿使不上”的情况本地配置完全正确但是账号权限或者灰度范围还没覆盖到你。遇到这种改哪都不好使只能等放量或者联系平台管理员开通。1.2 删配置重装为什么不是好办法我刚开始以为简单粗暴能解决把~/.codex下的配置目录整个删掉再卸载重装客户端。结果问题原样复现浪费了将近二十分钟。后来我想明白了重装客户端只能解决“程序文件损坏”或者“版本太旧”这两件事。如果你的配置里写了一个新模型名但客户端根本不认识那重装旧版等于白装如果你的配置文件被环境变量覆盖重装之后配置重新生成覆盖关系还是一样问题当然还在。所以遇到“不可用”第一件事不是动手而是先判断到底属于哪一类。判断完再动手效率完全不一样。2. 从一条报错信息到根因完整排查链路下面这段是我这次真实走过的排查路径。每个步骤的目的都讲清楚你跟着做一遍基本能定位自己的问题。2.1 先把报错现场完整记下来我在终端里执行codex run 写一个读取文本文件并统计词频的Python脚本 --model codex-next-v2结果error: unknown model codex-next-v2这里有个很容易被忽略的小细节报错提示中的模型名和你输入的是否完全一致。有时候是因为命令行参数被 shell 转义了比如$符号或者反斜杠导致程序收到的模型名变成了残缺字符串。这一步虽然不能解决问题但能帮你排除“自己手滑”的因素。我确认了模型名没写错那就是客户端本身不认识这个模型名。2.2 先确认客户端的版本基线排查的第一步永远是确认版本而不是猜。我执行codex --version输出显示的版本号比我印象中的要旧。这很关键因为厂商的模型清单是跟着客户端版本走的。旧版本的内置清单里很可能根本没有新模型的名字。如果你发现版本确实落后第一步直接把客户端升级到最新稳定版很可能问题就解决了一半。至少升级之后报错会变得更具体不再是一句干巴巴的unknown model。2.3 找出“真正生效的配置”升级完客户端我再试着运行一次。这次模型名不报“不认识”了但行为还是不对请求发出去了日志里显示用的还是默认模型。接下来我要确认当前生效的模型配置到底在哪个文件里。Codex 一类工具通常会有一个全局配置目录比如~/.codex/。我执行codex config get model输出内容和我在配置文件里写的不一样。到这里基本可以确认有某种更高优先级的“配置源”插了一脚。这里值得强调所有有配置中心的工具几乎都是多级配置合并的。文件里写的只是其中一级环境变量、命令行参数都可能成为另一级。只看文件就下结论很容易被误导。2.4 环境变量最容易被忽略的幕后黑手检查环境变量是最容易跳过、也最容易翻车的一步。我执行env | grep -i codex果然列表里出现了CODEX_MODEL这样一个变量值正好是老的默认模型名。这就是真相我在配置文件里无论怎么改环境变量都会在最外层覆盖它。而且当时的终端会话早就把这个变量加载进内存了我即使修改~/.bashrc或者~/.zshrc不重启终端或者不主动取消它也依旧生效。明白这一点之后我立刻在这个会话里清掉它unset CODEX_MODEL再跑一次codex config get model配置文件里的值终于回来了。2.5 查看本地模型清单为了确认新模型名已经在本地清单里我查了一下客户端提供的模型查看命令。不同版本提供的命令不太一样有些是codex model list有些是codex list-models你在自己的环境里可以用codex --help查看。如果实在没有这个命令也可以直接去安装目录里找模型清单文件一般是 JSON 或 TOML 格式里面列出了能用的模型标识。我在新版客户端的清单里看到了codex-next-v2这个名字心里就有数了本地没有问题了后续不能被误导。3. 修复动作从改配置文件到端到端验证类型判断清楚了根因也找到了接下来就是真正的修复动作。3.1 修改模型配置的正确姿势首选做法是改配置文件因为这样对每次运行都生效而且在多人协作时更可控。Codex 的配置文件通常位于~/.codex/macOS 和 Linux或对应的用户目录下格式是 TOML。里面模型相关部分可以这样写[model] name codex-next-v2如果不想直接编辑文件也可以用配置命令修改codex config set model codex-next-v2改完之后建议先停掉所有正在运行的 Codex 相关进程再重新开启一个新终端。很多人改完配置发现不生效是因为旧终端里还挂着环境变量或者后台还有一个旧进程占着配置。3.2 环境变量的优先级什么时候该用什么时候该删大多数这类工具的优先级排序是命令行参数 环境变量 配置文件 内置默认值。也就是说你命令行写了--model命令行参数优先环境变量和配置都得靠边站没有命令行参数时CODEX_MODEL这类环境变量就能盖掉配置文件环境变量为空或没设置配置文件才轮到说话。所以如果你希望配置文件生效就要确保环境变量里没有把模型名锁死。如果团队里需要统一切换模型可以把模型名统一放到一个环境变量里比如.env文件中统一管理而不是散落在各个人的配置文件里。我个人的习惯是本地调试用命令行参数长期使用写在配置文件里环境变量只留认证信息。3.3 升级客户端保证内置清单是最新的模型清单这类东西通常跟随客户端版本更新所以升级动作不能省略。我重新安装为官方文档对应的最新稳定版后再次运行codex --version确认版本号已经变化。如果只是大版本一样但小版本落后也尽量升到当前的最新小版本。这里特别提醒升级之后最好干一件很容易被忽略的事——确认一下你的模型名是否在升级说明里出现过。有些模型在正式发布时会改名比如codex-preview改成codex-next-v2如果还用老名字选中的其实是另一个东西或者直接报错。3.4 端到端验证别只看“能回复”就完事改完之后我做了三步验证确保问题真正解决执行codex config get model确认当前生效模型名正确在日志模式下重新运行一次codex run --debug 你好看 debug 日志里请求体中的模型字段是不是codex-next-v2触发一次带抽象推理的任务观察回答风格是否有变化。为什么第三点很重要因为有时候配置生效了但模型名和另一个旧模型的跳转行为是重叠的光看能不能回复根本看不出来。到了日志请求体这一层才算真正验证通过。我这次在 debug 日志里看到请求体中已经带着新模型名之后回答也出现了明显的新模型语气和思考特征才敢确认修复成功。4. 再说透 model 选择的几个隐藏机制排查过一次之后我对“模型选择”这件事有了更深的理解。它表面上只是一个字段实际背后藏着好几个容易踩的坑。4.1 选择优先级不是“改哪都能生效”而是“谁在上面谁说了算”前面讲的是配置层面的优先级但还有一个容易被忽略的层面请求缓存的优先级。这次排查中我发现Codex 进程在启动后会缓存一份有效配置如果你改了配置文件但旧进程还没退出新请求可能依然沿用旧配置。所以我操作时专门检查了后台进程ps aux | grep -i codex但凡有残留进程先退出再验证。这一点在 macOS 上尤其常见因为 GUI 版本和命令行的进程不一定共用同一个进程管理器你以为退干净了其实后台还活着一个。4.2 模型别名方便也最容易出错Codex 这类工具通常支持模型别名比如[model] name latest这里latest是一个别名它最终会解析到某个具体模型。问题在于别名到底指向谁也是随客户端版本变的。我见过一个团队配置文件里写的是name latest新模型发布后他们以为自动就用上了。结果一查 debug 日志latest还是指向发布前的旧旗舰模型因为本地规则还没更新。所以说如果你追求的是“确定用上某个新模型”就别在关键配置里用别名直接写明确模型名。别名适合日常尝鲜不适合精确锁定。4.3 灰度发布新模型“可用”其实分两个层级还有一个大家常误解的点新模型的“可用”分成两层。第一层是“客户端本地能用”也就是刚才说的客户端静态清单里有这个名字命令行能传过去。第二层是“服务端对这个账号放开了权限”。就算本地都不报错请求也发出去了服务端可能在你的账号或者你所在的组织哪个阶段还没启用这个模型于是返回model not allowed或类似错误。遇到这种情况本地怎么调都没用。我处理过的几个案例里有同事一直在改配置最后发现是组织账号还没被拉进灰度名单。所以遇到权限类报错不如直接确认一下账号是否在灰度范围或者换一个已经确认有权限的账号做对照测试这样能快速区分是配置问题还是服务端权限问题。4.4 一个容易误判的场景模型名改了但文档没跟上模型名的变更是最坑的一种情况。厂商经常在新模型正式推送时顺手改名原来叫codex-next-preview正式版叫codex-2025-08。搜索结果里如果混着老文章你照着老文章里的模型名去配置很可能得到一个“曾经存在但现在失效”的模型名。怎么避免只信官方说明和客户端内置清单不要信任何第三方博客里的模型名——包括我现在写的这个在你看到时可能也已经过时了。命中的验证方式永远是codex config get model之后再看 debug 日志请求体里的名字才是最终真相。5. 新模型选择问题补充自查清单最后我整理了一份可以照着做的自查清单适合你下次再遇到类似问题时快速走一遍。5.1 5分钟排查顺序完整记录当前报错文案特别注意模型名有没有被截断或转义确认客户端版本codex --version落后就升级到最新稳定版查看当前生效配置codex config get model检查环境变量env | grep -i codex有CODEX_MODEL之类的就优先处理查看本地模型清单确认模型名真实存在杀掉残留进程开全新终端重新验证开 debug 日志模式看请求体中的模型字段如果请求被服务端拒绝换一个已知有权限的账号做对照测试判断是不是账号权限问题。5.2 我的几个实操建议这些是我踩过坑之后沉淀下来的习惯分享给你参考不要在生产配置里同时写多个配置来源。要么只写配置文件要么只写环境变量否则一旦环境变量的优先级盖过配置文件你排查起来会非常伤。第一次使用新模型时开一次 debug 日志。亲眼看到请求体里的模型名比一百次“应该没问题”都靠谱。升级客户端之后先看发布说明。确认模型的名称、别名指向、权限要求都变了什么再动手改配置。团队协作时把模型名固定成一个共享变量。这样大家不会因为各自的本地配置文件不一致而讨论半天。5.3 如果这些都排除了问题还可能在哪里本地全都检查正常、服务端权限也确认没问题但还是“看起来不可用”那大概率是这几个方向中间网关或转发层缓存了旧的模型清单需要刷新或联系管理员API Key 本身有权限模型范围限制换一个 Key 就能验证出来请求超时导致看起来像是模型不可用但日志时间戳能证明其实只是慢。这一步之后问题基本就不再是“模型选择”本身的事了。最后再分享一个小技巧我会在终端的启动脚本里固定一个变量来记忆当前稳定模型名比如export CODEX_MODEL_LABEL...切换新模型时只改一个地方。要升级到新版本、要回退旧版本都是一条命令的事。模型选择这件事配置本身不复杂复杂的是搞清楚谁在生效。希望这篇记录能让你下次遇到同类问题时第一反应不再是删掉重装而是准确判断、快速验证。