mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 15:30:39 +00:00
caf1b84822
Merged via squash.
Prepared head SHA: a3d6d6c845
Co-authored-by: starbuck100 <25417736+starbuck100@users.noreply.github.com>
Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com>
Reviewed-by: @jalehman
105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
---
|
||
summary: "Context window + compaction: how OpenClaw keeps sessions under model limits"
|
||
read_when:
|
||
- You want to understand auto-compaction and /compact
|
||
- You are debugging long sessions hitting context limits
|
||
title: "Compaction"
|
||
---
|
||
|
||
# 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’s JSONL history.
|
||
|
||
## Configuration
|
||
|
||
Use the `agents.defaults.compaction` setting in your `openclaw.json` 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:
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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](/concepts/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 JSONL.
|
||
- **Session pruning**: trims old **tool results** only, **in-memory**, per request.
|
||
|
||
See [/concepts/session-pruning](/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](/providers/openai) for model params and overrides.
|
||
|
||
## 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.
|