OpenAI Codex、Deep Research 与 Computer Use 在 7 月 23 日下线前的迁移指南

2026 年 4 月 22 日，OpenAI 宣布弃用一批旧模型快照，涵盖 Codex 变体、deep-research 模型、computer-use 预览版和旧版 search-preview ID。所有模型均于 2026 年 7 月 23 日关停。距今日（7 月 3 日）仅剩 20 天。

如果你的生产代码调用了上述任一模型 ID，关停后请求将直接报错。这不是逐步降级——而是端点直接对旧名称停止响应。你需要在 7 月 23 日之前完成迁移、测试和部署。

我们通过配置的 provider 路由 OpenAI 兼容请求，在现有产品路径支持的前提下支持 provider/model 路由与回退。我们不承诺零宕机、全模型覆盖或最低价格。本指南中所有日期和价格数据均来自 OpenAI 官方文档，并注明检索时间。

1. 替换三个值，不是三个 SDK。在现有 OpenAI 客户端里改 api_key、base_url、model。请求与响应代码保持不变。
2. 显式映射 model ID。目标供应商的 model id 几乎不会和 OpenAI 完全一致。 在业务代码之外维护一份 { openai_id: target_id } 映射。
3. 验证流式格式。SSE 分片必须遵循 OpenAI 的 data: {...} + data: [DONE] 契约。切生产前先跑一次流式调用。
4. 检查限流响应头。部分供应商不返回 x-ratelimit-*。 在包装层 做缺省兜底，缺头不要崩。
5. 留回滚路径。用 feature flag 切流；新旧 endpoint 影子并行 24 小时，再正式切换。

30 秒速览

• 关停日期： 2026 年 7 月 23 日。此日期后无任何宽限期（OpenAI Deprecations，检索于 2026-07-03）。
• 下线类别： Codex 变体（gpt-5-codex、gpt-5.1-codex、gpt-5.1-codex-max、gpt-5.1-codex-mini）、deep-research 模型（o3-deep-research、o4-mini-deep-research）、computer-use preview、旧版 search-preview ID，以及 audio/realtime mini 快照。
• 主要替换目标： gpt-5.5（Codex/旗舰）、gpt-5.4-mini（mini/search-preview/computer-use）、gpt-5.5-pro（deep research）。
• 通知期： 这些模型属于专用变体（Codex、deep-research）和预览版——OpenAI 政策规定变体至少提前 3 个月通知，预览版最短仅 2 周。此次通知符合政策。
• 立即行动： 在代码库中搜索以下模型 ID，对替换版本进行影子测试，并于 7 月 20 日前完成部署。

完整模型替换矩阵

所有数据来自 OpenAI Deprecations，检索于 2026-07-03。

核心规律——三个替换目标： Codex 和旗舰 chat 变体统一迁移至 gpt-5.5；mini 和 preview 变体迁移至 gpt-5.4-mini；deep-research 工作负载迁移至 gpt-5.5-pro；audio/realtime 获得同类快照升级。

代码 diff 对比

Codex 变体（gpt-5-codex、gpt-5.1-codex、gpt-5.1-codex-max）

这些 ID 用于代码补全场景——通常出现在智能体代码流水线、CI 代码审查或 Codex CLI 集成中。替换目标为 gpt-5.5。

# 迁移前
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5.1-codex",          # ← 7 月 23 日下线
    messages=[{"role": "user", "content": "请重构这个函数：..."}],
)

# 迁移后
response = client.chat.completions.create(
    model="gpt-5.5",                 # ✓ 替换目标
    messages=[{"role": "user", "content": "请重构这个函数：..."}],
)

对于 gpt-5.1-codex-mini（成本优化型 Codex 变体），使用 gpt-5.4-mini：

# 迁移后（mini 工作负载）
response = client.chat.completions.create(
    model="gpt-5.4-mini",            # ✓ codex-mini 替换目标
    messages=[{"role": "user", "content": "..."}],
)

Deep research（o3-deep-research、o4-mini-deep-research）

Deep-research 模型通过 Responses API 用于长周期研究任务。替换目标为 gpt-5.5-pro。

# 迁移前——通过 Responses API 使用 o3-deep-research
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="o3-deep-research",        # ← 7 月 23 日下线
    input="总结 2026 年量子纠错的研究现状。",
    tools=[{"type": "web_search_preview"}],
)

# 迁移后
response = client.responses.create(
    model="gpt-5.5-pro",             # ✓ 替换目标
    input="总结 2026 年量子纠错的研究现状。",
    tools=[{"type": "web_search_preview"}],
)

注意：gpt-5.5-pro 的价格显著高于 o3-deep-research。如果成本是考量因素，建议先测试 gpt-5.5——许多研究工作负载无需 Pro 级别即可满足质量要求。详见下方价格章节。

Computer use（computer-use-preview）

Computer-use 应用通过 computer-use-preview 控制浏览器/桌面环境。OpenAI 将其映射至 gpt-5.4-mini。

# 迁移前
response = client.responses.create(
    model="computer-use-preview",    # ← 7 月 23 日下线
    input=[{"type": "text", "text": "打开终端并运行 `ls -la`。"}],
    tools=[{"type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser"}],
)

# 迁移后——使用 gpt-5.4-mini 配合 computer_use 工具
response = client.responses.create(
    model="gpt-5.4-mini",            # ✓ 替换目标（依据 OpenAI 弃用通知）
    input=[{"type": "text", "text": "打开终端并运行 `ls -la`。"}],
    tools=[{"type": "computer_use_preview", "display_width": 1024, "display_height": 768, "environment": "browser"}],
)

请务必充分测试：gpt-5.4-mini 是通用模型，部署前需验证 computer-use 任务完成率是否达到基线水平。

Web 搜索预览（gpt-4o-search-preview、gpt-4o-mini-search-preview）

这些是配备 web_search_preview 工具的模型，迁移目标为 gpt-5.4-mini 配合当前非预览版搜索工具。

# 迁移前
response = client.chat.completions.create(
    model="gpt-4o-search-preview",   # ← 7 月 23 日下线
    messages=[{"role": "user", "content": "最新的 OpenAI 模型价格是多少？"}],
)

# 迁移后——通过 Responses API 使用 gpt-5.4-mini 配合 web_search 工具
response = client.responses.create(
    model="gpt-5.4-mini",            # ✓ 替换目标
    input="最新的 OpenAI 模型价格是多少？",
    tools=[{"type": "web_search_preview"}],
)

注意：Responses API 是 Web 搜索的官方归宿。如果你目前仍在 Chat Completions 上使用 search-preview，这次迁移也是转向 Responses API 的好时机——详见我们的 Assistants 到 Responses API 迁移指南。

价格变化

价格来自 OpenAI API Pricing，检索于 2026-07-03。

Deep research 成本警告： 如果你大规模使用 o3-deep-research，gpt-5.5-pro 的 $30/$180 每百万 tokens 是显著的成本提升。在承诺使用 Pro 级别之前，请先评估 gpt-5.5 是否能满足质量要求。用相同的研究任务批次分别测试两个模型，对比输出质量后再做决策。

Codex/mini 成本变化： gpt-5.4-mini 的 $0.75/$4.50 价格与 Codex-mini 工作负载通常使用的成本区间相近。大多数团队将面临中性或小幅成本变化。

搜索预览模型： 这些模型以前仅按模型 token 费率计费，无额外搜索调用费用。替换为带 web search 工具的 gpt-5.4-mini 后，每 1,000 次搜索调用收费 $10，另加模型 token 费用。高频搜索场景需提前规划预算。

注意事项与迁移检查清单

身份验证与请求头

无需任何身份验证变更。所有替换模型使用相同的 Authorization: Bearer $OPENAI_API_KEY 请求头和相同的 base URL（https://api.openai.com/v1）。

模型 ID 格式与别名

OpenAI 同时支持带版本号的快照（o3-deep-research-2025-06-26）和不带版本号的别名（o3-deep-research）。两者均于 7 月 23 日下线。请在代码中同时搜索两种形式。

API 接口差异

• Codex → gpt-5.5： Chat Completions 或 Responses API 接口不变，仅需修改 model 字段。
• o3-deep-research → gpt-5.5-pro： Responses API 接口不变，reasoning.effort 参数在 gpt-5.5-pro 上仍然有效，无需结构性修改。
• computer-use-preview → gpt-5.4-mini： computer_use_preview 工具 schema 不变，仅修改 model。
• search-preview → gpt-5.4-mini + web_search： 如果你在 Chat Completions 上使用 search-preview 模型，建议同步迁移至 Responses API 的 web_search_preview 工具。

快照固定与回滚

如需为关键工作负载保持稳定的模型响应，可固定到替换模型的带日期快照（例如，如果有 gpt-5.5-2026-05-15 可用）。请在 OpenAI models reference 中确认各替换模型的可用快照列表。

7 月 23 日前，非关键路径仍可继续调用旧模型 ID 作为缓冲。7 月 23 日后无法回滚——端点将直接下线。

回滚方案

我们建议分阶段推进：

1. 现在（7 月 3 日—7 月 10 日）： 识别所有下线模型 ID 的调用方，更新代码中的模型 ID，部署至 staging 环境。
2. 7 月 10 日—7 月 17 日： 对新旧模型 ID 进行影子流量测试，对比输出质量和延迟。
3. 7 月 17 日—7 月 20 日： 将生产流量逐步切换至新模型 ID，在路由配置中禁用旧 ID。
4. 7 月 20 日—7 月 23 日： 完成全量生产切换，监控旧 ID 的错误率——若错误率为零，迁移完成。

如果部署新模型 ID 后发现质量回归，可将 model 字段回滚至旧 ID，但此选项仅在 7 月 23 日前有效。

TheRouter 集成：过渡期回退配置

如果你通过 TheRouter 路由 OpenAI 兼容流量，可在过渡期为下线模型 ID 配置自动回退，为未能在 7 月 20 日前完成迁移的调用方提供兜底保障。

{
  "routes": [
    {
      "match": { "model": "gpt-5.1-codex" },
      "rewrite_model": "gpt-5.5",
      "provider": "openai",
      "comment": "gpt-5.1-codex 7 月 23 日下线——重写为 gpt-5.5"
    },
    {
      "match": { "model": "o3-deep-research" },
      "rewrite_model": "gpt-5.5-pro",
      "provider": "openai",
      "comment": "o3-deep-research 7 月 23 日下线——重写为 gpt-5.5-pro"
    },
    {
      "match": { "model": "computer-use-preview" },
      "rewrite_model": "gpt-5.4-mini",
      "provider": "openai",
      "comment": "computer-use-preview 7 月 23 日下线——重写为 gpt-5.4-mini"
    },
    {
      "match": { "model": "gpt-4o-search-preview" },
      "rewrite_model": "gpt-5.4-mini",
      "provider": "openai",
      "comment": "gpt-4o-search-preview 7 月 23 日下线——重写为 gpt-5.4-mini"
    }
  ]
}

TheRouter 在现有产品路径支持的前提下路由 OpenAI 兼容请求并支持路由与回退。使用此配置前，请先验证 gpt-5.5、gpt-5.4-mini 和 gpt-5.5-pro 在你的 OpenAI provider 配置中可用。

详见我们的 OpenAI 迁移指南 和 model fallback 文档。

与其他下线批次的关系

本次 7 月 23 日批次与另外两个 OpenAI 下线事件不同：

• 2026 年 12 月 11 日： 六个初代 GPT-5 和 O3 模型快照（gpt-5-2025-08-07、o3-2025-04-16 等）——详见我们的 GPT-5 下线规划指南。
• 2026 年 11 月 30 日： OpenAI 可复用 prompt、Evals 平台和 Agent Builder——2026 年 6 月 3 日公告，非模型 ID。

优先处理 7 月 23 日这批。截止日期过后，再审计 12 月批次。

生产检查清单

7 月 23 日前完成以下步骤：

• 搜索代码库，找出所有下线模型 ID 字符串（完整列表见上方替换矩阵）
• 识别 API 接口：Chat Completions、Responses API 还是旧版 Assistants
• 按表映射每个下线 ID 到对应替换目标
• 更新所有调用方和配置文件中的 model 字段
• 部署至 staging 并运行现有测试套件
• 影子测试（7 月 10 日—17 日）生产流量对比新旧模型 ID
• 成本审计： 按新模型价格估算月均 token 支出——尤其是 deep-research 场景
• TheRouter 配置： 如适用，为尚未完成迁移的调用方添加模型重写规则
• 7 月 20 日前部署至生产（距关停留 3 天缓冲期）
• 监控旧 ID 错误率——零错误即代表迁移成功
• 切换完成后从代码中移除旧模型 ID 引用

相关资源

• OpenAI Deprecations 页面 — 权威来源，检索于 2026-07-03
• OpenAI API 价格 — 模型定价，检索于 2026-07-03
• OpenAI models 参考 — 快照可用性
• Assistants 迁移至 Responses API — 适用于仍在 Chat Completions 或 Assistants 上的 search-preview 调用方
• GPT-5 2026 年 12 月下线指南 — 下一批 OpenAI 弃用
• OpenAI provider 页面 — TheRouter 上的模型路由状态
• model fallback 文档 — 回退路由配置