OpenClaw

Architecture

A comprehensive deep dive into the architecture of
your self-hosted personal AI assistant platform

Node.js 22+TypeScriptSQLite + sqlite-vec32+ Channels59+ Tools54 Skills
Scroll to explore↓
32+
Channel Extensions
59+
Agent Tools
54
Skills
8+
LLM Providers
177+
CLI Commands
01

What is OpenClaw?

▼

OpenClaw is your personal AI assistant that runs on YOUR computer — not someone else's server. It connects to all your messaging apps and can respond to messages, run tasks, and remember things for you.

🦞 How OpenClaw Works

📱
Message Arrives
Someone texts you on WhatsApp, Telegram, Slack, etc.
→
🔌
Channel Connector
OpenClaw has "connectors" for 32+ messaging apps
→
🎛️
Control Center
The "Gateway" routes messages to the right place
→
🤖
AI Brain
Uses Claude, GPT-4, or other AI models to think
→
✉️
Reply Sent
Response goes back through the same app

🧩 The Main Parts

📱
Messaging Connectors
What it does: Connects to your messaging apps

Supported apps: WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, and 25+ more

How it works: Each app has its own "connector" that knows how to send and receive messages for that app
32+ APPS
🎛️
The Gateway (Control Center)
What it does: The brain that coordinates everything

Main jobs: Routes messages to the right place, keeps track of conversations, manages settings

Runs at: localhost:18789 on your computer
CENTRAL HUB
🤖
AI Agent (The Smart Part)
What it does: The AI that actually thinks and responds

AI models: Works with Claude, GPT-4, Gemini, or local models like Llama

Special powers: Can use 59+ tools to browse the web, run commands, search memory, and more
AI POWERED
🛠️
Tools (AI Superpowers)
What it does: Gives the AI abilities beyond just chatting

Examples: Read/write files, browse websites, run code, send messages, search your memory, schedule tasks

Safety: Tools can be restricted so the AI only does safe things
59+ TOOLS
🧠
Memory (Remembers Things)
What it does: Stores information so the AI can remember past conversations

How it works: Uses a local database to store and search through memories

Smart search: Can find relevant memories even if you don't use exact words
LONG-TERM MEMORY
⏰
Heartbeat (Stays Active)
What it does: Wakes up the AI periodically to check on things

Default: Checks every 30 minutes

Uses: Reminders, monitoring tasks, sending scheduled messages, background automation
PROACTIVE

💾 Where Your Data Lives

Everything is stored in a folder on your computer called ~/.openclaw/

📝 Conversations
All your chat history saved as text files
🧠 Memory Database
Searchable knowledge stored locally
⚙️ Settings
Your configuration and preferences
🔑 API Keys
Your AI provider credentials (encrypted)

⚡ Quick Facts

✅Runs entirely on your computer
✅Works with 8+ AI providers (Claude, GPT-4, etc.)
✅Connects 32+ messaging apps
✅Has 59+ built-in tools for the AI
✅Can run in Docker or as a system service
✅Open source and customizable
02

Messaging Channels

▼

OpenClaw connects to 32+ messaging platforms through dedicated channel adapters. Each adapter implements the ChannelPlugin interface with adapters for auth, messaging, status, security, and more.

Core Channels (Built-in)

💬
WhatsApp
@whiskeysockets/baileys
Multi-device, media, groups, reactions
✈️
Telegram
grammY framework
Bot API, inline queries, formatting
💼
Slack
@slack/bolt
Workspaces, threads, reactions
🎮
Discord
discord-api-types
Servers, voice, slash commands
🔐
Signal
signal-utils
E2E encryption, disappearing msgs
🍎
iMessage
imsg / BlueBubbles
macOS native, tapbacks

Extension Channels (32 plugins)

🏢
Microsoft Teams
🔷
Matrix
💬
Mattermost
☁️
Nextcloud Talk
📺
Twitch
🌐
WebChat
💙
Zalo
🟢
LINE
📞
Voice Call
🔮
Nostr
🍎
BlueBubbles
🌊
Tlon
📧
Google Chat
💜
Viber
🟩
WeChat
Channel Plugin Interface
interface ChannelPlugin { ChannelAuthAdapter // OAuth/login handling ChannelConfigAdapter // Configuration ChannelMessagingAdapter // Send/receive messages ChannelOutboundAdapter // Message delivery ChannelStatusAdapter // Health checks ChannelHeartbeatAdapter // Periodic monitoring ChannelStreamingAdapter // Real-time streaming ChannelThreadingAdapter // Thread context ChannelGroupAdapter // Group management ChannelSecurityAdapter // DM policy ChannelCommandAdapter // Slash commands }
03

Gateway Control Plane

▼

The Gateway is the central nervous system of OpenClaw. Running on localhost:18789, it uses a WebSocket + NDJSON protocol with 27+ RPC method categories for all communication.

🔀
Channel Router
Routes by session key, handles DM/Group, manages allowlists, bindings system
📋
Session Manager
Session state, locking, JSONL transcripts, compaction with backup rotation
⚙️
Config System
Hot-reload, Zod validation, YAML/JSON5 support, runtime updates
🖥️
Node Registry
Device identity, TLS fingerprints, Bonjour/mDNS discovery, Tailscale
📡
Wire Protocol
NDJSON over WebSocket, sequence numbers, gap detection, handshake
🔌
RPC Methods
27+ handler categories: agent, chat, send, cron, models, tts, browser, and more
Gateway RPC Methods (Selection)
// Agent & Chat agent // Run agent inference agent.wait // Await completion chat.send // Send message to agent chat.history // Message history // Sessions & Channels sessions.list // List all sessions channels.status // All channels health send // Route to channel // Scheduling & System cron.add/run // Scheduled jobs health // Health check models.list // Available models tts.convert // Text-to-speech browser.request // Browser automation
04

Agent Execution Layer

▼

The Pi Embedded Runner executes agent sessions through a sophisticated pipeline that loads workspaces, configures tools, and manages streaming responses. Supports multi-agent architecture with subagent spawning.

1. Resolve Workspace & Sandbox
Determine execution environment, set up file system boundaries, configure security sandbox (Docker/gateway/node/elevated)
2. Load Skills & Bootstrap
Read SOUL.md, USER.md, BOOTSTRAP.md, TOOLS.md. Load 54 available skills and persona configuration
3. Create Tools (59+ available)
Initialize tool suite: read, write, edit, exec, browser, message, memory_search, web_fetch, web_search, canvas, cron, tts, sessions_spawn...
4. Build System Prompt
Construct complete system prompt from identity, tools, context, session history, and channel-specific context
5. Create Agent Session
Select auth profile, configure model parameters, establish LLM connection with automatic failover
6. Execute with Streaming
Process user message, stream responses, handle tool calls, persist to transcript, manage subagent spawning

Supporting Systems

🔑
Auth Profiles
Multi-profile rotation, cooldown tracking, usage balancing, OAuth + API key support
🤖
Model Registry
Provider catalog, capability mapping, context window awareness, intelligent routing
🔄
Model Failover
Primary/secondary chains, context overflow recovery, rate limit retries, cost optimization
👥
Subagent System
Spawn child agents, model selection per subagent, session inheritance, announcement queues
05

Tools Layer (59+ Tools)

▼

OpenClaw provides 59+ tools that the agent can invoke. Each tool operates within configurable security boundaries. Tools are organized by category with dedicated implementations.

File & Code Operations

read
Read files
write
Write files
edit
Diff-based edit
exec
Shell commands
process
Background procs

Web & Browser

web_fetch
HTTP requests
web_search
Web search
browser
Playwright automation
link_preview
URL previews

Communication

message
Send via channel
slack_actions
Slack-specific
telegram_actions
Telegram-specific
discord_actions
Discord guild/mod
whatsapp_actions
WhatsApp-specific

Session & Memory

sessions_list
List sessions
sessions_send
Send to session
sessions_history
Session history
sessions_spawn
Create subagent
memory_search
Semantic search

Media & UI

image
Image gen/process
canvas
A2UI adaptive UI
tts
Text-to-speech
media_understand
OCR/vision

System & Scheduling

cron
Schedule jobs
gateway
Gateway ops
nodes
Node management
agents_list
Multi-agent mgmt

Security Layers

sandbox
Docker container isolation. Fully isolated filesystem with configurable RW/RO mounts.
gateway
Local execution with allowlists. Safe binaries only, approval prompts for dangerous commands.
node
Remote paired devices. Execute on other machines via Tailscale or direct connection.
elevated
Full access bypass. Configurable for trusted environments. Use with caution.
06

LLM Providers (8+)

▼

OpenClaw supports 8+ LLM providers with intelligent failover, load balancing, and context window awareness. Configure multiple API keys per provider for redundancy and cost optimization.

Anthropic
Claude Opus 4.5, Sonnet, Haiku
OpenAI
GPT-4o, o1, GPT-4 Turbo
Google Gemini
Gemini 2.0, 1.5 Pro, Flash
AWS Bedrock
Claude, Mistral, Cohere
Ollama
Llama 3, Mistral (local)
GitHub Copilot
VS Code integration
Qwen
Portal auth
Venice / Custom
HTTP providers
~/.openclaw/agents/<agentId>/auth.json
{ "profiles": [ { "name": "primary", "provider": "anthropic", "apiKey": "sk-ant-...", "rateLimit": 1000, "cooldown": 60 }, { "name": "backup", "provider": "openai", "apiKey": "sk-..." } ], "rotation": "round-robin", "failover": true }
07

Heartbeat & Cron System

▼

OpenClaw has two proactive systems: the Heartbeat for periodic task checking (HEARTBEAT.md), and the Cron scheduler for arbitrary scheduled jobs. Both enable autonomous agent behavior.

Heartbeat System

⏰
Timer
Every 30m
→
✅
Guards
Check conditions
→
📄
Read
HEARTBEAT.md
→
🤖
Evaluate
Agent processes
→
💬
Deliver
Send alert
Heartbeat Triggers
• Interval timer (30m default)
• Exec completion events
• Cron job completion
• Manual wake request
Skip Conditions
• Outside active hours (quiet)
• Queue size > 0
• Empty HEARTBEAT.md
• Heartbeat disabled
Cron Scheduler
• croner library
• One-shot and recurring
• Run logs and history
• Isolated agent execution
config.yml - Heartbeat & Cron
heartbeat: every: "30m" target: "last" ackMaxChars: 300 activeHours: start: "09:00" end: "22:00" cron: jobs: - name: "daily-summary" schedule: "0 9 * * *" command: "Generate daily summary"
08

Persistence & Storage

▼

All data is stored locally in ~/.openclaw/. Sessions use JSONL files for append-only transcripts, while the memory index uses SQLite with sqlite-vec for vector search.

💾
Session Storage
~/.openclaw/sessions/

• sessions.json - Metadata
• transcripts/<agent>/*.jsonl
• Compaction + backup rotation
• Lock management
🧠
Memory Index
~/.openclaw/memory/

• SQLite + sqlite-vec
• chunks_vec - Vector search
• chunks_fts - FTS5 full-text
• Hybrid BM25 + vector
📁
Workspace Files
~/.openclaw/workspace/

• SOUL.md - Agent identity
• USER.md - User information
• HEARTBEAT.md - Tasks
• TOOLS.md - Custom tools
⚙️
Configuration
~/.openclaw/

• config.yml - Main config
• agents/*/auth.json - Keys
• exec-approvals.json
• Allowlists

Context Management Pipeline

Session Load
Load .jsonl
→
History Limit
Keep last N turns
→
Context Prune
Trim tool results
→
Compaction
Summarize if needed

Memory Search Pipeline

Sources
MEMORY.md, Sessions
→
Chunking
512 tokens/chunk
→
Embedding
OpenAI/Gemini
→
Hybrid Search
Vector + BM25
09

CLI & Terminal UI

▼

OpenClaw provides a comprehensive CLI with 177+ commands built on Commander.js, plus an interactive Terminal UI (TUI) for session browsing and real-time interaction.

⌨️
Core Commands
openclaw gateway - Start server
openclaw agent - Run directly
openclaw onboard - Setup wizard
openclaw health - Health check
📱
Channel Commands
openclaw channels auth
openclaw channels list
openclaw channels status
openclaw channels logout
🖥️
Terminal UI
openclaw tui

• Session browsing
• Command palette
• Real-time updates
🔌
ACP Bridge
openclaw acp

Agent Client Protocol for IDE integration (Zed editor support)
CLI Commands Overview
$ openclaw --help # Server & Runtime gateway Start gateway server agent Run agent directly tui Terminal UI # Configuration config Manage configuration onboard Interactive setup models Model management # Channels & Sessions channels Channel management sessions Session management message Send messages # System health Health check doctor Diagnostics browser Browser control skills Skills management plugins Plugin management
10

Deployment Options

▼

Deploy OpenClaw anywhere: Docker containers, cloud platforms (Fly.io, Render), or as a system service (systemd/launchd). Native apps available for mobile and desktop.

🐳
Docker
node:22-bookworm base
Bun runtime
Non-root user
docker-compose.yml included
🐧
Linux (systemd)
Unit file generation
Auto-restart on failure
Log rotation
Service management
🍎
macOS (launchd)
Plist generation
Login item support
Background daemon
Native integration
☁️
Cloud Platforms
Fly.io (fly.toml)
Render (render.yaml)
Any Docker host
Kubernetes ready
📱
Mobile Apps
Android native
iOS native
Shared codebase
apps/ directory
💻
Desktop
macOS native app
Web UI (ui/)
Terminal UI (TUI)
Canvas interface
docker-compose.yml
services: openclaw-gateway: build: . ports: - "18789:18789" volumes: - ./config:/home/node/.openclaw - ./workspace:/workspace environment: - ANTHROPIC_API_KEY - OPENAI_API_KEY openclaw-cli: build: . command: openclaw tui
11

Plugin SDK & Extensions

▼

OpenClaw ships with 32 extension plugins and 54 skills. The Plugin SDK provides tool factories, hook system, and custom auth providers for maximum extensibility.

🔐
Auth Plugins
auth-anthropic
auth-openai
auth-google
auth-qwen
auth-minimax
📱
Channel Plugins
channel-bluebubbles
channel-teams
channel-matrix
channel-mattermost
channel-twitch
🛠️
Plugin SDK
Tool factories
Hook system (events)
Config schema hints
Provider auth flows
🎯
Skills (54)
Specialized tools
Integration skills
Domain-specific
skills/ directory

Advanced Features

🔊
TTS System
Multiple TTS providers, voice synthesis, audio playback integration
👁️
Media Understanding
Image recognition, OCR, video frame extraction, link previews
🔍
Security Audit
File permission auditing, vulnerability scanning, exec approvals
📡
Device Discovery
Bonjour/mDNS for local network discovery, gateway advertisement