OpenClaw compaction: when context is full
Use /compact to continue a long OpenClaw conversation. How compaction differs from pruning and /new, and what to check when context still will not fit.
Compaction gives a long OpenClaw conversation room to continue by summarizing older history while retaining recent turns. It normally happens automatically as context fills. Type /compact to request it yourself, or /status to inspect context usage. It is different from /new, which starts with a fresh conversation context.
What “context full” actually means
A model can only receive a limited amount of material in one request. That allowance includes more than the messages you typed: OpenClaw also sends instructions, tool definitions, workspace material and tool results. A short exchange that reads several large files can use more context than a long conversation consisting only of text.
OpenClaw’s context reference documents /context list for a breakdown and /context detail for a closer look. Use those when compaction keeps recurring: the useful question is what occupies the space, not simply how many messages the chat contains.
Compact when you want to continue the same work
Send the command directly in the conversation:
/compactYou can add a short instruction about what the summary should preserve. Name the active objective, unresolved decisions or important constraints; do not paste the whole conversation back in. The compaction documentation describes automatic compaction near the context limit and manual compaction with optional focus instructions.
The summary takes the place of older detail in the model’s active context. The saved conversation is not the same thing as the material present in its next request. A summary can preserve that you settled a decision without carrying every argument or exact phrase that led to it.
Before a consequential continuation, ask the agent to state the current objective and the decisions it is using. Correct anything missing before it edits, sends or commits work. If exact wording or a detailed specification matters, keep that in a file the agent can reread rather than relying on a conversational summary to reproduce it.
Compaction, pruning and a fresh session do different jobs
| Action | What changes | When it helps |
|---|---|---|
| Compaction | Older conversation is represented by a summary. | The same task should continue with less history in context. |
| Pruning | Older tool results are trimmed from a request. | Large tool output is taking up room. |
/new | A fresh conversation context begins. | The subject has changed or you want a clean start. |
Session pruning does not rewrite the stored transcript; it changes what is sent in a request. Neither pruning nor compaction should be treated as deleting sensitive content from the conversation record.
A new session still has access to durable workspace files and configured memory. It does not automatically have the old thread’s full working context. Save the current state of a task before starting over, especially if the next conversation needs to resume it.
If compaction does not fix the error
Look at what the failing request must include even after older chat is summarized. Oversized workspace instructions, extensive tool schemas or a newly attached document can consume the allowance on their own. Shorten instructions that do not need to be present every turn, ask for relevant sections of a large source, or narrow the tools available for the job. Raising a context-limit setting does not give the model a larger actual window.
Compaction also needs a functioning model service. An authentication failure, exhausted quota or provider outage is not repaired by asking the same unavailable service to summarize. Read the reported failure and fix that cause, or use an already-configured working model. Avoid resetting a useful conversation just because the summarization request failed.
The behavior described here is OpenClaw’s built-in compaction path. A separate runtime or custom context engine can own its own context handling; use the error from the runtime serving that conversation when diagnosing a mismatch.
Recover a session from the terminal
If you operate the Gateway and need to compact a particular session, first list the sessions and identify its full key:
openclaw sessions --agent main --json
openclaw sessions compact "<session-key>"Replace main with the relevant agent and <session-key> with the exact key you selected. The sessions CLI requires a running Gateway for this command. Without additional truncation options it requests model summarization.
Do not add --max-lines as an ordinary context fix: that option permanently truncates the stored transcript and does not create a backup archive. It is not a stronger version of summarization.
Keep the durable work outside the summary
Compaction is a way to keep talking, not a filing system. Keep a project’s decisions, source documents and current state in durable memory or workspace files, with enough context that the agent can pick up the work after a fresh session. Then a summary only has to carry the thread of the conversation, not the sole copy of everything that matters.