OpenAI 7月23日关停 gpt-5-codex 等11个模型快照:完整清单、grep 排查与逐类迁移实操

OpenAI 官方 deprecations 页已挂出一批将于2026-07-23停止服务的模型快照,共 11 个,覆盖 Codex 代码系列、chat-latest 浮动指针、gpt-4o 搜索预览、computer-use 预览以及一个 TTS 快照。截至本文撰写日 2026-07-16,距关停只剩7 天。

这类停服不是"降速"“限流”,而是到点后请求直接报错(通常是model_not_found或 4xx),没有灰度缓冲。凡是在生产、CI、定时任务、Agent 编排里硬编码了这些快照名的代码,都需要在这周内完成替换和回归。本文按"背景 → 完整对照表 → 怎么查自己在用哪个 → 逐类迁移 → 回归测试 → 下一波预警 → FAQ"的顺序,给一份可直接照做的迁移清单。

一、这批关停的背景

OpenAI 的模型生命周期一直是"快照(snapshot)+ 别名(alias)"双轨:带日期后缀的是冻结快照(如gpt-4o-mini-tts-2025-03-20),不带日期的是滚动别名(如computer-use-preview)。快照的意义是可复现,代价是它会随新一代能力上线被官方标记 deprecated,到期停服。

这次 07-23 批次的共同逻辑有三点,理解了它,后面的迁移就不会踩坑:

1. Codex 专用代码模型整体并入通用旗舰。过去gpt-5-codex系列是为代码任务单独调优的分支,这批之后官方不再单独维护代码专用快照,统一由通用模型gpt-5.5承接,mini 档由gpt-5.4-mini承接。
2. 搜索预览类不是"换个模型名"就完事。gpt-4o-search-preview这类模型把"联网搜索"内置在 Chat Completions 里,替代方案是改用 Responses API 的 web search 工具——这是 API 形态的变化,不是简单替换model字符串。
3. 别名与同族快照做无损延续。computer-use-preview-2025-03-11去掉日期后的别名computer-use-preview继续可用;TTS 则是同族快照升级(2025-03-20→2025-12-15)。

区分清楚哪一类属于"直接改名"、哪一类属于"改 API 形态",是这次迁移的核心。

二、完整关停对照表(11 行)

下表逐字取自官方 deprecations 页 07-23 批次,型号名请直接复制,不要手敲(容易把5.1打成5.2)。

四种迁移类型对应四套不同的操作,后面第四节分别展开。

三、先查:你到底在用哪几个快照

迁移的第一步不是改代码,而是盘点。模型名可能出现在源码、配置文件、环境变量、数据库、甚至 CI 脚本里,漏一个就等于埋一颗到 07-23 才炸的雷。

3.1 全库 grep 一把梭

用一条正则覆盖全部 11 个快照名。注意.在正则里要转义,5\.1才不会误匹配。

grep-rn-E\"gpt-5-codex|gpt-5\.1-codex(-max|-mini)?|gpt-5\.2-codex|gpt-5-chat-latest|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="*.js"--include="*.ts"--include="*.tsx"\--include="*.go"--include="*.rb"--include="*.java"\--include="*.json"--include="*.yaml"--include="*.yml"--include="*.toml"\--include="*.env*"--include="*.sh"\.

如果用ripgrep,更快也更省心(默认递归、默认尊重.gitignore):

rg-n"gpt-5(\.[12])?-codex|chat-latest|search-preview-2025-03-11|gpt-4o-mini-tts-2025-03-20|computer-use-preview-2025-03-11"

3.2 别忘了 grep 抓不到的地方

模型名不总是以字面量存在。以下几处 grep 常常漏掉,要人工确认:

• 环境变量 / Secrets:OPENAI_MODEL、LLM_MODEL之类的值可能在部署平台的控制台里,不在仓库中。
• 数据库配置表:很多 Agent 平台把"渠道 → 模型"映射存在 DB,需要SELECT一遍。
• 字符串拼接:model = "gpt-5." + ver + "-codex"这种动态构造,正则匹配不到,要靠审查拼接逻辑。
• 前端/客户端硬编码:小程序、桌面端里也可能写死了模型名。

3.3 运行时兜底:让日志替你查

最稳的办法是让程序自己上报。在调用封装层加一段"废弃名告警",即使漏改也能在日志里第一时间发现:

DEPRECATED_0723={"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",}defguard_model(model:str)->str:ifmodelinDEPRECATED_0723:logging.warning("使用了将于 2026-07-23 关停的快照: %s",model)returnmodel

上线一两天就能从日志聚合里看到所有实际命中的快照名和调用频次,盘点即完成。

四、逐类迁移实操

4.1 Codex 代码系列(第 1–5 行)

gpt-5-codex/gpt-5.1-codex/gpt-5.1-codex-max/gpt-5.2-codex统一迁到gpt-5.5;gpt-5.1-codex-mini迁到gpt-5.4-mini。

字符串替换本身很简单:

- resp = client.chat.completions.create(model="gpt-5.2-codex", messages=msgs) + resp = client.chat.completions.create(model="gpt-5.5", messages=msgs)

但代码专用模型迁到通用模型,行为一定会变,这才是重点。建议按下面三条逐一核对:

1. 代码块格式:Codex 系列倾向直接吐代码,通用模型可能更爱加解释性文字。如果你的下游是正则抠代码块,先验证 ` ````围栏还在不在,或者把"只返回代码、不要解释"写进 system prompt。
2. 工具调用/函数调用:Codex 与通用模型在 function calling 的触发倾向、参数命名上有差异,凡是接了工具的链路必须重跑一遍。
3. 上下文长度与截断:换代承接模型的上下文窗口、最大输出可能不同,长文件补全场景要压测边界。

批量迁移时,用一张映射表集中管理,别在几十个文件里散着改:

MODEL_MIGRATION={"gpt-5-codex":"gpt-5.5","gpt-5.1-codex":"gpt-5.5","gpt-5.1-codex-max":"gpt-5.5","gpt-5.2-codex":"gpt-5.5","gpt-5.1-codex-mini":"gpt-5.4-mini",}model=MODEL_MIGRATION.get(raw_model,raw_model)

4.2 chat-latest 浮动指针(第 6–7 行)

gpt-5-chat-latest/gpt-5.1-chat-latest迁到gpt-5.5。

*-chat-latest是一个浮动别名,过去它会自动指向最新的对话优化版本。它被关停,意味着官方要把用户从"跟着滚"迁到明确的版本上。改法就是把浮动名换成固定名:

- model="gpt-5-chat-latest" + model="gpt-5.5"

顺带做一个决策:你原本用chat-latest是图"永远最新"。迁移后要想清楚——是继续用gpt-5.5这种带小版本的名字(相对稳定、可复现),还是接受未来每次官方大版本变动都要手动跟进。对话产品追求输出稳定的,建议固定版本 + 自己排期升级,而不是再找一个浮动别名接着漂。

4.3 搜索预览系列(第 8–9 行)—— 这一类要改 API 形态

gpt-4o-search-preview-2025-03-11/gpt-4o-mini-search-preview-2025-03-11表面上建议替代是gpt-5.4-mini,但它不是把 model 字符串换掉就行。

这两个 search-preview 模型的特点是把"联网搜索"内置进了 Chat Completions:你发一句话,它自己去搜、自己带着结果回答。而承接方案是——改用 Responses API,把搜索显式声明成一个工具(web search tool)。搜索能力从"模型内置"变成了"你挂一个工具给它"。

旧写法(内置搜索,即将失效):

resp=client.chat.completions.create(model="gpt-4o-search-preview-2025-03-11",messages=[{"role":"user","content":"查一下今天的相关新闻并总结"}],)

新写法(Responses API + web search 工具):

resp=client.responses.create(model="gpt-5.4-mini",tools=[{"type":"web_search"}],input="查一下今天的相关新闻并总结",)

迁移这一类时要额外注意:

• 返回结构变了。Responses API 的返回体与 Chat Completions 不同,解析代码(取正文、取引用来源 citation)要一起改。
• 搜索是否被触发不再由模型隐式决定,而是取决于工具是否挂载、以及模型判断要不要用。要验证"该搜的时候有没有搜"。
• 计费口径会变。内置搜索模型和"通用模型 + 搜索工具"的计价方式不一样,以官方 pricing 页当日牌价为准重新估算,别用旧模型的成本假设直接套。

4.4 computer-use 别名(第 11 行)

computer-use-preview-2025-03-11迁到computer-use-preview(或按需用gpt-5.4-mini)。

这是全场最省事的一类:去掉日期后缀即可。带日期的快照冻结版停服,不带日期的滚动别名继续可用。

- model="computer-use-preview-2025-03-11" + model="computer-use-preview"

唯一要留心的:别名是滚动的,意味着底层能力后续会跟着官方走。如果你的自动化流程对模型行为极其敏感,迁到别名后要做一遍完整回归,并把"别名会漂"这件事记进运维文档。

4.5 TTS 快照升级(第 10 行)

gpt-4o-mini-tts-2025-03-20迁到gpt-4o-mini-tts-2025-12-15,同族、新快照,直接替换日期:

- model="gpt-4o-mini-tts-2025-03-20" + model="gpt-4o-mini-tts-2025-12-15"

音色(voice)、格式(response_format)等参数一般延续,但新快照的发音、语速、韵律可能有细微差异。对语音质量敏感的场景(有声书、客服播报),挑几段代表性文本 A/B 试听一遍再全量切。

五、回归测试要点

改完不等于迁完。这批里既有"改名"也有"改 API 形态",回归要覆盖以下几点,建议做成一份 checklist 逐项打勾:

• 冒烟调用:每个被替换的模型,先跑一条最简单的请求,确认不报model_not_found。
• 输出格式契约:凡是下游用正则/JSON schema 解析模型输出的,验证格式没崩(尤其 Codex → 通用模型这一类)。
• 工具/函数调用:function calling、web search 工具是否被正确触发、参数是否合法。
• 返回体解析:搜索预览迁到 Responses API 后,取正文和 citation 的代码要专门测。
• 长度边界:上下文窗口、最大输出 token 的边界用例。
• 延迟与吞吐:换代模型的 P95 延迟可能变化,影响超时设置和用户体验。
• 成本核算:按官方当日牌价重算单位成本,更新预算和限额告警阈值。
• 灰度而非全切:有条件的话先按 1%→10%→100% 放量,留观察窗口。

一个实用技巧:把新旧模型对同一批固定测试用例的输出并排 diff,人工抽检差异最大的若干条,比只看"有没有报错"可靠得多。

六、别只顾眼前:12-11 还有下一波

处理完 07-23,顺手把日历上的下一颗雷也标了。官方 deprecations 页显示,2026-12-11还有一批停服:

• gpt-5-2025-08-07、gpt-5-mini、gpt-5-nano、gpt-5-pro、o3、o3-pro
• 对应替代:gpt-5.5、gpt-5.4-mini/gpt-5.4-nano、gpt-5.5-pro

也就是说,gpt-5.5/gpt-5.4-mini系列既是这次 07-23 的承接方,也是 12-11 那批的承接方——现在把迁移映射表和封装层建好,12 月那波基本只是往表里再加几行的事。建议现在就把"模型名集中管理 + 运行时废弃告警"这套机制沉淀下来,以后每一批 deprecation 都能低成本应对。

七、FAQ

Q1:到 07-23 当天不改会怎样?
到点后调用被停快照的请求会直接失败(常见model_not_found或 4xx),没有自动回退。依赖它的功能会当场不可用,不是降级而是中断。

Q2:官方建议的替代模型是"等价替换"吗?
不是。只有 computer-use 去日期别名、TTS 同族升级接近无损;Codex → 通用模型、search-preview → Responses API 工具这两类都有行为或形态变化,必须回归测试,不能盲替。

Q3:搜索预览类为什么不能只改 model 名?
因为它把联网搜索内置在 Chat Completions 里,而承接方案是改用 Responses API 并显式挂载 web search 工具。API 端点、请求体、返回体解析都要一起改,不是一行字符串替换。

Q4:*-chat-latest迁移后还能找个"永远最新"的别名吗?
可以继续用滚动别名,但要接受它会随官方更新漂移、输出未必可复现。对稳定性敏感的对话产品,更推荐固定到gpt-5.5这类带版本号的名字,自己排期升级。

Q5:怎么确认自己一个都没漏?
三层兜底:全库 grep(第三节正则)+ 人工检查环境变量/数据库/动态拼接 + 运行时废弃名告警日志。三者都过一遍,基本能穷尽。

Q6:型号名总记混,5.15.2怎么办?
一律从官方 deprecations 页复制粘贴,不要手敲。本文第二节的对照表也可直接复制。

小结:07-23 这批 11 个快照,按迁移难度可分四档——去日期别名(computer-use)和同族升级(TTS)几乎零成本;chat-latest 和 Codex 系列是改名 + 回归;search-preview 系列最重,要从 Chat Completions 迁到 Responses API 的 web search 工具。7 天时间,建议今天先跑 grep 盘点、加运行时告警,明后天分类改代码,留出至少两天做灰度和回归。把这套机制建好,12-11 的下一波只是往映射表里再加几行的事。所有型号名与替代关系以 OpenAI 官方 deprecations 页为准。人