对于长时间运行的 OpenClaw Agent 会话，Prompt Caching（提示缓存）是控制 Token 成本最直接的杠杆之一——本文基于官方文档，详解 cacheRetention、contextPruning 和心跳保温三个核心配置项如何配合使用。
提示缓存解决什么问题
提示缓存让模型提供商能复用未变化的提示前缀
（通常是系统/开发者指令和其他稳定的上下文），
而不是每一轮都重新处理一遍
首次匹配的请求会写入缓存 token（cacheWrite）
后续匹配的请求可以读取缓存（cacheRead）
价值很直接——更低的 token 成本、更快的响应速度，以及长时间运行会话中更可预期的性能表现。没有缓存的话，即便大部分输入内容没变，每一轮对话都要为完整提示付费。
核心配置一：cacheRetention
# 全局默认值，适用于所有模型
agents:
defaults:
params:
cacheRetention: "long" # none | short | long# 针对特定模型覆盖
agents:
defaults:
models:
"anthropic/claude-opus-4-6":
params:
cacheRetention: "short" # none | short | long# 针对特定 agent 覆盖
agents:
list:
- id: "alerts"
params:
cacheRetention: "none"配置合并优先级（从低到高）：
1. agents.defaults.params （全局默认，适用所有模型）
2. agents.defaults.models[provider/model].params （按模型覆盖）
3. agents.list[].params （匹配到具体agent id时覆盖）
旧版配置兼容——如果你的配置里还在用 cacheControlTtl，系统依然接受并自动映射：5m 映射为 short，1h 映射为 long。不过新配置建议直接用 cacheRetention。
核心配置二：contextPruning cache-ttl 模式
agents:
defaults:
contextPruning:
mode: "cache-ttl"
ttl: "1h"这个配置的作用是——在缓存 TTL 窗口过期后，修剪掉旧的工具调用结果上下文，避免会话空闲一段时间后重新触发的请求要为过大的历史记录重新写入缓存。这一点和 Session Pruning 机制紧密相关（详见下文）。
核心配置三：心跳保温（Heartbeat keep-warm）
agents:
defaults:
heartbeat:
every: "55m"心跳可以让缓存窗口保持"温热"状态，减少空闲间隔后的重复缓存写入开销。也支持在 agents.list[].heartbeat 层级做 per-agent 的心跳配置。
这三个配置项配合起来的逻辑很清晰——cacheRetention 决定缓存本身保留多久，contextPruning 在缓存过期时顺手把过大的旧上下文修剪掉，heartbeat 则通过定期"探活"防止缓存因为空闲太久而失效重来一遍。
实战建议
1. 高频交互、上下文相对稳定的 Agent（如客服类）：
优先用 cacheRetention: "long" + heartbeat 保温组合，
最大化缓存命中率
2. 低频、偶发触发的 Agent（如告警响应类）：
可以考虑 cacheRetention: "none"，
避免为极少复用的缓存支付写入开销
3. 会大量调用工具、产生长输出的场景：
务必搭配 contextPruning: cache-ttl，
否则每次缓存重写都要为累积的工具输出买单
4. 多模型/多agent混用场景：
善用配置合并优先级，只在真正需要差异化的层级
（模型级或agent级）做覆盖，减少配置维护复杂度
总结
Prompt Caching 调优本质上是在"缓存命中率"和"缓存写入开销"之间找平衡——cacheRetention 管保留策略，contextPruning 管上下文体积，heartbeat 管缓存保温，三者组合使用才能真正把长会话的 Token 成本压下来。
来源：Prompt Caching — OpenClaw 官方文档