GPT-5.4 八月三十一号从 Codex 退役：迁移前要改的五处，以及漏改会怎样

2026-08-09

Codex（OpenAI Codex）官方文档《Models》页写得很直白：“GPT-5.4 and GPT-5.4 mini retire from Codex on August 31, 2026.”（核对日 2026-08-09，以官方最新说明为准）。

如果你是第一次处理这类退役迁移，很容易把它理解成”到时候在对话框里换个模型就行”。实际不是。官方在同一处点名了五个需要一起改的位置：workspace 默认模型、保存的模型设置、managed config（受管配置）、自定义 agent、计划任务（scheduled tasks）。这五处里任何一处还写着 gpt-5.4，8 月 31 日之后都会出问题——而且出问题的时候，你很可能不在场（比如计划任务是半夜跑的）。

这篇就按”第一次做”的顺序走一遍。每一步我都会说清两件事：为什么要改这里，以及漏掉它会怎样。

先记住替换关系，只有两行

官方给定的迁移映射就两条：

旧模型（要退役）	官方给的替换
`gpt-5.4`	`gpt-5.6-terra`
`gpt-5.4-mini`	`gpt-5.6-luna`

为什么要照抄这两行、不要自己发挥：模型名一律是小写连字符的原名，写成 GPT-5.6 Terra 或者 gpt5.6-terra 都不是同一个字符串。配置文件里模型名写错，不会因为”看起来差不多”就被容错。

顺带提一句：官方另外把 gpt-5.2、gpt-5.3-codex 标记为 deprecated。它们和 8 月 31 日这条退役公告不是一回事，但如果你在翻配置的时候正好看到这两个名字，说明这份配置已经有一阵子没人动过了，一并处理掉更省事。

至于换过去之后拿到的是什么，官方《Models》页给的定位是这样（星级与描述均来自该页，核对日 2026-08-09）：gpt-5.6-terra 是”平衡型、日常工作用”，能力 4 星 / 速度 3 星；gpt-5.6-luna 是家族里成本最低的一档，能力 3 星 / 速度 4 星。另有旗舰 gpt-5.6-sol，能力 5 星 / 速度 2 星。这里不要顺手把所有位置都改成 sol——理由在后面”云端那一节”里讲，先按官方映射一一对应地换。

第 0 步：先把”到底有几处写着 gpt-5.4”找出来

新手最常见的错法是”想到哪改到哪”，改完自己也说不清还剩几处。先做一次盘点，后面才有得验收。

CLI 这一侧最好查：配置文件在 $CODEX_HOME/config.toml，默认就是 ~/.codex/config.toml（Windows 上即 <你的用户目录>\.codex\config.toml）。用你顺手的编辑器打开这个文件，把 gpt-5.4 当关键词搜一遍，重点看这几个键：

键	作用	漏改的后果
`model`	会话使用的模型	主线全挂
`review_model`	`/review` 专用模型；不设则继承会话模型	平时不报错，只有走评审时才炸
`agents.default_subagent_model`	子代理默认模型	主会话正常，派出去的子代理不正常
`model_catalog_json`	启动时加载的模型目录 JSON	问题被挪到另一个文件里，搜 config.toml 搜不到

review_model 这一条特别值得单拎出来说：它不设的时候是继承会话模型的。所以有两种情况——你要么根本没写过这个键（那改 model 就顺带解决了），要么当初专门给评审指定过一个便宜模型（那它极可能就写着 gpt-5.4-mini，而你改 model 的时候不会碰到它）。后一种就是典型的”平时一切正常，直到某天走评审才发现”。

model_catalog_json 同理：它指向的是另一个文件。你在 config.toml 里搜不到 gpt-5.4 不代表干净，还得去那份 JSON 里再搜一次。

本机实测：在 codex-cli 0.147.0（Windows 11）上，~/.codex/config.toml 里 model = "gpt-5.6-sol"、model_reasoning_effort = "high"、service_tier = "default"——也就是说模型名就是明文写在这个文件里的一个字符串，你改它、验它都是直接看文本，没有隐藏状态。

五处逐一：改哪里、为什么、漏了会怎样

一、workspace 默认模型

为什么要改：这是工作区层面的默认值，新会话从这里取。你把自己电脑上的配置改干净了，只要工作区默认还挂着 gpt-5.4，团队里其他人（或者你换台机器）起的新会话仍然会命中退役模型。

漏改会怎样：症状是”我明明改过了，怎么还是老模型”——因为你改的是本地那一层，没改上游那一层。

这一层属于工作区管理面，我们没有实测。官方文档站有一页叫《Workspace model availability》，我们没有取过该页内容，具体入口与做法以官方文档为准。

二、保存的模型设置

为什么要改：官方把”保存的模型设置”和当前会话使用的模型分开单列，说明这是两处独立的设定。官方给的判断依据也写得很直接：只改交互界面里当前会话的模型是不够的——那只是运行时的一次选择，不代表存下来的那份设置跟着变了。

漏改会怎样：这一处只要还写着 gpt-5.4，8 月 31 日之后同样会出问题。它的迷惑性在于，你”明明刚刚才在界面上换过模型”，很容易误以为这一条已经处理完了，从而在盘点清单上直接跳过它。这一层我们没有实测，具体在哪里改、改完何时生效，以官方文档为准。

三、managed config（受管配置）

为什么要改：如果你在一个有 IT 统一下发配置的环境里（企业、团队），受管配置这一层是压在本地配置之上的。

漏改会怎样：这是所有五处里最容易让人抓狂的一处——你把本地 config.toml 改得完美无缺，实际生效的仍然是上游那份。而且这一层通常不归你改，你得找管理员。

所以第一次做迁移，先确认自己是不是在受管环境里。如果是，把这一条排到最前面去推动，因为它的处理周期取决于别人的排期，不是你今晚就能搞定的事。我们没有实测受管配置的下发机制，别照着我这段去猜它的具体行为。官方文档站有一页叫《Managed configuration》，我们没有取过该页内容，具体入口与做法以官方文档为准。

四、自定义 agent

为什么要改：自定义 agent 有它自己的模型设定，不跟着主会话走。配置参考里能看到 agents.default_subagent_model（子代理默认模型）和 agents.<name>.config_file（某个角色的 TOML 配置层路径）这两个键——注意后者意味着某个 agent 的模型可能写在另一个 TOML 文件里。

漏改会怎样：主会话跑得好好的，一派子代理就出问题。而且这种故障往往发生在任务跑到一半的时候，比开局就报错更难受。

这一步的检查动作：如果 config.toml 里出现了 agents.<name>.config_file，把它指向的每个文件都打开搜一遍 gpt-5.4。只搜主配置文件是不够的。

五、计划任务（scheduled tasks）

为什么要改：计划任务是”你不在场的时候自己跑”的东西，它带着创建当时的模型设定。

漏改会怎样：这是后果最隐蔽的一处。前面四处你多少能当场察觉，唯独计划任务是到点自己跑，跑失败了你未必立刻知道——等你发现的时候可能已经空转了好几天。我们没有实测计划任务的调度行为；官方文档站有一页叫《Scheduled tasks》，我们没有取过该页内容，具体入口与做法以官方文档为准。

给新手的建议：如果你实在只来得及处理一处，先处理受管配置（因为它要等别人），第二个处理计划任务（因为它出事你看不见）。

一份组合示例（CLI 侧）

如果你的 config.toml 里原来是这样写的：

model = "gpt-5.4"
review_model = "gpt-5.4-mini"

[agents]
default_subagent_model = "gpt-5.4-mini"

按官方映射逐一替换之后：

model = "gpt-5.6-terra"
review_model = "gpt-5.6-luna"

[agents]
default_subagent_model = "gpt-5.6-luna"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。

为什么是这样一一对应，而不是全换成 sol：官方给的是等价替换关系，gpt-5.4-mini 对应的是 gpt-5.6-luna 而不是旗舰。你把评审和子代理全换成旗舰，行为和成本都会和你原来的预期对不上——迁移这一步要做的是”保持原样地活下来”，调档是迁移完成之后另一件事。

云端这一节，是最容易改错方向的地方

有三条官方口径必须一起看，否则很容易做出错误的决定：

gpt-5.6-terra 与 gpt-5.6-luna 在 Codex cloud 上不可用。想让云端任务跑，选型只能落在 gpt-5.6-sol。
Codex cloud 是自动选择模型的，不是你在本地配置里写什么它就用什么。
官方变更说明里，gpt-5.6-sol 现为符合条件客户的 Codex cloud 代码评审与 QA 的驱动模型。

把这三条连起来读，结论是：本地那份配置和云端选到的模型，本来就不是同一回事。所以不要因为”云端不支持 terra”就把本地全改成 sol——本地该按映射换成 terra 的就是 terra；云端那边你改本地配置也左右不了它。

顺带说一句 gpt-5.3-codex-spark：官方定位是纯文本的研究预览（research preview）模型，只在桌面应用与 CLI 两个面上出现，且仅面向 ChatGPT Pro 用户。它不是这次退役的替换项，别拿它去顶 gpt-5.4 的位置。

改完怎么验收

第一次做迁移，验收环节不要省，因为前面五处里有三处的故障是延迟暴露的。

文本搜索复查：在 ~/.codex 目录以及 model_catalog_json、agents.<name>.config_file 指向的每个文件里，再搜一次 gpt-5.4。搜到零结果才算这一层干净。注意 gpt-5.4 是 gpt-5.4-mini 的前缀，搜 gpt-5.4 两者都能命中，这正是你要的。
确认自己改的是哪一层：本地改完、工作区默认和受管配置没动，等于没改完。这一条要单独打勾。
分面确认版本：如果你同时用 CLI 和桌面应用，注意官方《Troubleshooting》页里明确说过——同一个功能在 CLI 有、桌面应用没有，原因通常是两个面的 Codex 版本不同，官方给的做法是分别查版本（CLI 用 codex --version）。迁移同理，两个面要分别确认，不要假设改一处两边都生效。

一个反直觉的点：没收到迁移提示，不代表你不用迁移

本机实测：在 codex-cli 0.147.0（Windows 11）上，~/.codex/config.toml 里存在这样一段：

[notice.model_migrations]
"gpt-5.3-codex" = "gpt-5.4"

也就是说，Codex 会把”已经确认过的模型迁移”记在 notice.model_migrations 这张老名到新名的映射表里。这意味着迁移提示是一次性确认的——确认过一次，之后就不再提醒你。

所以”我没看到任何迁移提示”这件事，完全不能当成”我不需要迁移”的证据。老老实实按上面第 0 步搜一遍文件，比等提示靠谱。

什么情况这套流程不适用

你不在受管环境、也没用过计划任务和自定义 agent：那五处里实际只有前两处跟你有关，别把清单当仪式感，搜一遍配置文件就完事了。
你要判断的是”换过去之后表现如何”：这篇解决不了。我们在这台机器上跑过的全部是只读命令，一次模型对话请求都没发过，任何关于效果、速度、成本的对比都不该由我来替你下结论——按官方映射换过去，再自己在真实任务上观察。
你面对的是桌面应用、Codex cloud、IDE 扩展这些面：本文这几处一律是官方文档口径，我们没有实测，具体入口和界面以官方文档为准。

最后给一个查文档的小技巧（这条官方文档站是公开支持的）：任何文档页 URL 后面加上 .md 后缀就能拿到 Markdown 版本；文档站还提供 llms.txt（完整页面索引）和 llms-full.txt（合并全文）。迁移前想把《Models》页的原文抓下来对着核，比截图靠谱得多。