Optimize OpenClaw Prompt Caching for Lower Token Costs

Sending the same massive system prompt and conversation history every time you hit an LLM API is frustrating. You know the model has seen most of this before, yet you are still paying full price and waiting for the provider to re-process the same data. It makes long-running sessions feel sluggish and expensive.

Prompt caching means the model provider can reuse unchanged prompt prefixes—usually your system instructions and stable context—across turns instead of re-processing them every time. The first matching request writes cache tokens (cacheWrite), and later matching requests can read them back (cacheRead).

This helps you get lower token costs and faster responses. It also makes performance more predictable for long sessions. Without caching, repeated prompts pay the full prompt cost on every turn even when most input did not change.

This page covers all cache-related knobs that affect prompt reuse and token cost.

For Anthropic pricing details, see: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Primary knobs

cacheRetention (global default, model, and per-agent)

You can set cache retention as a global default for all your models:

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

If you need to override this for a specific model, use this format:

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

You can also override settings for a specific agent:

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

The configuration follows this merge order:

1. agents.defaults.params (global default — applies to all models)
2. agents.defaults.models["provider/model"].params (per-model override)
3. agents.list[].params (matching agent id; overrides by key)

Legacy cacheControlTtl

Legacy values are still accepted and mapped to the new settings:

• 5m -> short
• 1h -> long

You should use cacheRetention for any new configurations.

contextPruning.mode: "cache-ttl"

This setting prunes old tool-result context after cache TTL windows. This ensures that post-idle requests do not re-cache history that has grown too large.

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

Check out Session Pruning for the full behavior.

Heartbeat keep-warm

A heartbeat can keep your cache windows warm. This reduces repeated cache writes after idle gaps.

agents:
  defaults:
    heartbeat:
      every: "55m"

Per-agent heartbeat is supported at agents.list[].heartbeat.

Provider behavior

Anthropic (direct API)

• cacheRetention is supported.
• With Anthropic API-key auth profiles, OpenClaw seeds cacheRetention: "short" for Anthropic model refs when unset.

Amazon Bedrock

• Anthropic Claude model refs (amazon-bedrock/*anthropic.claude*) support explicit cacheRetention pass-through.
• Non-Anthropic Bedrock models are forced to cacheRetention: "none" at runtime.

OpenRouter Anthropic models

For openrouter/anthropic/* model refs, OpenClaw injects Anthropic cache_control on system/developer prompt blocks to improve prompt-cache reuse.

Other providers

If the provider does not support this cache mode, cacheRetention has no effect.

Tuning patterns

Mixed traffic (recommended default)

You can keep a long-lived baseline on your main agent while disabling caching on bursty notifier agents:

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

Cost-first baseline

• Set baseline cacheRetention: "short".
• Enable contextPruning.mode: "cache-ttl".
• Keep heartbeat below your TTL only for agents that benefit from warm caches.

Cache diagnostics

OpenClaw exposes dedicated cache-trace diagnostics for embedded agent runs.

diagnostics.cacheTrace config

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default true

Defaults:

• filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
• includeMessages: true
• includePrompt: true
• includeSystem: true

Env toggles (one-off debugging)

• OPENCLAW_CACHE_TRACE=1 enables cache tracing.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl overrides output path.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 toggles full message payload capture.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 toggles prompt text capture.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 toggles system prompt capture.

What to inspect

Cache trace events are JSONL and include staged snapshots like session:loaded, prompt:before, stream:context, and session:after. Per-turn cache token impact is visible in normal usage surfaces via cacheRead and cacheWrite. You can see these in /usage full and session usage summaries.

Quick troubleshooting

• High cacheWrite on most turns: check for volatile system-prompt inputs and verify your model/provider supports your cache settings.
• No effect from cacheRetention: confirm your model key matches agents.defaults.models["provider/model"].
• Bedrock Nova/Mistral requests with cache settings: these are expected to be forced to none at runtime.

下一步

• Anthropic
• Token Use and Costs
• Session Pruning
• Gateway Configuration Reference

AI Setup Assistant