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 idle-session unloading through the transcript marker. The last active attempt releases its prompt projections after cleanup; the next attempt restores them from the active transcript. Ordinary tool-result trims and the already-sent boundary are also saved before model requests when the projection changes, even with TTL pruning off. Changed projections record only added, updated, and removed entries, with a full checkpoint after at most 31 deltas or before accumulated delta payload reaches 64 KiB. Unchanged projections add no new projection marker. Restart restores the latest checkpoint and subsequent deltas on the active branch, stopping at a reset. Older full-snapshot markers remain readable as checkpoints; existing transcript rows need no migration and are not deleted. Runtimes predating delta support cannot replay changes after the last full checkpoint, so preserve a backup when rolling back across this format change. Bounded history reads acquire any omitted checkpoint as projection metadata without expanding the model's retained history. 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.

Image history

Image blocks and attachment references stay in retained conversation history as new turns arrive. Replacing an already-sent image with a cleanup marker changes the prompt prefix and discards the provider's cached context. Compaction and explicit history-window limits own removal of old image-bearing turns; there is no separate age-based image cleanup. The raw transcript keeps the original attachments for history viewers.

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.

For a custom OpenAI-compatible provider, set the model's compat.supportsPromptCacheKey to true as well. This opts configured models using openai-responses, openai-completions, or openai-chatgpt-responses into cache-TTL pruning even when their provider ID is not openai. Provider plugins with their own cache-TTL policy still control eligibility.

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