Codex 计划任务堆出一大堆 worktree 的判定、清理与验证

2026-08-09

用 Codex（OpenAI Codex）挂了几个计划任务之后，很多人会在某天发现一个不太舒服的画面：仓库目录旁边（或者仓库内部某个位置）多出一串看着像自动生成的工作目录，git worktree list 一敲，出来十几行甚至几十行。磁盘占用往上走，编辑器的全局搜索开始命中重复文件，git branch 里也多了一堆你不记得建过的分支。

这个现象官方是认的。Codex 官方排查页（Troubleshooting）里就有一条独立条目：计划任务产生了大量 worktree。它给了处置口径，但没有给出成因说明——那一栏是空的。所以下面的机制部分我不会替官方编原因，只讲你能实际做的判定、处置和验证。

一、先说清楚这篇覆盖的边界

有两件事必须先摆在前面，不然容易白折腾半天：

第一，官方排查页里的绝大多数条目是面向桌面应用的，包括本文这条。也就是说，「归档计划运行」「不要 pin」这类动作是官方针对桌面应用侧给的口径，我们没有实测，本文只能按「官方文档给的做法是……」的口径转述，不会告诉你按钮在哪、菜单点几层——那些我们没看过。

第二，本机这边（codex-cli 0.147.0，Windows 11）我们只跑过只读命令，一次模型对话请求都没发过，所以我不会写「我挂了个计划任务，跑了几轮以后目录变成什么样」。本文里凡是标「本机实测」的，都是 --help、doctor、目录列举这一类不产生副作用的观察。

二、怎么确认是这个问题

别一上来就删目录。先确认三件事：这些目录确实是 git worktree、它们和计划任务对得上、你的磁盘涨的确实是它们。

判定一：列出所有 worktree

git worktree list

这是 git 自带的命令，不是 Codex 的功能，任何装了 git 的机器上都能跑，纯只读。输出里每一行是一个工作树：路径、当前 commit、所在分支。主仓库自己也会占一行。

如果这条命令列出来的路径数量远超你自己手动建过的数量，那基本可以确定不是你手滑建的。

判定二：逐个看这些工作树里有没有你不能丢的东西

git -C <某个 worktree 路径> status

这一步的意义不在于诊断，在于保命。worktree 是独立的工作目录，里面完全可能躺着没提交的改动。后面无论是谁来清理，清掉的都是真文件。先把「哪几个有未提交改动」这张名单拉出来，再谈删。

判定三：确认磁盘涨的是 worktree，还是 Codex 自己的数据目录

这一步特别容易搞错方向。Codex 的主目录（~/.codex/，也就是 CODEX_HOME）本身就能吃掉不少空间。在 codex-cli 0.147.0（Windows 11）上执行：

codex doctor --summary

本机实测，doctor 的 Notes 区会报一行 rollouts，直接给出 active 文件数与占用体积；本机这一行显示的是几个 GB 量级，另外 ~/.codex/ 下的 SQLite 日志库单个文件也到了数百 MB。这些占用和 worktree 完全是两码事——它们在你的用户目录里，不在仓库旁边。

同样值得记一笔的是：在 codex-cli 0.147.0 上，codex doctor --summary 观测到的分组是 Environment / Configuration / Updates / Connectivity / Background Server 那几组，里面没有任何一项是检查 worktree 数量的。所以别指望 doctor 帮你发现 worktree 堆积，它管的是安装、配置、认证和运行时健康。

至于计划任务本身，本机在 ~/.codex/ 下确实观测到一个 automations/ 目录（这就是计划任务落地的位置）。但我们没有查看它的内容，所以我不会描述里面文件的格式或字段——卡外的东西一个字都不该写。

三、官方给出的处置

官方排查页对这条现象给的做法只有两句，我原样转述：

归档不需要的计划运行；
除非你确实要保留对应的 worktree，否则不要 pin。

第二条其实是这条排查项里最有信息量的部分：它暗示 pin 与 worktree 的保留是挂钩的。换句话说，如果你习惯性地把计划运行 pin 住，那些工作树就会一直留着。反过来，把不需要的计划运行归档掉，是官方给的正路。

这两个动作都属于桌面应用侧的口径，我们非亲测，具体入口请以官方文档为准。

这里有个很容易张冠李戴的坑：Codex CLI 里确实有 codex archive / codex unarchive / codex delete 这组子命令（本机实测帮助文本），但它们的作用对象是已保存的会话——按 id 或会话名归档、取消归档、永久删除。官方排查页说的「归档不需要的计划运行」和 CLI 的会话归档不是同一件事。事实卡里没有任何一条能证明「跑 codex archive 就能连带清掉计划任务建出来的 worktree」，所以别把它当清理工具用。

至于把已经躺在磁盘上的那些工作树目录本身处理掉，官方这条排查项没有列具体做法。这属于 git 自己的地盘：worktree 是 git 的机制，git 也提供了对应的管理命令。我不打算在这里编一套官方没写过的清理流程给你抄，只提醒一句——动手前请务必先把「判定二」那张名单过一遍，确认里面没有你还要的改动，也确认对应分支上的提交是否已经推走。

四、处置之后怎么验证

验证同样用只读命令，三步：

git worktree list

第一步是先跑一次记下行数，但别急着用这一个数字判定成败。官方这条排查项只写了「归档不需要的计划运行」「除非要保留 worktree 否则不要 pin」两个动作，没有说明归档之后已经存在的工作树目录会不会被回收，我们也没有实测过。所以第一次验证时把两种可能都留着：行数下降、行数停在原地，都不能直接当成失败。真正可靠的信号是下面第二条的增量。

第二看增量，这才是这一节的重点。隔一个计划任务的执行周期再跑一次 git worktree list，把两次输出比一比，看的是新增了几行，而不是总共有几行。如果行数不再往上涨，至少说明「继续堆」这件事被按住了；如果照涨不误，说明还没解决——但成因这里我不替官方补：官方对这条只给了归档与不要 pin 两个动作，卡外的原因我们没有依据，这时候该回到官方文档的《Troubleshooting》页和《Scheduled tasks》页去确认，而不是继续在本机瞎猜。猜出来的结论会让你在错误的方向上再花一天。

第三看磁盘。用 Git Bash 的 du -sh、或 Windows PowerShell 里的目录统计命令，对着那批工作树的父目录量一次，和处置前的数字比。同时别忘了把 codex doctor --summary 的 Notes 那一行也记下来——把「仓库旁边的 worktree」和「~/.codex/ 里的 rollouts 与日志库」分开算，否则你会得出「清了半天怎么一点没少」的错误结论，而实际上少的那部分被另一处的增长盖住了。

五、什么情况说明不是这个原因

一条道走到黑是排查里最贵的错误。下面几种情况，问题根本不在「计划任务堆 worktree」上：

worktree 数量不多，但代码在 worktree 上跑不起来。 这是官方排查页里另一条独立条目，成因也写得很清楚：worktree 是另一个目录，只继承了 Git 追踪的文件，所以缺依赖。官方给的做法是——通过本地环境跑初始化脚本，或者用 .worktreeinclude 把那些被忽略、但实际需要的文件纳进来。如果你的症状是「目录在但 npm install 之类的产物没有」，直接去这条，别在数量上纠结。

磁盘涨了，但 git worktree list 只有一两行。 那多半就是上面说的 ~/.codex/ 侧占用，跟 worktree 无关，处置方向完全不同。

多出来的目录不在 git worktree list 里。 那它们就不是 worktree，可能是构建产物、缓存或者别的工具留下的目录。git 不认，这条排查项就套不上。

你根本没在用计划任务。 官方这条的前提是「计划任务产生的」。如果你的 worktree 是自己或队友手动建的、或者是某个 CI/脚本建的，那「归档计划运行」自然无从谈起，该去查建它的那个东西。

「同事的配置识别不到」被误当成 worktree 问题。 官方另有一条：配置没被识别，是因为 .codex 文件夹不在项目根目录；monorepo 场景要打开正确的目录。这跟工作树数量没关系。

六、想再往深挖的话

官方文档站有两页跟这个主题直接相关：/docs/automations（页名 Scheduled tasks）与 /docs/environments/git-worktrees（页名 Worktrees）。这两页的内容我们没有取，所以本文不会替它们总结任何细节——想深入请自己去读原页。

顺手给两个能省时间的用法：文档站任何一个页面的 URL 后面加 .md 后缀就能拿到 Markdown 版本；站点还提供 llms.txt（完整页面索引）和 llms-full.txt（合并全文），可以直接喂给你手边的 AI 工具去问。查这种「官方到底怎么说」的问题时，比在网页上翻要快。

最后提醒一句版本口径：本机在同一天里，先后两次 codex --version 拿到过不同的版本号（Codex 具备自更新能力）。所以你看到的行为和本文对不上时，第一件事是跑一次 codex --version 看当次的实时输出，别用记忆里的版本号去对照。