·7 min read·v1.0.0
OpenClaw Architecture
Personal AI assistant gateway — 82 channel plugins, 40+ LLM providers, file-based sessions, extensible plugin SDK with 60+ subpath modules.
gatewaymulti-channelpluginsllm-providerspersonal-aimcp
View repository →UI (Lit + Native Apps)
Gateway & Core Engine
Storage & Memory
Channel & Provider Plugins
External Services
Config & Skills
CLI & Dev Tools
System Layers
Clients & Interfaces
🖥Control UILit + Vite web components
📱iOS AppSwiftUI + Observation
📱Android AppKotlin + Compose
🍎macOS AppSwiftUI menubar + Sparkle
>_CLICommander + Clack
Gateway Server
⚡Gateway ServerExpress 5 + Hono — HTTP/WS
🔀Channel ManagerRouting + delivery queue
🔐Auth Layertoken / password / trusted-proxy
🔌Plugin RuntimeRegistry + lifecycle + SDK
🪝Hooks EngineGlobal + per-channel hooks
Core Engine
🤖Agent Enginepi-agent-core + multi-agent
💬Session EngineJSONL transcripts + metadata
🧠Memory SystemEmbeddings + vector search
⏰Cron Schedulercroner-based scheduling
🔑Secrets ManagerCredential resolution + rate limits
Agent Capabilities
🛡Node SandboxIsolated tool execution
🌐Browser AutomationPlaywright + Canvas host
🎬Media Pipelinesharp + pdfjs + readability
🔧MCP ClientModel Context Protocol SDK
🎯Skills & ToolsAgent capabilities + definitions
Channel Plugins (82 extensions)
💬Discord
💬Slack
💬Telegram
💬WhatsApp
💬Signal
💬iMessage
💬Matrix
💬MS Teams
💬IRC
💬Google Chat
💬Line
💬Feishu
📞Voice Call
++12 more channels
LLM Provider Plugins (40+)
🧠AnthropicClaude models
🧠OpenAIGPT models
🧠GoogleGemini models
🧠DeepSeek
🧠xAIGrok
🧠OllamaLocal models
🧠Groq
🧠Mistral
🧠Bedrock
++20 more providers
Data & Storage
📄JSONL SessionsFile-based transcripts
🔍sqlite-vecVector embeddings store
📁Agent WorkspacesIsolated per-agent dirs
🔒Credentials Store~/.openclaw/credentials/
⚙Config (YAML)~/.openclaw/config.yml
Core Flow — Message Lifecycle
1
Inbound message — Channel plugin receives via webhook, WebSocket, or polling (e.g. extensions/discord/src/channel.ts)
↓
2
Route & session resolve — src/routing/ parses session key (agent scope, user ID, thread ID) and resolves to a session entry
↓
3
Gateway dispatch — src/gateway/server.impl.ts loads agent config, resolves provider credentials, applies hooks
↓
4
Agent execution — src/agents/ invokes pi-agent-core with context tokens, tools, memory, and selected LLM model
↓
5
Tool & memory calls — Agent runs tools in Node sandbox, queries sqlite-vec embeddings, browses via Playwright, processes media
↓
6
LLM provider call — Request routed to provider plugin (Anthropic, OpenAI, etc.) with fallback chain support
↓
7
Response delivery — Final reply enters delivery queue, channel plugin formats and sends outbound; transcript appended to JSONL
Authentication Model
Gateway Auth
Four modes via gateway.auth.mode:
"none" — No auth (local dev)
"token" — Bearer token in header (default)
"password" — Prompted on first connection
"trusted-proxy" — Tailscale/reverse proxy
Surfaces: http and ws-control-ui
Defined in src/gateway/auth.ts
Provider & Channel Auth
Per-provider API keys in src/secrets/
OAuth flows (Google, Microsoft, OpenAI)
Rate limiting per provider
Fallback chains for model failover
Device pairing for mobile clients
Token rotation for long-lived sessions
Credentials stored at ~/.openclaw/credentials/
Key Subsystem — Plugin Architecture
extensions/<plugin-id>/ ├── openclaw.plugin.json ← Manifest: id, channels, configSchema ├── package.json ← Runtime deps (no workspace:*) └── src/ ├── channel.ts ← Channel adapter implementation ├── api.ts ← Public barrel export (internal use) └── runtime-api.ts ← Runtime-only exports src/plugins/ ← Plugin runtime host ├── registry.ts ← Discovery + lifecycle management └── loader.ts ← Dynamic import + context injection openclaw/plugin-sdk/ ← 60+ subpath exports ├── channel-setup, channel-runtime, channel-inbound ├── provider-setup, config-runtime, reply-runtime └── tools, hooks, routing, security, infra, media
Data Model & Storage
Session (JSONL)
session_key, agent_id, channel_id, transcript (JSONL lines), metadata.json, cost estimation, avatar
Agent Workspace
agent_id, config (per-agent), model selection, tools, behaviors, context_tokens budget
Memory (sqlite-vec)
embedding_id, vector, content, multilingual-e5 / llama-text-embed, similarity search index
Channel Account
channel_id, account_id, capabilities (send, receive, threads), health status, pairing state
Config (YAML)
gateway, agents, channels, models, providers, secrets, hooks, cron, tools definitions
Plugin Manifest
id, channels[], configSchema, npmSpec, channel.id, openclaw.plugin.json per extension
Cron History
schedule, last_run, next_run, retention policy, croner-based execution log
Credentials
provider_name, api_key/oauth_token, rate_limit counters, ~/.openclaw/credentials/ store
Package / Directory Map
openclaw/ ├── src/gateway/ Gateway server (Express+Hono, 50KB+ impl) ├── src/agents/ Agent engine, multi-agent isolation ├── src/channels/ Channel registry, capabilities, pairing ├── src/sessions/ Session lifecycle, transcripts, archives ├── src/plugins/ Plugin runtime, registry, loading ├── src/routing/ Session key parsing, delivery context ├── src/hooks/ Global + per-channel hook engine ├── src/config/ Schema (641KB), Zod validators, migrations ├── src/secrets/ Credential resolution, rate limits ├── src/memory/ Embeddings backend config ├── src/cli/ CLI wiring (Commander + Clack) ├── src/commands/ CLI command implementations ├── src/media/ Download, upload, format conversion ├── src/browser/ Playwright automation ├── src/node-host/ Node sandbox for tool execution ├── src/canvas-host/ Canvas rendering host ├── src/infra/ Low-level utilities (env, paths, logging) ├── extensions/ 82 plugins (channels + providers + utils) │ ├── discord/ Discord channel adapter │ ├── slack/ Slack channel adapter │ ├── telegram/ Telegram channel adapter │ ├── anthropic/ Anthropic provider plugin │ ├── openai/ OpenAI provider plugin │ ├── memory-core/ Memory/embeddings shared │ └── ... +76 more extensions ├── ui/ Control UI (Lit + Vite web components) ├── apps/ios/ iOS app (SwiftUI) ├── apps/android/ Android app (Kotlin + Compose) ├── apps/macos/ macOS menubar app (SwiftUI + Sparkle) ├── skills/ Agent skill definitions ├── docs/ Mintlify documentation ├── .agents/ Agent config + CI workflows ├── packages/ Workspace packages └── scripts/ Build + automation scripts
CLI Command Surface
openclaw setup
Initialize local config, Create agent workspace
openclaw gateway run
Start HTTP/WS server, --bind / --port / --force
openclaw onboard
Interactive onboarding, Gateway / workspace / skills
openclaw message
send / read / reactions, threads / pins / manage
openclaw agents
list / create / delete, auth / routing config
openclaw doctor
Health checks + fixes, Migration diagnostics
openclaw sessions
list / read / delete, archive conversations
openclaw status
Channel health + probes, Recent recipients
The Architectural Insight
OpenClaw is a personal AI gateway that treats every messaging platform as a pluggable channel and every LLM as a swappable provider. The 82-extension plugin system with its 60+ SDK subpath modules makes it possible to add a new channel or provider without touching core — the gateway simply routes messages between any channel and any model through a unified session, memory, and tool execution layer.