Codex CLI升级后多文件编辑静默失效：config.yaml枚举变更排查与修复指南实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex CLI升级后多文件编辑静默失效：config.yaml枚举变……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

Codex CLI 升级后多文件编辑静默失效：config.yaml 枚举变更排查与修复指南

结合项目来看，上周三我把一个老项目的 Codex CLI 升了一版，跑了个多文件重构任务，结果发现它只改了一个文件就停了。没报错，没警告，日志里干干净净。我反复排查了大半天，最后才定位到问题：实际处理时，新版 Codex CLI 对 GPT-5.5 系列的 model 参数做了枚举拆分，旧 config.yaml 里填的 gpt-5.5 通用值在新版会被静默映射回单文件模式的旧模型，多文件编辑能力根本没激活。

落到代码里，这个问题比较隐蔽——不报错，不提示，就是默默降级。你以为在用 GPT-5.5 的全部能力，实际上跑的是受限版本。

这篇适合谁

• 正在用 Codex CLI 日常写代码，最近升过级或者打算升级的
• config.yaml 里 model 字段填了 gpt-5.5 但发现多文件任务表现变差的
• 想搞清楚 GPT-5.5 系列到底有哪些子模型、分别对应什么能力的
• 落到代码里，借助 OpenRouter 等聚合网关接入 Codex CLI，需确认 model ID 怎么填的

整体流程

1. 确认你当前 Codex CLI 版本和 config.yaml 里的 model 值
2. 理解新版枚举拆分的逻辑——哪些值映射到哪个模型
3. 修改 config.yaml，填入正确的新枚举值
4. 验证多文件编辑模式是否正常激活
5. 针对不同场景选择合适的子模型

graph TD
 A[升级 Codex CLI] --> B{config.yaml 里<br>model 填的啥?}
 B -->|gpt-5.5 通用值| C[静默降级到单文件模式]
 B -->|支持多文件的具体子模型| D[多文件编辑正常激活]
 C --> E[改 config.yaml 枚举值]
 E --> D
 D --> F[验证: 跑一个多文件任务确认]

先说结论

一句话：理解这一步时，升级 Codex CLI 后，如果你在用 GPT-5.5 系列，必须检查 config.yaml 里的 model 枚举值，旧的通用写法会让你丢掉多文件编辑能力且不报任何错。

第一步：确认当前版本和设置

先看你现在跑的是什么版本：

# 如果已全局安装（npm install -g @openai/codex），用这条：
codex --version

# 如果未全局安装，用 npx 临时执行：
npx @openai/codex --version

两条命令的区别：第一条要求你已经全局安装了 Codex CLI；第二条借助 npx 临时拉取执行，不依赖全局安装，但每次会检查最新版本。日常采用建议全局安装后用第一条。

再看你的全局设置文件：

cat ~/.codex/config.yaml

若你的 config.yaml 长这样，那就是"中招"的典型：

model: gpt-5.5
approvalMode: auto-edit

注意：approvalMode 字段已在 Codex CLI 官方文档中确认。config.yaml 兼容的字段以当前版本官方文档为准，采用前建议核对，避免填入不兼容的字段后静默失效。

这个 gpt-5.5 在旧版 Codex CLI 里是个通用值，能正常路由到 GPT-5.5 的完整能力。但新版做了枚举拆分之后，这个值会被映射到一个基础版本——没有多文件编辑、没有跨文件上下文追踪。

第二步：理解新版枚举拆分逻辑

落到代码里，新版 Codex CLI 把 GPT-5.5 系列拆成了多个明确的枚举值。当前可用的 GPT-5.x 系列模型包括：

关键问题在这里：旧版 Codex CLI 遇到 gpt-5.5 会把它当作"GPT-5.5 系列最高能力版本"来用，但新版的枚举逻辑变了——gpt-5.5 这个裸值被当作基础版处理，多文件编辑需你显式指定兼容该能力的子模型。

在这个场景下，起初我不确定是不是这个原因，因为终端里没有任何提示。后来我对比了两次任务的实际输出文件数量，结合 token 消耗才发现端倪——多文件任务实际只修改了一个文件，token 用量也明显偏低。这里需留意，token 消耗低本身不能单独作为模型降级的证据（任务轻松或上下文窗口截断也会导致同样现象），应以实际修改的文件数量作为主要判断依据。

第三步：修改 config.yaml

若你需多文件编辑能力，把 config.yaml 改成这样：

model: gpt-5.6-terra
approvalMode: auto-edit

gpt-5.6-terra 是目前 GPT-5.x 系列里偏代码生成的子模型。如果你更看重推理能力（比如复杂的架构决策），能够换成 gpt-5.6-sol。

也能够用命令行参数临时覆盖，不改设置文件：

codex --model gpt-5.6-terra "重构 src/ 下所有组件为 hooks 模式"

从实现思路看，若你借助 API 中转层接入，OpenRouter 等聚合网关兼容在请求头里透传 model 短名，但不同网关对 GPT-5.6 系列子模型的枚举同步节奏不同——建议在各自的 model 列表页确认 gpt-5.6-terra 是否已上线，再写死到 config.yaml 里。

第四步：验证多文件编辑是否激活

跑一个明确需跨文件操作的任务来验证：

codex "把 src/utils.ts 里的 formatDate 函数移到 src/helpers/date.ts，并更新所有引用"

理解这一步时，若多文件编辑正常工作，你会看到 Codex 列出多个文件的修改计划（在 auto-edit 模式下会逐个让你确认）。如果它只改了一个文件就说"done"，那就是还没激活。

借助聚合网关接入时的注意事项

在这个场景下，若你不是直连 OpenAI，而是借助 API 聚合网关（比如 OpenRouter）接入的，model 参数的写法可能不太一样。

聚合网关场景下的 config.yaml：

provider:
  name: custom
  baseURL: https://openrouter.ai/api/v1
  apiKey: your-key-here
model: gpt-5.6-terra

这里有个常用问题：OpenRouter 采用 provider/model 格式的 model ID（比如 openai/gpt-5.6-terra），与直连 OpenAI 时只填短名的方式不同。两种格式的隔离层级和路由逻辑不同，不能混用。具体以 OpenRouter 官方文档为准，建议直接查阅其 model 列表页确认当前兼容的完整 ID。

落到代码里，若你用的是其他中转网关，情况类似。以 ofox.io 为例，其 config.yaml 设置结构与 OpenRouter 相近：

provider:
  name: custom
  baseURL: https://ofox.io/v1
  apiKey: your-key-here
model: openai/gpt-5.6-terra

在这个场景下，同样需留意 model ID 格式是否与网关文档一致，gpt-5.6-terra 的短名和 openai/gpt-5.6-terra 的完整 ID 在不同网关侧的路由行为不同，填错会触发 Error: Invalid model 或静默回退到默认模型。

不同场景怎么选

o4-mini 在日常单文件任务上已经很够用了，没必要所有任务都上 5.6 系列。具体定价以 OpenAI 官方定价页 为准，不同模型的成本差异在复杂任务量大时会比较显著，建议结合自己的用量实际估算。

报错对照表

升级过程中你可能遇到的报错：

结合项目来看，最后一行"多文件任务只改了一个文件，无报错"是最难发现的——因为它不报错，你可能跑了很久都没意识到多文件能力丢了。

常用问题 FAQ

Q: 升级 Codex CLI 后 config.yaml 会被覆盖吗？

不会。npm install -g @openai/codex 只更新二进制，不动 ~/.codex/config.yaml。但这恰恰是问题所在——旧设置文件里的 model 值在新版里语义变了，而工具不会提醒你。

Q: 我怎么知道当前跑的到底是哪个模型？

在这个场景下，目前 Codex CLI 没有一个 --verbose 级别的日志会打印实际路由到的模型 ID。比较可靠的做法是检查任务实际修改的文件数量是否符合预期。如果你借助 OpenRouter 等聚合网关接入，能够在网关的用量面板里直接看到实际调用的模型名和 token 数。直连 OpenAI 的话能够查 billing dashboard。

Q: gpt-5.6-luna、gpt-5.6-sol、gpt-5.6-terra 怎么选？

理解这一步时，这三个是 GPT-5.6 系列的不同特化方向，官方未公布详细 benchmark 对比。从社区反馈来看：terra 偏代码生成，sol 偏推理，luna 偏长上下文。日常编码建议从 terra 开始，写技术文档能够试试 luna，具体效果建议结合自己的任务类型实测。

Q: AGENTS.md 里写了模型相关的指令会覆盖 config.yaml 吗？

在这个场景下，不会。AGENTS.md 是项目级行为规范文件，注入到上下下文，控制的是"AI 应该怎么做事"（比如代码风格、提交规范、禁止操作的目录等）；config.yaml 控制的是"工具用哪个模型、什么审批模式"。两者职责完全不同，不要在 AGENTS.md 里写 model: xxx，那没用。

Q: full-auto 模式安全吗，会不会把我的文件搞乱？

从实现思路看，有沙箱保护。macOS 采用 Apple Seatbelt 进行系统调用级别的隔离；Linux 提供两种沙箱机制，Docker 借助容器实现网络和文件系统的整体隔离，Landlock 是内核级文件系统沙箱，仅限制文件访问路径，两者隔离层级和适用条件不同——有 Docker 环境时优先采用 Docker，Landlock 适合不便运行容器的场景。建议在有 git 版本控制的目录下采用 full-auto，跑完用 git diff 检查再 commit。需回滚时 git checkout . 一行即可。

Q: 能不能用本地模型跑 Codex CLI？

从实现思路看，能够。在 config.yaml 里设置 provider 指向本地服务就行：

provider:
  name: custom
  baseURL: http://localhost:11434/v1
  apiKey: ollama
model: llama3.2

实际处理时，不过本地模型的多文件编辑能力通常有限，该能力依赖模型本身对特定 function calling 格式的兼容。

小结

理解这一步时，这次升级最棘手的地方就是"不报错"。枚举值变了，旧值被静默降级，你以为一切正常其实能力打了折扣。目前 Codex CLI 没有针对这种情况的 deprecation warning，希望后续版本能补上。

修复方法很轻松：检查 ~/.codex/config.yaml 里的 model 字段，如果填的是 gpt-5.5 裸值且需多文件编辑能力，改成 gpt-5.6-terra 或其他明确兼容多文件的子模型即可。

从实现思路看，总的来说，Codex适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。