Principle:Openclaw Openclaw Context Assembly
| Knowledge Sources | |
|---|---|
| Domains | Agent_Runtime, LLM_Integration |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Context assembly is the process of building the complete input context for an LLM call: constructing the system prompt from workspace files and agent configuration, loading and preparing session history, resolving model and provider selection, initializing the tool set, and applying all pre-call directives before handing off to the inference layer.
Description
After an inbound message has been normalized into a MsgContext envelope and routed to an agent session, the runtime must assemble everything the LLM needs to produce a useful reply. This is a multi-stage pipeline that orchestrates several concerns:
Model and provider resolution: The agent's configured model (or a heartbeat-specific override) is resolved, including alias expansion and provider normalization. Fallback chains and auth profile rotation are prepared for resilience.
Workspace bootstrapping: The agent's workspace directory is ensured to exist and may be populated with bootstrap files (e.g., default system prompt templates) if the agent is new and skipBootstrap is not set. The workspace is the root for any file-based tools the agent may use during inference.
Media and link understanding: Attached media (images, audio, documents) and embedded links in the message are processed through understanding pipelines that produce textual descriptions, transcriptions, or summaries. These are injected into the finalized context so the LLM can reason about media content without direct access to binary data.
Session state initialization: The session store is loaded, session history is replayed, and state such as whether the session is new, whether a reset was triggered, and whether the previous run was aborted is determined. Session-scoped model overrides (e.g., a user switching models mid-conversation) are applied.
Directive resolution: Text-based directives embedded in the user message (e.g., /think, /verbose, /model) are parsed, validated against authorization, and resolved into concrete parameters (think level, verbose level, model override, tool policy adjustments). Inline actions (status queries, session commands) may short-circuit the pipeline and return an immediate reply.
Tool and skill preparation: The set of available tools is filtered by policy, skill filters (agent-scoped and channel-scoped), and sandbox configuration. The resulting tool set is what the LLM will see during inference.
Usage
Apply this principle whenever:
- Modifying how system prompts are constructed or how workspace files contribute to the prompt.
- Adding new directive types or changing how existing directives are parsed.
- Changing session initialization logic, compaction triggers, or history replay.
- Adjusting media understanding integration (when and how media descriptions enter the prompt).
- Understanding why a particular LLM call received certain tools, system instructions, or history.
Theoretical Basis
Context assembly follows a pipeline/middleware pattern where each stage transforms or enriches a shared context object. The pipeline has well-defined early-exit points: directive resolution and inline actions can short-circuit the pipeline and return a reply without ever reaching the LLM.
The assembly is designed for progressive enrichment:
- Start with the finalized
MsgContext(channel-agnostic envelope). - Enrich with media understanding (transcriptions, descriptions).
- Enrich with link understanding (URL summaries).
- Resolve command authorization.
- Initialize session state (history, scope, reset state).
- Apply session-level model overrides.
- Parse and resolve directives (think level, model, verbose, elevated).
- Handle inline actions (short-circuit if applicable).
- Stage sandbox media (copy attachments into the sandbox workspace).
- Delegate to
runPreparedReplyfor inference.
Each stage may produce side effects (persisting session state, emitting typing indicators) but the core data flow is linear: the context object grows richer at each step. The final handoff to runPreparedReply carries the fully assembled context including agent configuration, resolved model, tool set, directives, and session state.