提示缓存

Claude Code 不在每个回合重新处理整个对话，而是自动管理复用已处理部分的提示缓存 (prompt caching)。

背景参考

本页是关于 Claude Code 本身 的背景资料，也就是 MoAI-ADK 所依托的平台。MoAI-ADK 的使用方法请见 提示缓存 —— 概念与在 Claude Code 中的行为。

信息

一句话总结：把每次都不变的前段（前缀）直接从缓存读出，同一份工作不做第二遍，大幅降低成本与响应时间。

用比喻理解

提示缓存就像夹在书里的书签。每次请求都会再装入同样的前段（系统提示·项目上下文·历史对话），如果前段与上一次完全相同，就不必从头重读，而是跳到书签所在的位置。所以前段保持不变越久，缓存效果越大；前段一旦改变，从那一点起就要重新读。

模型在请求与请求之间什么都不记得。因此 Claude Code 每次发送消息都会创建新的 API 请求，重新传输完整上下文（系统提示、项目上下文、所有历史消息与工具结果、新消息）。

关键在于新内容总是追加在最末尾。因此每个请求的绝大部分与上一个请求相同。提示缓存正是让这"未变的部分"免于重复处理的机制。

API 会把每个请求的开头部分与最近处理过的内容比对。这个开头部分称为前缀 (prefix)。在一般的回合中，上一个请求的全部内容成为前缀，只有最近一次交换是新内容。

匹配采用精确一致方式，前缀中任何位置发生变化，其后的内容全部重新计算。不存在按文件或按区段的缓存。

flowchart TD
    A[新 API 请求] --> B{前缀与之前
一致吗}
    B -->|一致| C[从缓存读取
约为标准输入费率的 10%]
    B -->|不一致| D[变更点之后
全部重新处理 + 重写缓存]
    C --> E[仅新处理
最新交换]
    D --> E
    E --> F[返回回应]

为提高前缀匹配效率，Claude Code 把几乎不变的内容放在前面。

若只有对话层变化，系统提示与项目上下文保持在缓存中。反之，系统提示一变，其后所有内容都排在了不同的前缀之后，因此整体失效。

还有两个不包含在提示文本中、却属于缓存键一部分的因素。

• 模型：每个模型的缓存相互独立。用 /model 切换模型后即便内容相同也会整体重算。
• 努力等级 (effort level)：同一模型下不同努力等级的缓存也各自独立。会话中途用 /effort 更改会整体重算，Claude Code 会在应用前请求确认。

被缓存的对象归根结底是不常变化的、位于请求前部的大块内容。

• 系统提示：核心指令与输出样式
• 工具定义：内置工具与 MCP 工具的完整定义
• 项目上下文：CLAUDE.md、自动记忆、规则
• 累积的对话记录：历史消息、Claude 回应、工具结果、大块上下文（读入的大型代码库文件等）

这些大块内容在某一回合被处理一次并写入缓存，之后的回合只需支付约为标准输入费率 10% 的费用即可原样读取。

缓存性能体现在 API 随每次回应报告的两个令牌数值上。

• 成本：读取 (read) 令牌约为标准输入费率的 10%。缓存读取占比越高，同样的工作处理得越便宜。
• 延迟：未变的前缀无需重新处理，回应因而更快。反之，缓存失效的那一回合会一次性变慢变贵。

读取相对写入 (read-to-creation) 的比率越高，说明缓存运转越好。如果写入量每回合都居高不下，就是前缀中有什么在每次变化的信号。

以下行为会让下一个请求错过部分或全部缓存。经历一次又慢又贵的回合后，新前缀会被重新缓存。

Bash(rm *) 这类限定范围的 deny 规则以及所有 allow/ask 规则不会改变 Claude 看到的工具集合，前缀因此保持不变。

相反，以下行为只是追加到对话末尾或根本不触及请求本身，缓存得以存活。

• 编辑仓库中的文件（Claude 重新读取时追加到对话末尾）
• 会话中途编辑 CLAUDE.md（缓存保持，但编辑内容在下次 /clear·/compact·重启之前不生效）
• 更改输出样式（同样在下次 /clear·重启时生效）
• 更改权限模式（opusplan 计划模式除外）
• 调用技能·命令（指令作为用户消息插入）
• 执行 /recap、用 /rewind 回退

提示缓存默认开启，由 Claude Code 自动管理，无需任何开启配置。提高缓存命中率的最佳实践 (best practices) 很简单。

• 模型·努力等级·MCP 服务器在会话开始时定好，工作中途不更改。
• /compact 在任务与任务之间的自然间隙执行。
• 若走进了要放弃的路径，用 /rewind 回到已缓存的之前回合，而不是 /compact。

缓存实际上以一台机器·一个目录为范围。因为系统提示包含工作目录、平台、shell、OS 版本、自动记忆路径。同一仓库的工作树因目录不同也不共享彼此的缓存。

缓存的前缀在一段时间无活动后过期。每次命中缓存的请求都会重置计时器，持续工作期间缓存保持温热。

要查看缓存是否运转良好，就观察上述两个令牌数值（cache_read_input_tokens、cache_creation_input_tokens）。

• statusline 脚本：用读取 current_usage 对象的状态栏脚本，可每回合实时查看。
• OpenTelemetry 导出器：需要组织级可见性时，按用户·会话报告缓存读/写令牌。

如果缓存写入令牌每回合都居高不下，请在"使缓存失效的行为"表中查找原因。

只有在调试特定模型·提供方的行为时才需要临时关闭缓存。平时保持开启使用。

# 对所有模型禁用
export DISABLE_PROMPT_CACHING=1

# 仅禁用特定模型
export DISABLE_PROMPT_CACHING_OPUS=1

提示缓存是 MoAI-ADK 代币经济学各项要素中最容易度量的一项。MoAI-ADK 从两个方向运用缓存。

• 提高命中率的设计：在 SPEC 驱动工作流中维持稳定的前缀（系统提示、CLAUDE.md、规则），并给常驻加载的上下文瘦身，让缓存得以存活的前段尽可能大而稳定。
• 展示命中率的度量：在 statusline 上显示缓存命中 (cache hit) 信号，让上下文瘦身的效果在会话中即时可见。在 GLM 后端 (z.ai) 上会自动应用隐式提示缓存。

缓存在成本层面何时真正划算的盈亏平衡分析，在下面的文档中讲解。

• 提示缓存 —— 盈亏平衡分析

• How Claude Code uses prompt caching

提示

实战提示：会话开始时先敲定模型·努力等级·MCP 服务器，工作结束前不要更改。中途变更越少，缓存命中率越高，回应越快。