Compaction: Summarizing Long Conversations for Model Limits

Every model has a context window, which is the maximum number of tokens it can handle. Once a conversation reaches that limit, OpenClaw compacts older messages into a summary, allowing the chat to proceed.

How it works

1. Earlier conversation turns get condensed into a single compact entry.
2. That summary is stored in the session transcript.
3. The most recent messages remain unchanged.

When OpenClaw selects a split point for compaction, it keeps assistant tool calls paired with their corresponding toolResult entries. If the split point falls inside a tool block, OpenClaw shifts the boundary so the pair stays together and the unsummarized tail is preserved.

The full conversation history remains on disk. Compaction only affects what the model sees on the next turn.

Note

New configurations default agents.defaults.compaction.mode to "safeguard" (tighter guardrails with summary quality checks). To opt out, set mode: "default" explicitly.

Auto-compaction

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

You will see:

• embedded run auto-compaction start / complete in standard Gateway logs.
• 🧹 Auto-compaction complete when verbose logging is active.
• /status displaying 🧹 Compactions: <count>.

Info

Before compacting, OpenClaw automatically tells the agent to save important notes to memory files. This prevents context from being lost.

Overflow error patterns OpenClaw recognizes

OpenClaw recognizes dozens of provider-specific overflow error strings (Anthropic, OpenAI, Bedrock, Gemini, Ollama, OpenRouter, and others). Common examples:

• request_too_large
• context length exceeded
• input exceeds the maximum number of tokens
• input token count exceeds the maximum number of input tokens (Bedrock)
• input is too long for the model
• ollama error: context length exceeded

Manual compaction

Type /compact in any chat to force a compaction. Add instructions to steer the summary:

/compact Focus on the API design decisions

When agents.defaults.compaction.keepRecentTokens is configured (default: 20,000), manual compaction respects that cut point and keeps the recent tail in the rebuilt context. Without an explicit keep budget, manual compaction acts as a hard checkpoint and continues from the new summary alone.

Configuration

Compaction settings live under agents.defaults.compaction in your openclaw.json. The most common options are listed below; for the complete reference, see Session management deep dive.

Using a different model

By default, compaction uses the agent's primary model. Set agents.defaults.compaction.model to hand off summarization to a more capable or specialized model. The override accepts a provider/model-id string or a bare alias configured under agents.defaults.models:

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

Bare configured aliases resolve to their canonical provider and model before compaction starts. If a bare value matches both an alias and a configured literal model ID, the literal model ID takes precedence. An unmatched bare value remains a model ID on the active provider.

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

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

When unset, compaction starts with the active session model. If summarization fails with a model-fallback-eligible provider error, OpenClaw retries that compaction attempt through the session's existing model fallback chain. The fallback choice is temporary and is not written back to session state. An explicit agents.defaults.compaction.model override remains exact and does not inherit the session fallback chain.

Identifier preservation

By default, compaction summarization preserves opaque identifiers (identifierPolicy: "strict"). Override with identifierPolicy: "off" to disable. Custom guidance belongs in a compaction provider's summarize() implementation.

Active transcript byte guard

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

Warning

The byte guard applies to the active SQLite transcript history. Legacy JSONL checkpoint artifacts are not the active compaction target.

Successor transcripts

When agents.defaults.compaction.truncateAfterCompaction 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 records checkpoint metadata that points branch/restore flows at that compacted successor. 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.

OpenClaw no longer writes separate .checkpoint.*.jsonl copies for new compactions. Existing legacy checkpoint files can still be used while referenced and are pruned by normal session cleanup.

Compaction notices

By default, compaction runs silently. Set notifyUser to show brief status messages when compaction starts and completes, and to surface a degraded notice when a pre-compaction memory flush is exhausted but the reply still continues:

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

Memory flush

Before compaction, OpenClaw can run a silent memory flush turn to store durable notes to disk. Set agents.defaults.compaction.memoryFlush.model when this housekeeping turn should use a local model instead of the active conversation model:

{
  "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 registerCompactionProvider() 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:

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

Setting a provider automatically forces mode: "safeguard". 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.

Note

If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization.

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.

Noticing outdated context after compaction? Let /compact Focus on <topic> steer the summarization, or turn on the memory flush to keep your notes intact.

Want to start over? Use /new to launch a new session without running compaction.

For more detailed options like token reservation, identifier retention, custom context engines, or OpenAI's server-side compaction, refer to the Session management deep dive.

Related

• Session: handling the session lifecycle and its management.
• Session pruning: removing results from tools.
• Context: assembling context for each agent turn.
• Hooks: lifecycle hooks during compaction (before_compaction, after_compaction).