Session pruning

Session pruning trims old tool results from the model's context. It reduces context bloat from accumulated tool outputs (exec results, file reads, search results) without rewriting normal conversation text.

Why it matters

Long sessions accumulate tool output that inflates the context window. This increases cost and can force compaction sooner than necessary.

Pruning is especially valuable for Anthropic prompt caching. It reduces the tool content that must be cached and keeps later requests on the reduced prefix. Direct Anthropic API-key requests use server-side clearing; other eligible routes prune locally after the cache TTL expires.

How it works

Set agents.defaults.contextPruning.mode to "cache-ttl" to enable pruning. The request's provider, endpoint, and authentication determine where it runs.

Direct Anthropic API-key requests

For provider anthropic with the anthropic-messages API, API-key authentication, and the default endpoint or api.anthropic.com, OpenClaw delegates pruning to Anthropic's server-side tool-result clearing. OpenClaw opens no new client-side pruning rounds, and the server clears old results before the model sees them. Projections made earlier in the same session (for example on a proxy route, or restored from the transcript marker) still replay unchanged. Full local history is retained. ttl does not gate this path.

OpenClaw derives the request parameters without adding config options:

The request includes the clear_tool_uses_20250919 edit and context-management-2025-06-27 beta header. If server-side compaction is enabled, the clearing edit comes before the compaction edit. Explicit caller-provided context_management remains unchanged. Client-side soft-trim and hardClear settings do not change the server's clearing policy.

Clearing invalidates the prompt cache from the first cleared result; clear_at_least prevents a clearing event that would remove too few tokens to justify the new cache write. When clearing occurs, OpenClaw logs this info line:

[anthropic] server-side context edit: cleared N tool results (M input tokens)

Client-side pruning

Amazon Bedrock, Google, Microsoft Foundry, OAuth, proxies, Vertex, and other cache-TTL-eligible routes keep client-side pruning. New pruning rounds are gated on both a time check and a context-size check:

1. Wait for the cache TTL to expire. When you turn on cache-ttl mode and set no ttl, the TTL is 5 minutes. The bundled Anthropic plugin seeds 1h instead, see Smart defaults. Each successful model request refreshes the in-memory clock to its request start time, including tool-loop requests before turn settlement. Failed requests do not refresh it. Before the TTL elapses, no new pruning occurs. Existing projections still replay unchanged.
2. Once the TTL has elapsed, estimate total context size against the model's context window. Below roughly 30% usage, pruning is skipped and the TTL clock keeps running.
3. Soft-trim oversized tool results: results over 4,000 characters keep their first and last 1,500 characters with ... in between.
4. If context usage is still at or above roughly 50% and at least 50,000 characters of prunable tool content remain, hard-clear those results. A hard clear replaces the content of each result with a placeholder. The default placeholder is [Old tool result content cleared], and agents.defaults.contextPruning.hardClear.placeholder changes it. Set hardClear.enabled: false to skip this step.
5. Record each changed result as a session projection and reset the pruning TTL clock. Follow-up requests reuse the same projected bytes, including tool-loop continuations and later turns.

The TTL gates new pruning rounds, not replay of previous projections. Projections survive Gateway restarts and eviction from the in-memory session cache through the transcript marker. Ordinary tool-result trims and the already-sent boundary are also saved before model requests when the projection changes, even with TTL pruning off. Unchanged projections add no new marker; restart restores the latest marker on the active branch. Old results retain their projected bytes through tool loops and restarts. Original text and non-text content stay in the transcript. Compaction drops projections for results no longer in the active history; /new and session reset start without the old session's projections. Cache-TTL marker timestamps still support the existing cache and heartbeat bookkeeping.

Two safety rules apply regardless of thresholds: the last three assistant turns are never pruned, and nothing before the session's first user message is ever pruned (protects bootstrap reads like SOUL.md/USER.md). The size thresholds and trim windows above are built-in behavior, not config keys; the configurable surface is agents.defaults.contextPruning (mode, ttl, tools, hardClear).

Only toolResult messages are eligible; normal conversation text is left alone. Use agents.defaults.contextPruning.tools.{allow,deny} to scope which tool names are prunable on either path.

Legacy image cleanup

OpenClaw also builds a separate idempotent replay view for sessions that persist raw image blocks or prompt-hydration media markers in history.

• It preserves the 3 most recent completed turns byte-for-byte so prompt cache prefixes for recent follow-ups stay stable. This count includes all completed turns, not just image-bearing ones, so text-only turns consume the window too.
• The window advances only when a new user turn begins, never within a tool loop.
• In the replay view, older already-processed image blocks from user or toolResult history are replaced with [image data removed - already processed by model].
• Older textual media references such as [media attached: ...], [Image: source: ...], and media://inbound/... are replaced with [media reference removed - already processed by model]. Current-turn attachment markers stay intact so vision models can still hydrate fresh images.
• The raw session transcript is not rewritten, so history viewers can still render the original message entries and their images.
• This is separate from normal cache-TTL pruning above. It exists to stop repeated image payloads or stale media refs from busting prompt caches on later turns.

Smart defaults

The bundled Anthropic plugin auto-configures pruning and heartbeat cadence the first time it resolves an Anthropic (or Claude CLI) auth profile, but only for fields you have not already set explicitly:

If you set agents.defaults.contextPruning.mode or agents.defaults.heartbeat.every yourself, OpenClaw does not override them. This auto-default only fires for Anthropic-family auth; other providers get pruning off unless you configure it.

The seeded ttl applies to client-side pruning. Direct Anthropic API-key requests use the token thresholds above while retaining the same heartbeat defaults.

Enable or disable

Pruning is off by default for non-Anthropic providers. To enable:

{  agents: {    defaults: {      contextPruning: { mode: "cache-ttl", ttl: "5m" },    },  },}

To stop new pruning, set mode: "off". Existing client-side projections keep replaying, including after a Gateway restart, until compaction removes their results or the session is reset.

Pruning vs compaction

They complement each other -- pruning keeps tool output lean between compaction cycles.

Further reading

• Compaction: summarization-based context reduction
• agents.defaults.contextPruning: all pruning config knobs (contextPruning.*)

Related

• Session management
• Session tools
• Context engine
• Transcript hygiene - in-memory, provider-specific transcript sanitization applied before a run