{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在以下地址获取完整文档索引：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 参考中的[提示缓存工作原理](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works)。

<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="四轮显示为不断增长的水平条。每轮的请求包含上一轮的所有内容加上末尾追加的最新交换。在第二和第三轮，未更改的前缀从缓存读取，只有新交换被处理。在第四轮，系统提示更改，因此前缀不再匹配，整个请求被重新处理和写入。" width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=7434a04e08187edd26ec6c3dd332f624" className="hidden dark:block" alt="四轮显示为不断增长的水平条。每轮的请求包含上一轮的所有内容加上末尾追加的最新交换。在第二和第三轮，未更改的前缀从缓存读取，只有新交换被处理。在第四轮，系统提示更改，因此前缀不再匹配，整个请求被重新处理和写入。" width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

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

| 层级           | 内容                                                | 何时更改                                                       |
| -------------- | --------------------------------------------------- | -------------------------------------------------------------- |
| 系统提示       | 核心指令、工具定义、输出风格                        | MCP 服务器连接或断开，或 Claude Code 升级                      |
| 项目上下文     | CLAUDE.md、自动记忆、无范围规则                    | 会话开始，或 `/clear` 或 `/compact` 之后                       |
| 对话           | 您的消息、Claude 的响应、工具结果                   | 每轮                                                           |

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

前缀匹配规则解释了本页大部分行为。例如，[计划模式](/cn/permission-modes#编辑前先分析使用计划模式)和[技能加载](/cn/skills)将指令作为对话消息追加，因此缓存的前缀保持完整。

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

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

<Tip>
  在会话开始时选择模型、努力级别和 MCP 服务器，然后将 `/compact` 保存到任务之间的自然断点。任务中更改越少，缓存命中率越高。
</Tip>

### 缓存的位置

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

* **API 密钥、Claude 订阅或 [AWS 上的 Claude 平台](/cn/claude-platform-on-aws)**：缓存在 Anthropic 的基础设施中，通过 [Claude API](https://platform.claude.com/docs) 访问
* **Bedrock 或 Vertex AI**：缓存在您云提供商的服务基础设施中
* **Foundry**：请求路由到 Anthropic 的基础设施
* **自定义 `ANTHROPIC_BASE_URL` 或 [LLM 网关](/cn/llm-gateway)**：缓存在您的请求被转发到的位置，缓存是否工作取决于网关

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

## 使缓存失效的操作

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

* [切换模型](#切换模型)
* [更改努力级别](#更改努力级别)
* [连接或断开 MCP 服务器](#连接或断开-mcp-服务器)
* [拒绝整个工具](#拒绝整个工具)
* [压缩对话](#压缩对话)
* [升级 Claude Code](#升级-claude-code)

### 切换模型

每个模型有自己的缓存。使用 [`/model`](/cn/model-config#设置您的模型) 切换意味着下一个请求读取整个对话历史而无缓存命中，即使内容相同。

[`opusplan` 模型设置](/cn/model-config#opusplan-模型设置)在计划模式期间解析为 Opus，在执行期间解析为 Sonnet，因此每次计划模式切换都是模型切换并开始全新缓存。

### 更改努力级别

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

### 连接或断开 MCP 服务器

工具定义位于系统提示层，因此当 Claude 可用的 MCP 工具集在轮次之间更改时缓存失效。最常见的原因是 [MCP 服务器](/cn/mcp)在会话中连接或断开，这可能在您没有任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器[在瞬态失败后自动重新连接](/cn/mcp#自动重新连接)。已连接的服务器也可以推送[动态工具更新](/cn/mcp#动态工具更新)来更改其工具列表。

编辑 MCP 配置本身不会更改缓存。新配置仅在重启后生效，即服务器连接或断开时。

[MCP 工具搜索](/cn/mcp#使用-mcp-工具搜索扩展)通过延迟完整工具定义来减少每个工具对前缀的贡献，但工具名称集仍然必须保持稳定才能使缓存有效。

### 拒绝整个工具

将裸工具名称（如 `Bash` 或 `WebFetch`）添加为[拒绝规则](/cn/permissions#管理权限)会从 Claude 的上下文中完全移除该工具。工具定义位于系统提示层，因此在会话中添加或删除这些规则之一会使缓存失效，方式与 MCP 服务器连接或断开相同。无论您通过 `/permissions` 还是[直接编辑设置文件](/cn/settings#编辑何时生效)添加，更改在下一轮生效。

只有裸工具名称或等效的 `Bash(*)` 形式才有此效果。范围拒绝规则如 `Bash(rm *)`，以及所有允许和询问规则，不会更改 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。

### 压缩对话

[压缩](/cn/context-window#压缩后保留什么)用摘要替换您的消息历史。按设计，这会使对话层失效，因为下一个请求有新的、更短的历史，不与旧的共享前缀。Claude Code 重用系统提示层并从磁盘重新加载项目上下文，仅当 CLAUDE.md 和记忆自会话开始以来未更改时才缓存命中。

要生成摘要，Claude Code 发送一个一次性请求，具有与您对话相同的系统提示、工具和历史，加上追加为最终用户消息的摘要指令。因为它共享您的前缀，该请求读取现有缓存而不是重新处理完整历史。压缩的大部分时间用于生成摘要，而不是缓存未命中。压缩后重建对话缓存的轮次仅针对更短的摘要，因此压缩后的轮次不是慢的部分。

<Tip>
  当您丢弃的上下文是不再需要的内容时，压缩对您有利。要选择其开销发生的时间，在工作的自然断点（如任务之间）运行 `/compact`，而不是等待自动压缩在任务中触发。如果您走上了一条想完全放弃的路径，[`/rewind`](#回退对话)到更早的轮次。回退截断到已缓存的前缀，而不是像压缩那样构建新的。
</Tip>

### 升级 Claude Code

新的 Claude Code 版本通常更新系统提示或工具定义，因此升级后的第一个请求从顶部重建缓存。[自动更新](/cn/setup#自动更新)在后台下载新版本但在下次启动时应用，永远不会在会话中，因此您看到的是重启后未缓存的第一轮而不是会话中的意外。设置 `DISABLE_AUTOUPDATER=1` 以控制升级何时应用。

<Note>
  升级后[恢复会话](/cn/sessions#恢复会话)会重新处理整个对话历史而无缓存命中，因为历史现在位于不同的系统提示后面。成本随恢复对话的长度而扩展，因此回到长会话的第一轮可能是您发送的最昂贵的请求。
</Note>

## 保留缓存的操作

这些操作要么追加到对话末尾，要么根本不触及请求。其中一些（如编辑 CLAUDE.md 或更改输出风格）也是设置更改等待重启才生效的原因。

* [编辑仓库中的文件](#编辑仓库中的文件)
* [在会话中编辑 CLAUDE.md](#在会话中编辑-claudemd)
* [更改输出风格](#更改输出风格)
* [更改权限模式](#更改权限模式)
* [调用技能和命令](#调用技能和命令)
* [运行 `/recap`](#运行-recap)
* [回退对话](#回退对话)
* [生成子代理](#子代理和缓存)

### 编辑仓库中的文件

文件内容仅在 Claude 读取它们时进入上下文，读取追加到对话中。编辑 Claude 先前读取的文件不会追溯更改历史中的先前读取。相反，Claude Code 追加一个 `<system-reminder>` 说明文件已更改，Claude 在需要时重新读取它。

### 在会话中编辑 CLAUDE.md

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

[子目录中的嵌套 CLAUDE.md 文件](/cn/memory)和[带 `paths:` frontmatter 的规则](/cn/memory#路径特定规则)稍后加载，当 Claude 首次读取匹配文件时。在加载前编辑确实会生效。加载后，内容成为对话历史的一部分，因此会话中的编辑不会追溯更改它。

### 更改输出风格

[输出风格](/cn/output-styles)是系统提示的一部分，Claude Code 在会话开始时读取一次。通过 `/config` 或 `outputStyle` 设置在会话中更改不会使缓存失效，但更改也不会应用。Claude 继续使用会话开始时加载的风格。新风格在下次 `/clear` 或重启时加载。

### 更改权限模式

在[权限模式](/cn/permission-modes)之间切换（如从默认到接受编辑）不会更改系统提示或工具定义，因此模式更改是缓存安全的。例外是使用 [`opusplan`](/cn/model-config#opusplan-模型设置) 模型设置的计划模式，它在进入或离开计划模式时在 Opus 和 Sonnet 之间切换模型。这使得模式切换成为[模型切换](#切换模型)。

### 调用技能和命令

[技能](/cn/skills)和[命令](/cn/commands)在调用点将其指令注入为用户消息。对话中更早的内容不会更改。

### 运行 `/recap`

[`/recap`](/cn/interactive-mode#会话回顾)生成用于在终端中显示的摘要。与 `/compact` 不同，它将摘要作为命令输出追加而不是替换您的消息历史，因此缓存的前缀保持完整。

### 回退对话

[`/rewind`](/cn/checkpointing)将您的对话截断回更早的轮次。剩余的历史是该时点缓存构建的相同内容，系统提示和项目上下文层未更改，因此下一个请求命中更早的缓存条目。此后每一轮都通过该前缀读取，即使原始轮次比 TTL 更早，也保持条目温热。

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

## 缓存生命周期

缓存的前缀在一段时间不活动后过期。每个命中缓存的请求重置计时器，因此只要您继续工作缓存就保持温热。足够长的间隔后，下一个请求重新计算完整输入并重新建立缓存，这就是为什么离开后回来的第一轮可能明显更慢。

生存时间（TTL）控制缓存能存活多长的间隔。API 提供两种：五分钟 TTL 和[一小时 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，后者在更长的休息期间保持缓存温热，但[缓存写入的计费费率更高](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。Claude Code 根据您的认证方式为您选择 TTL，您可以使用环境变量覆盖它。

### 在 Claude 订阅上

在 Claude 订阅上，Claude Code 自动请求一小时 TTL。使用量包含在您的计划中而非按令牌计费，因此更长的 TTL 不会额外花费您任何费用，只影响缓存保持温热的时间。

如果您超出了计划的使用限制且 Claude Code 正在使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，您需要为该使用量付费，因此 Claude Code 自动将 TTL 降至五分钟。

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

在 API 密钥、Bedrock、Vertex、Foundry 或 AWS 上的 Claude 平台上，您按令牌费率付费，因此 TTL 默认保持在更便宜的五分钟。要选择加入[一小时 TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)，设置 `ENABLE_PROMPT_CACHING_1H=1`。

在 Bedrock 上，提示缓存支持、最小可缓存前缀长度和一小时 TTL 可用性都因模型而异。如果缓存令牌计数保持为零，请查看 Bedrock 文档中的[支持的模型、区域和限制](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)。

### 覆盖 TTL

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

## 缓存范围

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

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

底层 API 缓存更广泛。缓存在组织之间隔离，在某些提供商上，[在组织内的工作区之间隔离](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在这些边界内，任何两个具有相同模型和前缀的请求读取相同的缓存。对于运行自动化进程集群的 Agent SDK 调用者，请参阅[跨用户和机器改进提示缓存](/cn/agent-sdk/modifying-system-prompts#跨用户和机器改进提示缓存)以抑制系统提示的每台机器部分并跨机器共享缓存。

## 检查缓存性能

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

| 字段                          | 含义                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `cache_creation_input_tokens` | 本轮写入缓存的令牌，按缓存写入费率计费                                                 |
| `cache_read_input_tokens`     | 本轮从缓存服务的令牌，按大约标准输入费率的 10% 计费                                     |

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

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

## 子代理和缓存

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

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

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

## 禁用提示缓存

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

| 变量                            | 效果                    |
| ------------------------------- | ----------------------- |
| `DISABLE_PROMPT_CACHING`        | 对所有模型禁用          |
| `DISABLE_PROMPT_CACHING_HAIKU`  | 仅对 Haiku 禁用         |
| `DISABLE_PROMPT_CACHING_SONNET` | 仅对 Sonnet 禁用        |
| `DISABLE_PROMPT_CACHING_OPUS`   | 仅对 Opus 禁用          |

要在组织中设置缓存策略，将这些或 [TTL 变量](#缓存生命周期)中的任何一个放在[托管设置](/cn/settings#设置文件)的 `env` 块中。正常使用时，保持缓存启用。

## 相关资源

* [构建 Claude Code 的经验：提示缓存就是一切](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything)：计划模式、延迟工具加载和压缩的设计原理
* [探索上下文窗口](/cn/context-window)：什么加载到上下文中以及何时加载
* [减少令牌使用量](/cn/costs#减少令牌使用量)：缓存之外管理上下文大小的策略
* [跟踪和降低成本](/cn/agent-sdk/cost-tracking)：Agent SDK 调用者的缓存令牌跟踪和 TTL 配置
* [提示缓存](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)：底层 API 机制、断点和定价