Claude Code 如何使用 prompt caching

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Prompt caching 使 Claude Code 更快、更经济高效。没有缓存，API 会在每个回合重新处理您的完整历史记录。有了缓存，它会重用已经处理过的内容，只对更改的部分进行新工作。 Claude Code 为您处理 prompt caching，除非您禁用它。了解 prompt caching 的工作原理仍然很有用，因为某些操作会使缓存失效，使下一个响应更慢、更昂贵，同时它重建缓存。本页涵盖哪些操作会这样做、为什么某些设置等待重启才能应用，以及当使用量看起来很高时如何检查缓存性能。

​

缓存的组织方式

每次您在 Claude Code 中发送消息时，它都会发出新的 API 请求。模型在请求之间不记得任何东西，所以 Claude Code 重新发送完整的上下文：系统提示、您的项目上下文、每条先前的消息和工具结果，以及您的新消息。新内容附加在末尾，这意味着每个请求的大部分与前一个请求相同。Prompt caching 是 API 避免重新处理未更改部分的方式。 API 通过将每个请求的开始部分（称为前缀）与最近处理过的内容进行匹配来缓存。在正常回合中，前缀是整个先前请求，只有最新的交换是新的。匹配是精确的，所以前缀中任何地方的更改都会重新计算其后的所有内容。没有按文件或按段的缓存。有关底层机制，请参阅 API 参考中的prompt caching 如何工作。 为了充分利用前缀匹配，Claude Code 组织每个请求，使回合之间很少更改的内容首先出现： 对对话层的更改会保留系统提示和项目上下文缓存。对系统提示的更改会使所有内容失效，因为所有后续内容现在位于不同的前缀后面。第三列给出常见触发器而不是详尽列表，下面的部分涵盖完整集合，包括在会话开始时固定的输出样式等内容。 前缀匹配规则解释了本页上的大多数行为。例如，Plan Mode 和技能加载将其指令附加为对话消息，所以缓存的前缀保持完整。 两个设置根本不是提示文本的一部分，所以它们不出现在层表中。它们对缓存的行为不同：

• Model：缓存由模型键入，所以每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的切换模型。
• Effort level：不是缓存键或提示的一部分，所以在会话中期更改它对缓存没有影响。

​

缓存位置

缓存发生在服务器端，在为您的模型提供服务的任何基础设施中。它的位置取决于您如何进行身份验证：

• API 密钥、Claude 订阅或 Claude Platform on AWS：缓存位于 Anthropic 的基础设施中，通过 Claude API 访问
• Bedrock 或 Vertex AI：缓存位于您的云提供商的服务基础设施中
• Foundry：请求路由到 Anthropic 的基础设施
• 自定义 ANTHROPIC_BASE_URL 或 LLM gateway：缓存位于您的请求转发到的任何地方，缓存是否工作取决于网关

有关每个提供商存储和处理的内容，请参阅数据使用。无论缓存位于何处，条目在不活动期间后过期，缓存生命周期下面涵盖 TTL 以及如何延长它。

​

使缓存失效的操作

这些操作会导致下一个请求错过部分或全部缓存。您会看到一个一次性的较慢、更昂贵的回合，之后新的前缀被缓存。一旦您知道它们有成本，大多数都可以在任务中期避免。模型切换或 MCP 重新连接可能感觉是免费的，直到您注意到随后的较慢回合。

• 切换模型
• 连接或断开 MCP 服务器
• 拒绝整个工具
• 压缩对话
• 升级 Claude Code

​

切换模型

每个模型都有自己的缓存。使用 /model 切换意味着下一个请求读取整个对话历史记录而没有缓存命中，即使内容相同。 opusplan 模型设置在 Plan Mode 期间解析为 Opus，在执行期间解析为 Sonnet，所以每个 Plan Mode 切换都是模型切换并启动新缓存。

​

连接或断开 MCP 服务器

工具定义位于系统提示层中，所以当 Claude 可用的 MCP 工具集在回合之间更改时，缓存会失效。最常见的原因是 MCP 服务器在会话中期连接或断开连接，这可能在没有您采取任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器在暂时故障后自动重新连接。连接的服务器也可以推送动态工具更新来更改其工具列表。 编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，这是服务器连接或断开连接的时间。 MCP 工具搜索通过延迟完整工具定义来减少每个工具对前缀的贡献，但工具名称集必须保持稳定才能使缓存保持有效。

​

拒绝整个工具

添加像 Bash 或 WebFetch 这样的裸工具名称作为拒绝规则会将该工具从 Claude 的上下文中完全移除。工具定义位于系统提示层中，所以在会话中期添加或移除这些规则之一会使缓存失效，就像 MCP 服务器连接或断开连接一样。无论您通过 /permissions 添加它还是通过直接编辑设置文件，更改都会在下一个回合生效。 只有裸工具名称或等效的 Bash(*) 形式才有这种效果。作用域拒绝规则如 Bash(rm *)，以及所有允许和询问规则，都不会改变 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。

​

压缩对话

压缩用摘要替换您的消息历史记录。根据设计，这会使对话层失效，因为下一个请求有一个新的、更短的历史记录，与旧的历史记录不共享前缀。Claude Code 重用系统提示层并从磁盘重新加载项目上下文，只有在 CLAUDE.md 和内存自会话开始以来未更改时才缓存命中。 为了生成摘要，Claude Code 发送一个一次性请求，其系统提示、工具和历史记录与您的对话相同，加上作为最终用户消息附加的摘要指令。因为它共享您的前缀，该请求读取现有缓存而不是重新处理完整历史记录。压缩的大部分时间用于生成摘要，而不是缓存未命中。随后的回合仅为更短的摘要重建对话缓存，所以压缩后的回合不是缓慢的部分。

​

升级 Claude Code

新的 Claude Code 版本通常会更新系统提示或工具定义，所以升级后的第一个请求从顶部重建缓存。自动更新在后台下载新版本，但在下次启动时应用它们，从不在会话中期，所以您会看到这是重启后的一个未缓存的第一个回合，而不是会话期间的惊喜。设置 DISABLE_AUTOUPDATER=1 来控制何时应用升级。

​

保持缓存的操作

这些操作要么附加到对话的末尾，要么根本不接触请求。其中一些，例如编辑 CLAUDE.md 或更改输出样式，也是为什么设置更改等待重启才能应用的原因。

• 编辑存储库中的文件
• 在会话中期编辑 CLAUDE.md
• 更改输出样式
• 更改权限模式
• 调用技能和命令
• 运行 /recap
• 重绕对话
• 生成子代理

​

编辑存储库中的文件

文件内容仅在 Claude 读取它们时进入上下文，读取附加到对话。编辑 Claude 之前读过的文件不会追溯更改历史记录中的较早读取。相反，Claude Code 附加一个 <system-reminder> 注意文件已更改，如果需要，Claude 会重新读取它。

​

在会话中期编辑 CLAUDE.md

您的项目根目录和用户级 CLAUDE.md 文件在会话开始时读取一次并保存在内存中。在会话中期编辑它们不会使缓存失效，但编辑也不适用。Claude 继续使用在会话开始时加载的版本。新内容在下一个 /clear、/compact 或重启时加载。 子目录中的嵌套 CLAUDE.md 文件和带有 paths: frontmatter 的规则稍后加载，当 Claude 首次读取匹配文件时。在加载前编辑一个确实会生效。加载后，内容是对话历史记录的一部分，所以中期编辑不会追溯更改它。

​

更改输出样式

输出样式是系统提示的一部分，Claude Code 在会话开始时读取一次。通过 /config 或 outputStyle 设置在会话中期更改它不会使缓存失效，但更改也不适用。Claude 继续使用在会话开始时加载的样式。新样式在下一个 /clear 或重启时加载。

​

更改权限模式

在权限模式之间切换，例如从默认到接受编辑，不会改变系统提示或工具定义，所以模式更改是缓存安全的。例外是带有 opusplan 模型设置的 Plan Mode，它在进入或离开 Plan Mode 时在 Opus 和 Sonnet 之间切换模型。这使模式切换成为模型切换。

​

调用技能和命令

技能和命令在调用点将其指令注入为用户消息。对话中较早的任何内容都不会改变。

​

运行 /recap

/recap 生成一个摘要以在您的终端中显示。与 /compact 不同，它将摘要附加为命令输出而不是替换您的消息历史记录，所以缓存的前缀保持完整。

​

重绕对话

/rewind 将您的对话截断回较早的回合。剩余的历史记录是缓存在该点构建时的相同内容，系统提示和项目上下文层未更改，所以下一个请求命中较早的缓存条目。自那时以来的每个回合都通过该前缀读取，即使原始回合比 TTL 更久远，也保持条目温暖。 恢复文件检查点与对话一起对缓存没有单独的影响。文件内容仅在 Claude 读取它们时进入上下文，与编辑存储库中的文件相同。

​

缓存生命周期

缓存的前缀在不活动期间后过期。每个命中缓存的请求都会重置计时器，所以只要您继续工作，缓存就保持温暖。在足够长的间隙之后，下一个请求重新计算完整输入并重新建立缓存，这就是为什么步开后的第一个回合可能明显更慢。 生存时间 (TTL) 控制缓存存活的间隙有多长。API 提供两个：五分钟 TTL 和一小时 TTL，它通过更长的中断保持缓存温暖，但以更高的速率计费缓存写入。Claude Code 根据您如何进行身份验证为您选择 TTL，您可以使用环境变量覆盖它。

​

在 Claude 订阅上

在 Claude 订阅上，Claude Code 自动请求一小时 TTL。使用包含在您的计划中，而不是按令牌计费，所以更长的 TTL 不会额外花费您任何费用，只会影响缓存保持温暖的时间。 如果您已超过计划的使用限制，Claude Code 正在使用使用额度，您需要为该使用付费，所以 Claude Code 自动将 TTL 降低到五分钟。

​

在 API 密钥或第三方提供商上

在 API 密钥、Bedrock、Vertex、Foundry 或 Claude Platform on AWS 上，您支付按令牌费率，所以 TTL 默认保持在更便宜的五分钟。要选择加入一小时 TTL，设置 ENABLE_PROMPT_CACHING_1H=1。 在 Bedrock 上，prompt caching 支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请检查 Bedrock 文档中的支持的模型、区域和限制。

​

覆盖 TTL

设置 FORCE_PROMPT_CACHING_5M=1 以强制五分钟 TTL，无论身份验证如何。这在您调试缓存行为、比较两个 TTL 或覆盖在托管设置中设置的 ENABLE_PROMPT_CACHING_1H 时很有用。

​

缓存范围

在 Claude Code 中，缓存有效地限定在一台机器和目录。系统提示嵌入工作目录、平台、shell、OS 版本和自动内存路径，所以两个不同目录中的会话构建不同的前缀并错过彼此的缓存。这包括同一存储库的 worktrees，因为每个 worktree 都有自己的工作目录。 您在同一目录中并行运行的会话构建匹配的前缀并读取彼此的缓存。顺序会话仅当启动时的 git 状态快照匹配时才共享前缀，因为系统提示也捕获分支和最近的提交。 底层 API 缓存更广泛。缓存在组织之间隔离，在某些提供商上，在组织内的工作区之间隔离。在这些边界内，任何两个具有相同模型和前缀的请求读取相同的缓存。对于运行自动化流程队列的 Agent SDK 调用者，请参阅改进跨用户和机器的 prompt caching以抑制系统提示的按机器部分并跨机器共享缓存。

​

检查缓存性能

缓存性能显示为 API 在每个响应上报告的两个令牌计数。实时观看它们的最直接方式是读取 current_usage 对象的状态行脚本： 高读取与创建比率意味着缓存工作良好。如果创建在回合之间保持高位，您的前缀中有什么在改变。使缓存失效的操作部分列出了常见原因。 为了在整个组织中获得可见性，OpenTelemetry 导出器报告每个用户和会话的缓存读取和创建令牌。有关指标和事件属性参考，请参阅监控使用。

​

子代理和缓存

子代理启动自己的对话，具有自己的系统提示和工具集，与父代的分开。它构建自己的缓存，在第一次调用时没有缓存命中，并在自己的回合中预热。子代理使用五分钟 TTL，即使在订阅上，因为自动一小时 TTL 适用于主对话。 父代的缓存不受影响。从父代的一侧，子代理的调用和结果附加到对话，保留父代的前缀完整。 分叉相比之下，完全继承父代的系统提示、工具和对话历史记录，所以其第一个请求读取父代的缓存。压缩对话中描述的压缩摘要调用使用相同的前缀共享方法。

​

禁用 prompt caching

禁用缓存在使用特定模型或提供商调试缓存行为时偶尔很有用。要关闭它，请将以下环境变量之一设置为 1： 要在整个组织中设置缓存策略，请将这些或TTL 变量中的任何一个放在托管设置的 env 块中。对于正常使用，保持缓存启用。

​

相关资源

• 从构建 Claude Code 中学到的经验：Prompt caching 就是一切：Plan Mode、延迟工具加载和压缩的设计原理
• 探索上下文窗口：什么加载到上下文中以及何时加载
• 减少令牌使用：超越缓存的策略，用于管理上下文大小
• 跟踪和减少成本：Agent SDK 调用者的缓存令牌跟踪和 TTL 配置
• Prompt caching：底层 API 机制、断点和定价