Prompt caching means the model provider can reuse unchanged prompt prefixes (usually system\/developer instructions and other stable context) across turns instead of re-processing them every time. The first matching request writes cache tokens ( Why this matters: lower token cost, faster responses, and more predictable performance for long-running sessions. Without caching, repeated prompts pay the full prompt cost on every turn even when most input did not change.<\/p>\n This page covers all cache-related knobs that affect prompt reuse and token cost.<\/p>\n For Anthropic pricing details, see: Set cache retention on model params:<\/p>\n “`yaml theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Config merge order:<\/p>\n Legacy values are still accepted and mapped:<\/p>\n Prefer Prunes old tool-result context after cache TTL windows so post-idle requests do not re-cache oversized history.<\/p>\n “`yaml theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Per-agent heartbeat is supported at For If the provider does not support this cache mode, Keep a long-lived baseline on your main agent, disable caching on bursty notifier agents:<\/p>\n “`yaml theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Defaults:<\/p>\n Related docs:<\/p>\n Prompt Caching Prompt caching Prompt caching means the […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-634","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/634","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=634"}],"version-history":[{"count":2,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/634\/revisions"}],"predecessor-version":[{"id":711,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/634\/revisions\/711"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=634"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=634"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=634"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}cacheWrite<\/code>), and later matching requests can read them back (cacheRead<\/code>).<\/p>\n
\nhttps:\/\/docs.anthropic.com\/docs\/build-with-claude\/prompt-caching<\/a><\/p>\nPrimary knobs<\/h2>\n
cacheRetention<\/code> (model and per-agent)<\/h3>\n
\nagents:
\n defaults:
\n models:
\n “anthropic\/claude-opus-4-6”:
\n params:
\n cacheRetention: “short” # none | short | long<\/p>\n\nPer-agent override:\n\n```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}\nagents:\n list:\n - id: "alerts"\n params:\n cacheRetention: "none"\n<\/code><\/pre>\n\n
agents.defaults.models[\"provider\/model\"].params<\/code><\/li>\nagents.list[].params<\/code> (matching agent id; overrides by key)<\/li>\n<\/ol>\nLegacy
cacheControlTtl<\/code><\/h3>\n\n
5m<\/code> -> short<\/code><\/li>\n1h<\/code> -> long<\/code><\/li>\n<\/ul>\ncacheRetention<\/code> for new config.<\/p>\ncontextPruning.mode: \"cache-ttl\"<\/code><\/h3>\n
\nagents:
\n defaults:
\n contextPruning:
\n mode: “cache-ttl”
\n ttl: “1h”<\/p>\n\nSee [Session Pruning](\/concepts\/session-pruning) for full behavior.\n\n### Heartbeat keep-warm\n\nHeartbeat can keep cache windows warm and reduce repeated cache writes after idle gaps.\n\n```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}\nagents:\n defaults:\n heartbeat:\n every: "55m"\n<\/code><\/pre>\nagents.list[].heartbeat<\/code>.<\/p>\nProvider behavior<\/h2>\n
Anthropic (direct API)<\/h3>\n
\n
cacheRetention<\/code> is supported.<\/li>\ncacheRetention: \"short\"<\/code> for Anthropic model refs when unset.<\/li>\n<\/ul>\nAmazon Bedrock<\/h3>\n
\n
amazon-bedrock\/*anthropic.claude*<\/code>) support explicit cacheRetention<\/code> pass-through.<\/li>\ncacheRetention: \"none\"<\/code> at runtime.<\/li>\n<\/ul>\nOpenRouter Anthropic models<\/h3>\n
openrouter\/anthropic\/*<\/code> model refs, OpenClaw injects Anthropic cache_control<\/code> on system\/developer prompt blocks to improve prompt-cache reuse.<\/p>\nOther providers<\/h3>\n
cacheRetention<\/code> has no effect.<\/p>\nTuning patterns<\/h2>\n
Mixed traffic (recommended default)<\/h3>\n
\nagents:
\n defaults:
\n model:
\n primary: “anthropic\/claude-opus-4-6”
\n models:
\n “anthropic\/claude-opus-4-6”:
\n params:
\n cacheRetention: “long”
\n list:
\n – id: “research”
\n default: true
\n heartbeat:
\n every: “55m”
\n – id: “alerts”
\n params:
\n cacheRetention: “none”<\/p>\n\n### Cost-first baseline\n\n* Set baseline `cacheRetention: "short"`.\n* Enable `contextPruning.mode: "cache-ttl"`.\n* Keep heartbeat below your TTL only for agents that benefit from warm caches.\n\n## Cache diagnostics\n\nOpenClaw exposes dedicated cache-trace diagnostics for embedded agent runs.\n\n### `diagnostics.cacheTrace` config\n\n```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}\ndiagnostics:\n cacheTrace:\n enabled: true\n filePath: "~\/.openclaw\/logs\/cache-trace.jsonl" # optional\n includeMessages: false # default true\n includePrompt: false # default true\n includeSystem: false # default true\n<\/code><\/pre>\n\n
filePath<\/code>: $OPENCLAW_STATE_DIR\/logs\/cache-trace.jsonl<\/code><\/li>\nincludeMessages<\/code>: true<\/code><\/li>\nincludePrompt<\/code>: true<\/code><\/li>\nincludeSystem<\/code>: true<\/code><\/li>\n<\/ul>\nEnv toggles (one-off debugging)<\/h3>\n
\n
OPENCLAW_CACHE_TRACE=1<\/code> enables cache tracing.<\/li>\nOPENCLAW_CACHE_TRACE_FILE=\/path\/to\/cache-trace.jsonl<\/code> overrides output path.<\/li>\nOPENCLAW_CACHE_TRACE_MESSAGES=0|1<\/code> toggles full message payload capture.<\/li>\nOPENCLAW_CACHE_TRACE_PROMPT=0|1<\/code> toggles prompt text capture.<\/li>\nOPENCLAW_CACHE_TRACE_SYSTEM=0|1<\/code> toggles system prompt capture.<\/li>\n<\/ul>\nWhat to inspect<\/h3>\n
\n
session:loaded<\/code>, prompt:before<\/code>, stream:context<\/code>, and session:after<\/code>.<\/li>\ncacheRead<\/code> and cacheWrite<\/code> (for example \/usage full<\/code> and session usage summaries).<\/li>\n<\/ul>\nQuick troubleshooting<\/h2>\n
\n
cacheWrite<\/code> on most turns: check for volatile system-prompt inputs and verify model\/provider supports your cache settings.<\/li>\ncacheRetention<\/code>: confirm model key matches agents.defaults.models[\"provider\/model\"]<\/code>.<\/li>\nnone<\/code>.<\/li>\n<\/ul>\n\n