OpenClaw Context On-Demand Loading and Management

OpenClaw Context On-Demand Loading and Management

This article reviews how OpenClaw builds and controls runtime context, from inbound message normalization to prompt assembly, pruning, and diagnostics.

Key code entry points:
src/agents/system-prompt.ts, src/agents/bootstrap-files.ts, src/agents/workspace.ts, src/auto-reply/reply/*, src/agents/pi-extensions/context-pruning/*.

1. Context Composition and Goals

  • Context includes system prompt, conversation history, tool calls/results, and media attachments.
  • Max context window follows model registry contextWindow; fallback is DEFAULT_CONTEXT_TOKENS=200000.
  • Design goals:
    • Inject mandatory workspace instructions reliably.
    • Load large optional material only when needed.
    • Keep long sessions stable via pruning/compaction/refresh.

2. Context Build Pipeline

2.1 Inbound Standardization

finalizeInboundContext normalizes message fields and derives agent-facing bodies.

2.2 Inline Directives and Commands

Inline directives like /think, /model, /queue are parsed and stripped from user text before model input.

Inline commands like /help, /status, /whoami can run first, then remaining text continues through the model path.

2.3 Group History Injection

buildHistoryContext appends recent group history plus current message with explicit markers.

Default group history limit is message-count based (DEFAULT_GROUP_HISTORY_LIMIT=50).

2.4 Session Persistence

  • Session store: ~/.openclaw/agents/<agentId>/sessions/sessions.json
  • Transcript: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

2.5 Bootstrap File Injection

OpenClaw loads workspace bootstrap files such as AGENTS.md, TOOLS.md, HEARTBEAT.md, MEMORY.md/memory.md.

Subagents keep only a reduced subset (AGENTS.md + TOOLS.md).

Large bootstrap files are truncated (head + tail policy) with explicit marker text.

2.6 System Prompt Assembly

buildAgentSystemPrompt combines tools, skills, workspace context, time, sandbox info, and project context.

  • full prompt mode for primary session
  • minimal mode for subagents

2.7 Runtime Resource Control

OpenClaw explicitly disables default Pi skill loading (noSkills: true) and injects its own prompt override to keep context sources deterministic.

3. On-Demand Loading Strategy

3.1 Bootstrap Truncation + Read-on-Demand

Large bootstrap files are summarized/truncated first, with instruction to read original files when needed.

3.2 Skills

Prompt only includes available skill metadata snapshot. The model is instructed to read one specific SKILL.md only after selecting a skill.

3.3 Docs

Prompt includes doc paths and usage hints, not full doc payload.

3.4 Memory

memory_search + memory_get encourage retrieval-first behavior and partial reading.

3.5 Subagent Minimal Context

Subagents run with smaller prompt mode and restricted bootstrap files to reduce noise and cost.

4. Context Size Management

4.1 Bootstrap Limits

Default bootstrapMaxChars=20000; oversized files are truncated with marker boundaries.

4.2 Memory Flush

Near compaction threshold, OpenClaw can trigger a silent memory-flush pass to persist long-term info into memory files.

4.3 Compaction

/compact summarizes older history and keeps recent turns, reducing session payload size.

4.4 Context Pruning

context-pruning extension focuses on high-cost toolResult messages.

  • Soft trim first, then hard clear if still above threshold
  • Skip image-containing tool results
  • Preserve bootstrap-adjacent boundary semantics

4.5 Compaction Safeguard

Optional safeguard mode enforces historical share limits and can synthesize additional summaries.

5. Observability

5.1 /context Report

commands-context-report.ts exposes approximate usage details:

  • raw vs injected bootstrap sizes
  • tool list and schema payload sizes
  • skill list payload sizes

5.2 /status + usage persistence

Session store persists usage and context token stats for UI/CLI inspection.

6. Potential Issues (Code Review)

  1. Token estimate based on chars/4

    • Can under/over-estimate significantly for CJK text and code-heavy content.

  2. Group history limit is count-based, not token-budget based

    • A few very long messages can still create context spikes.

  3. Current pruning mainly targets toolResult

    • Other high-volume message types may remain unoptimized.

  4. Head-tail bootstrap truncation can lose critical middle sections

    • Constraints placed in the middle of long docs may be dropped.

  5. Runtime pruning state depends on session-manager object identity

    • Object replacement edge cases can miss policy runtime state.
Back to Resources

Table of Contents