Managing Context in OpenClaw

I have often found myself wondering why an AI agent suddenly loses track of a conversation or starts ignoring specific instructions. It usually happens because the context window—the model’s “short-term memory”—is full or cluttered with data I didn’t realize was there. Understanding exactly what gets sent to the model helps you keep your sessions fast and accurate.

In OpenClaw, “Context” is the total package of information sent during a run. It is not the same as long-term memory stored on a disk; it is the active data living inside the model’s current window.

What You’ll Need

• An active OpenClaw session.
• A workspace containing project files (like AGENTS.md or USER.md).
• Access to the built-in slash commands.

Quick Start

You can inspect your context usage right now using these four commands. It takes less than five minutes to get a clear picture of your token usage.

1. Check the basics: Type /status to see how full your window is and check your current session settings.
2. View injected files: Run /context list to see which workspace files are being sent and how large they are.
3. Get a deep dive: Use /context detail to see the exact size of tool schemas, system prompts, and individual skills.
4. Track tokens: Run /usage tokens to add a small footer to every reply showing how many tokens that specific message used.

How Context is Built

OpenClaw builds a new system prompt for every single run. I find it helpful to think of the context as a stack of four main components:

• The System Prompt: This includes the rules, the workspace location, and the current time.
• Conversation History: Your messages and the assistant’s previous replies.
• Tool Data: This includes the JSON schemas for tools and the results of any commands the agent ran.
• Project Context: Specific files from your workspace that OpenClaw injects automatically.

Workspace File Injection

By default, OpenClaw looks for specific files in your workspace to give the model immediate context. These include AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md.

If these files are too large, OpenClaw truncates them based on the agents.defaults.bootstrapMaxChars setting (which defaults to 20,000 characters). You can see if a file was cut off by looking for the TRUNCATED label in the /context list output.

The Hidden Cost of Tools

Tools affect your context window in two separate ways. First, there is the text description in the system prompt. Second, there are the Tool Schemas (JSON). These schemas tell the model how to use the tool. Even though you don’t see this JSON in your chat history, it still takes up space. If you use /context detail, you can see which tools are taking up the most room.

🧠 Context breakdown (detailed)
…
Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)

Managing Space

When your context window starts getting crowded, you have a few options to clean it up:

• Compaction: Use the /compact command. This summarizes older parts of your history into a single entry, which frees up space while keeping the important details.
• Pruning: OpenClaw automatically removes old tool results from the prompt during a run to save space, though these stay in your permanent transcript.

Troubleshooting

If things aren’t working as expected, check these common status messages in your /context list output:

• MISSING: The file (like HEARTBEAT.md) does not exist in your workspace. OpenClaw simply skips it.
• TRUNCATED: The file is larger than the character limit. You may need to split the file or increase bootstrapMaxChars.
• System prompt (estimate): This appears if you are using a backend that doesn’t support run reports. It means the sizes shown are calculated on the fly rather than captured from a real run.

If you need help configuring your context limits or workspace files, check out the AI Setup Assistant.

What’s Next

• Slash commands
• Token use & costs
• Compaction
• System Prompt