@@ -6,170 +6,149 @@ read_when:
66title: "Compaction"
77---
889-Every model has a context window -- the maximum number of tokens it can process.
10-When a conversation approaches that limit, OpenClaw **compacts** older messages
11-into a summary so the chat can continue.
9+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.
12101311## How it works
141215131. Older conversation turns are summarized into a compact entry.
16142. The summary is saved in the session transcript.
17153. Recent messages are kept intact.
181619-When OpenClaw splits history into compaction chunks, it keeps assistant tool
20-calls paired with their matching `toolResult` entries. If a split point lands
21-inside a tool block, OpenClaw moves the boundary so the pair stays together and
22-the current unsummarized tail is preserved.
17+When OpenClaw splits history into compaction chunks, it keeps assistant tool calls paired with their matching `toolResult` 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.
231824-The full conversation history stays on disk. Compaction only changes what the
25-model sees on the next turn.
19+The full conversation history stays on disk. Compaction only changes what the model sees on the next turn.
26202721## Auto-compaction
282229-Auto-compaction is on by default. It runs when the session nears the context
30-limit, or when the model returns a context-overflow error (in which case
31-OpenClaw compacts and retries). Typical overflow signatures include
32-`request_too_large`, `context length exceeded`, `input exceeds the maximum
33-number of tokens`, `input token count exceeds the maximum number of input
34-tokens`, `input is too long for the model`, and `ollama error: context length
35-exceeded`.
23+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).
24+25+You will see:
26+27+- `🧹 Auto-compaction complete` in verbose mode.
28+- `/status` showing `🧹 Compactions: <count>`.
36293730<Info>
38-Before compacting, OpenClaw automatically reminds the agent to save important
39-notes to [memory](/concepts/memory) files. This prevents context loss.
31+Before compacting, OpenClaw automatically reminds the agent to save important notes to [memory](/concepts/memory) files. This prevents context loss.
4032</Info>
413342-Use the `agents.defaults.compaction` setting in your `openclaw.json` to configure compaction behavior (mode, target tokens, etc.).
43-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`.
34+<AccordionGroup>
35+<Accordion title="Recognized overflow signatures">
36+OpenClaw detects context overflow from these provider error patterns:
443745-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:
38+- `request_too_large`
39+- `context length exceeded`
40+- `input exceeds the maximum number of tokens`
41+- `input token count exceeds the maximum number of input tokens`
42+- `input is too long for the model`
43+- `ollama error: context length exceeded`
44+</Accordion>
45+</AccordionGroup>
46+47+## Manual compaction
48+49+Type `/compact` in any chat to force a compaction. Add instructions to guide the summary:
465047-```json
48-{
49-"agents": {
50-"defaults": {
51-"compaction": {
52-"model": "openrouter/anthropic/claude-sonnet-4-6"
53- }
54- }
55- }
56-}
5751```
52+/compact Focus on the API design decisions
53+```
54+55+When `agents.defaults.compaction.keepRecentTokens` 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.
56+57+## Configuration
58+59+Configure compaction under `agents.defaults.compaction` in your `openclaw.json`. The most common knobs are listed below; for the full reference, see [Session management deep dive](/reference/session-management-compaction).
586059-This also works with local models, for example a second Ollama model dedicated to summarization or a fine-tuned compaction specialist:
61+### Using a different model
62+63+By default, compaction uses the agent's primary model. Set `agents.defaults.compaction.model` to delegate summarization to a more capable or specialized model. The override accepts any `provider/model-id` string:
60646165```json
6266{
6367"agents": {
6468"defaults": {
6569"compaction": {
66-"model": "ollama/llama3.1:8b"
70+"model": "openrouter/anthropic/claude-sonnet-4-6"
6771 }
6872 }
6973 }
7074}
7175```
727673-When unset, compaction uses the agent’s primary model.
74-75-## Pluggable compaction providers
76-77-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.
78-79-To use a registered provider, set the provider id in your config:
77+This works with local models too, for example a second Ollama model dedicated to summarization:
80788179```json
8280{
8381"agents": {
8482"defaults": {
8583"compaction": {
86-"provider": "my-provider"
84+"model": "ollama/llama3.1:8b"
8785 }
8886 }
8987 }
9088}
9189```
929093-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. If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization.
91+When unset, compaction uses the agent's primary model.
949295-## Auto-compaction (default on)
93+### Identifier preservation
969497-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.
95+Compaction summarization preserves opaque identifiers by default (`identifierPolicy: "strict"`). Override with `identifierPolicy: "off"` to disable, or `identifierPolicy: "custom"` plus `identifierInstructions` for custom guidance.
989699-You’ll see:
97+### Active transcript byte guard
10098101-- `🧹 Auto-compaction complete` in verbose mode
102-- `/status` showing `🧹 Compactions: <count>`
99+When `agents.defaults.compaction.maxActiveTranscriptBytes` 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.
103100104-Before compaction, OpenClaw can run a **silent memory flush** turn to store
105-durable notes to disk. See [Memory](/concepts/memory) for details and config.
101+<Warning>
102+The byte guard requires `truncateAfterCompaction: true`. Without transcript rotation, the active file would not shrink and the guard remains inactive.
103+</Warning>
106104107-## Manual compaction
105+### Successor transcripts
108106109-Type `/compact` in any chat to force a compaction. Add instructions to guide
110-the summary:
107+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 keeps the previous JSONL as the archived checkpoint source.
111108112-```
113-/compact Focus on the API design decisions
114-```
115-116-When `agents.defaults.compaction.keepRecentTokens` is set, manual compaction
117-honors that Pi cut-point and keeps the recent tail in rebuilt context. Without
118-an explicit keep budget, manual compaction behaves as a hard checkpoint and
119-continues from the new summary alone.
109+### Compaction notices
120110121-When `agents.defaults.compaction.truncateAfterCompaction` is enabled,
122-OpenClaw does not rewrite the existing transcript in place. It creates a new
123-active successor transcript from the compaction summary, preserved state, and
124-unsummarized tail, then keeps the previous JSONL as the archived checkpoint
125-source.
126-127-When `agents.defaults.compaction.maxActiveTranscriptBytes` is set, OpenClaw can
128-trigger normal local compaction before a run if the active JSONL reaches that
129-size. This is useful for long-running sessions where provider-side context
130-management may keep model context healthy while the local transcript keeps
131-growing. It does not split raw JSONL bytes; it only asks the normal compaction
132-pipeline to create a semantic summary. Combine it with
133-`truncateAfterCompaction: true` to move future turns onto the smaller successor
134-transcript; without transcript rotation, the byte guard remains inactive because
135-the active file would not shrink.
136-137-## Using a different model
138-139-By default, compaction uses your agent's primary model. You can use a more
140-capable model for better summaries:
111+By default, compaction runs silently. Set `notifyUser` to show brief status messages when compaction starts and completes:
141112142113```json5
143114{
144115 agents: {
145116 defaults: {
146117 compaction: {
147-model: "openrouter/anthropic/claude-sonnet-4-6",
118+notifyUser: true,
148119 },
149120 },
150121 },
151122}
152123```
153124154-## Compaction notices
125+### Memory flush
155126156-By default, compaction runs silently. To show brief notices when compaction
157-starts and when it completes, enable `notifyUser`:
127+Before compaction, OpenClaw can run a **silent memory flush** turn to store durable notes to disk. See [Memory](/concepts/memory) for details and config.
158128159-```json5
129+## Pluggable compaction providers
130+131+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.
132+133+To use a registered provider, set its id in your config:
134+135+```json
160136{
161- agents: {
162- defaults: {
163- compaction: {
164-notifyUser: true,
165- },
166- },
167- },
137+"agents": {
138+"defaults": {
139+"compaction": {
140+"provider": "my-provider"
141+ }
142+ }
143+ }
168144}
169145```
170146171-When enabled, the user sees short status messages around each compaction run
172-(for example, "Compacting context..." and "Compaction complete").
147+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.
148+149+<Note>
150+If the provider fails or returns an empty result, OpenClaw falls back to built-in LLM summarization.
151+</Note>
173152174153## Compaction vs pruning
175154@@ -179,28 +158,21 @@ When enabled, the user sees short status messages around each compaction run
179158| **Saved?** | Yes (in session transcript) | No (in-memory only, per request) |
180159| **Scope** | Entire conversation | Tool results only |
181160182-[Session pruning](/concepts/session-pruning) is a lighter-weight complement that
183-trims tool output without summarizing.
161+[Session pruning](/concepts/session-pruning) is a lighter-weight complement that trims tool output without summarizing.
184162185163## Troubleshooting
186164187-**Compacting too often?** The model's context window may be small, or tool
188-outputs may be large. Try enabling
189-[session pruning](/concepts/session-pruning).
165+**Compacting too often?** The model's context window may be small, or tool outputs may be large. Try enabling [session pruning](/concepts/session-pruning).
190166191-**Context feels stale after compaction?** Use `/compact Focus on <topic>` to
192-guide the summary, or enable the [memory flush](/concepts/memory) so notes
193-survive.
167+**Context feels stale after compaction?** Use `/compact Focus on <topic>` to guide the summary, or enable the [memory flush](/concepts/memory) so notes survive.
194168195169**Need a clean slate?** `/new` starts a fresh session without compacting.
196170197-For advanced configuration (reserve tokens, identifier preservation, custom
198-context engines, OpenAI server-side compaction), see the
199-[Session Management Deep Dive](/reference/session-management-compaction).
171+For advanced configuration (reserve tokens, identifier preservation, custom context engines, OpenAI server-side compaction), see the [Session management deep dive](/reference/session-management-compaction).
200172201173## Related
202174203-- [Session](/concepts/session) — session management and lifecycle
204-- [Session Pruning](/concepts/session-pruning) — trimming tool results
205-- [Context](/concepts/context) — how context is built for agent turns
206-- [Hooks](/automation/hooks) — compaction lifecycle hooks (before_compaction, after_compaction)
175+- [Session](/concepts/session): session management and lifecycle.
176+- [Session pruning](/concepts/session-pruning): trimming tool results.
177+- [Context](/concepts/context): how context is built for agent turns.
178+- [Hooks](/automation/hooks): compaction lifecycle hooks (`before_compaction`, `after_compaction`).
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。