Workflow:Openclaw Openclaw Agent Message Loop
| Knowledge Sources | |
|---|---|
| Domains | LLMs, Agent_Runtime, Message_Routing |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
End-to-end process for routing an inbound user message through the OpenClaw agent runtime, executing tool calls, and delivering the final reply back to the originating channel.
Description
This workflow describes the core message processing loop that powers every interaction in OpenClaw. When a user sends a message on any connected channel, the gateway routes it to the appropriate agent based on binding rules. The agent assembles context (system prompt, session history, workspace files, skills), calls the LLM provider, processes any tool invocations (file operations, browser control, web search, memory), and streams the final reply back through the channel adapter. This loop repeats for each user turn in a conversation.
Key outputs:
- Agent reply delivered to the originating messaging channel
- Session history updated with the new turn
- Tool side effects applied (files written, commands executed, memory updated)
- Token usage tracked for cost monitoring
Usage
This workflow executes automatically every time a user sends a message to the agent via any connected channel (WhatsApp, Telegram, Discord, Slack, web UI, CLI). It is the fundamental interaction pattern of OpenClaw.
Execution Steps
Step 1: Message Ingestion
An inbound message arrives from a connected channel adapter. The adapter normalizes the message into a common envelope format containing the sender identity, channel metadata, message content (text, media, or both), and timestamp.
Key considerations:
- Media attachments (images, audio, video, documents) are downloaded and processed
- Audio messages are transcribed using the configured speech-to-text provider
- Images can be auto-described via the media understanding pipeline
- The envelope includes channel-specific metadata (group ID, thread ID, reaction context)
Step 2: Session Resolution
The gateway resolves which agent and session should handle the message using the binding rules and session key derivation. The session key is deterministic, based on the agent ID, channel, and peer identity (DM partner or group ID).
What happens:
- Binding rules checked from most-specific to least-specific match
- Session key computed (e.g., agent:main:whatsapp:dm:+15551234567)
- Existing session loaded from disk if available
- DM policy checked (pairing approval, allowlist, or open access)
Step 3: Context Assembly
The agent assembles the full prompt context sent to the LLM provider. This includes the system prompt (built from workspace files), session history, available tools, and any injected context from skills or hooks.
What happens:
- System prompt assembled from AGENTS.md, SOUL.md, USER.md, TOOLS.md
- Session history loaded and pruned if near context limits
- Available tools enumerated (built-in + skill-provided + plugin-provided)
- Memory search results injected if relevant
- Compaction applied if context exceeds the configured threshold
Step 4: LLM Inference
The assembled context is sent to the configured LLM provider (Anthropic, OpenAI, Ollama, etc.) for inference. The agent handles streaming responses, tool call requests, and multi-turn tool loops where the model requests a tool, receives results, and continues reasoning.
Key considerations:
- Model selected per agent config (primary model, with optional fallback)
- Streaming enabled for supported channels (partial or block streaming)
- Tool calls executed in sequence or parallel as requested by the model
- Failover to fallback model if primary fails (timeout, rate limit, error)
- Thinking/reasoning level configurable per request
Step 5: Tool Execution
When the LLM requests tool use, the gateway dispatches the tool call to the appropriate handler. Tools include file operations, shell command execution, browser control, web search/fetch, memory search, canvas rendering, and node commands (camera, location).
What happens:
- Tool input validated against JSON schema
- Sandbox policy checked (run in Docker container or host)
- Tool executed with timeout and output size limits
- Results returned to the LLM for continued reasoning
- Multiple tool rounds may occur before final reply
Step 6: Reply Delivery
The final assistant reply is formatted for the target channel and delivered. Markdown formatting is adapted per channel (WhatsApp bold syntax differs from Telegram). Long replies may be chunked to fit platform message limits.
Key considerations:
- Channel-specific markdown formatting applied
- Message chunking for platforms with size limits (WhatsApp 4096, Slack 4000)
- Media attachments (images, files) delivered alongside text
- Typing indicators shown during processing on supported channels
- Session history updated with the complete turn