Prompt caching 允许模型 provider 在多轮对话中复用未变化的提示词前缀，避免每次都重新处理。OpenClaw 将 provider 的用量归一化为 cacheRead 和 cacheWrite。
核心价值：降低 token 费用、加快响应速度、提升长会话性能。
主要配置项
cacheRetention
agents:
defaults:
params:
cacheRetention: "long" # none | short | long配置合并顺序：agents.defaults.params → agents.defaults.models["provider/model"].params → agents.list[].params
contextPruning.mode: "cache-ttl"
在缓存 TTL 过期后裁剪旧工具结果，避免空闲后重新缓存超大历史：
agents:
defaults:
contextPruning:
mode: "cache-ttl"
ttl: "1h"Heartbeat 保温
agents:
defaults:
heartbeat:
every: "55m" # 低于 TTL 以保持缓存热态各 Provider 行为
| Provider | cacheRetention 支持 | 说明 |
|---|---|---|
| Anthropic 直连 | 支持 | short=5分钟，long=1小时 |
| OpenAI 直连 | 自动（无需标记） | 仅 cacheRead，无 cacheWrite |
| Anthropic Vertex | 支持 | 同直连 |
| Amazon Bedrock | 仅 Anthropic Claude 模型 | 非 Anthropic 模型强制 none |
| Google Gemini | 自动管理 cachedContents | 与 Anthropic/OpenAI 机制不同 |
系统提示词缓存边界
OpenClaw 将系统提示词分为稳定前缀（工具定义、技能元数据、工作区文件）和易变后缀（HEARTBEAT.md、运行时时间戳），确保稳定部分不因每轮变化而失效。
缓存诊断
diagnostics:
cacheTrace:
enabled: true
filePath: "~/.openclaw/logs/cache-trace.jsonl"环境变量快速开启：OPENCLAW_CACHE_TRACE=1
常见问题排查
- 高
cacheWrite：检查系统提示词中是否有每次变化的内容 - 低 OpenAI
cacheRead：确认稳定前缀在最前面，且重复前缀至少 1024 tokens cacheRetention无效：确认 model key 与agents.defaults.models["provider/model"]匹配