OpenClaw Architecture Overview

This is the top-level map. All other architecture documents branch from here.

Based on OpenClaw version 2026.2.23 (commit aceb17a).

High-level architecture

Message flow (inbound → outbound)

A message from Telegram to a reply, step by step:

1. Telegram webhook delivers message
        ↓
2. extensions/telegram/ normalizes to common format
        ↓
3. src/channels/plugins/ — Channel Plugin Manager receives message
        ↓
4. src/routing/resolve-route.ts — matches bindings to find agentId + sessionKey
   (binding priority: peer → guild+roles → guild → team → account → channel → default)
        ↓
5. src/auto-reply/ — command parsing (/help, /new, /model), directive handling
        ↓
6. src/agents/pi-embedded-runner/run.ts — runEmbeddedPiAgent()
   a. Load session history from JSONL transcript
   b. Build system prompt (identity + skills + tools + memory context)
   c. Select model + provider from config/overrides
   d. Execute Pi Agent loop: LLM → tool calls → execute → LLM → ...
   e. Stream text chunks back via block reply pipeline
   f. Append turn to session transcript
   g. Auto-compact if context exceeds limits
        ↓
7. src/channels/plugins/outbound/ — send reply to Telegram API

Module index

Each module has its own detailed document. Status indicates writing progress.

Module	File	Key source paths	Status
Gateway	Gateway	`src/gateway/server.impl.ts`, `server.ts`, `server-http.ts`	Done
Pi Agent Runtime	Pi Agent Runtime	`src/agents/pi-embedded-runner/`, `pi-embedded.ts`	Done
Channel Plugins	Channel Plugins	`src/channels/plugins/types.plugin.ts`, `extensions/*/`	Done
Routing	Routing	`src/routing/resolve-route.ts`, `bindings.ts`, `session-key.ts`	Done
Auto-Reply Pipeline	Auto-Reply Pipeline	`src/auto-reply/reply/agent-runner-execution.ts`	Done
Tool Policy	Tool Policy	`src/agents/tool-policy-pipeline.ts`, `tool-policy.ts`	Done
Skills System	Skills System	`src/agents/skills/workspace.ts`, `skills.ts`	Done
Memory (RAG)	Memory (RAG)	`src/memory/manager.ts`, `hybrid.ts`, `embeddings.ts`	Done
Sessions	Sessions	`src/sessions/`, `src/gateway/session-utils.ts`	Done
Cron & Heartbeat	Cron & Heartbeat	`src/cron/service.ts`, `service/timer.ts`, `service/jobs.ts`	Done
Config System	Config System	`src/config/io.ts`, `types.openclaw.ts`, `zod-schema.ts`	Done
Plugin SDK	Plugin SDK	`src/plugin-sdk/index.ts` (543 lines, 18+ adapter types)	Done
Control UI (Canvas)	Control UI (Canvas)	`ui/src/ui/app.ts`, `gateway.ts`	Done
Native Apps	Native Apps	`apps/macos/`, `apps/ios/`, `apps/android/`	Done

Cross-module patterns

Recurring design patterns that span multiple modules. See patterns index.

Pattern	File	Modules involved
Markdown-as-Config	Markdown-as-Config	Skills, Memory, Config
Append-Only JSONL	Append-Only JSONL	Sessions, Cron
Ed25519 Device Auth	Ed25519 Device Auth	Gateway, Control UI, Native Apps, Pairing
Cascading Config	Cascading Config	Config, Tool Policy
Context Overflow Recovery	Context Overflow Recovery	Pi Agent Runtime, Compaction

Deep dives

Code-level walkthroughs of high-impact subsystems. See deep-dives index.

Topic	File	Core source
Compaction Internals	Compaction Internals	`src/agents/compaction.ts` (406 lines)
Heartbeat Cost Analysis	Heartbeat Cost Analysis	`src/cron/service/timer.ts` (877 lines)
Context Budget Allocation	Context Budget Allocation	`src/agents/pi-embedded-runner/run.ts`, `defaults.ts`

Key architectural decisions (verified from source)

Single process: The Gateway (src/gateway/server.impl.ts) runs everything in one Node.js process — WebSocket server, HTTP API, channel plugins, agent runtime, cron. Default port 18789, with Canvas Host on port+1 and Browser Control on port+2.
Local-first persistence: Sessions as append-only JSONL files (~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl). Memory as SQLite with vector extensions (memory.db). Config as JSON5 with env var substitution (openclaw.json). No cloud dependency.
BYOM (Bring Your Own Model): The Pi Agent SDK (@mariozechner/pi-agent-core) abstracts the LLM provider. Supports Anthropic, OpenAI, Google Gemini, xAI Grok, DeepSeek, Mistral, Ollama, and more. Model selection per agent, per session, or per turn.
Markdown-as-Config: Skills are SKILL.md files with YAML frontmatter. Memory notes are Markdown. Agent workspace files are Markdown. All human-readable, Git-friendly, and natively parseable by LLMs.
Channel-agnostic plugin architecture: Each messaging platform is an extension package (extensions/*/) that implements the ChannelPlugin interface from src/channels/plugins/types.plugin.ts. 38 extensions currently, each with ~15 adapter types (config, security, outbound, status, gateway, threading, etc.).
Monorepo with pnpm workspaces: Root package + ui/ + extensions/* as workspace members. Build via tsdown. TypeScript 5.9, Node.js 22+, strict mode.

Source directory structure

openclaw/
├── src/                          # Core source (48 subdirectories)
│   ├── gateway/                  # Gateway server, WebSocket, HTTP, Control UI
│   ├── agents/                   # Pi Agent runtime, skills, tools, sessions, models
│   ├── channels/                 # Channel plugin infrastructure + types
│   ├── routing/                  # Message routing (bindings → agent + session)
│   ├── auto-reply/               # Inbound message → agent turn pipeline
│   ├── config/                   # openclaw.json loading, validation, schema
│   ├── memory/                   # RAG: SQLite vector + FTS5, embeddings, hybrid search
│   ├── sessions/                 # Session key utils, persistence
│   ├── cron/                     # Cron service, heartbeat, scheduled jobs
│   ├── security/                 # Audit, tool policy, dangerous tools list
│   ├── plugins/                  # Plugin SDK types, runtime, loading
│   ├── plugin-sdk/               # Public SDK for extension authors (544-line index.ts)
│   ├── hooks/                    # Lifecycle hooks system
│   ├── cli/                      # CLI wiring
│   ├── commands/                 # CLI commands (gateway, setup, doctor, etc.)
│   ├── browser/                  # Playwright browser automation
│   ├── media/                    # Media processing pipeline
│   ├── media-understanding/      # Image/video analysis
│   ├── tts/                      # Text-to-speech
│   ├── markdown/                 # Markdown utilities
│   ├── infra/                    # Infrastructure helpers
│   ├── logging/                  # Logging system
│   ├── pairing/                  # Device pairing protocol
│   ├── process/                  # Process management
│   ├── providers/                # LLM provider configs
│   ├── shared/                   # Shared utilities
│   ├── types/                    # Common type definitions
│   ├── utils/                    # General utilities
│   ├── web/                      # Web server helpers
│   ├── wizard/                   # Setup wizard
│   ├── telegram/                 # Telegram-specific src (shared with extension)
│   ├── discord/                  # Discord-specific src
│   ├── whatsapp/                 # WhatsApp-specific src
│   ├── slack/                    # Slack-specific src
│   ├── signal/                   # Signal-specific src
│   ├── imessage/                 # iMessage-specific src
│   ├── line/                     # LINE-specific src
│   └── ...
│
├── extensions/                   # 38 extension packages
│   ├── telegram/                 # @openclaw/telegram
│   ├── discord/                  # @openclaw/discord
│   ├── whatsapp/                 # @openclaw/whatsapp
│   ├── slack/                    # @openclaw/slack
│   ├── signal/                   # @openclaw/signal
│   ├── imessage/                 # @openclaw/imessage (via BlueBubbles)
│   ├── matrix/                   # @openclaw/matrix
│   ├── msteams/                  # @openclaw/msteams
│   ├── feishu/                   # @openclaw/feishu (Lark)
│   ├── irc/                      # @openclaw/irc
│   ├── nostr/                    # @openclaw/nostr
│   ├── twitch/                   # @openclaw/twitch
│   ├── memory-core/              # Core memory extension
│   ├── memory-lancedb/           # LanceDB memory backend
│   ├── voice-call/               # Voice call support
│   ├── phone-control/            # Phone automation
│   ├── llm-task/                 # LLM task delegation
│   ├── diagnostics-otel/         # OpenTelemetry diagnostics
│   └── ...
│
├── skills/                       # 52 bundled skills (SKILL.md format)
│   ├── github/                   # GitHub operations via gh CLI
│   ├── slack/                    # Slack channel tools
│   ├── canvas/                   # Canvas display actions
│   ├── coding-agent/             # Delegate to Codex/Claude Code
│   ├── obsidian/                 # Obsidian integration
│   ├── notion/                   # Notion integration
│   └── ...
│
├── ui/                           # Control UI (Lit + Vite)
│   ├── src/ui/app.ts             # Main <openclaw-app> component
│   ├── src/ui/gateway.ts         # WebSocket client (Ed25519 device auth)
│   └── vite.config.ts            # Builds to dist/control-ui/
│
├── apps/                         # Native clients
│   ├── macos/                    # Swift 6 / SwiftUI, menu bar app (macOS 15+)
│   ├── ios/                      # Swift 6 / SwiftUI, XcodeGen (iOS 18+)
│   ├── android/                  # Kotlin / Jetpack Compose (API 31+)
│   └── shared/OpenClawKit/       # Shared Swift package
│
├── package.json                  # name: openclaw, version: 2026.2.23
├── pnpm-workspace.yaml           # Monorepo: root + ui + extensions/*
├── tsconfig.json                 # strict, NodeNext, es2023
└── tsdown.config.ts              # Build entry points

Config structure (openclaw.json)

Verified from src/config/types.openclaw.ts and Zod schema:

{
  "agents": {
    "defaults": {
      "provider": "anthropic",
      "model": "claude-opus-4-6",
      "thinking": "auto",
      "compaction": { "enabled": true },
      "sandbox": { "tools": { "allow": ["*"], "deny": [] } },
      "skills": { "allowlist": ["*"] }
    },
    "list": [
      { "id": "default", "name": "OpenClaw", "avatar": "🦞" }
    ]
  },
  "channels": {
    "telegram": [{ "accountId": "bot1", "botToken": "${TELEGRAM_BOT_TOKEN}", "dmPolicy": "open" }],
    "discord": [{ "accountId": "bot1", "botToken": "${DISCORD_BOT_TOKEN}", "dmPolicy": "open" }]
  },
  "bindings": [
    { "match": { "channel": "telegram" }, "agentId": "default" }
  ],
  "gateway": { "enabled": true, "port": 18789, "bind": "loopback" },
  "cron": { "enabled": true, "heartbeat": { "enabled": true, "intervalSeconds": 600 } },
  "memory": { "provider": "openai", "model": "text-embedding-3-small", "enabled": true }
}

Honest record of what I don't yet understand. Updated as knowledge grows.

#OpenClaw Architecture Overview

#High-level architecture

#Message flow (inbound → outbound)

#Module index

#Cross-module patterns

#Deep dives

#Key architectural decisions (verified from source)

#Source directory structure

#Config structure (openclaw.json)

#My blind spots