OpenClaw caching policy: lower token cost without trusting stale context

Published May 26, 2026 · OpenClawBlog Team

An OpenClaw workflow can send the same instructions, tool definitions, workspace notes, and growing transcript on every turn. Reprocessing that prefix costs input tokens and adds time before the model can answer. Prompt caching can reuse the provider's processed prefix. The difficult part is deciding what belongs in that reusable prefix. A cache can make a request cheaper without making its facts current.

This guide treats caching as a workflow policy. Use it for material that is stable and repeated. Keep live facts, scoped approvals, and action evidence fresh. That conclusion is an editorial inference from the documented cache and context behavior; OpenClaw does not validate the truth of every cached instruction.

Scope note. The commands and settings below are documentation-derived. They were not run against a live OpenClaw installation for this article.

The short answer

Cache the parts of an agent that stay the same: system instructions, tool definitions, stable workspace guidance, versioned reference material, and repeated conversation history. OpenClaw's prompt-caching reference describes a stable system prefix above a volatile per-turn suffix. Anthropic and OpenAI both describe prompt caching as reuse of an identical prompt prefix, not as a semantic freshness check.

Start with cacheRetention: 'short' on a workflow that runs often enough to reuse its prefix. Pair it with contextPruning.mode: 'cache-ttl' when long tool-heavy sessions would otherwise re-cache oversized tool output after an idle period. Use a longer retention window only when the workflow actually returns after the short provider window and the additional write cost is justified.

Keep current status, external data, approval scope, and side-effect decisions outside the trusted stable baseline. Before an agent posts, merges, deletes, sends, or changes anything, fetch the current state again and check that the approval still covers that exact action. Caching is a cost and latency mechanism. It is not an authorization mechanism.

Separate caching, pruning, and compaction

The session-pruning documentation says pruning reduces context bloat without rewriting normal conversation text. The compaction reference describes a different operation: older turns become a saved summary. The context documentation also separates what the model sees from what remains inspectable on disk.

Map the workflow before changing a setting

Make the cache boundary a property of the job, not a property of the model's marketing name. Write down four groups of material.

1. Stable instructions. Include the task definition, output format, tool schemas, safety rules, and workspace guidance that should remain unchanged during a run.
2. Versioned reference material. Include documents or repository notes only when they carry a revision, commit, date, or other identifier that can change the prompt when the source changes.
3. Volatile facts. Treat current issue contents, branch state, CI results, inventory, prices, account status, time-sensitive policy, and external API responses as fresh inputs.
4. Action authority. Keep the resource, operation, actor, and expiry of an approval visible in the current turn. An old sentence that says approved is not enough to authorize a new side effect.

OpenClaw tries to keep stable workspace context above its cache boundary and per-turn runtime facts below it. That helps routine metadata changes avoid rebuilding the stable prefix. It does not make a stale document or an old API response current. If the source itself changes outside the prompt, add a new revision marker or retrieve the source again.

Keep the model, provider route, and reasoning or thinking level stable when cache continuity matters. OpenClaw documents that changing the model always creates a different cache lineage, while changing thinking or reasoning settings can also invalidate reuse. A planned model change should start a new measurement period rather than being compared with an old cache-hit sample.

Good places to use caching

A repeated agent baseline

A support drafter, code-review assistant, or documentation agent often repeats the same instructions and tool catalog. Those are sensible cache candidates. OpenClaw's cache-stability rules order stable workspace files before volatile runtime metadata, and provider documentation recommends placing reusable content at the beginning of the prompt.

Keep the tools themselves stable. A changed schema, permission set, or tool ordering may create a new prefix. That is usually the right result: a capability change should not silently reuse a prefix built for a different tool surface.

Long multi-turn work

Long conversations and large reference documents are useful caching targets when the user returns within the provider's retention window. Anthropic's documentation lists long instructions, uploaded documents, repetitive tasks, and multi-turn conversations as suitable cases. OpenAI describes the same general benefit for repeated prefixes and reports reduced input processing before the response starts.

This does not mean every growing transcript should remain intact forever. If old tool output is no longer needed, cache-TTL pruning can keep the next request smaller. Preserve a durable pointer to the source or artifact rather than relying on a large historical result that the model may later see only as a trimmed or cleared placeholder.

Read-only tool loops

Repeated searches, file reads, and diagnostic results can benefit from reuse when they are deterministic enough and the source has not changed. This is a good place to propose a test: run the same read-only task with caching enabled and disabled, then compare cache counters, time to first token, answer quality, and the evidence still visible to a reviewer.

Do not generalize that result to write operations. A cached read of yesterday's deployment status is useful only as historical context. It is not a current check that today's deployment is safe.

Versioned knowledge bases

Reference material can sit in a stable prefix when the workflow includes a revision identifier. When the knowledge base changes, change that identifier or rebuild the relevant section. This deliberately creates a cache miss for the changed material while allowing an earlier stable layer, such as tool definitions, to remain reusable where the provider supports separate cache breakpoints.

A conservative OpenClaw baseline

The official prompt-caching guide gives this cost-first pattern:

agents:
  defaults:
    params:
      cacheRetention: 'short'
    contextPruning:
      mode: 'cache-ttl'
      ttl: '5m'

The setting can be global, model-specific, or agent-specific. A practical policy is to keep the short baseline on a frequently used main agent and override bursty notifier agents with cacheRetention: 'none'. The exact result remains provider-specific.

For direct Anthropic routes, OpenClaw maps the short setting to the provider's default five-minute ephemeral cache and an explicit long setting to a one-hour request on eligible endpoints. Anthropic's current documentation says five-minute writes cost more than ordinary input, one-hour writes cost more again, and cache hits cost a fraction of the base input rate. If requests arrive regularly inside five minutes, the shorter cache can refresh without the extra one-hour write price.

OpenAI follows a different model. Supported models cache prompts automatically, and OpenClaw's cacheRetention: 'none' suppresses its cache key and lifetime fields but does not disable OpenAI's automatic prompt caching. Do not describe none as a universal provider opt-out. Check the route's own controls and pricing.

A heartbeat can keep a cache warm, but it also adds another model turn to the workflow. Use it only when the saved misses matter more than the work required to keep the cache alive. Include those turns in the same cost and correctness measurement as user-triggered requests.

Where stale context turns into a wrong action

Exact-prefix caching is not normally a mechanism that returns a different version of identical bytes. If the prompt matches, the provider reuses processed model state for that prompt. The risk is that the identical bytes contain an old fact, an old approval, or an old tool result and are therefore processed again without a fresh check. The cache's TTL controls reuse; it does not understand business freshness.

Old approvals

Suppose a user approved posting one message to one channel. A later turn sees that approval in retained history after the draft, channel, or content has changed. The agent may treat the old statement as authority for the new action. Keep approval scope in the current request and require a new confirmation when the target or effect changes. Compaction or caching should never widen an approval boundary.

Old operational facts

A cached issue, branch, deployment, account balance, or inventory result can be accurate at the time it was retrieved and wrong when the agent acts. Before a side effect, re-read the source and include its current identifier or timestamp. If the source cannot be checked, downgrade the operation to a draft or ask a person to review it.

Pruned evidence

Session pruning can replace large old tool results with a shortened view or a placeholder after its thresholds are reached. That reduces prompt size, but it may remove the line that explains why a command failed or why an exception was granted. Keep a compact artifact ID, log location, or source pointer in the working context. If the decision depends on the missing detail, retrieve it again instead of guessing.

Mixed users or workspaces

Do not put tenant-specific instructions or private records in a shared stable prefix. OpenAI documents separate cache keys as a way to separate accounting and reduce cache-hit probing across users. In OpenClaw, use separate agents, keys, or provider routes when the data boundary requires it. A cache hit is not evidence that two users should share context.

Measure the policy instead of trusting the setting

The OpenClaw token-use documentation lists /usage tokens for turn-level token and cache details, /status for session usage, and /usage cost for local cost summaries. A useful documentation-derived test is:

1. Run one read-only task with the current policy and record input tokens, output tokens, cache reads, cache writes, latency, and what evidence a reviewer can see.
2. Repeat the same task inside the expected cache window. A hit should be visible in provider usage or OpenClaw's normalized counters, not inferred from a fast-looking reply.
3. Repeat after the window expires, then repeat with a changed knowledge-base revision or tool schema. These runs show whether the workflow is paying to rebuild the right part of the prefix.
4. Compare correctness and review effort with the token and latency results. A lower bill is not a success if the operator must reconstruct missing evidence on every action.

For a short diagnostic, OpenClaw documents diagnostics.cacheTrace. It writes prompt-cache observations to a JSONL file and includes messages, prompt text, and the system prompt by default. Use sanitized disposable data or disable those payload fields for the test. Cache traces are themselves sensitive operational artifacts.

Failure paths and limits

• No cache reads. Check whether the model, provider route, reasoning setting, prefix length, cache key, and retention window are unchanged. A miss is not proof that caching is broken.
• High cache writes. Look for timestamps, changing workspace content, dynamic instructions, or a breakpoint placed after volatile material. OpenClaw recommends checking the stable-prefix boundary and provider support.
• Long retention costs more than it saves. Use the long window only when requests really fall outside the short window but return often enough to reuse the prefix. Provider prices differ.
• cacheRetention: 'none' appears ineffective. On direct OpenAI routes, automatic prompt caching can still occur. Verify the provider's own behavior before claiming a complete opt-out.
• The chat looks clean after compaction. A clean-looking current context is not deletion. OpenClaw preserves the transcript locally, and a compaction summary may not contain the exact evidence needed for an action. Start a fresh read-only check or a new approval rather than treating the summary as authority.

A worked policy for daily issue triage

Consider an agent that classifies repository issues and may later prepare a change. Its stable prefix can contain the triage labels, output schema, tool definitions, repository naming rules, and a versioned runbook. Its volatile context should contain the current issue payload, the latest branch and CI state, current ownership, and the review request for this issue.

Set a short cache baseline and enable cache-TTL pruning if the agent spends long periods reading logs. Let the agent use cached material to classify and draft. Before it opens a pull request or changes a tracker, it must retrieve the current issue, branch, and permission state again. If the only approval is an old transcript sentence or a compaction summary, ask for approval again.

This policy still benefits from repeated instructions and tool schemas. It refuses to make the cache responsible for facts that change. That is the useful boundary: reusable explanation may be cached, while authority and current state must be re-established.

Decision rule

Cache what is stable, repeated, and easy to version. Prune tool output only when the lost detail can be recovered. Compact conversation when a summary is acceptable, not when an exact approval or audit trail is required. Measure cacheRead, cacheWrite, cost, latency, and review quality together.

If a workflow cannot say which facts are fresh and which approvals still apply, it is not ready for an aggressive cache policy. A cheaper prompt is useful only when the action built from it remains explainable.

Sources

Sources were accessed on 2026-09-13. The official documentation pages used here do not list a publication date.

1. Prompt caching - OpenClaw
2. Session pruning - OpenClaw
3. Compaction behavior and settings - OpenClaw
4. Context - OpenClaw
5. Token use and costs - OpenClaw
6. Prompt caching - Claude Platform Docs
7. Prompt caching - OpenAI API