OpenClaw Architecture

A comprehensive guide to sessions, memory, agents, channels, and orchestration — the building blocks of an AI agent runtime.

What is OpenClaw?

OpenClaw is an AI agent runtime that connects large language models to messaging channels. Think of it as an operating system for agents — not a chatbot framework.

Gateway architecture

One long-running process manages multiple channels and multiple agents simultaneously.

Multi-tenant

Each agent is fully isolated — own workspace, own state, own sandbox.

Not a chatbot

Agents can exec shell commands, browse the web, read/write files, manage calendars, and more.

# Start the gateway
openclaw gateway start

# It manages:
#  → Channels (WhatsApp, Telegram, Discord, …)
#  → Agents (each with own workspace)
#  → Sessions (conversation contexts)
#  → Tools (exec, browser, read, write, …)

Sessions

A session is the conversation context an agent holds with a user or group. It includes the full message history and any accumulated state.

Session Keys

Every session has a unique key that determines its scope:

// DM session key
agent:<agentId>:<mainKey>
// Example: agent:jarvis:whatsapp:peer:31612345678

// Group session key
agent:<agentId>:<channelType>:channel:<channelId>
// Example: agent:jarvis:discord:channel:123456789

Session Lifecycle

Event	Description
Daily reset	Sessions automatically reset at 4 AM (configurable) to prevent context bloat.
Idle reset	After a period of inactivity, sessions may be garbage-collected.
Manual reset	Users can type `/new` or `/reset` to start fresh.

DM Scoping Modes

main

Shared session across all DM channels for this peer.

per-peer

One session per peer, regardless of channel.

per-channel-peer

Separate session for each channel × peer combination.

Session Storage

Sessions are persisted as JSONL transcripts (one JSON object per line, per message) alongside a sessions.json store that tracks metadata.

state/
├── sessions.json            // Session metadata & keys
└── transcripts/
    └── <session-key>.jsonl  // Full message history

Memory

Memory in OpenClaw is refreshingly simple: it’s just files. The agent reads and writes plain Markdown files. No special database, no proprietary format.

Two-Layer Memory

MEMORY.md

Long-term memory — relationship context, user preferences, persistent facts. The agent updates this file as it learns.

memory/YYYY-MM-DD.md

Daily logs — what happened today. Auto-created, one file per day. Great for temporal queries (“what did we discuss yesterday?”).

Memory Search

Vector embeddings: Markdown chunks are embedded and indexed for semantic search — find relevant context even when keywords don’t match.
Hybrid search: Combines BM25 (keyword matching) with vector search for best-of-both-worlds retrieval.
Pre-compaction flush: Before the context window is compressed, the agent automatically saves important information to memory files.

workspace/
├── MEMORY.md              // Long-term memory
└── memory/
    ├── 2025-01-15.md      // Daily log
    ├── 2025-01-16.md
    └── ...

Agents

An agent is a workspace + state directory + sessions. Each agent has its own personality, tools, memory, and conversation history — fully isolated from other agents.

Workspace Files

File	Purpose
`AGENTS.md`	How the workspace works
`SOUL.md`	Agent personality & identity
`USER.md`	Info about the primary user
`IDENTITY.md`	Name, model, appearance
`TOOLS.md`	Tool usage notes
`BOOTSTRAP.md`	First-run instructions

Agent Routing (Bindings)

Bindings determine which agent handles which messages. They match on channel type, account ID, and peer patterns.

// gateway.json5 bindings example
{
  agents: {
    jarvis: {
      bindings: [
        { channel: "whatsapp", accountId: "31612345678" },
        { channel: "discord", accountId: "bot-token-id" },
        { channel: "telegram", peer: "jonas_*" },  // Peer pattern matching
      ]
    }
  }
}

Skills

Skills extend what an agent can do:

Bundled skills: Ship with OpenClaw (calendar, contacts, web search).
Managed skills: Installed via the skill registry, auto-updated.
Workspace skills: Custom scripts in the agent’s skills/ directory.

Channels

Channels are how agents communicate with the outside world. Each channel connects to the Gateway and routes messages to the appropriate agent via bindings.

End-to-end encrypted messaging

Bot API with rich formatting

Discord

Server and DM support

Slack

Workspace integration

Signal

Privacy-focused messaging

iMessage

Apple ecosystem

Web Chat

Browser-based interface

Channel Routing

Multi-account: Run two WhatsApp numbers or multiple Telegram bots through one Gateway.
Group chat: Agents respond when mentioned (@agent) or based on configurable trigger patterns.
Routing flow: Incoming message → channel identifies sender → binding lookup → matched agent handles it.

Orchestration

Message Flow

The end-to-end path of a message through the system:

Message → Channel → Gateway → Binding → Agent → Session → LLM → Response

Sub-Agents

Agents can spawn sub-agents via sessions_spawn for background tasks — research, long-running computations, or parallel work. Results are automatically reported back to the parent agent.

Cron Jobs & Tools

Cron: Schedule recurring tasks (heartbeats, daily summaries, data syncs) via the gateway config.
Tools: The agent’s hands — exec shell commands, read/write files, control a browser, search the web, send messages, and more.

# Tools available to agents
exec        # Run shell commands
read        # Read files
write       # Write files
browser     # Control web browser
web_search  # Search the web
message     # Send messages to channels
nodes       # Control paired devices
canvas      # Present UI to users