Understanding Context in OpenClaw: What the Model Sees

"Context" refers to the complete set of data OpenClaw forwards to the model during a single run. Its size is constrained by the model's context window, which is the token ceiling.

A straightforward way to think about it:

• System prompt (assembled by OpenClaw): instructions, available tools, skill inventory, current time and runtime details, plus workspace files that are injected.
• Conversation history: the full exchange of user inputs and assistant outputs from the current session.
• Tool calls/results and attachments: outputs from commands, content from file reads, images, audio, and similar items.

Context should not be confused with "memory": memory gets persisted to disk and can be retrieved later, whereas context only exists within the model's active window.

Quick start (inspect context)

• /status → provides a fast check on how much of the window is used, along with session configuration.
• /context list → lists what gets injected and gives approximate sizes, both per file and in total.
• /context detail → offers a more detailed view: individual file sizes, tool schema dimensions, per-skill entry sizes, system prompt length, and counts of transcript messages that can be compacted.
• /context map → generates a treemap visualization, similar to WinDirStat, showing all tracked contributors to the current session's context.
• /usage tokens → adds a usage summary to the end of each normal reply.
• /compact → condenses older conversation into a single compact record to reclaim window space.

Related references: Slash commands, Token use & costs, Compaction.

Example output

The exact numbers depend on the model, the provider, tool policies, and the contents of your workspace.

/context list

🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 12,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))

Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)

Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)

Session tokens (cached): 14,250 total / ctx=32,000

/context detail

🧠 Context breakdown (detailed)
…
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
… (+10 more skills)

Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
… (+N more tools)

/context map

Produces an image based on the most recent cached run report and the session transcript. If no run report exists yet because a regular message hasn't been processed, /context map shows an unavailable notice rather than an estimate. The size of each rectangle corresponds to the number of tracked prompt characters:

• the conversation transcript, which includes user messages, assistant responses, tool results, and compaction summaries, plus any per-turn runtime context and hook prompt additions that are visible only to the model
• workspace files that are injected
• the base text of the system prompt
• skill prompt entries
• JSON schemas for tools

The conversation segment expands as the session progresses, so the map changes with each turn; after a compaction, it shrinks into a single tile for summaries.

When no run report is cached, /context list, /context detail, and /context json can still look at an on-demand estimate.

What counts toward the context window

Any data the model receives is counted, which covers:

• The system prompt in its entirety.
• The conversation history.
• Tool invocations and their results.
• Attachments and transcripts, such as images, audio, or files.
• Compaction summaries and artifacts from pruning.
• Provider wrappers or hidden headers, which aren't visible but still consume space.

How OpenClaw builds the system prompt

The system prompt is managed exclusively by OpenClaw and gets reconstructed for every run. Its contents include:

• The tool list with brief descriptions.
• The skills list, which only carries metadata, as explained below.
• The workspace path.
• The current time, in UTC and in the user's local timezone if that's configured.
• Runtime details like host, OS, model, and thinking mode.
• Workspace bootstrap files that are injected under Project Context.

A complete breakdown is available at: System Prompt.

Injected workspace files (Project Context)

Unless configured otherwise, OpenClaw injects a standard set of workspace files when they exist:

• AGENTS.md
• SOUL.md
• IDENTITY.md
• USER.md
• BOOTSTRAP.md, which appears only on the first run

Individual large files get cut off using agents.defaults.bootstrapMaxChars, with a default limit of 20000 characters. Across all files, OpenClaw applies a total bootstrap injection cap controlled by agents.defaults.bootstrapTotalMaxChars, which defaults to 60000 characters. /context displays the difference between raw and injected sizes and flags whether truncation took place.

If truncation happens, the runtime adds a short, built-in notice under Project Context stating that some bootstrap files were trimmed; the specific file names and sizes remain available in /context and other diagnostics. This notice is fixed and cannot be customized.

Skills: injected vs loaded on-demand

A compact skills list, containing each skill's name, description, and location, is part of the system prompt. Maintaining this list carries a real cost.

Skill instructions are excluded by default. The model is meant to read the skill's SKILL.md only when necessary.

Tools: there are two costs

Tools influence context through two channels:

1. The tool list text that appears in the system prompt, which you see as "Tooling".
2. Tool schemas in JSON format. These get sent to the model so it can invoke tools, and they consume context even though they aren't displayed as readable text.

/context detail provides a breakdown of the largest tool schemas, helping you identify which ones dominate.

Commands, directives, and "inline shortcuts"

The Gateway processes slash commands, which behave in a few distinct ways:

• Standalone commands: a message consisting solely of /... is treated as a command.
• Directives: /think, /fast, /verbose, /trace, /reasoning, /elevated, /exec, /model, and /queue get removed before the model sees the message.
  • When a message contains only directives, session settings are saved.
  • Directives placed inline within a normal message act as hints for that specific message.
• Inline shortcuts, available only to allowlisted senders: certain /... tokens within a regular message can execute right away, such as "hey /status", and are stripped before the model sees the remaining text.

For more information: Slash commands.

Sessions, compaction, and pruning (what persists)

What carries over between messages varies by mechanism:

• Normal history stays in the session transcript until policy triggers compaction or pruning.
• Compaction writes a summary into the transcript while keeping recent messages untouched.
• Pruning removes old tool results from the in-memory prompt to open up context-window space, but it doesn't modify the session transcript, so the complete history remains available for inspection on disk.

Documentation: Session, Compaction, Session pruning.

By default, OpenClaw relies on the built-in legacy context engine to handle assembly and compaction. When you install a plugin that offers kind: "context-engine" and choose it via plugins.slots.contextEngine, OpenClaw hands off context assembly, /compact, and the associated subagent context lifecycle hooks to that engine. ownsCompaction: false does not automatically revert to the legacy engine; the selected engine must still correctly implement compact(). For the complete pluggable interface, lifecycle hooks, and configuration details, refer to Context Engine.

What /context actually reports

/context opts for the most recent run-built system prompt report when one is available:

• System prompt (run) = taken from the last embedded (tool-capable) run and stored in the session store.
• System prompt (estimate) = generated on demand when no run report exists (or when operating through a CLI backend that does not produce the report).

In both cases, it provides sizes and top contributors; it does not output the entire system prompt or tool schemas. In detailed mode, it also checks the session transcript against the same real-conversation message predicate used for compaction, making it easier to tell apart high prompt/cache usage from compactable conversation history.

Related

• Context engine, Plugin-based custom context injection.

• Compaction, Condensing long conversations to fit within the model window.

• System prompt, The construction of the system prompt and its per-turn injections.

• Agent loop, The complete agent execution flow, from incoming message to final response.