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 怎么填的
整体流程
- 确认你当前 Codex CLI 版本和 config.yaml 里的 model 值
- 理解新版枚举拆分的逻辑------哪些值映射到哪个模型
- 修改 config.yaml，填入正确的新枚举值
- 验证多文件编辑模式是否正常激活
- 针对不同场景选择合适的子模型
先说结论
| 你的情况 | 要不要升 | 升完要改什么 |
|---|---|---|
config.yaml 填的 gpt-5.5 |
升完必须改 model 值，否则多文件编辑静默失效 | 改成 gpt-5.6-terra（支持多文件编辑）或其他明确支持多文件的子模型 |
用 o4-mini 跑日常任务 |
不受影响，放心升 | 不用改 |
用 codex-1 默认模型 |
不受影响 | 不用改 |
通过聚合网关转发，model 填的完整 ID 如 openai/gpt-5.5 |
需要确认网关侧的模型映射是否更新 | 检查网关文档 |
一句话：升级 Codex CLI 后，如果你在用 GPT-5.5 系列，必须检查 config.yaml 里的 model 枚举值，旧的通用写法会让你丢掉多文件编辑能力且不报任何错。
第一步：确认当前版本和配置
先看你现在跑的是什么版本：
bash
# 如果已全局安装（npm install -g @openai/codex），用这条：
codex --version
# 如果未全局安装，用 npx 临时执行：
npx @openai/codex --version两条命令的区别：第一条要求你已经全局安装了 Codex CLI；第二条通过 npx 临时拉取执行，不依赖全局安装，但每次会检查最新版本。日常使用建议全局安装后用第一条。
再看你的全局配置文件：
bash
cat ~/.codex/config.yaml如果你的 config.yaml 长这样，那就是"中招"的典型：
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 系列模型包括：
| model 枚举值 | 多文件编辑 | 适用场景 |
|---|---|---|
gpt-5.5 |
⚠️ 新版静默降级，不推荐 | 通用对话、单文件任务 |
gpt-5.4 |
❌ | 通用推理 |
gpt-5.4-mini |
❌ | 轻量任务 |
gpt-5.4-pro |
✅ | 复杂多文件重构 |
gpt-5.6-luna |
✅ | 多文件+长上下文 |
gpt-5.6-sol |
✅ | 偏推理 |
gpt-5.6-terra |
✅ | 偏代码生成 |
关键问题在这里：旧版 Codex CLI 遇到 gpt-5.5 会把它当作"GPT-5.5 系列最高能力版本"来用，但新版的枚举逻辑变了------gpt-5.5 这个裸值被当作基础版处理，多文件编辑需要你显式指定支持该能力的子模型。
起初我不确定是不是这个原因，因为终端里没有任何提示。后来我对比了两次任务的实际输出文件数量，结合 token 消耗才发现端倪------多文件任务实际只修改了一个文件，token 用量也明显偏低。需要注意的是，token 消耗低本身不能单独作为模型降级的证据（任务简单或上下文窗口截断也会导致同样现象），应以实际修改的文件数量作为主要判断依据。
第三步：修改 config.yaml
如果你需要多文件编辑能力，把 config.yaml 改成这样：
yaml
model: gpt-5.6-terra
approvalMode: auto-editgpt-5.6-terra 是目前 GPT-5.x 系列里偏代码生成的子模型。如果你更看重推理能力（比如复杂的架构决策），可以换成 gpt-5.6-sol。
也可以用命令行参数临时覆盖，不改配置文件：
bash
codex --model gpt-5.6-terra "重构 src/ 下所有组件为 hooks 模式"如果你通过 API 中转层接入，OpenRouter 等聚合网关支持在请求头里透传 model 短名，但不同网关对 GPT-5.6 系列子模型的枚举同步节奏不同------建议在各自的 model 列表页确认 gpt-5.6-terra 是否已上线，再写死到 config.yaml 里。
第四步：验证多文件编辑是否激活
跑一个明确需要跨文件操作的任务来验证：
bash
codex "把 src/utils.ts 里的 formatDate 函数移到 src/helpers/date.ts，并更新所有引用"如果多文件编辑正常工作，你会看到 Codex 列出多个文件的修改计划（在 auto-edit 模式下会逐个让你确认）。如果它只改了一个文件就说"done"，那就是还没激活。
通过聚合网关接入时的注意事项
如果你不是直连 OpenAI，而是通过 API 聚合网关（比如 OpenRouter）接入的，model 参数的写法可能不太一样。
聚合网关场景下的 config.yaml：
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 相近：
yaml
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 或静默回退到默认模型。
不同场景怎么选
| 你的场景 | 推荐 model 值 | 理由 |
|---|---|---|
| 日常写代码，单文件改改 bug | o4-mini |
成本低，够用 |
| 多文件重构、跨模块改接口 | gpt-5.6-terra |
代码生成能力强，多文件编辑支持完整 |
| 复杂架构决策、需要深度推理 | gpt-5.6-sol |
推理能力更强 |
| CI/CD 自动化脚本里跑 | o4-mini + full-auto |
成本可控，沙箱保护 |
| 预算紧张但需要多文件 | gpt-5.4-pro |
比 5.6 系列便宜，多文件能力有 |
| 不确定选啥 | gpt-5.6-terra |
代码任务综合表现稳定 |
o4-mini 在日常单文件任务上已经很够用了，没必要所有任务都上 5.6 系列。具体定价以 OpenAI 官方定价页 为准，不同模型的成本差异在复杂任务量大时会比较显著，建议结合自己的用量实际估算。
报错对照表
升级过程中你可能遇到的报错：
| 现象 | 原因 | 解法 |
|---|---|---|
Error: OPENAI_API_KEY is not set |
环境变量没设或者 config.yaml 里没写 apiKey | export OPENAI_API_KEY=sk-... 或在 config.yaml 的 provider 里加 apiKey |
Error: Cannot find module '@openai/codex' |
Node.js 版本低于 22 | node --version 检查，升级到 >= 22 |
Error: spawn docker ENOENT |
Linux 下用 full-auto 模式但没装 Docker | 装 Docker，或者用 auto-edit 模式绕过沙箱 |
Error: rate_limit_exceeded: Rate limit reached for model codex-1 |
默认模型限流了 | 切换到 o4-mini 或 gpt-5.6-terra，或者等一会儿重试 |
| 多文件任务只改了一个文件，无报错 | model 枚举值被静默映射到不支持多文件的版本 | 检查 config.yaml，改成 gpt-5.6-terra 等支持多文件的枚举 |
Error: Invalid model 或 model not found |
填了网关不认识的 model ID 格式 | 确认网关要求的格式（短名 vs 完整 ID）；OpenRouter、ofox.io 等网关各自的 model 列表页均可查到当前支持的完整 ID |
最后一行"多文件任务只改了一个文件，无报错"是最难发现的------因为它不报错，你可能跑了很久都没意识到多文件能力丢了。
常见问题 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 指向本地服务就行：
yaml
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 或其他明确支持多文件的子模型即可。