SpyBara
Go Premium

prompt-caching.md 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

This page contains 102 additions and 96 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Sun 13 21:00 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59 Wed 23 23:57 Fri 25 23:58

Claude Code 如何使用 prompt caching

Claude Code 自动管理 prompt caching。了解为什么模型切换会触发缓慢的未缓存回合、/compact 的成本、为什么 CLAUDE.md 编辑在会话中期不适用，以及如何检查缓存命中率。

Prompt caching 使 Claude Code 更快、更经济高效。没有缓存，API 会在每个回合重新处理您的完整历史记录。有了缓存，它会重用已经处理过的内容，按照缓存令牌费率对重新读取进行计费，并仅完全处理已更改的内容。

Claude Code 为您处理 prompt caching，除非您禁用它。了解 prompt caching 的工作原理仍然很有用，因为某些操作会使缓存失效，使下一个响应更慢、更昂贵，同时它重建缓存。本页涵盖哪些操作会这样做、为什么某些设置等待重启才能应用，以及当使用量看起来很高时如何检查缓存性能。

缓存的组织方式

每次在 Claude Code 中发送消息时，它都会发出一个新的 API 请求。模型在请求之间不会记住任何内容，因此 Claude Code 会重新发送完整的上下文：系统提示、你的项目上下文、所有之前的消息和工具结果，以及你的新消息。新内容被附加在末尾，这意味着每个请求的大部分内容与前一个请求相同。Prompt caching 是 API 避免重新处理未更改部分的方式。

API 通过将每个请求的开始部分（称为前缀）与最近处理的内容进行匹配来进行缓存。在正常的回合中，前缀是整个前一个请求，只有最新的交互是新的。匹配是精确的，因此前缀中任何地方的更改都会重新计算其后的所有内容。没有按文件或按段的缓存。有关底层机制，请参阅 API 参考中的 how prompt caching works。

Four turns shown as growing horizontal bars. Each turn's request contains everything from the previous turn plus the latest exchange appended at the end. On turns two and three, the unchanged prefix is read from cache and only the new exchange is processed. On turn four, the system prompt changed, so the prefix no longer matches and the entire request is reprocessed and written. Four turns shown as growing horizontal bars. Each turn's request contains everything from the previous turn plus the latest exchange appended at the end. On turns two and three, the unchanged prefix is read from cache and only the new exchange is processed. On turn four, the system prompt changed, so the prefix no longer matches and the entire request is reprocessed and written.

为了充分利用前缀匹配，Claude Code 对每个请求进行排序，使得在回合之间很少更改的内容首先出现：

Layer Content Changes when
System prompt Core instructions, tool definitions The set of loaded tool definitions changes
Project context CLAUDE.md, auto memory, unscoped rules Session starts, or after /clear or /compact
Conversation Your messages, Claude's responses, tool results Every turn

对对话层的更改会使系统提示和项目上下文保持缓存。对系统提示的更改会使所有内容失效，因为所有后续内容现在位于不同的前缀后面。第三列给出了常见的触发器，而不是详尽的列表，下面的部分涵盖了完整的集合。

前缀匹配规则解释了本页上的大多数行为。例如，Plan mode 和 skill loading 将其指令作为对话消息附加，因此缓存的前缀保持完整。

两个设置不在层表中出现，但仍然影响缓存的内容：

  • Model：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的 Switching models。
  • Effort level：在大多数模型上，每个努力级别都有自己的缓存，因此在会话中途更改努力级别会重新计算整个请求。在具有 API 密钥或 Claude 订阅的 Fable 5.1 上，缓存默认保持完整。请参阅下面的 Changing effort level。

缓存的位置

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

  • API key、Claude subscription 或 Claude Platform on AWS：缓存位于 Anthropic 的基础设施中，通过 Claude API 访问
  • Amazon Bedrock 或 Google Cloud 的 Agent Platform：缓存位于你的云提供商的服务基础设施中
  • Microsoft Foundry：取决于部署的 hosting option。在 Azure 上托管的部署在 Azure 基础设施上提供；在 Anthropic 上托管的部署在 Anthropic 的基础设施上提供
  • Custom ANTHROPIC_BASE_URL 或 LLM gateway：缓存位于你的请求被转发的地方，缓存是否有效取决于网关

Claude Code 还在对话中途附加系统上下文，例如文件更改通知，并在所有提供商和连接上标记该块以进行缓存，除非你设置了 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS，在这种情况下该块被发送为未缓存。

在提供商自己的端点、Amazon Bedrock 及其 Mantle endpoint、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，缓存该块的方式与 Claude API 相同。

当你的请求通过 LLM gateway、自定义 ANTHROPIC_BASE_URL 或云提供商基础 URL 覆盖（例如 ANTHROPIC_BEDROCK_BASE_URL）时，缓存的内容取决于网关如何处理 Claude Code 发送的 cache_control markers：

  • 原样转发它们：该块和你的对话缓存方式与在提供商自己的端点上相同。
  • 使用命名 cache_control 的 400 错误拒绝标记的请求：Claude Code 重新发送请求，将标记从块移到你的最后一条对话消息上，并在对话的其余部分保持在那里。该块作为未缓存的输入计费；你的对话保持缓存。
  • 在返回成功时删除标记：你的整个对话历史在每个回合上都作为未缓存的输入计费。将块形式的系统内容转换为纯字符串的网关以相同的方式删除标记。

有关每个提供商存储和处理的内容，请参阅 data usage。无论缓存位于何处，条目在不活动期间后过期，下面的 Cache lifetime 涵盖了 TTL 以及如何延长它。

使缓存失效的操作

这些操作会导致下一个请求缓存未命中的部分或全部。您会看到一次速度较慢、成本更高的回合，之后新的前缀会被缓存。一旦您了解它们的成本，大多数操作都可以在任务中途避免。模型切换可能看起来没有成本，直到您注意到随后的速度较慢的回合。

切换模型

每个模型都有自己的缓存。使用 /model 切换意味着下一个请求会读取整个对话历史记录而没有缓存命中，即使内容相同。

当您在终端运行 /model 时，Claude Code 仅在缓存仍然温暖时要求您确认切换。缓存在 Claude Code 在此对话中最后一次发送请求或 Claude 最后一次响应后的一个缓存 TTL 内保持温暖。一旦该时间过去，缓存就会过期，因此 Claude Code 会在不询问的情况下进行切换。

在 v2.1.238 之前，Claude Code 没有检查缓存 TTL，即使在缓存过期后也会询问。

您也可以使用 PreModelSwitch hook 要求此确认或跳过它。

opusplan 模型设置在计划模式下解析为 Opus，在执行期间解析为 Sonnet，因此每个计划模式切换都是一个模型切换并启动新的缓存。

自动模型回退在 Fable 模型和 Opus 5 上也是一个模型切换。当安全分类器在具有回退模型的类别中标记请求时，Claude Code 会在该模型上重新运行请求，会话会在那里继续。

当技能或命令的 frontmatter 命名一个model不同于会话当前模型的模型时，该回合也是一个模型切换：下一个请求会读取整个对话历史记录而没有缓存命中。会话模型在您的下一个提示时恢复。context: fork 技能会设置分叉子代理的模型。

更改工作量级别

在大多数模型上，在会话中途更改工作量级别意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。

在具有 API 密钥或 Claude 订阅的 Fable 5.1 上，更改工作量会保持缓存，Claude Code 会在不询问的情况下应用新级别。这不适用于 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Claude 应用网关，或当您设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 或您的组织具有 HIPAA 配置时。

在 v2.1.260 之前，在具有 API 密钥或 Claude 订阅的 Fable 5.1 上更改工作量也会使缓存失效。

启用快速模式

启用快速模式会添加一个请求标头，该标头是缓存键的一部分，因此 Claude Code 发送的启用快速模式的第一个请求会读取整个对话历史记录而没有缓存命中。Claude Code 在回合开始时设置该标头一次，并为整个回合保持它，因此当您在 Claude 工作时启用快速模式时，标头的缓存未命中会在您下一个回合的第一个请求时发生。这些未缓存的输入令牌按快速模式费率计费，这就是为什么在会话开始时启用它的成本比在长会话深处启用它的成本要低。如果您当前的模型不支持快速模式，启用快速模式也会切换您的模型，该切换从运行回合中的下一个请求开始启动新的缓存。

成本每个对话应用一次。在第一个快速模式回合之后，Claude Code 继续发送标头，仅改变请求的速度设置，这不是缓存键的一部分。关闭快速模式、在速率限制后自动回退到标准速度以及稍后重新启用它都会保持缓存。如果您在会话中途用完使用额度，Claude Code 会以相同的方式在标准速度下重试每个被拒绝的快速模式请求，因此此回退也会保持缓存。/clear 和 /compact 会重置此设置，因为它们无论如何都会在这些点重建缓存。

连接或断开 MCP 服务器

工具定义位于系统提示层，因此当请求中的工具定义集在回合之间发生变化时，缓存会失效。切换顾问工具是一个例外：其定义位于缓存断点之后，因此启用或禁用 /advisor 会保持缓存的前缀完整。MCP 服务器更改是否执行此操作取决于其工具是否由工具搜索延迟或加载到前缀中：

  • 延迟工具，在支持的模型上是默认值：服务器连接、断开连接或更改其工具列表只会追加新内容，不会扰乱已缓存的任何内容。
  • 加载到前缀中的工具：对它们的任何更改都会使缓存失效。这发生在工具搜索不可用或被禁用时，例如在早于 Claude 4.5 代的 Google Cloud Agent Platform 模型上、使用自定义 ANTHROPIC_BASE_URL 网关或在 Microsoft Foundry 部署在 Azure 上一旦 Claude Code 检测到部署拒绝工具搜索时。它也发生在标记为 alwaysLoad 的服务器或工具上，以及由基于阈值的加载保持在前面的定义上。

当工具加载到前缀中时，失效的最常见原因是服务器在会话中途连接或断开连接，这可能在没有您采取任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器在暂时故障后自动重新连接。连接的服务器也可以推送动态工具更新来更改其工具列表。

编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，这是服务器连接或断开连接的时候。

启用或禁用插件

当您启用或禁用插件时，更改的成本取决于插件提供的组件类型。下面的情况涵盖每个组件类型、Claude Code 何时应用更改以及在同一会话中再次禁用插件时会发生什么。

保持缓存的插件组件

Claude Code 永远不会为插件的技能、命令、代理、hooks、监视器或主题使缓存失效。它在现有对话之后追加其内容，因此下一个请求为该内容付费，并仍然从缓存中读取其之前的所有内容。

提供 MCP 服务器的插件

当您启用或禁用提供 MCP 服务器 的插件时，Claude Code 遵循与连接或断开 MCP 服务器相同的规则：

  • 如果 Claude Code 延迟服务器的工具，它会保持缓存。
  • 如果 Claude Code 将它们加载到前缀中，下一个请求会重新读取整个对话。

代码智能插件

当您启用代码智能插件时，Claude 会获得 LSP 工具。

插件更改何时应用

您在 /plugin 菜单中所做的更改会通过 /reload-plugins 进行，Claude Code 在您关闭菜单时为您运行。您需要支付成本，无论是追加公告还是完整重新读取，都在更改应用后的第一个回合。Claude Code 也可以自行应用更改：

  • 对于具有 command 源的插件，Claude Code 可以自行重新加载插件。
  • 当您从 /plugin 界面安装插件时，Claude Code 可以在安装期间激活它。安装摘要会告诉您它是否这样做了。
  • 当您在 v2.1.246 或更高版本上使用 /cd 移动会话时，Claude Code 会在移动过程中应用新目录的设置启用的插件，而不会出现保持 /reload-plugins 的完整重新读取警告。
  • 在交互式会话中，当您在使用 --plugin-dir 传递的插件文件夹中添加或删除插件时，更改会立即应用。如果应用它会触发完整重新读取，Claude Code 会保持更改并显示运行 /reload-plugins 的通知。需要 Claude Code v2.1.265 或更高版本。

当 /reload-plugins 运行且重新加载会触发完整重新读取时，Claude Code 会显示警告并不应用重新加载。运行 /reload-plugins --force 以无论如何应用它。

/reload-plugins 也在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 和非交互式模式与 -p，当您直接将其输入到会话中时。需要 Claude Code v2.1.260 或更高版本。

在这些会话中，重新加载应用除了插件 MCP 服务器更改之外的所有内容，这些在您的下一个会话中生效，因此在会话中途永远不会成本完整重新读取。

您在一个会话中启用然后禁用的插件

当您禁用您在会话中较早启用的插件时，Claude Code 会恢复之前的请求形状。如果该前缀仍在其缓存生命周期内，下一个请求会读取较旧的缓存条目，而不是重建。

拒绝整个工具

添加像 Bash 或 WebFetch 这样的裸工具名称作为拒绝规则会将该工具从 Claude 的上下文中完全删除。Claude Code 将内置工具定义加载到系统提示层，因此在会话中途添加或删除这些规则之一会使缓存失效。Claude Code 在下一个请求时应用更改，无论您通过 /permissions 添加规则还是通过直接编辑设置文件。这包括您在回合中途通过 /permissions 添加的规则。

只有在工具名称位置匹配的拒绝规则才有此效果：裸工具名称、等效的 Bash(*) 形式或工具名称 glob 如 "*"。仅匹配 MCP 工具的 glob，例如 "mcp__*"，会以相同的方式删除这些工具，但当匹配的工具是延迟时保持缓存完整，这是默认值，因为延迟定义从未在缓存的前缀中。作用域拒绝规则如 Bash(rm *)，以及所有允许和询问规则，不会改变 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。

压缩对话

压缩用摘要替换您的消息历史记录。根据设计，这会使对话层失效，因为下一个请求具有新的、更短的历史记录，不与旧历史记录共享前缀。Claude Code 重用系统提示层，除非对话是在保持会话的同时恢复的，该会话会以其他方式改变；在这种情况下，第一次压缩会切换到当前提示，该层会重建一次。它从磁盘重新加载项目上下文，仅当 CLAUDE.md 和内存自会话开始以来未更改时才缓存命中。

为了生成摘要，Claude Code 会发送一个单独的请求，其系统提示、工具和历史记录与您的对话相同，加上作为最终用户消息追加的摘要指令。当缓存温暖时，该请求从缓存中读取您的前缀，因此中会话 /compact 的成本是上下文大小建议的一小部分，并花费大部分时间生成摘要。

在长于缓存生命周期的中断后，没有缓存可读，因此摘要请求会重新处理完整历史记录作为未缓存输入。这就是为什么当您恢复旧会话时 /compact 成本最高。在温暖和冷的情况下，压缩后的回合仅为更短的摘要重建对话缓存，因此该回合不是缓慢的部分。

积累许多图像

API 限制每个请求可以携带多少图像和 PDF。有关当前数字，请参阅 API 文档中的请求限制。Claude Code 也限制了请求中图像和 PDF 的总大小，因此大型屏幕截图比小型屏幕截图更快达到限制。

当下一个请求会超过任一限制时，Claude Code 会从它发送的内容中删除一批最旧的图像和 PDF，这为更多内容腾出空间，然后才需要再次删除任何内容。Claude 不再能看到删除的图像。如果 Claude 再次需要其中一个，请再次共享它。

删除图像会改变保存它们的消息，因此下一个请求会从这些消息中最早的消息开始重新处理对话。因为 Claude Code 一次删除一批，您会看到每批一个较慢的回合，而不是每个新屏幕截图一个。

升级 Claude Code

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

保持缓存的操作

这些操作要么追加到对话的末尾，要么根本不触及请求。其中一些操作（例如编辑 CLAUDE.md）保持缓存的原因与该更改在运行会话中不会生效直到 /clear、/compact 或重启的原因相同。

编辑存储库中的文件

文件内容仅在 Claude 读取文件时进入上下文，而读取操作会追加到对话中。编辑 Claude 之前读过的文件不会追溯性地改变历史记录中的早期读取。相反，Claude Code 会追加一条 <system-reminder> 注明文件已更改，Claude 会在需要时重新读取该文件。

在会话中编辑 CLAUDE.md

您的项目根目录和用户级 CLAUDE.md 文件在会话开始时读取一次并保存在内存中。在会话中编辑它们不会使缓存失效，但编辑也不会应用。Claude 继续使用在会话开始时加载的版本。新内容在下一次 /clear、/compact 或重启时加载。

子目录中的嵌套 CLAUDE.md 文件和带有 paths: frontmatter 的规则稍后加载，当 Claude 首次读取匹配的文件时。在加载前编辑它确实会生效。加载后，内容成为对话历史的一部分，所以中途编辑不会追溯性地改变它。

更改权限模式

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

更改输出样式

当您在会话中使用 /config 或 outputStyle 设置切换输出样式时，Claude 从您的下一条消息开始使用新样式。Claude Code 将新样式的指令作为对话中的消息传递，所以该请求仍然从缓存中读取系统提示和早期对话。

在 v2.1.251 之前，中途样式切换保持缓存但直到您运行 /clear 或启动新会话时才应用。

调用 skills 和命令

Skills 和命令在调用点将其指令作为用户消息注入。对话中早期的任何内容都不会改变。frontmatter 中命名 model 的 skill 或命令可以是该轮的模型切换。

运行 `/recap`

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

回溯对话

/rewind 将您的对话截断回到较早的轮次。剩余的历史是缓存在该点构建时的相同内容，系统提示和项目上下文层保持不变，所以下一个请求会命中较早的缓存条目。从那时起的每一轮都读过该前缀，即使原始轮次比 TTL 更久远，也保持了该条目的活跃。

恢复文件检查点与对话一起对缓存没有单独的影响。文件内容仅在 Claude 读取文件时进入上下文，与编辑存储库中的文件相同。

恢复会话

当你恢复会话时，Claude Code 会重新发送整个对话，请求会从缓存中读取其前缀中未更改且仍在缓存生命周期内的任何部分。本页顶部的层表说明了每一层的变化。

系统提示词会在Claude Code 升级后或在恢复时使用不同的--append-system-prompt文本时发生变化。默认情况下，恢复的对话会保持其启动时的系统提示词，因此其历史记录仍然位于相同的提示词后面，更改会在对话被压缩或在新对话中生效。恢复的对话中的系统提示词标志涵盖了--system-prompt-snapshot off和裸模式，其中这不适用。

缓存生命周期

缓存的前缀在不活动期间后过期。每个命中缓存的请求都会重置计时器，所以只要您继续工作，缓存就保持温暖。在足够长的间隙之后，下一个请求重新计算完整输入并重新建立缓存，这就是为什么步开后的第一个回合可能明显更慢。

在 Pro 或 Max 计划上，当您在长时间休息后恢复大型会话时，Claude Code 提供从摘要恢复，以便后续请求不会携带完整历史记录。

生存时间 (TTL) 控制缓存存活的间隙有多长。API 提供两个：五分钟 TTL 和一小时 TTL，它通过更长的中断保持缓存温暖，但以更高的速率计费缓存写入。较长的 TTL 在您让会话空闲并返回到它时很有帮助，因为您跳过了过期前缀成本的重新处理。对于从不空闲超过五分钟的短工作突发，它成本更高，其中更高的写入速率适用，较长的缓存生命周期未被使用。

每个请求获得哪个 TTL

Claude Code 按请求决定 TTL，每个请求都属于以下两个固定桶之一：

  • 主对话：您的交互式回合、非交互式 -p 运行和 Agent SDK 回合，加上 Claude Code 与它们内联运行的助手
  • 其他所有内容：Claude Code 在该对话之外进行的请求，例如子代理、工作流、进程内队友、分支、压缩和会话标题

除非您自己选择 TTL，否则 Claude Code 仅在您计划包含的使用范围内的 Claude 订阅上请求一小时 TTL。在那里，它为主对话请求一小时，加上 Anthropic 在服务器端控制的一小组助手请求。此表给出了两种计费方式下每个桶的默认 TTL。

请求桶 Claude 订阅，在计划使用范围内 使用额度、API 密钥或云提供商
主对话 一小时 五分钟
其他所有内容 五分钟，除了服务器控制的助手请求获得一小时 五分钟

一旦您超过计划的使用限制，Claude Code 使用使用额度，您需要为该使用付费，所以 Claude Code 将主对话降低到更便宜的五分钟 TTL。要在那里保持一小时 TTL，自己选择 TTL。

自己选择 TTL

您可以为任一桶设置 TTL。每个控制采用 5m 或 1h，Claude Code 忽略任何其他值。

两个设置和两个环境变量都需要 Claude Code v2.1.242 或更高版本。如果您使用 API 密钥登录或使用云提供商，将 promptCacheTtl 设置为 1h 以为主对话提供一小时缓存。其外的请求保持五分钟默认值，直到您也为该桶选择 TTL。

当多个控制适用时，Claude Code 按此顺序采用第一个匹配：

  1. FORCE_PROMPT_CACHING_5M=1，为两个桶强制五分钟
  2. 桶的环境变量
  3. 桶的设置
  4. 对于子代理的请求，子代理的 experimental frontmatter 字段中的 cacheTtl 值，需要 Claude Code v2.1.248 或更高版本。当您的 Claude 订阅使用使用额度时，Claude Code 忽略那里的 1h
  5. ENABLE_PROMPT_CACHING_1H=1，为两个桶请求一小时
  6. 请求桶的默认值

当您调试缓存行为、比较两个 TTL 或覆盖在托管设置中设置的较长 TTL 时，设置 FORCE_PROMPT_CACHING_5M=1。

要确认您的主对话的缓存写入使用了哪个 TTL，运行 claude -p "hello" --output-format json 并读取结果中的 usage.cache_creation。Claude Code 在 ephemeral_1h_input_tokens 下报告一小时缓存写入，在 ephemeral_5m_input_tokens 下报告五分钟缓存写入。

通过您使用 ANTHROPIC_BASE_URL 设置的 LLM 网关，部分一小时请求在 anthropic-beta 标头中传输，所以配置网关以原样转发该标头。一小时 TTL 在Claude 应用网关上不可用。在 Amazon Bedrock 上，prompt caching 支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请检查 Amazon Bedrock 文档中的支持的模型、区域和限制。

缓存范围

在 Claude Code 中，缓存有效地限定在一台机器和目录。每个对话都携带工作目录、平台、shell 和 OS 版本，系统提示命名您的自动内存路径，所以两个不同目录中的会话构建不同的前缀并错过彼此的缓存。这包括同一存储库的 worktrees，因为每个 worktree 都有自己的工作目录。

您在同一目录中并行运行的会话构建匹配的前缀并读取彼此的缓存。顺序会话仅当启动时的 git 状态快照匹配时才共享前缀，因为每个对话也携带该快照中的分支和最近的提交。

底层 API 缓存更广泛。缓存在组织之间隔离，在某些提供商上，在组织内的工作区之间隔离。在这些边界内，任何两个具有相同模型和前缀的请求读取相同的缓存。对于运行自动化流程队列的 Agent SDK 调用者，请参阅改进跨用户和机器的 prompt caching以抑制系统提示的按机器部分并跨机器共享缓存。

检查缓存性能

缓存性能显示为 API 在每个响应上报告的两个令牌计数。实时观看它们的最直接方式是读取 current_usage 对象的状态行脚本：

字段 含义
cache_creation_input_tokens 在此回合写入缓存的令牌，按缓存写入速率计费
cache_read_input_tokens 在此回合从缓存提供的令牌，按标准输入速率的大约 10% 计费

高读取与创建比率意味着缓存工作良好。如果创建在回合之间保持高位，您的前缀中有什么在改变。使缓存失效的操作部分列出了常见原因。

为了获得每个会话的摘要，运行 /usage。在主对话的第一个响应之后，Claude Code 会在会话块中添加一个Prompt cache (main) 行，显示会话的命中率、未命中计数以及缓存现在是否处于热状态。状态行脚本可以从prompt_cache 对象读取相同的数字。两者都需要 Claude Code v2.1.251 或更高版本。

当 Claude Code 能够识别时，Prompt cache (main) 行还会命名最后一次未命中的可能原因，例如 likely cause: tool definitions changed。可能原因文本需要 Claude Code v2.1.260 或更高版本。

为了在整个组织中获得可见性，OpenTelemetry 导出器报告每个用户和会话的缓存读取和创建令牌。有关指标和事件属性参考，请参阅监控使用。

子代理和缓存

子代理启动自己的对话，具有自己的系统提示和工具集，与父代的分开。它的第一个请求不读取父代的缓存，因为两个前缀不同，并在自己的回合中预热自己的缓存。子代理不在主对话TTL 桶之外，所以即使在订阅上也能获得五分钟，直到你选择更长的时间。

父代的缓存不受影响。从父代的一侧，子代理的调用和结果附加到对话，保留父代的前缀完整。

分叉相比之下，完全继承父代的系统提示、工具和对话历史记录，所以其第一个请求读取父代的缓存。

其他请求也可以读取较早请求缓存的前缀：

  • 会话副本：你使用 /fork 复制的会话在复制的对话末尾作为消息接收其隔离指令，所以原始对话构建的缓存保持完整。
  • 压缩：压缩对话中描述的摘要调用使用相同的前缀共享方法。
  • 恢复的子代理：当 Claude 恢复子代理时，恢复运行的第一个请求可以读取原始运行预热的缓存。
  • 工作流扇出：在工作流扇出中，相同前缀的代理，Claude Code 默认将除第一个外的所有代理保留最多 5 秒，所以它们的第一个请求可以读取第一个代理缓存的前缀。

禁用 prompt caching

禁用缓存在使用特定模型或提供商调试缓存行为时偶尔很有用。要关闭它，请将以下环境变量之一设置为 1：

变量 效果
DISABLE_PROMPT_CACHING 对所有模型禁用
DISABLE_PROMPT_CACHING_HAIKU 仅对 Haiku 禁用
DISABLE_PROMPT_CACHING_SONNET 仅对 Sonnet 禁用
DISABLE_PROMPT_CACHING_OPUS 仅对 Opus 禁用
DISABLE_PROMPT_CACHING_FABLE 仅对 Fable 禁用

要在整个组织中设置缓存策略，请将这些或TTL 变量中的任何一个放在托管设置的 env 块中。对于正常使用，保持缓存启用。