如果你只是在 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.4	gpt-5.6-terra	日常开发、代码修改、工具调用
gpt-5.4-mini	gpt-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 模型调整更稳妥的处理方式。