Claude Code 如何使用提示缓存

提示缓存使 Claude Code 更快、更省成本。没有缓存时，API 会在每一轮重新处理完整历史。有了缓存，会复用已处理部分，只为变化部分做新工作。

Claude Code 会为您处理提示缓存（除非您禁用它）。某些操作会使缓存失效，下一轮会变慢、更贵，直到重建缓存。

缓存如何组织

每次发送消息时，Claude Code 都会发起新的 API 请求。模型在请求之间不保留记忆，因此会重新发送完整上下文。提示缓存避免重新处理未变化部分。

API 通过将每次请求的前缀与最近处理的内容匹配来缓存。匹配是精确的：前缀中任何位置的变化都会使其后全部重新计算。没有按文件或分段的缓存。

Claude Code 将轮次间很少变化的内容排在前面：

对话层变化时，系统提示与项目上下文仍可缓存。系统提示变化会使之后全部失效。

以下两项也是缓存键的一部分，但不在提示文本中：

• 模型 — 每个模型独立缓存。切换模型会整段重算。
• Effort 等级 — 每个 effort 独立缓存。会话中更改会整段重算。

在会话开始时选定模型、effort 与 MCP，在任务间隙而非中途使用 /compact。

缓存存放位置

缓存在服务端。使用 API 密钥或 Claude 订阅时，缓存在 Anthropic 基础设施中。Bedrock 或 Vertex 上则在云提供商侧。自定义 ANTHROPIC_BASE_URL 或网关时，缓存位于请求转发目标。

缓存前缀在一段时间不活动后过期；命中会刷新计时器。

使缓存失效的操作

以下操作会导致下一轮部分或全部缓存未命中：

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

切换模型

每个模型有独立缓存。用 /model 切换后，下一轮会无缓存地读取完整对话历史。

更改 effort 等级

缓存键包含 effort。会使缓存失效的 effort 变更前，Claude Code 可能显示确认对话框。

连接或断开 MCP 服务器

工具定义在系统提示层，MCP 工具集变化会使缓存失效。仅编辑 MCP 配置不会立即改变缓存；重启后生效。

拒绝整个工具

将 Bash 或 WebFetch 等裸工具名加入 deny 会从上下文中移除该工具，效果类似 MCP 变化。

仅裸工具名或等价的 Bash(*) 有此效果。Bash(rm *) 等作用域 deny 不改变 Claude 可见的工具集。

压缩对话

压缩用摘要替换历史，使对话层失效。系统提示层复用，项目上下文从磁盘重新加载。

在任务自然间隙运行 /compact。若要放弃整条路径，用 /rewind 截断到已缓存前缀。

升级 Claude Code

新版本常更新系统提示或工具定义，升级后首轮会自顶重建缓存。自动更新在下次启动应用，不会中途应用。

保持缓存的操作

• 编辑仓库中的文件
• 会话中编辑 CLAUDE.md（要到 /clear、/compact 或重启才生效）
• 会话中更改输出风格（同上）
• 更改权限模式（opusplan 在计划模式切换模型除外）
• 调用 skill 与命令
• 运行 /recap
• 回退对话

编辑 Claude 曾读过的文件不会 retroactively 改变先前读取；会追加文件已变更说明并在需要时重读。

缓存生命周期

不活动后前缀过期。API 提供 5 分钟与 1 小时 TTL。

• Claude 订阅 下 Claude Code 通常自动请求 1 小时 TTL。
• API 密钥或第三方 默认 5 分钟；设 ENABLE_PROMPT_CACHING_1H=1 可开 1 小时。
• FORCE_PROMPT_CACHING_5M=1 可强制 5 分钟。

缓存范围

在 Claude Code 中，缓存 effectively 按机器与目录限定。系统提示嵌入工作目录、平台、shell 及启动时 git 快照。

同目录并行会话可互相读缓存。顺序会话仅当启动时 git 快照一致时才共享前缀。

查看缓存表现

读多写少说明缓存工作良好。

子代理与缓存

子代理以独立系统提示与工具集开启自己的对话并建立自己的缓存，不影响父会话缓存。分叉继承父前缀，首轮可读父缓存。

禁用提示缓存

正常使用请保持缓存开启。