请添加图片描述

如果你只是在 Codex 界面里手动选择模型，这次迁移可能并不复杂。

真正容易被遗漏的，是散落在项目和本地环境里的固定配置：

config.toml
Custom Agent 配置
codex exec 脚本
定时任务
CI 工作流
团队托管配置

这些位置一旦固定写入旧模型名，即使 Codex 本身已经更新，脚本仍可能在 8 月 31 日后继续请求已经退役的模型。

OpenAI 当前官方说明明确指出：使用 ChatGPT 登录 Codex 时，gpt-5.4 和 gpt-5.4-mini 将于 2026 年 8 月 31 日退役，建议进行以下替换：

旧模型建议迁移目标典型用途
gpt-5.4gpt-5.6-terra日常开发、代码修改、工具调用
gpt-5.4-minigpt-5.6-luna明确、重复、偏轻量的任务

需要特别注意的是，这一退役说明针对使用 ChatGPT 登录的 Codex。OpenAI API，以及使用自有 API Key 进行身份验证的 Codex，不受此次 GPT-5.4 退役直接影响。OpenAI 官方模型说明

因此，这次不能简单地对整个仓库执行一次全局替换。

一、先判断自己是否需要迁移

可以按以下顺序确认。

1. 查看 Codex 当前使用的登录方式

如果通过 ChatGPT 账号登录 Codex，并且在配置、Custom Agent 或自动任务中固定使用了 gpt-5.4、gpt-5.4-mini，就需要纳入排查。

如果项目调用的是 OpenAI API，不能仅根据这篇退役公告自动替换 API 模型。API 模型是否可用，应单独查看当时的 API 模型与弃用说明。

2. 检查本地默认模型

Codex 桌面端、CLI 和 IDE 扩展共享 config.toml 配置。可以先检查用户配置目录：

rg -n 'model\s*=' ~/.codex/config.toml

Windows PowerShell 可以使用：

Select-String -Path "$env:USERPROFILE\.codex\config.toml" `
  -Pattern "model\s*="

如果看到：

model = "gpt-5.4"

应结合实际任务考虑改为：

model = "gpt-5.6-terra"

如果没有手动设置模型，Codex 会使用当前推荐模型，因此不一定需要修改配置。

3. 检查命令行脚本

除了配置文件，还要搜索带有 --model 或 -m 的命令：

rg -n --hidden \
  --glob '!.git/**' \
  --glob '!node_modules/**' \
  'codex\s+(exec\s+)?(--model|-m)|gpt-5\.4' .

常见旧命令：

codex exec --model gpt-5.4 \
  "Review the current changes"

迁移后：

codex exec --model gpt-5.6-terra \
  "Review the current changes"

请添加图片描述

二、为什么不能直接全仓库替换

假设执行：

sed -i 's/gpt-5.4/gpt-5.6-terra/g' ...

这里至少存在三个风险。

风险 1：短名称会破坏 mini 模型

gpt-5.4 是 gpt-5.4-mini 的前半部分。

如果先替换短名称，可能得到：

gpt-5.6-terra-mini

这不是正确的目标模型。正确映射应该是：

gpt-5.4-mini → gpt-5.6-luna

因此，程序必须优先匹配更长的模型名。

风险 2：可能误改 API 配置

仓库中出现 gpt-5.4，不代表它一定属于此次 Codex 迁移范围。

例如：

export const apiModel = "gpt-5.4";

如果这是使用 API Key 的 OpenAI API 调用，就不能仅凭本次 Codex 退役说明自动替换。

风险 3：可能修改历史记录与测试夹具

下面这些内容通常应该先人工判断：

历史迁移文档
版本发布记录
模型对比报告
测试夹具
失败案例快照
成本评估记录

改变历史文本可能导致测试失效，也可能让旧版本记录失真。

更安全的方法是：先全局发现，再分类确认，最后只对明确的 Codex 活跃配置执行白名单迁移。

三、建立一个可复现的迁移示例

这次准备了以下演示项目：

codex-model-migration-demo/
├── codex/config.toml
├── agents/reviewer.toml
├── scripts/nightly-review.sh
├── tasks/security-audit.json
├── api/client.mjs
├── tools/migrate-codex-models.mjs
└── test/migrate-codex-models.test.mjs

四个文件属于 Codex 活跃配置：

codex/config.toml
agents/reviewer.toml
scripts/nightly-review.sh
tasks/security-audit.json

api/client.mjs 用于模拟 API Key 工作流，不在本次自动修改范围内。

示例旧配置

codex/config.toml：

model = "gpt-5.4"
reasoning_effort = "medium"

agents/reviewer.toml：

name = "reviewer"
model = "gpt-5.4-mini"
reasoning_effort = "low"

scripts/nightly-review.sh：

#!/usr/bin/env sh
codex exec --model gpt-5.4 \
  "Review the current changes"

tasks/security-audit.json：

{
  "name": "nightly-security-audit",
  "model": "gpt-5.4-mini",
  "schedule": "0 2 * * *"
}

四、先搜索，但不要立即修改

可以先执行一次全局搜索：

rg -n --hidden \
  --glob '!.git/**' \
  --glob '!node_modules/**' \
  'gpt-5\.4-mini|gpt-5\.4|gpt-5\.3-codex|gpt-5\.2' .

这里额外搜索了 gpt-5.2 和 gpt-5.3-codex，因为官方文档显示，它们在使用 ChatGPT 登录 Codex 时已经处于弃用状态。

但搜索结果只是待核验清单，不能直接等同于替换清单。

建议给每个结果增加分类：

搜索结果是否自动迁移判断依据
Codex 默认配置是明确属于 ChatGPT 登录的 Codex
Custom Agent 模型是属于活动 Agent 配置
codex exec 脚本是明确调用 Codex
Codex 定时任务是属于官方提示的迁移范围
OpenAI API 配置否不受本次退役直接影响
历史文档否应保留原始记录
测试夹具人工确认修改可能改变测试含义

五、编写白名单迁移脚本

下面的 Node.js 脚本只修改四个已经确认的文件，不扫描并覆盖整个仓库。

import fs from "node:fs";
import path from "node:path";
import { pathToFileURL } from "node:url";

const legacyTerra = `gpt-${"5.4"}`;
const legacyLuna = `gpt-${"5.4-mini"}`;

const replacements = new Map([
  [legacyLuna, "gpt-5.6-luna"],
  [legacyTerra, "gpt-5.6-terra"]
]);

const legacyPattern = /gpt-5\.4(?:-mini)?/g;

const targetFiles = [
  "codex/config.toml",
  "agents/reviewer.toml",
  "scripts/nightly-review.sh",
  "tasks/security-audit.json"
];

export function migrateText(source) {
  let output = source;

  for (const [from, to] of replacements) {
    output = output.replaceAll(from, to);
  }

  return output;
}

export function inspectTargets(rootDir, write = false) {
  const changes = [];

  for (const relativePath of targetFiles) {
    const absolutePath = path.join(rootDir, relativePath);
    const before = fs.readFileSync(absolutePath, "utf8");
    const after = migrateText(before);

    if (before === after) continue;

    const found = [
      ...new Set(before.match(legacyPattern) ?? [])
    ];

    changes.push({ relativePath, found });

    if (write) {
      fs.writeFileSync(absolutePath, after, "utf8");
    }
  }

  return changes;
}

function runCli() {
  const write = process.argv.includes("--write");
  const changes = inspectTargets(process.cwd(), write);

  if (changes.length === 0) {
    console.log(
      "OK: no retired Codex model references found"
    );
    return;
  }

  for (const change of changes) {
    console.log(
      `${write ? "UPDATED" : "FOUND"}: ` +
      `${change.relativePath} -> ` +
      change.found.join(", ")
    );
  }

  if (!write) {
    console.error(
      `FAILED: ${changes.length} ` +
      "Codex configuration files need migration"
    );
    process.exitCode = 1;
  } else {
    console.log(
      `DONE: migrated ${changes.length} ` +
      "Codex configuration files"
    );
  }
}

if (
  process.argv[1] &&
  import.meta.url === pathToFileURL(process.argv[1]).href
) {
  runCli();
}

这里有两个关键点。

第一，替换表先处理 gpt-5.4-mini，再处理 gpt-5.4，避免产生错误的 gpt-5.6-terra-mini。

第二，脚本只操作 targetFiles 中已经确认的配置。团队实际使用时，应根据自己的目录增加目标文件，不能直接照搬路径。

六、先以检查模式运行

不要第一次执行就写入文件，先运行：

node tools/migrate-codex-models.mjs

本次示例实际输出：

FOUND: codex/config.toml -> gpt-5.4
FOUND: agents/reviewer.toml -> gpt-5.4-mini
FOUND: scripts/nightly-review.sh -> gpt-5.4
FOUND: tasks/security-audit.json -> gpt-5.4-mini
FAILED: 4 Codex configuration files need migration

脚本使用非零退出码表示检测到旧配置，因此可以接入 CI，阻止新的旧模型名称进入活跃配置。

确认文件范围无误后，执行：

node tools/migrate-codex-models.mjs --write

实际输出：

UPDATED: codex/config.toml -> gpt-5.4
UPDATED: agents/reviewer.toml -> gpt-5.4-mini
UPDATED: scripts/nightly-review.sh -> gpt-5.4
UPDATED: tasks/security-audit.json -> gpt-5.4-mini
DONE: migrated 4 Codex configuration files

七、给迁移规则增加单元测试

自动替换脚本本身也可能存在 Bug，尤其是短名称与长名称重叠时。

使用 Node.js 内置测试模块编写三个测试：

import test from "node:test";
import assert from "node:assert/strict";
import {
  migrateText
} from "../tools/migrate-codex-models.mjs";

test(
  "migrates the mini model without a partial name",
  () => {
    assert.equal(
      migrateText('model = "gpt-5.4-mini"'),
      'model = "gpt-5.6-luna"'
    );
  }
);

test("migrates the standard model to Terra", () => {
  assert.equal(
    migrateText('model = "gpt-5.4"'),
    'model = "gpt-5.6-terra"'
  );
});

test("leaves a migrated model unchanged", () => {
  assert.equal(
    migrateText('model = "gpt-5.6-sol"'),
    'model = "gpt-5.6-sol"'
  );
});

执行：

node --test

本文示例在 Node.js v24.19.0 环境中的实际结果：

✔ migrates the mini model without a partial name
✔ migrates the standard model to Terra
✔ leaves an already migrated model unchanged

tests 3
pass 3
fail 0

第三项测试用于验证幂等性：已经完成迁移的配置再次经过脚本时，不应该继续被修改。

请添加图片描述

八、迁移后检查不能只看脚本提示

再次执行检查模式：

node tools/migrate-codex-models.mjs

输出应变为：

OK: no retired Codex model references found

然后查看具体配置：

rg -n \
  'gpt-5\.4|gpt-5\.6-(terra|luna)' \
  codex agents scripts tasks api

本次示例结果：

api/client.mjs:
export const apiModel = "gpt-5.4";

codex/config.toml:
model = "gpt-5.6-terra"

agents/reviewer.toml:
model = "gpt-5.6-luna"

scripts/nightly-review.sh:
codex exec --model gpt-5.6-terra ...

tasks/security-audit.json:
"model": "gpt-5.6-luna"

可以看到，四个 Codex 配置已经迁移，但 API 示例仍保留原值。这正是白名单迁移与全仓库替换之间的区别。

如果日常需要使用 ChatGPT Plus、Codex 或其他 AI 工具，并涉及会员充值需求，可以通过 gpt985.com了解相关信息。其定位是第三方 AI 会员充值平台，并非相关产品的官方网站或授权合作方；使用前仍应确认套餐说明、账号要求及售后规则。

九、迁移完成后还要做任务级回归

配置名称正确，不等于迁移已经结束。

Terra 和 Luna 的定位不同，不能只检查命令是否成功启动，还要验证任务质量是否满足原来的要求。

建议选择三类历史任务：

回归任务重点检查
小范围代码修改是否遵守文件范围，是否引入无关改动
代码审查是否遗漏明显错误，结论能否定位到具体代码
自动定时任务是否能按时启动，输出格式是否兼容下游流程

可以记录以下结果：

任务是否成功启动
运行时间
修改文件数量
测试通过情况
人工修正次数
输出格式是否改变
是否触发额外权限

官方对 Terra 的定位是日常工作的均衡模型，而 Luna 更适合边界明确、重复性较强的任务。这是一种选型建议，不代表旧任务迁移后一定保持完全相同的输出。

尤其是以下场景，不建议只做字符串替换后直接上线：

  • 输出结果被其他脚本解析；
  • 定时任务会自动修改仓库；
  • Agent 具有网络或外部系统权限；
  • 代码审查结果直接影响合并；
  • 原任务对推理深度和格式稳定性要求较高。

十、把检查脚本接入 CI

迁移完成后，可以让 CI 持续阻止旧配置重新进入仓库。

package.json：

{
  "scripts": {
    "check:models":
      "node tools/migrate-codex-models.mjs",
    "migrate:models":
      "node tools/migrate-codex-models.mjs --write",
    "test":
      "node --test"
  }
}

在 CI 中执行：

npm run check:models
npm test

如果开发者再次提交旧配置，检查脚本会返回退出码 1，使流水线失败。

但这个检查只覆盖白名单内的活跃配置。新增 Custom Agent、定时任务或脚本以后，应同步更新 targetFiles。

十一、最终迁移清单

正式完成前，可以逐项确认：

  • 是否确定自己使用的是 ChatGPT 登录的 Codex；
  • 是否检查了本地 config.toml；
  • 是否检查了 Custom Agents；
  • 是否检查了 codex exec --model 命令；
  • 是否检查了定时任务与托管配置；
  • 是否区分 Codex 配置与 OpenAI API 配置；
  • 是否先处理 gpt-5.4-mini；
  • 是否避免修改历史文档和测试夹具；
  • 是否运行迁移脚本测试；
  • 是否重新执行旧模型残留检查；
  • 是否使用历史任务验证迁移后的输出质量。

模型迁移最危险的地方，不是少改一个字符串，而是把不属于同一适用范围的配置一起修改。

先发现全部引用，再判断身份验证方式和工作负载，最后执行白名单迁移与任务回归，才是这次 Codex 模型调整更稳妥的处理方式。

# 人工智能
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

状态丢失排障：Claude 持久记忆的跨会话局限与知芽 Notebook Skill 单元记忆如何沉淀可复用知识资产

avatar DeepSeek技术社区
cover

不加一个参数，能力反超旗舰：大模型的“另一半功夫“

avatar DeepSeek技术社区
cover

基于AI agent的智能图书馆

avatar DeepSeek技术社区