OpenClaw Architecture | Infrared Thermal View

Section 01

Overview & Scale

247K+

GitHub Stars

50+

Integrations

13,700+

ClawHub Skills

14

LLM Providers

20+

Msg Channels

OpenClaw is a free, open-source autonomous AI agent platform created by Peter Steinberger. It runs as a single persistent Gateway process on hardware you control, connecting to messaging apps (Signal, Telegram, WhatsApp, Discord) and orchestrating LLM-powered tool execution. TypeScript monorepo, local-first, always-on.

High-Level Architecture — Thermal Map

graph TD
    U[" User Layer 
Signal / Telegram / WhatsApp / Discord"]
    CA[" Channel Adapters "]
    GW[" Gateway 
Node.js Process"]
    AL[" Agent Loop "]
    LLM[" LLM Providers 
14 Backends"]
    SK[" Skills 
13,700+ ClawHub"]
    TL[" Tools 
50+ Integrations"]
    SH[" Smart Home 
IoT Devices"]
    MEM[" Memory / Storage "]

    U --> CA
    CA --> GW
    GW --> AL
    AL --> LLM
    AL --> SK
    AL --> TL
    AL --> SH
    AL --> MEM

    style U fill:#ef4444,stroke:#dc2626,color:#0a0010
    style CA fill:#f97316,stroke:#ef4444,color:#0a0010
    style GW fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style AL fill:#eab308,stroke:#f59e0b,color:#1a0030
    style LLM fill:#f59e0b,stroke:#f97316,color:#1a0030
    style SK fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style TL fill:#84cc16,stroke:#22c55e,color:#1a0030
    style SH fill:#84cc16,stroke:#22c55e,color:#1a0030
    style MEM fill:#6366f1,stroke:#3b82f6,color:#ffffff

Section 02

Gateway Core

The Gateway is a single long-lived Node.js process (default 127.0.0.1:18789). It is the entire control plane — no separate microservices, no orchestrator, no message broker. Everything runs in one process on your machine.

Gateway Internals

graph TD
    WS[" WebSocket Server "]
    CR[" Channel Router "]
    SM[" Session Manager "]
    CQ[" Command Queue 
Two-Level Lanes"]
    AL[" Agent Loop "]
    LP[" LLM Provider "]
    TE[" Tool Executor "]
    MS[" Memory Store "]
    SL[" Session Lane 
Serialized per session"]
    GL[" Global Lane 
Caps parallel calls"]

    WS --> CR
    CR --> SM
    SM --> CQ
    CQ --> AL
    AL --> LP
    AL --> TE
    AL --> MS
    CQ --> SL
    CQ --> GL

    style WS fill:#3b82f6,stroke:#6366f1,color:#ffffff
    style CR fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style SM fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style CQ fill:#eab308,stroke:#f59e0b,color:#1a0030
    style AL fill:#f59e0b,stroke:#f97316,color:#1a0030
    style LP fill:#f59e0b,stroke:#f97316,color:#1a0030
    style TE fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style MS fill:#6366f1,stroke:#3b82f6,color:#ffffff
    style SL fill:#1e3a8a,stroke:#3b82f6,color:#c4b5fd
    style GL fill:#1e3a8a,stroke:#3b82f6,color:#c4b5fd

Session Lanes

Keyed on sessionId, serialized. Only one active run per session — prevents tool conflicts and history corruption.

Global Lanes

Caps total parallel model calls. Defaults: main=4, subagent=8. Prevents overloading LLM rate limits.

Steer Mode

Queue checked after each tool call. If a queued message is waiting, remaining tool calls are skipped and the new message is processed.

Hot Reload

Config file is watched via fs.watch. Changes are applied without restarting the Gateway process.

Section 03

Messaging Providers

OpenClaw connects to 20+ messaging platforms via Channel Adapters. Each adapter normalizes platform-specific events into a unified internal message format before handing off to the Gateway.

Channel Adapter Map

graph LR
    TG[" Telegram 
Bot API"]
    WA[" WhatsApp 
Baileys WS"]
    SG[" Signal 
signal-cli"]
    DC[" Discord 
Bot API"]
    SL[" Slack 
Events API"]
    IM[" iMessage 
macOS bridge"]
    MT[" MS Teams 
Graph API"]
    CA[" Channel 
Adapter"]
    GW[" Gateway "]

    TG --> CA
    WA --> CA
    SG --> CA
    DC --> CA
    SL --> CA
    IM --> CA
    MT --> CA
    CA --> GW

    style TG fill:#3b82f6,stroke:#6366f1,color:#ffffff
    style WA fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style SG fill:#6366f1,stroke:#3b82f6,color:#ffffff
    style DC fill:#3b82f6,stroke:#6366f1,color:#ffffff
    style SL fill:#3b82f6,stroke:#6366f1,color:#ffffff
    style IM fill:#7c6faa,stroke:#6366f1,color:#ffffff
    style MT fill:#3b82f6,stroke:#6366f1,color:#ffffff
    style CA fill:#f97316,stroke:#ef4444,color:#0a0010
    style GW fill:#14b8a6,stroke:#0d9488,color:#0a0010

Platform	Protocol	Type	Notes
Telegram	Bot API (long-polling)	Official	Most mature, recommended starting point
WhatsApp	Baileys WebSocket	Community	Web client protocol, not Meta's official API
Signal	signal-cli	Community	Most private, E2EE
Discord	Bot API	Official	Full guild + DM support
Slack	Events API / WS	Official	Workspace bot integration
iMessage	Unofficial bridge	Community	macOS only, requires running Mac
MS Teams	Graph API	Official	Enterprise org support

Section 04

LLM Backend Layer

14 built-in model providers with automatic fallback cascading. When one provider hits rate limits or errors, the request cascades to the next available provider in the chain.

Model Router & Provider Chain

graph TD
    MR[" Model Router "]
    OA[" OpenAI 
GPT-4o / o1"]
    AN[" Anthropic 
Claude 3.5 / Opus"]
    GG[" Google Gemini 
2.0 Flash / Pro"]
    OR[" OpenRouter 
Multi-provider"]
    OL[" Ollama 
Local Models"]
    LM[" LM Studio 
Local GUI"]
    LL[" LiteLLM 
Proxy"]
    FB[" Fallback 
Cascade"]

    MR --> OA
    MR --> AN
    MR --> GG
    MR --> OR
    MR --> OL
    MR --> LM
    MR --> LL
    OA -.->|rate limit| FB
    AN -.->|rate limit| FB
    FB -.-> OR

    style MR fill:#eab308,stroke:#f59e0b,color:#1a0030
    style OA fill:#f59e0b,stroke:#f97316,color:#1a0030
    style AN fill:#f59e0b,stroke:#f97316,color:#1a0030
    style GG fill:#f59e0b,stroke:#f97316,color:#1a0030
    style OR fill:#f59e0b,stroke:#f97316,color:#1a0030
    style OL fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style LM fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style LL fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style FB fill:#ef4444,stroke:#dc2626,color:#0a0010

Model Config

Each model declares: id, name, reasoning flag, input types (text/image/audio), contextWindow, maxTokens, and cost per token.

Third-Party Routers

ClawRouter scores requests on 14 dimensions and routes to LIGHT / MEDIUM / HEAVY tiers for cost optimization.

Context Management

4-stage pipeline: Guards → Hygiene → Compaction → Snapshots. Prevents context overflow while preserving critical information.

Section 05

Skills System

Skills are the primary extension mechanism. Each skill is a SKILL.md file with YAML frontmatter and Markdown instructions. The runtime selectively injects only relevant skills into each prompt turn.

Skill Architecture & Loading

graph TD
    BU[" Bundled Skills 
In-repo"]
    MG[" Managed Skills 
ClawHub Registry"]
    WK[" Workspace Skills 
Local dirs"]
    DS[" Discovery "]
    DC[" Dependency Check "]
    EF[" Eligibility Filter "]
    RS[" Relevance Scoring "]
    SI[" Selective Injection "]
    PR[" Prompt "]

    BU --> DS
    MG --> DS
    WK --> DS
    DS --> DC
    DC --> EF
    EF --> RS
    RS --> SI
    SI --> PR

    style BU fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style MG fill:#84cc16,stroke:#22c55e,color:#1a0030
    style WK fill:#84cc16,stroke:#22c55e,color:#1a0030
    style DS fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style DC fill:#eab308,stroke:#f59e0b,color:#1a0030
    style EF fill:#eab308,stroke:#f59e0b,color:#1a0030
    style RS fill:#f59e0b,stroke:#f97316,color:#1a0030
    style SI fill:#f97316,stroke:#ef4444,color:#0a0010
    style PR fill:#ef4444,stroke:#dc2626,color:#0a0010

Skill Eligibility Flow

flowchart LR
    A[" SKILL.md "] --> B{"Env vars
present?"}
    B -->|Yes| C{"Binaries
installed?"}
    B -->|No| X[" Skip "]
    C -->|Yes| D{"OS
match?"}
    C -->|No| X
    D -->|Yes| E[" Eligible "]
    D -->|No| X
    E --> F[" Score
Relevance "]
    F --> G[" Inject into
Prompt "]

    style A fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style B fill:#eab308,stroke:#f59e0b,color:#1a0030
    style C fill:#eab308,stroke:#f59e0b,color:#1a0030
    style D fill:#eab308,stroke:#f59e0b,color:#1a0030
    style E fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style F fill:#f59e0b,stroke:#f97316,color:#1a0030
    style G fill:#ef4444,stroke:#dc2626,color:#0a0010
    style X fill:#1e3a8a,stroke:#6366f1,color:#c4b5fd

SKILL.md Format

YAML frontmatter (name, description, requires.env, requires.bins) plus Markdown body. Description acts as trigger phrase for relevance matching.

Selective Injection

NOT all skills are loaded every turn. Runtime scores each skill by relevance to the current message and injects only matching ones.

ClawHub Registry

13,700+ community skills. No formal code review gate. Automated scanning: VirusTotal + Gemini behavioral analysis.

Section 06

Smart Home & IoT

OpenClaw acts as a natural-language controller for smart home devices. Integrations are implemented as Skills that bridge voice/text commands to device APIs.

Smart Home Integration Map

graph LR
    AL[" Agent Loop "]
    HA[" Home Assistant 
REST / WebSocket"]
    HU[" Philips Hue 
OpenHue CLI"]
    EL[" Elgato 
Key Light / Deck"]
    SO[" Sonos 
Speaker Control"]
    SP[" Spotify 
Web API"]
    SL[" 8Sleep 
Smart Mattress"]
    WH[" WHOOP 
Wearables"]
    AW[" Apple Watch 
HealthKit"]

    AL --> HA
    AL --> HU
    AL --> EL
    AL --> SO
    AL --> SP
    AL --> SL
    AL --> WH
    AL --> AW

    style AL fill:#eab308,stroke:#f59e0b,color:#1a0030
    style HA fill:#84cc16,stroke:#22c55e,color:#1a0030
    style HU fill:#84cc16,stroke:#22c55e,color:#1a0030
    style EL fill:#84cc16,stroke:#22c55e,color:#1a0030
    style SO fill:#84cc16,stroke:#22c55e,color:#1a0030
    style SP fill:#22c55e,stroke:#14b8a6,color:#1a0030
    style SL fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style WH fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style AW fill:#14b8a6,stroke:#0d9488,color:#0a0010

Home Assistant is the deepest integration: the moltbot-ha skill exposes 34 tools covering lights, climate, scenes, automations, and entity queries. Philips Hue uses the OpenHue CLI for local-network-only control with no cloud dependency.

Section 07

Tool & Extension Ecosystem

50+ integrations organized by category. Extensions come in three flavors: Skills (SKILL.md-driven), Plugins (TypeScript Gateway extensions), and Webhooks (HTTP POST endpoints).

Integration Ecosystem — Category Map

graph TD
    subgraph PROD["Productivity"]
        NO["Notion"]
        OB["Obsidian"]
        AN["Apple Notes"]
        TH["Things 3"]
        TR["Trello"]
        GM["Gmail"]
        GC["Google Cal"]
        LN["Linear"]
    end
    subgraph DEV["Developer"]
        BA["Bash / Shell"]
        FS["Filesystem"]
        MC["MCP Bridge"]
    end
    subgraph AI["AI / Agent"]
        MB["Moltbook"]
        CW["ClawRouter"]
        MU["memU"]
        LO["Lobster"]
    end
    subgraph HEALTH["Health"]
        WP["WHOOP"]
        AW["Apple Watch"]
    end
    subgraph MEDIA["Music"]
        SP["Spotify"]
        SN["Sonos"]
    end

    GW[" Gateway "] --> PROD
    GW --> DEV
    GW --> AI
    GW --> HEALTH
    GW --> MEDIA

    style GW fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style PROD fill:#1a0f30,stroke:#22c55e,color:#c4b5fd
    style DEV fill:#1a0f30,stroke:#3b82f6,color:#c4b5fd
    style AI fill:#1a0f30,stroke:#f59e0b,color:#c4b5fd
    style HEALTH fill:#1a0f30,stroke:#14b8a6,color:#c4b5fd
    style MEDIA fill:#1a0f30,stroke:#84cc16,color:#c4b5fd

Skills

SKILL.md-driven extensions. Natural language triggers mapped to API calls and CLI commands. Hot-reloaded on file change.

Plugins

Deep Gateway extensions written in TypeScript/JavaScript. Full access to the Gateway lifecycle, sessions, and internal APIs.

Webhooks

HTTP POST endpoints exposed by the Gateway. External systems (CI, monitoring, calendars) push events into OpenClaw sessions.

Section 08

Security & Trust Model

OpenClaw has major documented security issues. Skills execute with full user privileges, no sandboxing exists, and the ClawHub registry lacks formal code review. Multiple independent security audits have confirmed systemic vulnerabilities.

Trust Boundaries

flowchart TD
    USR[" User "]
    MSG[" Messaging App "]
    GW[" Gateway "]
    SK[" Skills 
UNTRUSTED"]
    CH[" ClawHub Registry 
No code review"]
    SOUL[" SOUL.md 
Attack target #1"]
    MEM[" MEMORY.md 
Persistence vector"]
    EXT[" External Content 
Prompt injection"]

    USR -->|trusted| MSG
    MSG -->|trusted| GW
    GW -->|"UNTRUSTED
full privileges"| SK
    SK -->|no verification| CH
    SK -->|reads/writes| SOUL
    SK -->|reads/writes| MEM
    EXT -->|injection| SK

    style USR fill:#eab308,stroke:#ca8a04,color:#0a0010
    style MSG fill:#3b82f6,stroke:#2563eb,color:#ffffff
    style GW fill:#14b8a6,stroke:#0d9488,color:#0a0010
    style SK fill:#ef4444,stroke:#dc2626,color:#0a0010
    style CH fill:#f97316,stroke:#ea580c,color:#0a0010
    style SOUL fill:#ef4444,stroke:#dc2626,color:#0a0010
    style MEM fill:#f97316,stroke:#ea580c,color:#0a0010
    style EXT fill:#ef4444,stroke:#dc2626,color:#0a0010

Attack Surface — Known Campaigns

graph LR
    CH[" ClawHavoc 
335 infostealers"]
    SN[" Snyk ToxicSkills 
36% prompt injection"]
    CI[" Cisco Audit 
9 vulns, 2 critical"]
    MA[" March 2026 Audit 
3,401 / 9,234 flawed"]
    AS[" Atomic macOS Stealer "]
    KL[" Keyloggers "]
    BD[" Backdoors "]
    EX[" Data Exfiltration "]

    CH --> AS
    CH --> KL
    CH --> BD
    SN --> EX
    CI --> EX
    MA --> CH
    MA --> SN

    style CH fill:#ef4444,stroke:#dc2626,color:#0a0010
    style SN fill:#ef4444,stroke:#dc2626,color:#0a0010
    style CI fill:#f97316,stroke:#ea580c,color:#0a0010
    style MA fill:#ef4444,stroke:#dc2626,color:#0a0010
    style AS fill:#f97316,stroke:#ea580c,color:#0a0010
    style KL fill:#f97316,stroke:#ea580c,color:#0a0010
    style BD fill:#f97316,stroke:#ea580c,color:#0a0010
    style EX fill:#ef4444,stroke:#dc2626,color:#0a0010

No Sandboxing

Skills run with full user privileges — unrestricted exec, filesystem, and network access. Any installed skill can read/write any file the user can.

SOUL.md Attacks

The agent identity file is the #1 attack target. ClawHavoc inserted malicious content into MEMORY.md and SOUL.md for persistent compromise across sessions.

Supply Chain

ClawHub has no verification, no signing, no sandboxing. RFC #10890 proposes fixes but remains unimplemented. 341 explicitly malicious skills found.

Mitigations

clawsec (prompt-security/clawsec) provides SOUL.md integrity verification and automated audits. VirusTotal + Gemini behavioral scanning on ClawHub submissions.

⚠ CRITICAL SECURITY WARNING: As of March 2026, 36.82% of audited ClawHub skills (3,401 of 9,234) contain security flaws. Skills execute with full user privileges and no sandboxing. Exercise extreme caution with community skills.

Section 09

Data & Request Flow

End-to-end message lifecycle from user input to delivered response, showing the agent loop’s iterative tool-calling pattern and state persistence.

Complete Request Lifecycle

sequenceDiagram
    participant U as User
    participant MA as Messaging App
    participant CA as Channel Adapter
    participant GW as Gateway
    participant SM as Session Manager
    participant AL as Agent Loop
    participant LLM as LLM Provider
    participant TE as Tool Executor
    participant SS as Session Store

    U->>MA: Send message
    MA->>CA: Webhook / WebSocket
    CA->>GW: Normalized message
    GW->>SM: Route to session
    SM->>AL: Load context + skills
    AL->>LLM: Prompt + tools
    LLM-->>AL: Response + tool calls
    AL->>TE: Execute tool
    TE-->>AL: Tool result
    AL->>LLM: Tool result (loop)
    LLM-->>AL: Final response
    AL->>CA: Format output
    CA->>MA: Deliver reply
    AL->>SS: Persist state

<10ms

Access Control

<50ms

Session Load

200-500ms

First LLM Token

<100ms

Bash / Shell

1-3s

Browser Automation

Context Management Pipeline

graph LR
    G[" Guards 
Access control"]
    H[" Hygiene 
Memory flush"]
    C[" Compaction 
Summarize old history"]
    S[" Snapshots 
Checkpoint to
session-state.md"]

    G --> H
    H --> C
    C --> S

    style G fill:#ef4444,stroke:#dc2626,color:#0a0010
    style H fill:#f59e0b,stroke:#d97706,color:#0a0010
    style C fill:#f59e0b,stroke:#d97706,color:#0a0010
    style S fill:#6366f1,stroke:#4f46e5,color:#ffffff

Section 10

Evolution & Ecosystem

From a personal project to 247K GitHub stars in under five months — OpenClaw’s rapid rise has been marked by naming disputes, security crises, and explosive community growth.

Project Timeline

timeline
    title OpenClaw History
    November 2025 : Clawdbot created by Peter Steinberger
    January 27 2026 : Renamed to Moltbot (Anthropic trademark request)
                    : 230 malicious skills uploaded to ClawHub same day
    January 29-30 2026 : Renamed to OpenClaw
                       : Fake Solana token incident
    Early February 2026 : ClawHavoc campaign discovered (335 infostealers)
    February 14 2026 : Steinberger announces joining OpenAI
                     : Project moves to open-source foundation
    February 28 2026 : 13,729 ClawHub skills
    March 2 2026 : 247K GitHub stars (surpasses React)
    March 8 2026 : Shenzhen AI Bureau draft policy supporting OpenClaw
    March 10 2026 : Nvidia announces NemoClaw enterprise competitor

Scott Hanselman

Built openclaw-windows-hub — a system tray app + PowerToys Command Palette extension for Windows integration.

Nvidia NemoClaw

Enterprise-focused competitor, open-source, pitched to Salesforce, Cisco, Google, and Adobe as a managed alternative.

China Adoption

Adapted for DeepSeek model and domestic messaging apps. Shenzhen AI Bureau drafted policy supporting OpenClaw deployments.

Foundation Model

Project governance moved to an open-source foundation after creator Peter Steinberger announced he was joining OpenAI in February 2026.

Reference

Acronym Guide

Acronym	Meaning
API	Application Programming Interface
CDP	Chrome DevTools Protocol
CLI	Command-Line Interface
ClawHub	OpenClaw Skills Registry
E2EE	End-to-End Encryption
ESM	ECMAScript Module
FTS5	Full-Text Search 5
GUI	Graphical User Interface
IoT	Internet of Things
LLM	Large Language Model
MCP	Model Context Protocol
PTY	Pseudo-Terminal
RFC	Request for Comments
SKILL.md	Skill definition file
SOUL.md	Agent identity / values file
WS	WebSocket