你让 Codex “把 auth module 重构到用新的 session API”。四十分钟后它中途停了：PR 改了 8 个文件，另外 6 个动过的文件还留着 // TODO: migrate this 注释。或者 transcript 结尾是 context_length_exceeded，又或者它停下来做 compaction 然后再没缓过来。Codex 干了真活，但中途 context 不够了，你的 branch 现在半新半旧。
最快的修法： 别想一次 run 把整个重构做完。把任务重新窄到「一个动词 + 一份明确的文件列表」（Step 1）；如果改动确实大，就拆成多 PR plan（Step 2），让每次 run 都塞得进 context window。光这一步就能解决绝大多数这类卡死。剩下的篇幅讲那些光靠切范围还不够的情况——配置调优和 resume 工作流。
这不是 Codex 的 bug。是任务跨的代码量超过了 model context window 装得下的量。截至 2026 年 6 月，Codex CLI 并不强制一个硬性的「per-task tool-call 上限」——它的机制是 token 用量过阈值时自动 auto-compact（压缩对话历史），而一个过大的重构只会不断冲破 compaction 能保住的范围。解药是开工前的范围纪律，加上几个 harness 层面的开关（选 model、拆多 PR、精确列文件、调 compaction）。
你属于哪一类？
把你 Codex transcript 的最后几行（或 TUI 状态栏）对到下表的某一行，再跳到它指向的修法。
| transcript / TUI 里的症状 | 可能原因 | 跳到 |
|---|---|---|
context_length_exceeded 或 “Context window exceeded” | 任务跨的代码超过 window 容量 | Step 1-3 |
| ”Compacting context…” 之后卡住或报错 | auto-compaction 保不住足够内容；session 太长 | Step 1-2、5 |
| 跑了 N 个文件后停，剩下没动，也没报错 | 预算见底，没下文 | Step 1-3 |
git diff --stat 里某个文件改了几千行 | generated/lockfile/vendored 大文件吃光预算 | Step 4 |
同一个 read_file path 在 transcript 里出现 3 次以上 | 重复读已经在 context 里的文件 | Step 3-4 |
| 它改了没关系的文件（“既然来了，顺便…”） | 范围太开放 | Step 1、6 |
常见原因
1. 任务跨的文件太多，context 装不下
你要重构 auth module，30 个文件、8k 行。哪怕 context window 很大，Codex 也要读每个文件、产生 edit。跑到一半，下一个文件的内容塞不进还在跑的 plan 旁边，于是 auto-compaction 触发——而一旦 compaction 没能让线程保持连贯，这次 run 就停了。
如何判断：transcript 结尾是 context_length_exceeded 或 Maximum context reached，或者跑了 N 个文件后就没下文，剩下没动。
2. context 填满的速度超过 compaction 能恢复的速度
长 refactor 会攒一大堆历史：read_file、apply_patch、再 read_file 验证、run_shell 跑 type check。用量一旦越过 model_auto_compact_token_limit，Codex 就会总结对话、重建一份更短的历史。在特别长的 session 上这一步会失败——压缩 GPT-5.5 的长 session 是 2026 年中已知的薄弱点（/compact 可能在 UI 上显示成功，却仍然报 context_length_exceeded）。
如何判断：状态栏显示 “Compacting context…”，然后这次 run 要么报错，要么跟丢线索（忘了前面的决定，开始返工）。
3. patch 里某个文件巨大
5000 行的 generated 文件（lockfile、SVG、vendored 库）进了 diff。读和写它一次就吞掉一大块预算。
如何判断：git diff --stat 里某个文件改了几千行。或者 agent “卡” 在单个文件上不动。
4. Codex 重复读已经在 context 里的文件
Model 跟丢了它已经加载过什么，对同一个 path 调好几次 read_file。每次都吃 token，最后 window 里很大一块是重复的文件内容。（注意：每次 compaction 之后，Codex 会自动重新读最近编辑过的最多 5 个文件——本意是好的，但在大任务上这意味着反复重载同几个大文件。）
如何判断：在 transcript 里搜对同一 path 的重复 read_file。
5. 任务太开放（“全部清理一遍”）
你写 “把 auth module 清理一下”。Codex 理解成 “重写 12 个文件”，但你本来只想 “把 auth module 里的 User.uid 全改名成 User.id”。开放任务的范围会一直膨胀直到撞预算。agentic PR 的实测数据也印证这点：被拒的 PR 比通过的 PR 平均多动约 10% 的文件、多改约 17% 的行（MSR 2026 对约 33000 个 agentic PR 的研究）。小不只是对 agent 友好——它的合并率也更高。
如何判断：对比你的任务描述和 Codex 实际动的文件。它动了没关系的东西，就是范围没设界。
最短修复路径
Step 1：任务窄到一个动词 + 一个 module
差：「重构 auth module。」
好：「只在 src/auth/*.ts 里，把 User.uid 改名成 User.id。改所有 call site。Test 文件只做机械改名。」
好的 prompt 包含：
- 一个动词：rename、extract、replace、delete、add
- 一个范围：path glob 或显式文件列表
- 一个 non-goal：“不要碰 X、Y、Z”
# 推荐的 Codex 任务模板
GOAL: <一句话，一个动词>
SCOPE: <显式文件列表或 glob>
NON-GOALS: <哪些不要碰>
ACCEPTANCE: <测试通过 + 1 个具体检查>Step 2：大改拆成多 PR plan
凡是跨 10 个文件以上（或大约 300 改动行——一个好用的单 PR 上限）的改动，写 plan 让 Codex 每个 PR 跑一步：
# Auth 迁移 plan
PR 1：新增 `Session` API，和老的 `auth.cookie` 并存（caller 暂不动）
PR 2：迁移 `src/auth/login.ts` 和 `src/auth/logout.ts`
PR 3：迁移 `src/auth/middleware/`（3 个文件）
PR 4：迁移 `src/pages/api/` 的 caller（10 个文件，机械改）
PR 5：删除旧 `auth.cookie`，更新 README每个 PR 都小到能在一次 Codex run 里塞下，Reviewer 也跟得上。用 Codex app 的话，每个 task 会拿到自己的 git worktree，所以你能并行跑互不相干的 PR 步骤而不撞 branch。
Step 3：prompt 里预先列出要改的文件
省掉 agent 自己 discover 的步骤（这步本身也要花 read 和 token）：
要改的文件（仅限这些）：
- src/auth/session.ts
- src/auth/cookie.ts
- src/auth/middleware/withAuth.ts
- tests/auth/session.test.ts
如果你需要改不在这个列表里的文件，停下来问。既缩小 working set 又防 scope creep。
Step 4：让 lockfile 和 generated 文件不进 agent 的视野
在 repo 根目录的 AGENTS.md 里写：
## 规划时跳过的文件
除非明确要求，不要完整读这些：
- package-lock.json、pnpm-lock.yaml、yarn.lock
- 超过 200 行的 *.svg
- src/generated/**
- public/**
- *.min.js、*.min.css
要更新 lockfile，跑 `npm install`，不要手动编辑。这些是最大的预算大户，agent 一行一行读它们永远不值。你还可以用一个 .codexignore 文件（glob 语法和 .gitignore 一样）让索引直接跳过它们。
Step 5：调 model 和 auto-compaction 阈值
Codex CLI 能挑底层 model，也能控制它何时 compact。真正跨多文件的任务，用最强的 model 并给 compaction 多留余量。
# 在推荐 model 上非交互跑一个任务
codex exec --model gpt-5.5 "执行 PLAN.md 里的 plan"截至 2026 年 6 月，gpt-5.5 是 Codex 里复杂编码的推荐默认 model；另有 gpt-5.4 和更快的 gpt-5.4-mini（适合 subagent）。用 --model/-m 选 model，或在 config.toml 里设。
注意这里没有 --max-tool-calls 这种 flag——Codex 靠 auto-compaction，不靠硬性 call 上限，别浪费时间找它。要调就在 ~/.codex/config.toml（或 per-project 的 .codex/config.toml）里调 compaction：
# ~/.codex/config.toml
model = "gpt-5.5"
# 让 Codex 在 compact 之前用满整个 window。
model_context_window = 400000
# 抬高触发 auto-compaction 的阈值
# （Codex 会把它 clamp 到 context window 的约 90%）。
model_auto_compact_token_limit = 350000model_auto_compact_token_limit 是触发自动总结历史的 token 阈值；在 clamp 范围内把它抬高，能让一次 run 在被迫 compact 前跑得更远。设对 model_context_window 也重要——如果它被探测得偏低，Codex 会比实际需要更早 compact。但在没切范围的任务上预算越大、烂摊子越大，所以先做 Step 1。
Step 6：让 Codex 停下来时写 resume note
AGENTS.md 里：
如果你的 context 快不够用，停下来之前写一个文件
`.codex/resume.md`，包含：
- 哪些文件做完了
- 哪些文件改了一半（当前状态是什么）
- 哪些文件没动
- 下一个该做的具体动作是什么
把 `.codex/resume.md` 一起 commit 进 PR。下一次 run 从这个 note 接着干，不用重新 discover 状态——你也可以把这个 note 贴进一个全新 session，从而彻底绕开不靠谱的长 session /compact 路径。
怎么确认修好了
- run 跑完且没有 context 报错。 transcript 以 agent 的总结和一个通过的检查结束，而不是
context_length_exceeded。 - diff 和你的文件列表一致。
git diff --stat只显示你圈定的文件——没有意外多出来的。如果 stat 里冒出 generated 文件或 lockfile，就收紧AGENTS.md/.codexignore。 - 没有残留的迁移标记。
git grep -n "TODO: migrate"（或你项目里的标记）在动过的 path 里应该什么都搜不到。 - acceptance 检查通过。 跑你
ACCEPTANCE那行写的具体检查（一个测试、一次 type-check、一个确认旧符号已消失的 grep），而不只是 “测试通过”。
四条都成立，任务才是真干完了——而不只是停下了。
常见问答
有没有办法让 Codex 永远不会 context 用尽？ 没有。每个 model 都有固定 window，而 auto-compaction 是有损的——它总结旧历史，细节会丢。可靠的路子是把每个任务切到根本碰不到上限的大小，而不是指望 compaction 来救一个过大的任务。
光换成 gpt-5.5 能不能修好卡住的重构？
通常不能。更大或更强的 model 多给点余量，但开放任务会膨胀着把余量填满。先切范围（Step 1-3），再换 model。
Codex 显示 “Context compacted”，紧接着却报 context_length_exceeded，为什么？
压缩很长的 GPT-5.5 session 是 2026 年中已知的薄弱点：总结用的 payload 本身就可能超过 window。别硬扛——开个全新 session，把你的 .codex/resume.md（Step 6）交给它，别去 compact 一个巨大的线程。
给 agent 用的 PR 多大合适？ 每个 PR 控制在一个 concern、大约 300 改动行以内。agentic PR 的数据很直白：越大的 PR（更多文件、更多行）被拒得越多。改动需要更多，就需要拆多 PR（Step 2）。
repo 级规则和单任务指令分别放哪？
长期规则（跳过列表、约定、写 resume note 的指令）放 AGENTS.md。单任务范围（文件列表、那一个动词、non-goal）放 prompt。别把任务范围埋进 AGENTS.md——那会让每次 run 的 context 都变臃肿。
预防
- 每个任务窄到一个动词 + 一个 module + 显式文件列表。
- 跨 10 个文件（或约 300 行）以上的改动拆成多 PR plan。
AGENTS.md/.codexignore里列出要跳过的 path（lockfile、generated、public asset）。- 实在需要大改，用
gpt-5.5并在切好范围后抬高model_auto_compact_token_limit。 - 让 Codex 写
.codex/resume.md以便中断后能续上。 - 每次跑完，diff 一下 file 列表，多动了就把 prompt 收紧。
相关
外部参考：Codex CLI 命令行参考 · Codex models