The Big Picture

OpenClaw is a 430K-line TypeScript project that turns any messaging platform into an interface for an autonomous AI agent. Instead of reading about it, explore the architecture below.

OpenClaw: The Full Topology
A hub-and-spoke architecture that composes familiar systems abstractions into an autonomous AI agent.
430K
Lines TypeScript
15+
Channels
5,705+
Skills
197K
GitHub Stars
WhatsApp
Baileys
Unofficial WA Web API via Baileys library
Telegram
grammY
Bot API via grammY framework
Discord
discord.js
Rich embeds, slash commands, voice
iMessage
native macOS
Native macOS AppleScript bridge
Slack
Bolt
Workspace bot via Slack Bolt SDK
+10 more
Matrix, Email...
Matrix, Gmail, Voice, SMS, and more
Gateway
WebSocket + Scheduler
Session Resolver
namespace isolation
Isolates each conversation's state
Context Assembler
prompt building
Builds prompt from AGENTS.md + SOUL.md + memory
Streaming LLM
Claude, GPT, etc.
Streaming inference with any provider
Tool Executor
5,705+ skills
Executes skills, web search, calendar, code
State Persister
JSONL + SQLite
Durable state in JSONL logs + SQLite
Memory System
MEMORY.md + search
Virtual memory: MEMORY.md, daily logs, embeddings
Primitive 1: Autonomous Invocation
The agent doesn't wait for messages. It can wake itself via cron, webhooks, voice, heartbeats, or Pub/Sub triggers, each scoped to an isolated session.
Click to expand trigger types
Cron schedules (daily summaries, check-ins)
Webhooks (GitHub, Stripe, custom)
Voice wake word detection
Heartbeat / keep-alive pings
Gmail Pub/Sub (email-triggered actions)
Session isolation per conversation
Primitive 2: Externalized Memory
Long-term memory lives on disk, not in the context window. The agent pages knowledge in and out like an OS manages virtual memory.
Click to expand memory components
MEMORY.md (persistent knowledge base)
Daily logs (memory/YYYY-MM-DD.md)
SQLite (structured session data)
Hybrid search (BM25 + vector similarity)
/compact command for context paging

"Composition, Not Invention" — familiar systems abstractions (message queues, schedulers, filesystems, virtual memory) composed into something new.

Three-Layer Architecture

The hub-and-spoke topology collapses into three clean layers, each with a single responsibility.

The Three-Layer Architecture
Here's how messages move through the system — from incoming connection to LLM response. Click any component for details.
Layer 1: Gateway
Routing + Scheduling
This is where connections come in. The gateway handles routing, payload validation, and scheduled triggers.
WebSocket Server
connections
Channel Manager
routing
Scheduler
cron + triggers
Control UI
dashboard
TypeBox Validator
schema
route
Layer 2: Channel Adapters
Normalize + Authorize
Each adapter wraps a platform's SDK and converts its messages into a common StandardMessage shape we can work with.
WhatsApp
Baileys
Telegram
grammY
Discord
discord.js
iMessage
native macOS
Slack
Bolt
Matrix
matrix-bot-sdk
dispatch
Layer 3: Agent Runtime
Reason + Execute
Where the actual thinking happens — resolve the session, build context, call the LLM, run tools, save state.
Session Resolver
namespace
Context Assembler
prompt
Streaming LLM
inference
Tool Executor
skills
State Persister
JSONL

Click a component to see what it does, which files matter, and how fast it needs to be.

Component
Layer
Description goes here.

Responsibilities

    Key Files

      The key idea: each layer stays in its lane. Gateway routes, adapters normalize, runtime reasons. When we keep those boundaries clean, the whole thing stays manageable.

      Message Flow

      Seeing the layers in isolation is one thing. Here’s what happens when an actual message flows through them.

      Message Journey: WhatsApp to Response
      Follow a single message through all three layers. Click any phase to expand its sub-steps.
      WhatsApp +1-555-0199
      →
      1
      Trigger
      ~5ms
      WhatsApp message from +1-555-0199: "What's the weather in Tokyo?"
      Webhook received from Baileys connection
      Idempotency key checked (message dedup)
      2
      Gateway
      ~8ms
      Route to correct adapter and session
      Channel identified: WhatsApp (Baileys)
      TypeBox schema validation passed
      Scheduler check: no pending cron conflicts
      3
      Adapter
      ~12ms
      Normalize and authorize the incoming message
      Baileys payload → StandardMessage format
      Allowlist check: +1-555-0199 authorized
      DM pairing verified (not a group message)
      4
      Runtime
      ~1.85s
      Resolve → Assemble → Invoke → Execute
      Session namespace loaded (<50ms)
      Prompt assembled: AGENTS.md + SOUL.md + memory (<100ms)
      Streaming LLM: first token (200-500ms)
      Tool call: weather_lookup("Tokyo") (1.2s)
      5
      Response
      ~15ms
      Format and deliver the reply to WhatsApp
      Markdown → WhatsApp formatting (bold, lists)
      Sent via Baileys connection to +1-555-0199
      Cumulative Latency
      0ms
      Total
      Trigger 0ms
      Gateway 0ms
      Adapter 0ms
      Runtime 0ms
      Response 0ms

      System Prompt Filesystem

      The runtime’s “brain” isn’t code — it’s a filesystem of markdown documents that compose into the system prompt.

      System Prompt as Filesystem
      The agent's identity, rules, and capabilities are composed from markdown files on disk. Skills are natural-language documents, not code.
      Session Directory
      AGENTS.md ~800
      SOUL.md ~600
      TOOLS.md ~400
      ▶ skills/
      weather/SKILL.md ~120
      calendar/SKILL.md ~150
      code-review/SKILL.md ~180

      Click any file to preview its content and role in the system prompt.

      File Type
      Role description
      Content
      Token Contribution to Assembled Prompt (~4,200 tokens)
      AGENTS
      SOUL
      TOOLS
      Skills
      Memory
      History
      AGENTS.md (800)
      SOUL.md (600)
      TOOLS.md (400)
      Active Skills (450)
      Memory Pages (900)
      Conversation History (1,050)
      ClawHub: Community Skills
      5,705+ skills
      weather
      Real-time weather data for any city worldwide
      12.4K installs
      google-calendar
      Read, create, and manage Google Calendar events
      8.9K installs
      code-review
      Automated code review with style and security checks
      6.2K installs
      web-search
      Search the web and summarize results
      15.1K installs
      notion-sync
      Sync notes and databases with Notion
      4.7K installs
      image-gen
      Generate images via DALL-E or Stable Diffusion
      9.3K installs

      Memory System

      The most distinctive primitive: long-term memory that lives on disk, not in the context window.

      Virtual Memory for Cognition
      Long-term memory lives on disk, not in the context window. The agent pages knowledge in and out like an OS manages virtual memory.
      LLM Context
      Cache (volatile)
      The active working set. Fast but limited. Everything here is lost when the conversation ends or context fills up.
      Context Usage 85%
      170K tokens used 200K limit
      System prompt (4.2K)
      Conversation history (95K)
      Tool results (48K)
      Memory pages (22.8K)
      Local Disk
      Source of truth (durable)
      Persistent storage that survives across sessions. Unlimited capacity. The ground truth for all agent knowledge.
      MEMORY.md 12KB
      memory/2026-02-16.md 3KB
      sessions.sqlite 8MB
      embeddings.db 24MB
      Search & Retrieval
      Page-in mechanism
      Dual search paths find relevant memories and page them back into context when needed.
      BM25 Keyword
      Exact term matching, fast
      Vector Similarity
      Semantic matching, flexible
      merge & re-rank
      Ranked Results
      Top-K memory pages paged into context
      /compact — Context Paging
      1
      Write durable notes from context to MEMORY.md
      ✓
      2
      Summarize conversation history (compress)
      ✓
      3
      Drop redundant tool outputs from context
      ✓
      4
      Rebuild context window with essential state only
      ✓
      Before
      170K tokens
      85% capacity
      →
      After
      50K tokens
      25% capacity

      "RAM is limited, disk is large, and paging decides what comes back." The OS metaphor that ties the entire architecture together.

      The entire system is an exercise in composition: message queues, schedulers, filesystems, and virtual memory, familiar abstractions from operating systems, recomposed into an AI agent.