最近升级了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=...，切换新模型时只改一个地方。要升级到新版本、要回退旧版本，都是一条命令的事。模型选择这件事，配置本身不复杂，复杂的是搞清楚谁在生效。希望这篇记录能让你下次遇到同类问题时，第一反应不再是删掉重装，而是准确判断、快速验证。
