Claude Code 正在悄悄吃掉你的磁盘：`~/.claude` 里有什么、哪些能删、怎么设上限

Q: /compact 会释放 Claude Code 的磁盘空间吗？

不会。/compact 只会压缩当前会话里的对话上下文；磁盘上的会话记录(transcript)还是会继续增长。磁盘占用和上下文占用是两回事。

Q: 直接删除 ~/.claude/projects 安全吗？

安全，前提是你不需要对任何旧会话使用 --resume 或 --continue。登录状态和设置在别处（~/.claude.json 和 settings.json），不会被碰到。

Q: 为什么 Claude Code 会一夜之间把我的磁盘填满？

长时间运行的代理循环会持续写会话记录(transcript)，还会为每次编辑写 1 份文件快照。多代理设置会按子代理数量继续放大。检查 du -sh ~/.claude/projects/*，也检查 $TMPDIR 里有没有 claude-* 文件。

Q: cleanupPeriodDays 也会清理调试日志和 file-history 吗？

按文档看不会。文档只承诺清理会话文件。debug/ 和 file-history/ 要手动清，比如用上面按 -mtime 过滤的 find 命令。

6 月 11 日发布 · 6 分钟阅读

本周，有人在 r/AI_Agents 上说，自己让代理跑了一夜，醒来发现 SSD 几乎被塞满。这不是偶发事故：Claude Code 会写下每个会话的会话记录(transcript)、调试日志，以及它编辑过的每个文件快照；除非你明确设置，否则它不会主动删除。我们自己的机器上，约 3 周高强度使用代理后，~/.claude 里留下了 732 MB，其中 77% 是会话记录(transcript)。记录最严重案例的 GitHub issue 里，有人积累了 300 GB 文件快照。这个报告后来被关闭并标记为「不计划修复」(原文:“not planned”)。

30 秒版本

运行 du -sh ~/.claude/*——大头几乎肯定是 projects/ 里的会话记录(transcript)。
在 ~/.claude/settings.json 加上 "cleanupPeriodDays": 14。这是唯一官方保留期开关：启动时会删除超过 N 天的会话文件（默认 30，最小 1）。
claude clean 不存在（已在 2.1.172 验证）。说它存在的教程写的是功能请求，不是已经发布的功能。
不要真的把磁盘写到 0。已有记录表明，一连串故障会把 .claude.json 写成 0 字节文件；下次启动时，你的设置和登录状态都会被清掉。

真正增长的是哪些东西

下面是我们自己的机器在约 3 周日常多代理使用后的大小，以及 GitHub issue 里报告的数字：

路径	内容	我们的机器	issue #24207 报告
`~/.claude/projects/`	每个会话 1 个 JSONL 会话记录(transcript)：每次工具调用、文件读取、响应都会写进去，也包括子代理	565 MB	2,707 MB
`~/.claude/plugins/`	已安装插件及其依赖	103 MB	—
`~/.claude/debug/`	调试日志，不会自动清理	这台机器很小	734 MB
`~/.claude/file-history/`	Claude Code 每次编辑文件时留下的快照（支撑 `/rewind`）	13 MB	188 MB — 另有用户报告 300 GB
`~/.claude/shell-snapshots/`	Shell 环境快照	1.1 MB	—
其他所有内容	历史记录、待办、缓存、用量数据	< 2 MB	~6 MB

同一个报告里还有 2 个增长点不在 ~/.claude 下面：一个原生 .node 插件每周在临时存储里堆出约 20 GB；另一个是在临时目录里留下成千上万个 claude-*-cwd 标记文件。如果你在 ~/.claude 里对不上数字，检查 $TMPDIR。

长时间运行的代理会话会把这些数放大。单个会话记录(transcript)经常超过 10 MB；跑一整夜的循环再加子代理，会写出几十个这样的文件。

这个故障模式值得知道

issue #24207 记录了磁盘真的写满时会发生什么：Claude Code 试图写 .claude.json，写入失败后留下一个长度为 0 的文件；下次启动时，它把这个文件读成无效 JSON，然后重建默认配置——你的项目设置和 OAuth 登录状态就一起没了。正在跑的代理会半路死掉。事前没有警告，也没有自动恢复；你只能先腾空间，再重新登录，如果有备份就再恢复设置。

Anthropic 在 2026 年 2 月把这个 issue 关闭并标记为「不计划修复」(原文:“not planned”)。所以上限得你自己设。下面按有用程度列出真正有效的做法。

修复 1 — 官方设置

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 14
}

按官方文档，这个周期之外的会话文件会在启动时删除（默认 30 天，最小 1；设置成 0 会被拒绝）。它也控制孤儿子代理工作树（worktree）什么时候被移除。

文档明确写了 2 点，还有 1 点它没写：

清理只在启动时运行——如果一台机器连续跑同一个长会话好几周，就不会触发。
删除旧会话文件后，--resume 和 --continue 就不能再接回那些对话。
文档只承诺清理会话文件。debug/ 和 file-history/ 的保留期没有文档说明，按需要手动清。

如果你完全不想保存会话记录(transcript)：设置 CLAUDE_CODE_SKIP_PROMPT_HISTORY 环境变量，或者在脚本化/-p 运行里传 --no-session-persistence。代价是不能恢复会话；CI 任务和一次性自动化通常不在乎。

修复 2 — 2 条 find 命令

随时可以跑；它们只碰可再生成的数据：

# 14 天前的会话记录(transcript)
find ~/.claude/projects -name '*.jsonl' -mtime +14 -delete

# 14 天前的编辑快照（只会让这些会话不能再用 /rewind）
find ~/.claude/file-history -type f -mtime +14 -delete

你不能删的是：~/.claude/settings.json、~/.claude.json（注意：它在 $HOME 下，不在 ~/.claude 里面）、任何叫 .credentials* 的东西、你的 memory/ 目录，以及 CLAUDE.md 文件。那些是配置和登录状态，不是缓存。

修复 3 — 第三方清理工具

有 2 个开源工具把同一套思路包了一层预览：

工具	形态	增加了什么
claude-code-cleaner	Rust TUI	检测孤儿项目缓存（仓库已删除，但会话记录还在）、过期过滤、dry-run 预览
claude-clean	CLI	按目录给出大小报告、删除前预览、按保留时间清理

它们都可以用；但只要你设了 cleanupPeriodDays，并且知道上面 2 条 find 命令，就不是必需品。

不存在的东西

claude clean——2.1.172 里没有这个命令。它是功能请求 #11646，从 2025 年开到现在。至少有一个教程站把它写得像已经发布了一样；事实不是。
磁盘占用警告——Claude Code 会一直写，直到操作系统拒绝。
容量上限——没有按 MB 限制 ~/.claude 的设置；你唯一能调的是时间。

配套阅读

AI 编程代理实际会往磁盘写什么——本文是从那张 8 个代理全景图里放大看 Claude Code，也包括 Codex、Cursor 和 Gemini 的对应目录。
Claude Code 用量限额讲清楚——另一个会被用满的额度：速率窗口、周限额，以及怎么盯住自己的消耗。

来源

FAQ

/compact 会释放 Claude Code 的磁盘空间吗？ 不会。/compact 只会压缩当前会话里的对话上下文；磁盘上的会话记录(transcript)还是会继续增长。磁盘占用和上下文占用是两回事。

直接删除 ~/.claude/projects 安全吗？ 安全，前提是你不需要对任何旧会话使用 --resume 或 --continue。登录状态和设置在别处（~/.claude.json 和 settings.json），不会被碰到。

为什么 Claude Code 会一夜之间把我的磁盘填满？ 长时间运行的代理循环会持续写会话记录(transcript)，还会为每次编辑写 1 份文件快照。多代理设置会按子代理数量继续放大。检查 du -sh ~/.claude/projects/*，也检查 $TMPDIR 里有没有 claude-* 文件。

cleanupPeriodDays 也会清理调试日志和 file-history 吗？ 按文档看不会。文档只承诺清理会话文件。debug/ 和 file-history/ 要手动清，比如用上面按 -mtime 过滤的 find 命令。

Claude Code 正在悄悄吃掉你的磁盘：~/.claude 里有什么、哪些能删、怎么设上限