How to Manage the Context Window in OpenClaw

Conversation history accounts for 40 to 50 percent of total token consumption in a typical OpenClaw session. Tool call output adds another 20 to 30 percent. That means by the time your agent has processed a dozen turns with file reads and code edits, input tokens on turn 20 can be roughly 20 times the cost of turn one. Users on the OpenClaw subreddit and cost-tracking blogs report monthly bills jumping from under $200 to over $900 when context goes unmanaged.

The context window is not memory. Memory lives on disk in files like SOUL.md, AGENTS.md, and the session transcript. Context is what the model actually receives on each turn: the system prompt, injected workspace files, conversation history, tool schemas, and tool results. When that window fills up, the model loses access to earlier instructions and starts producing less coherent output. One user running MiniMax 2.5 reported that their agent "woke up already at 136K tokens" before a single task, because memory files consumed most of the budget at session start.

Context management is not just a cost problem. It is a quality problem. Research from Chroma's 2025 "Context Rot" study found that model performance grows increasingly unreliable as input length grows. Keeping your context lean means your agent follows instructions more precisely and produces better results for longer.

The good news: OpenClaw ships with monitoring commands, configurable limits, and automatic compaction. The rest of this guide shows you how to use each one.

Every turn, OpenClaw assembles a prompt from four layers. Understanding each one helps you figure out where tokens are going and where to cut.

System prompt includes rules, tool descriptions, skill metadata, runtime info, and the current time. A typical system prompt runs around 9,600 tokens. The browser tool schema alone consumes roughly 2,450 tokens. If you have several MCP servers registered, their tool schemas stack on top of that.

Injected workspace files are loaded automatically at session start. OpenClaw looks for AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md (first run only). Each file is subject to the bootstrapMaxChars limit of 12,000 characters per file, with a combined cap of 60,000 characters across all files. Files that exceed these limits get truncated, and /context list shows "TRUNCATED" next to them.

Conversation history is every user message, assistant response, and tool call/result from the current session. This is the layer that grows with every turn and is the biggest cost driver in longer sessions.

Provider overhead includes hidden headers and wrappers that the API provider adds. These tokens are counted against your limit but are not visible in the transcript.

You cannot eliminate any of these layers, but you can control how large each one gets. Trimming workspace files, limiting tool registrations, and triggering compaction before the window fills are the three highest-impact moves.

OpenClaw provides four commands for inspecting context, each at a different level of detail. Use them regularly rather than waiting for the model to start producing incoherent output.

/status gives you a quick snapshot of context fullness alongside session settings. It shows session tokens, cached tokens, and the total context limit for your current model. The output looks something like "Session tokens (cached): 14,250 total / ctx=200,000." This is your first check when you suspect context is getting full.

/context list shows every injected file and its approximate size, with totals at the bottom. This is where you catch oversized workspace files and see which ones are being truncated. If a file shows a raw size of 18,000 characters but an injected size of 12,000, you know bootstrapMaxChars is doing the truncating.

/context detail breaks down per-file, per-tool-schema, and per-skill token costs. This is the command to use when you want to know exactly which tool schema is eating 2,400 tokens or which skill is adding unexpected overhead.

/context map renders a WinDirStat-style treemap image of all context contributors. It is the fast way to visually identify which components dominate your token budget without reading through tables.

/usage tokens appends a per-reply token usage footer to every subsequent response. Enable this early in sessions where you are tracking costs or debugging context growth. It shows input tokens, output tokens, and cache hit rates for each turn.

A practical routine: run /status at the start of each session to see your baseline. Enable /usage tokens if costs matter. Check /context detail whenever you add a new tool or skill. Run /context map periodically in long sessions to catch growth before it degrades output quality.

Keep Agent Artifacts Safe Between Compactions

Free 50 GB workspace with semantic search and MCP access. Write important state to persistent storage before compaction wipes it from context. No credit card, no expiration.

Start 14-Day Trial

OpenClaw exposes several settings that control how much context each component can consume. Adjusting these is the fast way to reclaim token budget.

bootstrapMaxChars sets the per-file character limit for injected workspace files. The default is 12,000 characters. If you have a large AGENTS.md or SOUL.md but only need the first few sections in context, lower this value. A setting of 6,000 cuts workspace file overhead roughly in half while still loading the most important instructions at the top of each file.

bootstrapTotalMaxChars caps the combined size of all workspace files at 60,000 characters. If you have six files at 12,000 characters each, you are already at the cap and the last file may be truncated or dropped entirely. Either consolidate files or lower per-file limits to stay under the total.

bootstrapPromptTruncationWarning controls whether OpenClaw notifies you when files get truncated. The default is "always," which is noisy but informative. Set it to "once" after you have your files dialed in, or "off" if you have deliberately oversized files that you expect to be trimmed.

contextWindow for custom providers deserves special attention. When using an OpenAI-compatible provider that OpenClaw does not natively support, the default context window is only 4,096 tokens, well below the 16,000-token minimum. Users connecting DeepSeek and other third-party models through custom providers hit this wall immediately. Set contextWindow to at least 16,000 in your openclaw.json provider configuration to avoid the "Model context window too small" error.

toolResultMaxChars limits how much output from a single tool call gets retained in context. Large file reads or verbose command outputs can consume thousands of tokens per call. Lowering this value forces truncation of tool results, which saves context at the cost of potentially losing details from long outputs. Start with the default and only reduce it if /context detail shows tool results dominating your budget.

For model routing, consider using a cheaper model for compaction summaries. The compaction.model setting lets you offload summarization to a smaller model like Claude Sonnet instead of burning Opus tokens on summaries. This does not affect context window size directly, but it reduces the cost of maintaining long sessions.

When a session runs long enough, compaction becomes essential. OpenClaw offers both automatic and manual compaction, plus a lighter-weight pruning mechanism.

Auto-compaction triggers when the session approaches the model's context limit or when the provider signals that the request exceeds available capacity. Before compacting, OpenClaw prompts the agent to save important notes to memory files, preventing information loss. After completion, /status reflects the compaction count so you can track how often it fires.

Manual compaction via /compact lets you force a summary at any point. You can pass a short instruction telling the summary what to prioritize, like focusing on design decisions over debugging tangents. When a recent-token preservation boundary is configured, manual compaction respects it and keeps recent turns intact. Without that setting, /compact summarizes the full conversation history.

Pruning is lighter than compaction. It trims old tool results from the in-memory prompt without rewriting the session transcript. Full history stays on disk. Enable session pruning if you find yourself compacting frequently due to large tool outputs rather than long conversation history.

Memory flush runs a silent turn before compaction that prompts the agent to save important notes into memory files. You can route this flush to a cheaper model in your configuration so compaction housekeeping does not consume expensive tokens.

Successor transcripts split the session after compaction. OpenClaw starts a fresh active transcript from the summary and unsummarized content, archiving the previous transcript as a checkpoint. This prevents the on-disk transcript from growing without bound in very long sessions.

Practical guidance: do not wait for auto-compaction to kick in. By the time the model returns an overflow error, your last few turns may have already degraded in quality. Run /compact proactively when /status shows you are past 70 percent of the context limit. Write important state to files before compacting, because summaries are lossy by nature.

The context window is temporary. Everything in it either gets compacted into a summary or lost when the session ends. For anything that matters beyond the current conversation, you need external persistence.

OpenClaw's workspace files (SOUL.md, AGENTS.md, MEMORY.md) are one layer of persistence, but they have a ceiling. At 60,000 characters combined, they cannot hold large datasets, generated reports, or versioned project artifacts. And they reload into every session, consuming context whether or not the agent needs that specific information.

For larger or more structured persistence, a shared workspace solves the problem. Local filesystems work, but they are tied to one machine and one user. S3 buckets provide durability but no search, no previews, and no collaboration. Google Drive offers sharing but requires manual organization and has limited API access for agents.

Fastio provides workspaces designed for agent workflows. Agents access files through the MCP server using Streamable HTTP at /mcp. Intelligence Mode auto-indexes uploaded files for semantic search, so an agent can query "find the Q3 revenue analysis" by meaning rather than filename. Ownership transfer lets an agent build a complete project workspace and hand it to a human client while retaining admin access.

The practical pattern for context management: before compaction, have your agent write important artifacts, summaries, and reference data to a persistent workspace. After compaction or in a new session, the agent reads back only what it needs rather than carrying everything in context. This keeps the context window lean while preserving institutional knowledge across sessions.

The Business Trial includes 50 GB of storage, included credits, and 5 workspaces with no credit card required. For OpenClaw users, there is a dedicated storage-for-openclaw guide that covers the setup.