什么是暂存区
Anthropic 的文档定义如下:“暂存区是 Claude Code 为 Claude 提供的每个会话的目录,用于存放临时文件:中间结果、辅助脚本以及不属于项目的草稿。”
两个细节使其非常方便。Claude 使用它来代替通用的临时文件夹,文档称 Claude “可以在其中创建、编辑和读取文件,而无需权限提示”。因此,当 Claude 需要尝试某些操作时,它可以直接执行,而无需每次都询问你,也不会向你的仓库添加文件。
当 Claude 说它将某些内容保存到暂存区时,这是字面意思:文件就在这个目录中。
因为它是基于会话的,每个 Claude Code 会话都有自己的暂存区。一个会话暂存区中的文件不会出现在下一个会话中。
它在哪里
暂存区位于你的项目和 Claude Code 配置文件夹之外。“暂存区位于 Claude Code 的临时目录下,而不是 ~/.claude。”
文档记录的路径:
- macOS:
/private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/ - Linux:
/tmp/claude-<uid>/<project>/<session-id>/scratchpad/,或者当系统设置了$TMPDIR时,位于该目录下的相同结构中 - Windows:
%TEMP%\claude\<project>\<session-id>\scratchpad\
<project> 部分是你的工作目录路径,除了字母和数字以外的每个字符都被替换为连字符,例如 -Users-you-my-project。在 Windows 上,它是该字符串的 16 位哈希值。在桌面应用会话中,它可以是字符串本身。
找到当前路径最简单的方法也在文档中:“要获取确切路径,请询问 Claude。”
两个设置会改变这一情况:
CLAUDE_CODE_TMPDIR。 如果你设置了它,整个目录树将移至该目录下。- Hooks。 “Hooks 接收当前会话的路径作为
scratchpad_dir。”如果你想让 hook 在会话结束时从暂存区复制某些内容,这非常有用。
哪些会话拥有暂存区
并非每个会话都有暂存区。文档列出了必须同时满足的三个条件:
- 你使用 claude.ai 账号登录,而不是 API key。
- 会话使用 Anthropic API,而不是 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。
enableArtifact设置未设为false。
如果其中任何一项不适用,会话就没有暂存区,Claude 将在没有暂存区的情况下工作。hook 字段反映了这一点:当会话没有暂存区或临时目录不可用时,scratchpad_dir 不存在。
文件能保存多久
这部分解释了辅助脚本丢失的原因。文档直截了当:“暂存区文件的保存时间与会话的转录文本 (transcript) 一样长:保留清理程序在删除转录文本时会删除该目录,而 claude purge 不会触碰临时目录。”
保留清理程序根据转录文本的存续时间运行。一旦清理路径中的文件超过 cleanupPeriodDays 设置的时间,Claude Code 就会删除它们。默认值为 30 天,最小值为 1 天。当转录文本消失时,其暂存区也会随之消失。
还有第二种丢失方式,与 Claude Code 无关:“由于该目录位于系统临时位置,你的操作系统也可以清理它,例如在重启时。”
因此,暂存区文件可能会在以下情况消失:
- 会话的转录文本达到保留限制并被清理,或者
- 你的操作系统清理了其临时位置,这可能发生在重启时。
第二种情况完全不依赖于 Claude Code 的保留设置。你昨天看到的文件可能在重启后就消失了。
claude purge 会删除和不会删除什么
claude purge 会删除 Claude Code 为一个项目持有的状态:projects/ 下的转录文本和自动记忆 (auto memory)、每个会话的任务、调试和文件历史记录条目、提示词历史记录中的匹配行,以及 ~/.claude.json 中的项目条目。
它不会触碰暂存区。文档解释了原因:粘贴的图像和“每个会话的暂存区都存储在 Claude Code 的临时目录下,而不是 ~/.claude,因此清除操作不会删除它们”。
如果你出于隐私原因清除项目,这引出了一个值得注意的细节:“已清除会话的暂存区会一直保留,直到你手动删除它或操作系统清理临时目录”。
如果你想删除所有内容,请在清除后使用上述路径自行删除项目的暂存区文件夹。
当写入受限时,哪些内容保持可写
一些团队开启了 permissions.blockWritesOutsideWorkingDirectories,这会使 Claude 的文件编辑工具拒绝访问工作目录之外的路径。暂存区是例外之一。Anthropic 的设置参考列出了计划文件、暂存区、后台会话的 tmp 目录以及自动记忆 .md 文件,这些作为 Claude Code 自身的文件保持可写状态。
因此,即使该限制阻止了文件工具写入项目之外的其他地方,Claude 仍可以继续使用暂存区进行草稿创作。计划文件是另一个例外,我们在Claude Code 保存计划文件的位置指南中介绍了它们的保存位置。
2.1.325 版本中的变化
11 月 13 日发布的版本更改了 Claude 的指令,使其将你想要保留的文件移出暂存区。这一变化在于告知 Claude:你将重复使用的内容(如脚本、报告或数据集)应该存放在暂存区文件夹以外的地方,因为该文件夹可能会被清理。
这只是一个指令,而不是保证。文档本身的建议仍然适用:“要保留 Claude 写入那里的内容,请要求 Claude 将其移动到你的项目中。”
其他值得了解的细节
桌面会话遵循不同的保留规则。 保留清理程序不会对每个转录文本应用通常的年龄限制。Anthropic 的文档称,除非你设置了 desktopSessionCleanupPeriodDays,否则 Claude Code 会保留你在 Claude Desktop 或 Cowork 中开始或最近继续的会话转录文本,无论其存续时间多长。由于暂存区文件的寿命与会话转录文本一样长,对于这些会话,操作系统清理临时位置是需要注意的情况。
粘贴的图像存储在附近。 你在项目会话中粘贴或附加的图像也存储在 Claude Code 的临时目录下,而不是 ~/.claude。保留清理程序会在它们超过 cleanupPeriodDays 后将其删除。
Claude 会指明完整路径。 一个变更日志条目修复了 Claude 使用纯文件名或相对路径引用暂存区文件的问题,因此当 Claude 告诉你它将内容保存到何处时,路径应该是完整的。这就是你应该复制的路径。
Artifacts 可以从清理后的暂存区恢复。 另一个变更日志条目修复了在会话在另一台机器上恢复或暂存区被清理后 Artifact 更新失败的问题。在这种情况下,将恢复页面的最后发布版本。已发布的工作可以幸存;暂存区中的工作草稿则没有这种保护。
你可以缩短保留时间。 如果你不希望临时文件留存太久,降低 cleanupPeriodDays 可以让清理程序更快地移除旧的转录文本及其暂存区。Anthropic 建议降低此数值,作为减少敏感值在磁盘上留存时间的一种方法。
暂存区适用于什么
暂存区是存放应该消失的工作的理想场所:
- 中间结果,例如日志文件的过滤副本。
- 一次性脚本,用于检查某些内容。
- 草稿,你在正式使用前会重写它们。
对于你下周想要的内容,这里是错误的地方:可重复使用的脚本、你将分享的报告、你仔细处理的数据,或关于脚本揭示内容的笔记。这些应该放在你的项目中,或者你特意保存的地方。
在结束会话前进行快速测试:如果你会因为丢失 Claude 创建的文件而感到烦恼,那么它就不应该留在暂存区。要求 Claude 列出它在会话期间保存在那里的内容,并在路径仍然容易找到时移动任何通过测试的内容。
人们首先尝试的操作
在项目文件夹中寻找。 暂存区在项目文件夹之外。
在 ~/.claude 中寻找。 它位于 Claude Code 的临时目录下。
运行 claude purge 来清除所有内容。 它不会删除暂存区。
期望文件能像项目一样持久。 它们的寿命与会话转录文本一样长,如果操作系统清理了临时文件,寿命会更短。
在 API-key 会话中寻找暂存区。 会话需要 claude.ai 登录和 Anthropic API。
解决方法:将重要内容移出暂存区
第 1 步:询问 Claude 保存到了哪里
如果 Claude 提到了暂存区,请在会话仍开启时询问完整路径。
第 2 步:将任何可重复使用的内容移入项目
按照 Anthropic 的建议,要求 Claude 将你以后需要的脚本、报告或数据移入你的项目中。
第 3 步:使用 hook 在会话结束时复制
如果你经常需要暂存区的输出,可以使用 hook 通过 scratchpad_dir 将文件复制到你保留的文件夹中。
第 4 步:记录下工作显示的内容
脚本的输出是临时的。将它告诉你的内容(例如哪些记录格式错误)记录在可以持久保存的地方。
在 MemoryLake 中设置
暂存区的设计初衷就是为了被清理。在那里完成的工作得出的结论(例如一次性分析发现了什么,或者为什么需要辅助脚本)才是下一个会话所需要的。
MemoryLake 是此类项目上下文(如发现、决策及其背后的原因)的记忆层,保存在一个由你维护的地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言亲自编写条目。不会从你的暂存区、Claude Code 的临时目录、你的转录文本、你的 ~/.claude 文件夹、你的项目文件或任何供应商的存储中读取、写入或删除任何内容。暂存区及其清理工作仍按照 Anthropic 描述的方式运行。
第 1 步:创建 API key
登录并从控制面板生成一个 key。像对待其他凭据一样,将其存储在仓库之外。

第 2 步:上传你的第一条记忆
从你在解决方法的第 4 步中写下的内容开始:最近的分析显示了什么,你发现了哪些数据问题,以及你因此做出了什么决定。每个条目记录一个发现。

第 3 步:连接你的 AI 和 agent
连接 Claude Code 和你使用的其他助手。在旧的暂存区消失后的新会话中,可以利用相同的发现。

这在实践中改变了什么
第一个区别是清理不再让你损失任何重要的东西。暂存区可以被清理,而发现已经记录下来了。
第二个区别是减少了重复工作。你不需要为了重新发现分析结果而重新运行分析。
第三个区别是跨工具的连续性。Codex 或同一项目上的另一个助手可以使用相同的发现。
Claude Code 暂存区的最佳实践
将其视为临时的。 文件最多只能保存到会话转录文本被删除为止。
预料到重启会清理它。 它位于系统临时位置。
将需要保留的内容移入项目。 在会话开启时要求 Claude 执行此操作。
不要依赖 purge 来保护隐私。 在执行 claude purge 后,自行删除暂存区文件夹。
在 hooks 中使用 scratchpad_dir。 它会提供当前会话的路径。
检查你的登录状态。 使用 API key 或第三方提供商的会话不会获得暂存区。
单独记录结论。 输出是临时的;但其意义不应是临时的。
结论
Claude Code 暂存区是存放临时文件的每个会话文件夹,位于 Claude Code 的临时目录下,而不是 ~/.claude 或你的项目中。Claude 可以在不询问的情况下在那里写入内容,且只有在 Anthropic API 上使用 claude.ai 账号登录的会话才拥有暂存区。
其文件的寿命与会话转录文本一样长,保留清理程序会在 cleanupPeriodDays 后将其移除,而你的操作系统可能会更早地清理它们(例如在重启时)。claude purge 不会删除暂存区。自 2.1.325 版本起,Claude 收到指令要保留你以后需要的文件,Anthropic 的建议也是一样的:将任何值得保留的内容移入你的项目中。