Codex 模型三天后退役，你的代码还在硬编码模型名吗？

上周六的下午，我喝了一杯完全不享受的咖啡，用 git bisect 逐帧回放，才定位到一个诡异的生产事故：工具调用参数突然变了，但代码一行没改。

凶手是一个 -latest 别名。OpenAI 静默地把它指向了一个新快照，新快照的工具调用行为有一处微妙差异，我的解析器立刻崩了。一个本该轻松度过的周六，被一个浮动别名吃掉了。

从那以后，我所有东西都指向带日期的固定快照。gpt-5-codex 就是其中之一。

然后，上周我花了十五分钟认真读了一遍 OpenAI 的模型废弃页面，而不是像往常一样扫一眼就关掉。然后我看到了它：gpt-5-codex，退役日期 2026 年 7 月 23 日，安静地躺在另外十个模型旁边。

今天已经是 7 月 20 日。三天。

如果你像我一样锁定了下面这些快照，这篇文章就是给你的预警。以下是完整的退役清单、如何用大约十分钟排查暴露面、每个模型该迁移到哪里、该回归测试什么，以及最重要的一件事：那次让我把「被迫迁移」从恐惧变成无聊的结构性改动。

退役清单（2026-07-23）#

以下内容直接来自 OpenAI 的 API 废弃页面，我在写作时逐行核对过。行动前也请你自己再看一遍，因为日期和替换方案可能会修订。

看清楚规律就好办了。*-codex 几乎全线收束到 gpt-5.5，只有 gpt-5.1-codex-mini 降级到了 gpt-5.4-mini。*-chat-latest 别名也折叠到 gpt-5.5。两个 *-search-preview 快照都指向 gpt-5.4-mini。TTS 和 Computer Use 只是滚动到更新的快照。看清楚这几个桶，迁移就没表格看起来那么吓人。

十分钟排查暴露面#

陷阱不是你记得硬编码过的模型 ID。陷阱是你忘了的那些，埋在 .env 里、藏在配置表里、托管在某个同事跑过一次就没删的 notebook 里。

两步走，基本全覆盖。

第一步：grep 代码。 一个正则覆盖全部退役 ID：

grep -rniE \
  'gpt-5-codex|gpt-5\.1-codex|gpt-5\.2-codex|gpt-5(\.1)?-chat-latest|gpt-4o(-mini)?-search-preview-2025-03-11|gpt-4o-mini-tts-2025-03-20|computer-use-preview-2025-03-11' \
  --include='*.py' --include='*.ts' --include='*.js' --include='*.go' \
  --include='*.rb' --include='*.java' --include='*.env*' --include='*.y*ml' \
  --include='*.json' --include='*.toml' .

第二步：grep 实际调用日志。 代码搜索会漏掉来自数据库、后台开关或用户输入参数的模型 ID。如果你记录外发请求为 JSON 行且包含 .model 字段：

jq -r 'select(.model) | .model' requests.log \
  | sort | uniq -c | sort -rn \
  | grep -E 'codex|chat-latest|search-preview|tts-2025|computer-use'

没有结构化日志？OpenAI 的用量导出面板按模型分解消费，按名称排序，找上面那十一个名字。如果某个退役 ID 在这里出现但在你的 grep 里没有，那就是典型的配置驱动调用，你靠代码搜索根本找不到。

我还会把这组退役 ID 写成一个常量，挂在 CI 里做检查，任何提交再出现这些字符串就直接构建失败：

RETIRING_2026_07_23 = {
    "gpt-5-codex", "gpt-5.1-codex", "gpt-5.1-codex-max",
    "gpt-5.1-codex-mini", "gpt-5.2-codex", "gpt-5-chat-latest",
    "gpt-5.1-chat-latest", "gpt-4o-search-preview-2025-03-11",
    "gpt-4o-mini-search-preview-2025-03-11",
    "gpt-4o-mini-tts-2025-03-20", "computer-use-preview-2025-03-11",
}

迁移映射，以及我真正会测试什么#

换一个字符串简单。但这些替换不是平替，每个桶都是一次行为变更，不是一次重命名。

*-codex → gpt-5.5。 这是最大的跳跃。Codex 快照是为编程 Agent 场景专门调优过的，gpt-5.5 是一个通用模型。重跑你的编程评测和金标准对话，关注推理深度、补丁/差异格式、工具调用参数。如果你的输出解析器比 “trust me” 严格哪怕一丁点，先在真实样本上对比新旧输出，再切生产。

gpt-5.1-codex-mini → gpt-5.4-mini。 不同家族，不只是小号的 Codex。延迟特征和工具调用形态可能跟你调过的 mini 不一样，重新检查超时设置和依赖旧行为的 few-shot 示例。

*-chat-latest → gpt-5.5。 你之前锁定的是一个移动别名，这本身就不是好习惯。迁移到具体模型其实是进步，确认系统提示词遵循度和输出格式在你的核心流程上没问题即可。

*-search-preview → gpt-5.4-mini。 这些预览模型内置了搜索 grounding。普通的 gpt-5.4-mini 可能不会以同样方式接地，验证你依赖的能力还在不在。如果需要实时检索，在 Responses API 上接入 web-search 工具，别假设基座模型自己会搜索。

gpt-4o-mini-tts → 更新快照。 同家族，更新版本，风险最低。但仍然抽查语音、韵律和所有语音/格式参数。

computer-use-preview → 移动别名。 从固定快照退回到无日期别名。理论上没问题，但你又回到了移动目标上。如果关注可复现性，一旦新快照发布，立刻钉住它。

切换生产前，我的最低回归清单：

1. 把现有评测集在新模型上跑一遍，对比输出，别靠肉眼扫一个提示词就下结论
2. 重新验证所有消费模型输出的解析器和 schema（工具调用 JSON、代码块、函数参数）
3. 检查新模型的 token 计费和成本，别让一次 “快速替换” 悄悄改变了热路径的账单
4. 确认所有特殊能力的等价性（搜索 grounding、Computer Use、TTS 语音），替换可能丢弃或迁移某个功能

下一波已经在路上了（2026-12-11）#

趁你还在废弃页面上，往下翻。第二批次，gpt-5-2025-08-07、gpt-5-mini、gpt-5-nano、gpt-5-pro、o3、o3-pro，预定 2026 年 12 月 11 日退役，分别迁移到 gpt-5.5、gpt-5.4-mini、gpt-5.4-nano、gpt-5.5-pro。这周不急，但如果你已经在碰模型配置了，现在就记下来，别让 12 月变成又一次紧急加班的理由。

把模型名抽到一个层里，让下一次变得无聊#

这是我反复学到的教训：一次被迫迁移的痛苦程度，和模型名字散落在多少个地方成正比。

当 gpt-5-codex 以字面量字符串形式出现在十九个文件、三个服务和一个配置表里时，一次废弃就是一个 deadline 下的 19 文件 PR。当模型名字只存在一个路由层/配置层时，就是一行改动加一次重部署。

所以我现在的规则是：应用代码永远不拼写模型 ID。它请求一个角色：code-agent、cheap-classifier、tts，由一个小型配置表把角色映射到具体快照。一次被迫迁移变成编辑那个映射表、重跑评测、发布。上面那十一个模型，在我这里就是一次提交。

你不一定需要网关。一个常量文件或一个 MODEL_ROLES 字典就能给你 80% 的好处。关键在于间接层，不在于用什么工具。

但如果你像我一样用了兼容 OpenAI 的网关（我用的是 Byesu，一个 key 同时面对 GPT-5.5/5.6、Claude、Gemini 和 Grok），那替换模型只是把现有客户端指向一个 base URL，改一个地方的模型字符串，SDK、请求形态、解析代码全都不动。这种体验，是让我能把 “gpt-5-codex 没了” 当成一次配置编辑而不是全仓库大搜捕的根本原因。

写在最后#

三天。具体地说，7 月 23 日之前：跑两个 grep，列出暴露的快照，按表格选替换，在真实流量上对比输出，发布。

如果你那十一个字符串还散落在代码库各处，这也是把模型名抽到角色映射层的完美时机。因为 12 月的批次已经排好了，后面永远还会有下一波。

去吧，自己打开 OpenAI 的废弃页面，把日期和自己的技术栈对一遍。模型废弃表是唯一一种你不能 “下个 sprint 再说” 的文档，它有一个硬截止日期。

如果你也像我一样锁了 gpt-5-codex，时钟已经在走了。

本文基于 amdmsz 在 dev.to 发布的原创文章（发布于 2026 年 7 月 15 日）进行中文原创重写，补充了工程架构视角和实践经验。原文作者：amdmsz。