文档索引

在以下地址获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

Claude Code 如何使用提示缓存

Claude Code 自动管理提示缓存。了解为什么模型切换会触发缓慢的未缓存轮次、/compact 的成本、为什么 CLAUDE.md 编辑不会在会话中生效，以及如何检查缓存命中率。

提示缓存使 Claude Code 更快且更具成本效益。没有缓存时，API 会在每个轮次重新处理您的完整历史。有缓存时，它重用已处理的内容，只对更改的部分做新工作。

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

缓存的组织方式

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

API 通过将每个请求的开头（称为前缀）与其最近处理的内容匹配来缓存。在正常轮次中，前缀是整个先前的请求，只有最新的交换是新的。匹配是精确的，因此前缀中任何位置的更改都会重新计算其后的所有内容。没有按文件或按段缓存。有关底层机制，请参阅 API 参考中的提示缓存工作原理。

为了充分利用前缀匹配，Claude Code 排列每个请求，使轮次之间很少更改的内容放在前面：

对话层的更改保留系统提示和项目上下文的缓存。系统提示的更改会使所有内容失效，因为所有后续内容现在位于不同的前缀后面。第三列给出常见触发因素而非详尽列表，以下部分涵盖完整集合，包括输出风格等在会话开始时固定的内容。

前缀匹配规则解释了本页大部分行为。例如，计划模式和技能加载将指令作为对话消息追加，因此缓存的前缀保持完整。

有两个设置根本不属于提示文本，因此不出现在层级表中，但两者都是缓存键的一部分：

• 模型：每个模型有自己的缓存。切换模型会重新计算整个请求，即使内容相同。参见下方切换模型。
• 努力级别：每个努力级别在同一模型上有自己的缓存。在会话中更改会重新计算整个请求，Claude Code 在应用更改前要求您确认。参见下方更改努力级别。

缓存的位置

缓存发生在服务器端，在服务您模型的基础设施中。位置取决于您的认证方式：

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

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

使缓存失效的操作

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

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

切换模型

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

opusplan 模型设置在计划模式期间解析为 Opus，在执行期间解析为 Sonnet，因此每次计划模式切换都是模型切换并开始全新缓存。

更改努力级别

缓存按努力级别和模型作为键，因此使用 /effort 切换意味着下一个请求读取整个对话历史而无缓存命中。对话开始后，Claude Code 在应用会使缓存失效的努力更改前显示确认对话框。解析为已生效的相同级别的更改（如明确设置模型默认值）跳过对话框并保留缓存。

连接或断开 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 模型设置的计划模式，它在进入或离开计划模式时在 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 或 AWS 上的 Claude 平台上，您按令牌费率付费，因此 TTL 默认保持在更便宜的五分钟。要选择加入一小时 TTL，设置 ENABLE_PROMPT_CACHING_1H=1。

在 Bedrock 上，提示缓存支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请查看 Bedrock 文档中的支持的模型、区域和限制。

覆盖 TTL

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

缓存范围

在 Claude Code 中，缓存实际上限定到一台机器和一个目录。系统提示嵌入工作目录、平台、shell、操作系统版本和自动记忆路径，因此不同目录中的两个会话构建不同的前缀并互相缓存未命中。这包括同一仓库的 worktree，因为每个 worktree 有自己的工作目录。

在相同目录中并行运行的会话构建匹配的前缀并互相读取缓存。顺序会话仅在启动时的 git 状态快照匹配时共享前缀，因为系统提示还捕获分支和最近的提交。

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

检查缓存性能

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

高读取与创建比率意味着缓存工作良好。如果创建持续在轮次之间保持较高，说明您的前缀中有内容在变化。使缓存失效的操作部分列出了常见原因。

要获得组织范围的可见性，OpenTelemetry 导出器按用户和会话报告缓存读取和创建令牌。有关指标和事件属性参考，请参阅监控使用量。

子代理和缓存

子代理启动自己的对话，有自己的系统提示和工具集，与父级分开。它构建自己的缓存，第一次调用时没有缓存命中，在自己的轮次中预热。子代理使用五分钟 TTL，即使在订阅上也是如此，因为自动一小时 TTL 适用于主对话。

父级的缓存不受影响。从父级的角度看，子代理的调用和结果追加到对话中，保持父级的前缀完整。

相比之下，fork完全继承父级的系统提示、工具和对话历史，因此其第一个请求读取父级的缓存。压缩对话中描述的压缩摘要调用使用相同的前缀共享方法。

禁用提示缓存

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

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

相关资源

• 构建 Claude Code 的经验：提示缓存就是一切：计划模式、延迟工具加载和压缩的设计原理
• 探索上下文窗口：什么加载到上下文中以及何时加载
• 减少令牌使用量：缓存之外管理上下文大小的策略
• 跟踪和降低成本：Agent SDK 调用者的缓存令牌跟踪和 TTL 配置
• 提示缓存：底层 API 机制、断点和定价