Skip to main content

Context Window & Compaction

Every model has a context window (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, OpenClaw compacts older history to stay within limits.

What compaction is​

Compaction summarizes older conversation into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:

  • The compaction summary
  • Recent messages after the compaction point

Compaction persists in the session history.

Configuration​

ClawCentral

In ClawCentral, compaction settings are configured via Admin UI → Settings → Agent. The openclaw.json config blocks below apply to self-hosted OpenClaw deployments.

Use the agents.defaults.compaction setting to configure compaction behavior (mode, target tokens, etc.). Compaction summarization preserves opaque identifiers by default (identifierPolicy: "strict"). You can override this with identifierPolicy: "off" or provide custom text with identifierPolicy: "custom" and identifierInstructions.

You can optionally specify a different model for compaction summarization via agents.defaults.compaction.model. This is useful when your primary model is a local or small model and you want compaction summaries produced by a more capable model. The override accepts any provider/model-id string:

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

This also works with local models, for example a second Ollama model dedicated to summarization or a fine-tuned compaction specialist:

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

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

Auto-compaction (default on)​

When a session nears or exceeds the model’s context window, OpenClaw triggers auto-compaction and may retry the original request using the compacted context.

You’ll see:

  • 🧹 Auto-compaction complete in verbose mode
  • /status showing 🧹 Compactions: <count>

Before compaction, OpenClaw can run a silent memory flush turn to store durable notes to disk. See Memory for details and config.

Manual compaction​

Use /compact (optionally with instructions) to force a compaction pass:

/compact Focus on decisions and open questions

Context window source​

Context window is model-specific. OpenClaw uses the model definition from the configured provider catalog to determine limits.

Compaction vs pruning​

  • Compaction: summarises and persists in session history.
  • Session pruning: trims old tool results only, in-memory, per request.

See /concepts/session-pruning for pruning details.

OpenAI server-side compaction​

OpenClaw also supports OpenAI Responses server-side compaction hints for compatible direct OpenAI models. This is separate from local OpenClaw compaction and can run alongside it.

  • Local compaction: OpenClaw summarizes and persists into session JSONL.
  • Server-side compaction: OpenAI compacts context on the provider side when store + context_management are enabled.

See OpenAI provider for model params and overrides.

Custom context engines​

Compaction behavior is owned by the active context engine. The legacy engine uses the built-in summarization described above. Plugin engines (selected via plugins.slots.contextEngine) can implement any compaction strategy — DAG summaries, vector retrieval, incremental condensation, etc.

When a plugin engine sets ownsCompaction: true, OpenClaw delegates all compaction decisions to the engine and does not run built-in auto-compaction.

When ownsCompaction is false or unset, OpenClaw may still use Pi's built-in in-attempt auto-compaction, but the active engine's compact() method still handles /compact and overflow recovery. There is no automatic fallback to the legacy engine's compaction path.

If you are building a non-owning context engine, implement compact() by calling delegateCompactionToRuntime(...) from openclaw/plugin-sdk/core.

Tips​

  • Use /compact when sessions feel stale or context is bloated.
  • Large tool outputs are already truncated; pruning can further reduce tool-result buildup.
  • If you need a fresh slate, /new or /reset starts a new session id.