Codex 磁盘占用异常: 失控写盘的根因与排查清理

“Codex 会把磁盘给烧了吗?” 这句听上去夸张的吐槽，背后其实是一个很现实的问题: 当你把一个能自己读写文件、跑命令、装依赖、起容器的自主编程 agent 放到本地长时间运行，它确实有可能在你不注意的时候把磁盘占用悄悄推到几十 GB 量级，严重时直接把分区写满，导致系统卡顿、构建失败、甚至别的服务跟着崩。

“烧磁盘” 当然不是字面意义上把 SSD 物理烧坏——现代固态盘的写入寿命远没有那么脆弱。真正的风险是磁盘空间被异常占满，以及在极端循环下产生的高频无意义写入。这篇文章用一次复盘的方式，把这类 agent 吃满磁盘的真实机理、复现思路、排查命令和预防边界讲清楚，给所有在本地跑 Codex、Claude Code、Cursor 这类工具的人一份可以直接照做的 checklist。

TL;DR: 先给结论

不会烧坏硬件，但会写满分区。自主编程 agent 的本质是”能写盘的循环”，循环失控就是磁盘异常的根因。
占用通常不在你的项目目录里，而是藏在缓存、日志、临时文件、容器镜像、会话快照这些”看不见的角落”。
排查的第一原则是 先量后猜: 用 df -h 看分区，用 du -sh 和 ncdu 定位大目录，不要凭感觉删文件。
预防的核心是给 agent 划边界: 审批模式、沙箱隔离、资源限额、定时清理，四件套缺一不可。
大多数”吃满磁盘”事故，根因是没设上限的自动循环 + 没人看的后台任务，而不是工具本身有 bug。

如果你正在排查一个具体的占用问题，可以直接跳到下面的复现与排查章节。如果你想从根上避免，重点看修复与预防。

现象: 它是怎么一步步把盘吃满的

先描述一类典型场景，便于对号入座。

你让 Codex 帮你完成一个稍微复杂点的任务，比如”把这个项目重构成 monorepo，顺便把测试补全”。这种任务天然需要 agent 反复读写文件、安装依赖、跑构建、看输出、再修正。一切看上去正常，直到某个时刻你发现:

IDE 开始卡，保存文件变慢
终端报 No space left on device
Docker 拉镜像失败，提示磁盘不足
git status 慢得离谱，或者干脆报错

这时候 df -h 一看，根分区或者 home 分区已经红了。问题是: 你的项目源码加起来可能也就几百 MB，那几十 GB 到底去哪了?

这就是这类事故最反直觉的地方——占用的大头几乎从不在你盯着的地方。它分散在一堆你平时根本不会打开的目录里，而 agent 在自动循环里把它们一点点喂大了。理解这一点，比记住任何具体命令都重要。

换个角度看，人类开发者和 agent 在磁盘行为上有一个本质差异: 人写代码是”目标导向、用完即走”，装一次依赖、构建一次、清理收工; agent 则是”过程留痕、反复试错”，它把每一次尝试的中间状态都落到盘上，因为它需要这些状态来观察和修正。这个机制让它强大，也让它成了磁盘消耗的放大器。所以排查它的占用，思路不能照搬人类经验里”项目目录最大”的直觉，而要专门盯那些”过程态”产物聚集的角落。

根因: 为什么自主编程 agent 容易吃满磁盘

要复盘，先得理解机理。这类 agent 吃磁盘不是单一原因，而是几条路径叠加。下面逐条拆。

一、失控的文件生成与重试循环

这是最危险、也最容易被低估的一类。Agent 的工作模式是”生成—执行—观察—修正”的闭环。正常情况下这个闭环会收敛，但在某些条件下它会发散:

任务目标定义不清，agent 反复重写同一批文件，每次都留下中间产物
某个命令一直失败，agent 不断重试，每次重试都生成新的日志、新的临时文件
agent 误判”需要更多数据”，开始批量下载、生成、导出，没有上限

这种循环一旦没有外部约束，写盘速度可以很快，几小时内膨胀到数十 GB 并不夸张，具体取决于运行时长和单次写入的体量。它的可怕之处在于”看上去一切正常”——agent 没有报错、没有卡死，只是安静地一遍遍重写，而每一遍都比上一遍多留下一点垃圾。等你察觉时，往往已经是分区报红的时刻。这也是为什么社区里反复强调任务边界——关于把任务拆清楚、何时该写规格的讨论，可以看 Claude Code 长项目踩坑: vibe coding 与 spec coding 何时切换，规格不清正是循环发散的温床。一个被定义模糊的目标，等于给 agent 发了一张”无限重试”的通行证。

二、缓存膨胀: 包管理器与构建系统

第二大头是缓存。Agent 在帮你装依赖、跑构建时，会大量触发包管理器和构建工具的缓存写入，而这些缓存默认是只增不减的:

npm / pnpm / yarn 的全局缓存(~/.npm、~/.local/share/pnpm 等)
pip / uv 的 wheel 缓存(~/.cache/pip)
cargo、go、gradle、maven 的下载与编译缓存
各类构建中间产物(node_modules、target、build、dist)

人类开发者一个项目装一次依赖就完事，但 agent 在试错过程中可能反复切换分支、重装依赖、清了又装，缓存因此被放大好几倍。当 agent 同时维护多个仓库时，这个问题更突出——多仓库场景下缓存和产物的爆炸式增长，多仓库开发的AI困境: 如何实现从设计稿到多库代码的全链路自动化里也提到过类似的工程复杂度。

三、日志与会话历史: 看不见的稳定增长

第三条路径增长不快，但持续且隐蔽:

agent 自己的运行日志、调试日志
每一次会话、每一轮对话的上下文快照、历史记录
工具调用的 trace、token 计量、请求/响应留档

单条日志可能就几 KB，但 agent 是高频调用的，几万次调用累积下来体量很可观。尤其是开了 verbose / debug 模式后，日志体量可能翻几倍。如果你在做批量任务——比如像 Claude Code 实战: 20篇顶会文献瞬间总结那种成规模的处理——日志和上下文留档的增量就更明显。顺带一提，盯着 token 消耗的同时也该顺手看一眼盘，很多人只盯额度不看磁盘，这是个盲区，相关的额度监控思路可参考开源工具: 开发者推出 Windows 版 Codex 额度监测应用。

四、容器与沙箱镜像堆积

如果你让 agent 在容器或沙箱里跑——这本身是个好习惯——那要警惕镜像和卷的堆积。Docker 这类运行时的悬空镜像(dangling image)、停止但未删除的容器、匿名卷、构建缓存层，全都占盘，而且默认不会自动回收:

反复 build 产生大量中间镜像层
跑完没清理的临时容器
匿名卷(anonymous volume)残留数据

一个中等规模项目反复构建,Docker 相关占用涨到两位数 GB 是常态。这恰恰是用沙箱换来安全的代价——隔离越彻底，留下的”壳”越多。关于在隔离环境里跑 agent 的配置思路，打造专属 AI 渗透测试助手: 详解 Codex CTF 模式配置与工作流给了一个把 Codex 关进受控环境的实例。

五、误装、误下载与”善意的”批量操作

最后一类是 agent 的”好心办坏事”。它在尝试解决问题时，可能:

下载了体积巨大的数据集 / 模型权重 / 二进制
把整个依赖树装进项目本地而非全局
生成了大量它认为”有用”的样例、fixture、mock 数据

这类操作单看每一步都合理，合在一起就是磁盘黑洞。它和工具本身的稳定性无关，更多是 agent 自主性的副作用——而当工具同时出现”降智”或异常重试时，副作用会被放大，社区对这种性能波动的讨论可见开发者反馈主流 AI 编程工具性能降智，寻找 Claude Code 及 Codex 替代方案。

复现与排查: 命令照着敲

理解了机理，排查就有方向了。核心原则一句话: 先量后猜，从大到小。下面是一套通用流程，命令都是标准 shell 工具，不依赖任何 Codex 专属子命令。

第一步: 看整体，分区还剩多少

任何磁盘排查都从这一步开始。先确认是哪个分区满了:

# 看所有挂载点的占用，-h 人类可读
df -h

# 只看根分区和 home，关注 Use% 列
df -h / /home

# 如果是 inode 被占满(海量小文件场景)，Use% 看着不满但仍报 No space
df -i

注意第三条: 如果 agent 生成了海量小文件(典型是失控循环留下的碎片)，可能空间没满但 inode 先耗尽，照样报 No space left on device。这是个经典陷阱。

第二步: 定位大目录，从根往下挖

确定了是哪个分区，接下来从该分区的根开始逐层下钻，找出占用大头:

# 列出当前目录下各子目录的总大小，按可读单位
du -sh ./* 2>/dev/null

# 更实用: 排序，把最大的几个揪出来
du -h --max-depth=1 . 2>/dev/null | sort -rh | head -20

# 直接锁定家目录里的隐藏缓存(大头常在这)
du -sh ~/.cache ~/.npm ~/.local 2>/dev/null

如果系统里有 ncdu，强烈推荐用它，比反复敲 du 直观得多——可以交互式进出目录，按大小排序，当场删:

# 没装就先装(任选其一)
# brew install ncdu   /   apt install ncdu

# 扫描整个家目录，交互式浏览
ncdu ~

# 扫描指定分区
ncdu /

第三步: 锁定缓存、日志、临时文件

根据前面的根因分析，重点检查这几类目录:

# 包管理器缓存
du -sh ~/.npm ~/.cache/pip ~/.cargo ~/Library/Caches 2>/dev/null

# 项目内的构建产物(在项目根跑)
du -sh node_modules target build dist .next .turbo 2>/dev/null

# 系统临时目录
du -sh /tmp /var/tmp 2>/dev/null

# 找出最近被频繁写入的大文件(1GB 以上)
find ~ -type f -size +1G 2>/dev/null -exec ls -lh {} \;

最后那条 find 很关键: 它能直接把”谁是那个几十 GB 的胖子”揪出来。配合 -mmin -60(最近 60 分钟修改)还能判断是不是当前正在跑的 agent 写的。

第四步: 容器和镜像占用

如果用了 Docker，单独查一遍:

# 看 Docker 各类对象的占用总览
docker system df

# 详细到每个镜像/容器/卷
docker system df -v

docker system df 会清楚告诉你镜像、容器、卷、构建缓存各占多少，以及有多少是”可回收”(reclaimable)的。

第五步: 实时盯着它写

如果 agent 还在跑，你怀疑它正在疯狂写盘，可以实时观察:

# 每 2 秒刷新一次某目录的大小，看它涨不涨
watch -n 2 'du -sh ~/.cache 2>/dev/null'

# 看哪个进程在猛写磁盘(Linux，需要 root)
sudo iotop -o

# macOS 下用 fs_usage 跟踪文件系统调用
sudo fs_usage -w -f filesys | grep -i codex

看到写入速率异常、目标目录持续膨胀，基本就能确认是失控循环了。这时候第一动作是停掉 agent，而不是急着删文件——边删边写是白费功夫，你删掉的空间它转头又写回来，还可能因为文件被占用而引发更难解释的报错。先按下暂停键，让现场静止下来，再从容排查，这是所有线上故障排查的通用纪律，对 agent 同样适用。

修复与预防: 给 agent 划清边界

排查是止血，预防才是治本。这类问题的根治思路只有一句: 不要让一个能写盘的循环在没有边界的情况下自由奔跑。具体落到四个层面。

一、清理: 安全地把空间拿回来

确认了大头之后，按”可再生 / 不可再生”分类清理。缓存、构建产物、悬空镜像都是可再生的，删了顶多下次重新生成，可以放心清:

# 包管理器缓存(都能安全清，会自动重建)
npm cache clean --force
pip cache purge
# pnpm store prune / yarn cache clean / cargo cache 同理

# Docker: 清掉悬空镜像、停止的容器、未用网络和构建缓存
docker system prune
# 更狠(连未被引用的卷也清，确认数据不要再用)
docker system prune -a --volumes

# 手动删项目构建产物
rm -rf node_modules dist build .next

铁律: 删之前一定先用前面的命令确认目录内容是可再生的。不要对着 du 的输出无脑 rm -rf，尤其别碰 ~/.config、~/.ssh、数据库目录、还有你不认识的 dotfile。

二、边界: 审批模式与沙箱隔离

这是最有效的预防手段。这类 agent 通常都提供审批 / 确认模式——让它在执行写文件、删文件、跑命令前先问你一句。在做不熟悉或体量大的任务时，把自动批准关掉、改成手动确认，能拦下绝大多数失控操作。

更进一步是沙箱隔离: 把 agent 关进容器或受限环境里跑，给它一个独立的、容量有上限的工作目录。这样即使它写疯了，炸的也是沙箱，不会波及主系统。如何在隔离环境里跑 agent，可以参考前面提到的 Codex CTF 模式配置与工作流，思路是通用的。多工具统一管理配置、把边界设置固化下来，开源工具 SMRmanager: 一键统一管理 Claude、Cursor 等 AI 编程工具配置是个可参考的方向。

三、限额: 给磁盘上硬上限

光靠 agent 自觉不够，系统层面也该设硬限制，这样无论循环多失控都有天花板:

# 方案 A: 用独立分区/卷给 agent 的工作目录，容量物理隔离

# 方案 B: Docker 跑 agent 时限制容器可写层和卷大小
docker run --storage-opt size=10G ...   # 视存储驱动支持情况

# 方案 C: Linux 上用 quota 给某个用户/目录设磁盘配额
# 方案 D: 临时目录挂 tmpfs 并限制大小，写满即报错而非吃光真实磁盘

核心是: 宁可让它因为超限而报错失败，也别让它把整个磁盘吃光。报错你能立刻发现并修，磁盘吃光是连锁灾难。

四、监控: 不要等到报错才发现

最后，加一层主动监控。最简单的是一个定时检查脚本，磁盘超过阈值就告警:

# 一个极简的磁盘水位告警，可挂 cron 每 10 分钟跑一次
USAGE=$(df / | awk 'NR==2 {print $5}' | tr -d '%')
if [ "$USAGE" -gt 85 ]; then
  echo "磁盘告警: 根分区已用 ${USAGE}%" # 接入你的通知渠道
fi

把它和你已有的资源监控放一起。很多人已经在盯 token 和额度消耗了——比如实测分享: Codex55 省 Token 配置方案和实测避坑: 阿里云 Token Plan 难以支撑 AI 编程，3小时消耗 50% 额度都在讲怎么把消耗控制住——磁盘水位完全可以挂进同一套看板，多盯一个指标而已。

FAQ

Q1: Codex 真的会把硬盘”烧坏”吗?

不会。”烧”是个比喻，指的是磁盘空间被异常占满，以及极端循环下的高频写入。现代 SSD 的写入寿命很高，正常使用一个失控的 agent 跑几天，远达不到损耗硬件的程度。真正要担心的是分区写满引发的系统故障，而不是物理损坏。

Q2: 我的项目目录就几百 MB，那几十 GB 到底在哪?

大概率在你不会主动打开的地方: 包管理器缓存(~/.cache、~/.npm)、Docker 镜像和卷、agent 的日志与会话历史、/tmp 临时文件、构建中间产物。用 ncdu ~ 或 du -h --max-depth=1 / | sort -rh 从根往下挖，几分钟就能定位。

Q3: 清理缓存和镜像会不会丢数据 / 弄坏环境?

缓存、悬空镜像、构建产物都是可再生资源，删了下次自动重建，不会丢业务数据。但 docker system prune -a --volumes 里的 --volumes 会删未引用的卷，如果你有数据存在匿名卷里要先确认。原则: 只清你能解释清楚”删了会重建”的东西。

Q4: 怎么从根上避免再次发生?

四件套: 大任务开手动审批模式、把 agent 关进沙箱/独立分区、给磁盘设硬配额(超限报错而非吃光)、挂一个磁盘水位告警。本质是给”会写盘的循环”加上外部边界，别指望 agent 自己收敛。

Q5: agent 正在疯狂写盘，我该先删文件还是先停它?

先停 agent。边删边写是白费力气，而且在它还在跑的时候删它正在用的文件可能引发更怪的错误。停掉之后再按”看占用 → 定位 → 清理”的顺序慢慢来。

结语

把 Codex 这类 agent 想象成一个不知疲倦、但也不知节制的实习生: 你给方向，它给产出，但它不会自己关水龙头。磁盘占用异常从来不是某个工具的 bug，而是”自主写盘”这件事本身的代价。划好边界、设好上限、留个监控，它就是利器; 放任不管，它就替你把盘喂满。