Prompt 缓存

Prompt 缓存是指模型提供商可以跨回合复用未变的 prompt 前缀（通常是系统/开发者指令和其他稳定上下文），而非每次重新处理。首次匹配的请求写入缓存 token（cacheWrite），后续匹配的请求可以读回（cacheRead）。

好处：更低的 token 费用、更快的响应、更可预测的性能。没有缓存时，重复的 prompt 每轮都要付全额输入成本。

主要配置项

在模型参数上设置：cacheRetention: "short" / "none" / "long"。按 agent 覆盖也支持。

配置合并顺序：agents.defaults.models["provider/model"].params -> agents.list[].params（按 key 覆盖）。

遗留 cacheControlTtl 仍接受，映射为：5m -> short，1h -> long。新配置用 cacheRetention。

在缓存 TTL 窗口后修剪旧的工具结果上下文，避免空闲后重新缓存过大的历史。

心跳可以保持缓存窗口温暖，减少空闲后的重复缓存写入。

Anthropic（直接 API）：支持 cacheRetention。API key 认证 profile 时自动为 Anthropic 模型设置 "short"。
Amazon Bedrock：Anthropic Claude 模型支持显式 cacheRetention 透传。非 Anthropic Bedrock 模型强制为 "none"。
OpenRouter Anthropic 模型：OpenClaw 在系统/开发者 prompt 块上注入 Anthropic cache_control。
其他提供商：如不支持此缓存模式，cacheRetention 无效果。

主 agent 用长期基线，突发通知 agent 禁用缓存。

设置 cacheRetention: "short"，启用 contextPruning.mode: "cache-ttl"，只对受益于温暖缓存的 agent 保持心跳低于 TTL。

OpenClaw 提供专用的缓存跟踪诊断。通过 diagnostics.cacheTrace 配置或 OPENCLAW_CACHE_TRACE=1 环境变量启用。缓存跟踪事件是 JSONL 格式，包含分阶段快照。