新模型发布之后我第一时间打开终端敲了codex --version。不是急着体验而是这种工具你越早遇到新模型无法使用、模型选择不生效的问题越容易在排查上浪费时间。Codex 这类 CLI 工具的新模型上线从来不是模型发布了我就能直接用这么简单。你可能会遇到交互界面里根本看不到新模型、用参数指定却报 unknown model、明明切换了模型但下一轮对话又回到旧模型。这篇就从模型选择的机制讲起把排查链路和实操步骤一起梳理清楚给遇到同样问题的读者一条能照做的路线。1. Codex的模型选择机制默认模型、参数与配置的优先级1.1 模型清单从哪来先说一个很多人没意识到的点Codex CLI 在启动时会加载一份当前版本支持的模型注册表。这份清单决定了你能够在交互界面里看到哪些模型、命令行里能识别哪些模型名。它跟官方发布的模型列表之间有时间差——新模型可能已经在官方后台发布但你的 CLI 版本还停留在旧的模型清单上自然就看不到、选不了、报错不认识。我常把这个机制类比成手机系统的应用商店应用上架了不代表你的手机商店里立刻就有你得先把系统/商店版本更新到最新再刷新列表才能看到。Codex 的模型注册表也一样捆绑在安装包或本地组件的版本中。所以遇到新模型无法使用的问题第一种高频根因就是本地组件版本太旧。1.2 三种指定模型的方式在 Codex 里指定模型有三大入口这决定了你后续排查的方向。第一是交互式命令。在运行中的 Codex 会话里输入/model会弹出当前会话可用的模型列表通过方向键或编号选择。它只对当前会话生效关闭会话就失效。这是最直观的方式但也是很多人误以为我已经选了新模型的地方因为下次启动又恢复成默认模型。第二是启动参数。运行 Codex 时直接加--model或常见简写-m比如codex --model gpt-5-codex这种方式一次性指定本次运行使用的模型适合临时验证。它的优先级很高但同样不持久你下次不写这个参数它就不会沿用。第三是配置文件。Codex 会把用户级配置存在~/.codex/config.toml这类路径下。在配置里写model gpt-5-codex相当于给所有未显式指定模型的会话设定默认值。这是只想改一次之后每次都用新模型的正解。三种方式的优先级大体是命令行参数 配置文件 内置默认值。交互式/model在会话期内会覆盖配置文件指定的模型但不会反过来改写配置文件。1.3 为什么新模型不出现把上面机制理清之后所谓新模型无法使用/模型选择的问题其实就对应几个具体原因本地 CLI 版本旧模型注册表里根本没有新模型。输入了官方发布的新模型名但名字拼写或带不带日期后缀不一致CLI 不识别。当前 API Key 或账户没有被授权访问该模型请求被拒绝。切换模型后没有新建会话旧会话快照继续沿用之前模型。配置项里model被误写成其他字段名导致配置静默失效。后面两类尤其隐蔽因为 CLI 不一定给你明显报错。你可能看到的是没报错但回答风格还是旧模型或者一切正常但新模型的能力完全没体现出来。我把这些典型表现单独列一节方便你对号入座。2. 新模型无法使用的典型表现先对号入座2.1 报错 unknown model 却查不到最常见的报错是类似unknown model: gpt-5-codex或invalid model。这时候先别怀疑官方参数写错了绝大多数情况是本地 CLI 版本不认识这个名称。我遇到过一次很典型的情况官方文档已经更新了某个新模型的代码示例我也照抄了但 CLI 依然报 unknown model。后来一查本地版本落后了两个小版本。升级之后同样的命令立刻生效。所以这个报错第一顺位排查项是版本不是拼写。2.2 不报错但仍在用旧模型这比报错更磨人。你运行 Codex输入内容感觉回复风格和能力都不像新模型但没有任何错误提示。原因通常是你先前用旧模型开过一个会话这次只是恢复了历史对话。会话恢复时会沿用快照记录的模型信息新模型根本没有被吸入。也有一种情况是配置文件里的默认模型没改你以为交互式/model选择过一次就永久生效了其实它只作用在那个会话里。下次启动默认又回去了。判断方法很简单看对话上下文是否保留保留的话模型大概率也停留在旧状态。2.3 切换模型只对当前会话生效下个会话又失效交互式/model切换模型后的效果范围很多人会高估。我明明选了新模型为什么重启后还是旧的——因为交互式选择不写配置文件它的生命周期绑定在会话上。想要跨会话默认使用新模型必须在配置里落盘。如果你在工作中经常同时开着多个项目目录、多个终端窗口这个问题尤其明显。每个终端首次启动都可能读取同一份默认配置你上个终端里/model的选择自然影响不到这个新终端。3. 从报错文本到根因的排查链路3.1 先确认 CLI 版本与模型清单是否同步排查永远从版本开始。运行codex --version拿到版本号之后对照官方发布说明确认你当前版本是否已经支持目标模型。一个实用经验如果版本号落后至少一个主/次版本先升级再讨论其他原因否则往下排查大概率是白费功夫。如果版本已经是最新但依然找不到模型再往下看模型名称与权限。3.2 再核对模型名称与别名这里的坑在别名和全名上。同一个模型对外宣传名、API 模型 ID、CLI 注册名可能是三套写法。你在文档里看到的名称未必是本地 CLI 能直接识别的那一个。一个稳妥的办法是用交互式/model打开列表看当前 CLI 实际提供了哪些模型名。列表里没有的名字命令行参数写得再对也没用。列表里有的名字直接抄下来放到启动参数或配置里不容易出错。如果你确实需要命令行快速指定可以拿列表中的名称作为基准而不是凭记忆抄文档。3.3 用返回码区分权限与名称问题CLI 底层调用服务端接口时错误码是很好的诊断信号。我在实践中把常见的情况整理成了一张对照表现象返回码或特征主要根因处理方向unknown model / invalid model404 或本地直接拒绝CLI 版本未收录模型名 / 名称拼写错误升级 CLI、用/model列表核对名称请求被拒绝403当前 API Key 没有该模型权限检查账户权限、确认 API Key 是否有该模型的访问资格认证失败401API Key 失效或未正确加载重新登录、刷新凭证、检查环境变量无报错但模型不变无明显错误会话快照保留旧模型 / 默认配置未改新建会话、修改配置文件交互式能选 / 命令行无效无明显错误--model参数没被实际传入检查参数拼写、验证 wrapper 脚本是否有额外覆盖这张表不是让你背而是排查时按行对号入座。我之前遇到过一次 403折腾了半天模型名最后发现是 API Key 对应的权限范围不含那个新模型换个有权限的凭证立刻就好。3.4 检查会话状态与配置文件残留如果报错和权限都排除了就要想会话状态。旧会话上下文会锁定当时使用的模型所以尝试--model指定新模型后建议直接用/new开启新会话别在旧会话里接着问。旧会话相当于一个装着旧模型状态的容器新参数很难挤进去。配置文件残留也要看。Codex 读取~/.codex/config.toml时如果你之前手动编辑过配置里面可能保留了旧模型名、旧的模型供应商配置或者干脆字段写错了。一个常见的低级错误是model_name gpt-5-codex看着挺合理但没有被识别正确字段是model gpt-5-codex这种静默失败最坑因为不报错就是没效果。检查配置文件时逐行核对字段名不要凭印象。3.5 我的排查顺序小结如果你现在正卡在问题里按这个顺序走大概率能定位升级 CLI 到最新版本。用codex --version确认升级成功。启动交互式会话输入/model查看列表里是否有目标模型。有 → 手动选择然后用/new开新会话验证。没有 → 检查 API Key 权限和账户模型授权状态。想在之后每次默认使用 → 改配置文件model字段再开新会话。这套链路实际测试下来能覆盖九成以上的新模型无法使用场景。4. 实操让新模型立即生效4.1 升级 CLI 到包含新模型注册的版本升级是很多问题的解药。Codex 的 CLI 一般走官方提供的安装渠道比如包管理器或安装脚本。最稳妥的操作是在官方文档里找到当前系统对应的安装命令然后重新执行一遍让本地组件更新到最新版本。升级完成后再跑一次codex --version确认版本号已经变化。如果升级后依然没有新模型再考虑是否卡在模型权限上。这里有个容易被忽视的细节很多用户是通过 Node 包管理器或 Homebrew 安装的 CLI。这类安装方式在源仓库更新后需要显式执行升级命令不会自动更新。我看到过不少案例用户以为装过了就是最新版实际版本停留在几个月前自然识别不了新模型。4.2 交互式查看可选模型并切换升级完成后最快验证模型是否可用的方式就是交互式会话。在任意终端运行codex进入交互界面后输入/model此时界面会列出当前 CLI 识别到的可用模型。如果目标新模型出现在列表里直接选择即可。然后输入/new开启一个干净会话再随便问一个能体现模型能力的问题确认它真的在工作。这个验证步骤别省因为能选和能用之间还隔着权限验证只有实际提问成功才说明链路全通。4.3 用配置文件持久化默认模型如果你希望每次启动 Codex 都默认使用新模型改配置文件是最省事的方式。打开~/.codex/config.toml具体路径以你本机实际为准把模型配置写成model gpt-5-codex注意模型名要和/model列表里显示的一致。保存后重新启动 Codex再用/model查看当前选中项确认默认值已经变化。配置文件的好处是稳定。它不依赖你每次启动时手输参数也不会因为忘记参数而悄悄回到旧模型。尤其是在多终端、多项目场景下配置文件能保证所有新会话的模型起点一致。4.4 用 --model 参数启动即用如果你只是临时想跑一次新模型不想改动全局配置那启动参数最合适codex --model gpt-5-codex这适合做对照实验同一段提示词分别用旧模型和新模型跑一遍比较输出差异。注意参数指定的模型在本次会话内生效如果你想这条命令之后每次都生效还是得写进配置。4.5 验证新模型是否真正生效怎么确定生效了不要只看界面显示。我推荐两个验证点一是看会话信息。Codex 在会话启动时会在日志或状态信息里标记当前模型交互式/model打开的列表里也会高亮当前项。如果高亮项还是旧模型说明配置或参数没生效。二是看实际输出。新模型通常在推理质量、响应格式或特定任务上有可感知的差异。拿一个你能判断对错的小问题去测试比如让模型写一段逻辑明确的代码或者解释一个你已经知道答案的概念。如果输出明显和旧模型一致大概率模型没切换成功。5. 容易踩的坑与经验补充5.1 参数覆盖顺序可能反直觉很多人以为交互式/model选完模型就一劳永逸了实际上它的生效范围是当前会话。如果你同时配置了--model参数和 config.toml命令行参数优先如果你在会话里/model切换了又临时改配置并重载配置不会覆盖当前会话的选择。理解这个覆盖顺序能避免你反复修改但看不到效果。5.2 新模型上下文格式可能变化新模型上线后如果它的上下文组织方式、工具调用格式和旧模型不同直接恢复旧会话可能会出兼容性问题。最好的做法是新模型配合新会话使用不要试图把旧会话直接搬到新模型上。我在实际使用中就碰到过旧会话里带着大量历史记录切换到新模型后我期待新模型的能力但输出依然被旧上下文的格式限制住了。开启/new之后表现立刻正常。5.3 账户权限与 API Key 不匹配模型名称正确、CLI 版本最新但请求依然失败时往账户权限方向查。这里要区分两类权限一类是账户层面是否被允许使用该模型另一类是当前 API Key 的作用域是否包含该模型对应权限。我的经验是不要只看API Key 有效就放心有效只代表身份验证通过不代表它有权限调用新模型。遇到 403 时去检查凭证的权限范围必要时重新生成一个包含目标模型权限的 Key。这个点技术文档里往往写得隐晦但实际踩坑频率很高。5.4 配置里的字段名别想当然配置文件是给人看的字段名自然有语义但 Codex 并不是把所有看着合理的名字都认下来。model就是model不是model_name也不是model_id。写错字段时配置会被读取但配置项没匹配上于是静默回到默认模型。这种问题不报错隐藏性极强。改完配置后务必用/model看当前高亮项而不是看一眼文件就完事。5.5 升级后本地缓存不刷新的问题有些用户在升级 CLI 之后依然看不到新模型是因为本地缓存还留着旧版本的模型注册表信息。这种情况不常见但如果出现可以尝试清理本地 CLI 的缓存目录让它重新加载。清理缓存前注意它会清掉本地保存的会话历史和登录状态你需要重新登录。所以这是最后手段不要一上来就清缓存。在我的工作流程里缓存清理被列为明确前因后果才能动的操作。清缓存之前先确认版本号确实变了、模型名确实在官方列表里、API Key 权限确实到位。只有这些条件都满足还看不到模型才考虑清缓存重建本地状态。最后分享一个我常用的做法每次有重要的新模型上线我会写一个小脚本用--model参数带上新模型名跑一个固定测试问题输出结果保存下来。这样既能快速验证模型是否可用也为以后对比不同模型的表现留下样本。如果你正在被 Codex 的新模型问题卡住按上面的链路走一遍。先升级再查名字然后看权限最后检查会话和配置。这套顺序我踩过不少坑才总结出来照着做比到处搜报错信息要快得多。