OpenClaw Architecture Explorer

378K

Lines of Source

2,188

Source Files

Extensions

10+

Messaging Channels

Native Apps

System Architecture

Click any component to see details. The system follows a layered architecture: user-facing surfaces connect through messaging channels to a central gateway that orchestrates AI agents.

User-Facing Surfaces

CLI

src/cli + src/commands

Web UI

ui/ (Lit + Vite)

TUI

Terminal UI

macOS App

apps/macos (SwiftUI)

iOS App

apps/ios (Swift)

Android App

apps/android (Kotlin)

▼

Messaging Channels

src/web (Baileys)

src/telegram (grammY)

Discord

src/discord (Carbon)

Slack

src/slack (Bolt)

Signal

src/signal

iMessage

src/imessage

LINE

src/line

+20 more

via extensions/

▼

Gateway (Core Engine)

Gateway Server

src/gateway/server.ts

Routing

src/routing

Sessions

src/sessions

Auth

src/gateway/auth.ts

Hooks

src/hooks

▼

AI Agent Layer

Agent System

src/agents (Pi-embedded)

Tool System

Bash, Browser, Canvas

Skills

skills/ + agents/skills

Sandbox

Docker isolation

Sub-Agents

Spawning & lifecycle

▼

Infrastructure & Storage

Memory

src/memory (SQLite+Vec)

Config

src/config

Plugin System

src/plugins

Media Pipeline

src/media

Security

src/security

Infra

src/infra (utilities)

▼

AI Model Providers

Anthropic

Claude models

OpenAI

GPT / o-series

Google

Gemini models

Ollama

Local models

+15 more

Bedrock, vLLM, etc.

Message Data Flow

How a user message travels through the system and returns as an AI response.

Inbound: User Message to AI

User

Sends message via
any channel

→

Channel

WhatsApp, Telegram,
Discord, CLI, etc.

→

Routing

Allow-list check,
session key resolve

→

Gateway

WebSocket server,
auth, rate-limit

→

Agent

Pi-embedded runner,
system prompt, tools

→

LLM Provider

Anthropic, OpenAI,
Gemini, local, etc.

Tool Execution Loop

Agent

Decides to use tool

→

Tool Policy

Permission check,
sandbox gating

→

Sandbox

Docker/native
execution

→

Tool Result

Output back to
agent context

→

Agent

Continues or
responds

Outbound: AI Response to User

LLM Response

Streamed tokens

→

Stream processing,
block chunking

→

Gateway

Broadcast to
connected clients

→

Channel

Format for platform
(Markdown, etc.)

→

User

Receives reply

Core Module Reference

The main source directories under src/ and their responsibilities.

CLI

src/cli/

Command-line interface wiring. Entry point parsing, Commander program setup, all CLI subcommands (gateway, config, channels, browser, etc). Uses src/cli/program.ts as the root.

~100 filesEntry Point

Commands

src/commands/

Business logic for all CLI commands: onboarding, doctor, status, configure, sessions, agents management, model picking, sandbox, auth-choice, health checks.

~200 filesCore

Gateway

src/gateway/

The core server. WebSocket + HTTP server, channel management, agent chat orchestration, OpenAI-compatible API, session management, auth, hooks, node events, model catalog.

~120 filesCore Engine

Agents

src/agents/

AI agent system: Pi-embedded runner, system prompts, tool definitions, tool policy, sandbox config, skills, subagent spawning/registry, model catalog, bash/browser tools, compaction, workspace management.

~250 filesAI Core

Channels

src/channels/

Shared channel infrastructure: allow-lists, command gating, mention gating, session management, status reactions, typing indicators, draft stream controls, dock management.

~30 filesShared

Memory

src/memory/

Vector memory system with SQLite-vec. Embedding management (OpenAI, Gemini, Voyage, local llama), hybrid search (semantic + keyword), batch operations, query expansion, temporal decay, MMR reranking.

~60 filesAI Core

Plugins

src/plugins/

Plugin runtime: discovery, loading (via jiti), installation (npm), manifest registry, hook system, tool/service registration, slot management (memory slot is exclusive).

~40 filesExtensibility

Infra

src/infra/

Infrastructure utilities: env management, port handling, file locks, device identity, Bonjour/mDNS, Tailscale, SSH tunnels, update checking, heartbeat system, exec approvals, provider usage tracking.

~130 filesInfra

Routing

src/routing/

Message routing: session key derivation, route resolution (which agent handles which message), account ID mapping.

~6 filesCore

Security

src/security/

Security auditing: channel metadata, dangerous config/tool flags, DM policy, external content scanning, skill scanning, secret comparison, Windows ACL.

~20 filesSecurity

Media

src/media/

Media processing pipeline for images, audio, video, and documents. Handles transcoding, format detection, and media understanding via AI models.

mediaCore

Config

src/config/

Configuration management: config file loading/saving, session store, profile management. Data stored at ~/.openclaw/.

configInfra

Channel Implementations

Each channel lives in its own directory with platform-specific integration code.

src/web/

WhatsApp Web integration via Baileys library. QR code pairing, message handling, media upload/download.

Channel

src/telegram/

Telegram bot via grammY framework. Supports groups, DMs, inline queries, throttling.

Channel

Discord

src/discord/

Discord bot via Carbon library. Guild management, slash commands, voice support.

Channel

Slack

src/slack/

Slack app via Bolt framework. Workspace events, slash commands, interactive messages.

Channel

Signal

src/signal/

Signal messenger integration. Private messaging with E2E encryption.

Channel

iMessage

src/imessage/

Apple iMessage integration (macOS only). BlueBubbles extension available.

Channel

Extensions (38 plugins)

Extensions are workspace packages under extensions/. They extend OpenClaw with additional channels, memory backends, AI tools, and integrations.

Messaging Channels

MS Teams

extensions/msteams

Matrix

extensions/matrix

IRC

extensions/irc

Nostr

extensions/nostr

Twitch

extensions/twitch

Feishu

extensions/feishu

Google Chat

extensions/googlechat

Mattermost

extensions/mattermost

Nextcloud Talk

extensions/nextcloud-talk

Synology Chat

extensions/synology-chat

Zalo

extensions/zalo

Zalo User

extensions/zalouser

Tlon

extensions/tlon

Telegram (ext)

extensions/telegram

Discord (ext)

extensions/discord

Slack (ext)

extensions/slack

Signal (ext)

extensions/signal

WhatsApp (ext)

extensions/whatsapp

iMessage (ext)

extensions/imessage

LINE (ext)

extensions/line

BlueBubbles

extensions/bluebubbles

AI & Agent Tools

LLM Task

extensions/llm-task

Lobster

extensions/lobster

Open Prose

extensions/open-prose

Voice Call

extensions/voice-call

Talk Voice

extensions/talk-voice

Phone Control

extensions/phone-control

Thread Ownership

extensions/thread-ownership

Diagnostics (OTel)

extensions/diagnostics-otel

Memory & Auth

Memory Core

extensions/memory-core

Memory LanceDB

extensions/memory-lancedb

Copilot Proxy

extensions/copilot-proxy

Google Antigravity Auth

extensions/google-antigravity-auth

Google Gemini CLI Auth

extensions/google-gemini-cli-auth

Minimax Portal Auth

extensions/minimax-portal-auth

Qwen Portal Auth

extensions/qwen-portal-auth

Device Pair

extensions/device-pair

Shared

extensions/shared

Technology Stack

Language

TypeScript (ESM)

Primary language. Strict typing, no any. Node 22+ runtime. Bun supported for dev.

Language

Swift / SwiftUI

macOS and iOS native apps. Uses Observation framework for state management.

Language

Kotlin

Android app under apps/android/. Gradle build system.

Build

tsdown

TypeScript bundler for building dist/. Fast, ESM-native.

Build

pnpm (workspaces)

Package manager with workspace support. Monorepo with root + ui + packages + extensions.

Test

Vitest

Testing framework. Multiple configs: unit, e2e, live, extensions, gateway. V8 coverage at 70% threshold.

Lint/Format

Oxlint + Oxfmt

Rust-based linter and formatter. Fast, type-aware linting. SwiftLint/SwiftFormat for Swift.

CLI

Commander

CLI framework. Program built in src/cli/program.ts with extensive subcommand tree.

Web Server

Express 5 + WebSockets

Gateway HTTP server with WebSocket support via ws. OpenAI-compatible API layer.

Web UI

Lit + Vite

Web component framework. Lightweight, standards-based UI under ui/.

Messaging

Baileys (WhatsApp)

WhatsApp Web protocol library for direct WhatsApp integration.

Messaging

grammY (Telegram)

Telegram Bot API framework with runner and throttler plugins.

Messaging

Carbon (Discord)

Discord bot framework. Voice support via @discordjs/voice.

Messaging

Bolt (Slack)

Official Slack app framework for events, commands, and interactive messages.

Pi Agent (embedded)

AI agent runtime from @mariozechner/pi-*. Powers the core agent loop, coding tools, TUI.

Multi-Provider

Anthropic, OpenAI, Google, Bedrock, Ollama, vLLM, HuggingFace, Together, xAI, and more.

Storage

SQLite + sqlite-vec

Vector database for memory. Embeddings stored locally. Hybrid semantic + keyword search.

Schema

TypeBox + Zod

Runtime schema validation. TypeBox for tool schemas (JSON Schema), Zod for general validation.

Browser

Playwright

Browser automation for agent tools. Headless browsing, screenshots, interaction.

Deploy

Docker + Fly.io

Containerized deployment. Multiple Dockerfiles: main, sandbox, sandbox-browser.

Protocol

ACP (Agent Client Protocol)

Standardized protocol for agent communication. SDK at @agentclientprotocol/sdk.

New Contributor Quick Start

Follow these steps to get oriented and productive in the OpenClaw codebase.

Setup & Install

Node 22+ required. Install dependencies with pnpm install. The project uses pnpm workspaces with root + ui + packages + extensions. Bun is also supported for dev.

Read the Key Docs

Start with AGENTS.md (repo guidelines), VISION.md (project direction), CONTRIBUTING.md (PR rules), and SECURITY.md. These define coding style, naming, commit conventions, and what will/won't be merged.

Understand the Entry Points

src/entry.ts is the CLI bootstrap. It calls src/cli/run-main.ts which loads src/cli/program.ts (Commander). The gateway server lives at src/gateway/server.ts. src/index.ts is the library export.

Learn the Core Loop

A message arrives at a channel (src/telegram, src/discord, etc.) → gets routed (src/routing) → hits the gateway (src/gateway/server.ts) → runs through the agent (src/agents/pi-embedded-runner.ts) → calls an LLM provider → streams response back.

Build & Test

Build: pnpm build. Type-check: pnpm tsgo. Lint: pnpm check. Test: pnpm test (parallel vitest). Tests are colocated as *.test.ts files. Coverage target: 70%.

Run in Dev Mode

Run the CLI: pnpm openclaw ... or pnpm dev. Gateway dev mode: pnpm gateway:dev (skips channel startup for faster iteration). Web UI dev: pnpm ui:dev.

Explore a Feature Area

Adding a channel? Look at src/telegram/ or an extension like extensions/matrix/ as templates. Adding a tool? See src/agents/tools/. Adding a plugin? See docs/tools/plugin.md and src/plugins/.

Commit & PR Rules

Use scripts/committer "msg" file... for commits. One PR = one issue. Max ~5,000 changed lines. Format: pnpm format:fix before committing. Pre-commit hooks enforced.

Key Patterns to Know

DI: createDefaultDeps() pattern for dependency injection. Plugins: loaded via jiti, manifest-based. Config: stored at ~/.openclaw/. Sessions: JSONL files per agent. TypeBox: for tool schemas (no Union types). Oxlint: type-aware linting.

What NOT To Do

No @ts-nocheck. No any. No prototype mutation. No editing node_modules. No Carbon dependency updates. Keep files under ~500 LOC. Don't bundle unrelated changes. Don't add skills to core (use ClawHub). Don't add MCP to core (use mcporter).