Compaction

Every model has a context window: the maximum number of tokens it can process. When a conversation approaches that limit, OpenClaw compacts older messages into a summary so the chat can continue.

How it works

1. Older conversation turns are summarized into a compact entry.
2. The summary is saved in the session transcript.
3. Recent messages are kept intact.

When OpenClaw splits history into compaction chunks, it keeps assistant tool calls paired with their matching

entries. If a split point lands inside a tool block, OpenClaw moves the boundary so the pair stays together and the current unsummarized tail is preserved.

The full conversation history stays on disk. Compaction only changes what the model sees on the next turn.

Auto-compaction

Auto-compaction is on by default. It runs when the session nears the context limit, or when the model returns a context-overflow error (in which case OpenClaw compacts and retries).

You will see:

• text

  Copy

  🧹 Auto-compaction complete
  in verbose mode.
• text

  Copy

  /status
  showing
  text

  Copy

  🧹 Compactions: <count>
  .

Recognized overflow signatures

Manual compaction

Type

in any chat to force a compaction. Add instructions to guide the summary:

text
Copy
/compact Focus on the API design decisions

When

is set, manual compaction honors that Pi cut-point and keeps the recent tail in rebuilt context. Without an explicit keep budget, manual compaction behaves as a hard checkpoint and continues from the new summary alone.

Configuration

Configure compaction under

in your . The most common knobs are listed below; for the full reference, see Session management deep dive.

Using a different model

By default, compaction uses the agent's primary model. Set

to delegate summarization to a more capable or specialized model. The override accepts any string:

json
Copy
{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

This works with local models too, for example a second Ollama model dedicated to summarization:

json
Copy
{
  "agents": {
    "defaults": {
      "compaction": {
        "model": "ollama/llama3.1:8b"
      }
    }
  }
}

When unset, compaction uses the agent's primary model.

Identifier preservation

Compaction summarization preserves opaque identifiers by default (

). Override with to disable, or plus for custom guidance.

Active transcript byte guard

When

is set, OpenClaw triggers normal local compaction before a run if the active JSONL reaches that size. This is useful for long-running sessions where provider-side context management may keep model context healthy while the local transcript keeps growing. It does not split raw JSONL bytes; it asks the normal compaction pipeline to create a semantic summary.

Successor transcripts

When

is enabled, OpenClaw does not rewrite the existing transcript in place. It creates a new active successor transcript from the compaction summary, preserved state, and unsummarized tail, then keeps the previous JSONL as the archived checkpoint source. Successor transcripts also drop exact duplicate long user turns that arrive inside a short retry window, so channel retry storms are not carried into the next active transcript after compaction.

Pre-compaction checkpoints are retained only while they stay below OpenClaw's checkpoint size cap; oversized active transcripts still compact, but OpenClaw skips the large debug snapshot instead of doubling disk usage.

Compaction notices

By default, compaction runs silently. Set

to show brief status messages when compaction starts and completes:

json5
Copy
{
  agents: {
    defaults: {
      compaction: {
        notifyUser: true,
      },
    },
  },
}

Memory flush

Before compaction, OpenClaw can run a silent memory flush turn to store durable notes to disk. Set

when this housekeeping turn should use a local model instead of the active conversation model:

json
Copy
{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

The memory-flush model override is exact and does not inherit the active session fallback chain. See Memory for details and config.

Pluggable compaction providers

Plugins can register a custom compaction provider via

on the plugin API. When a provider is registered and configured, OpenClaw delegates summarization to it instead of the built-in LLM pipeline.

To use a registered provider, set its id in your config:

json
Copy
{
  "agents": {
    "defaults": {
      "compaction": {
        "provider": "my-provider"
      }
    }
  }
}

Setting a

automatically forces . Providers receive the same compaction instructions and identifier-preservation policy as the built-in path, and OpenClaw still preserves recent-turn and split-turn suffix context after provider output.

Compaction vs pruning

Session pruning is a lighter-weight complement that trims tool output without summarizing.

Troubleshooting

Compacting too often? The model's context window may be small, or tool outputs may be large. Try enabling session pruning.

Context feels stale after compaction? Use

to guide the summary, or enable the memory flush so notes survive.

Need a clean slate?

starts a fresh session without compacting.

For advanced configuration (reserve tokens, identifier preservation, custom context engines, OpenAI server-side compaction), see the Session management deep dive.

Related

• Session: session management and lifecycle.
• Session pruning: trimming tool results.
• Context: how context is built for agent turns.
• Hooks: compaction lifecycle hooks (
  text

  Copy

  before_compaction
  ,
  text

  Copy

  after_compaction
  ).