Chapter 2: OpenClaw Architecture

Understanding OpenClaw's architecture demystifies everything else. The system is built as a composable pipeline: You → Channel → Gateway → Agent → Tools → World. The Channel (WhatsApp, desktop, CLI) ingests your message, the Gateway daemon orchestrates everything, the Agent (an AI model) decides what to do, and Tools are the hands that actually take action—reading files, running shell commands, controlling browsers, sending messages. The Gateway is the central piece of infrastructure: a long-running daemon that listens on all channels, manages session contexts, executes cron jobs, maintains workspace state, and handles node connections. It's configured via ~/.openclaw/openclaw.json, and after any config change you must restart it with openclaw gateway restart.

Sessions are the unit of isolation in OpenClaw. Every conversation runs in a session with its own message history and agent instance. The main session is labeled agent:main:main; sub-agents get agent:main:subagent:{id}. Sessions have a context window—older content gets compacted when it fills up, which is a design constraint for long-running workflows (covered in Chapter 8 on memory). Multiple sessions can run simultaneously, and the subagents tool lets the main agent list, steer, or kill running sub-sessions. Tools are gated by policy in openclaw.json, with some running freely and others requiring explicit user confirmation. The exec tool is the most powerful and dangerous—it runs arbitrary shell commands and should be restricted with security: "allowlist" for most automation.

The workspace is a local filesystem directory where everything OpenClaw does with files happens. Conventionally it includes AGENTS.md (the agent operating manual), SOUL.md (identity and principles), MEMORY.md (persistent cross-session memory), USER.md (user profile), a memory/ folder with daily logs, a projects/ folder for active work, and protocols/ for operating procedures like HEARTBEAT.md. Config files are layered: openclaw.json controls runtime behavior (needs restart on change), while SOUL.md, AGENTS.md, MEMORY.md, and USER.md are read fresh at each session start. A complete request trace—say, checking sales data via WhatsApp—involves channel ingestion, context loading (reading SOUL/MEMORY/USER files), AI planning, sequential tool execution, memory update, and response delivery, typically in 15-30 seconds.

Key Patterns

  • Pipeline model: You → Channel → Gateway → Agent → Tools → World; composable and chainable
  • Gateway as singleton: One persistent daemon per machine; all channels connect to it; restart after config changes
  • Session isolation: Each conversation has its own context window; sub-agents are labeled agent:main:subagent:{id}
  • Tool policy gating: openclaw.json controls which tools are available and at what security level (deny/allowlist/full)
  • Workspace-as-boot: SOUL.md, MEMORY.md, USER.md are read at every session start to restore identity and context

Reference Appendices

Agent Patterns