Overview

Relevant source files

• CHANGELOG.md
• README.md
• docs/cli/index.md
• docs/docs.json
• docs/gateway/index.md
• docs/gateway/troubleshooting.md
• docs/index.md
• docs/start/getting-started.md
• docs/start/hubs.md
• docs/start/onboarding.md
• docs/start/wizard.md
• extensions/copilot-proxy/package.json
• extensions/google-antigravity-auth/package.json
• extensions/google-gemini-cli-auth/package.json
• extensions/matrix/CHANGELOG.md
• extensions/matrix/package.json
• extensions/msteams/CHANGELOG.md
• extensions/msteams/package.json
• extensions/voice-call/CHANGELOG.md
• extensions/voice-call/package.json
• extensions/zalo/CHANGELOG.md
• extensions/zalo/package.json
• extensions/zalouser/package.json
• package.json
• pnpm-lock.yaml
• src/index.ts
• ui/package.json

Purpose and Scope

This page introduces OpenClaw, a self-hosted multi-channel AI gateway that connects AI agents to messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, etc.) through a centralized control plane. It explains the system's core architecture, key components, and how they interact.

For detailed terminology definitions, see Key Concepts. For installation and first-run instructions, see Quick Start. For in-depth architecture diagrams, see Architecture Diagrams.

---

What is OpenClaw

OpenClaw is a personal AI assistant framework that runs on your own infrastructure. It provides:

• Multi-channel messaging: Connect one AI agent to multiple messaging platforms simultaneously
• Centralized control: Single Gateway server (ws://127.0.0.1:18789) coordinates all channels, agents, and tools
• Hot-reload configuration: Change settings without restarting the Gateway
• Sandboxed execution: Run agent tools in isolated Docker containers for security
• Extension system: Add new channels and capabilities via npm-installable plugins
• Session management: Isolated conversation contexts per user/channel/group

The system is built around a hub-and-spoke architecture: the Gateway acts as the central control plane, with channels, clients, and agents connecting via WebSocket RPC.

Sources: README.md1-498 package.json1-217

---

System Architecture Overview

Key Code Entities:

• Gateway Server: src/gateway/server.ts
• Agent Executor: src/agents/agent-pi.ts
• Config Schema: src/config/zod-schema.ts
• Memory Manager: src/memory/manager.ts
• Tool System: src/tools/

Sources: src/index.ts1-94 src/config/zod-schema.ts1-470 README.md180-197

---

Core Components

Gateway Server

The Gateway is the central WebSocket server (port 18789 by default) that coordinates all system components. It exposes an RPC protocol defined in src/gateway/protocol.ts for:

• Configuration management: config.get, config.set, config.apply, config.patch
• Agent control: agent.send, agent.execute
• Session operations: sessions.list, sessions.history, sessions.send
• Channel management: channels.status, channels.login
• System diagnostics: gateway.health, gateway.status

The Gateway runs as a background service via platform-specific supervisors:

• macOS: launchd (LaunchAgent)
• Linux: systemd (user service)
• Windows: Task Scheduler

Configuration: Gateway behavior is controlled by gateway.* config keys:

Field	Purpose	Default
gateway.port	WebSocket listen port	18789
gateway.bind	Network binding mode	"loopback"
gateway.auth.mode	Authentication type	"token"
gateway.reload.mode	Config hot-reload behavior	"hybrid"
gateway.controlUi.enabled	Serve web dashboard	true

Sources: src/config/types.gateway.ts docs/gateway/configuration.md1-480

---

Configuration System

OpenClaw uses a strict, hot-reloadable configuration system:

1. Schema: Defined via Zod schemas in src/config/zod-schema.ts All config keys must match the schema or the Gateway refuses to start.
2. File: ~/.openclaw/openclaw.json (JSON5 format supporting comments and trailing commas)
3. Validation: src/config/validation.ts validates config on load and plugin registration
4. Hot Reload: src/config/io.ts watches the config file and applies changes automatically

Reload Modes (gateway.reload.mode):

Mode	Behavior
hybrid (default)	Hot-apply safe changes; auto-restart for infrastructure changes
hot	Hot-apply only; log warnings for restart-needed changes
restart	Restart Gateway on any config change
off	No file watching; manual restart required

Hot-Apply vs Restart:

• Hot-apply: channels.*, agents.*, tools.*, cron.*, hooks.*, session.*, messages.*
• Restart required: gateway.port, gateway.bind, gateway.auth, gateway.tailscale, gateway.tls

Include System: Configs support $include directives to split large configs:

Sources: src/config/config.ts1-15 src/config/zod-schema.ts95-470 docs/gateway/configuration.md327-366

---

Agent Runtime

The Agent Runtime executes AI agent turns via runEmbeddedPiAgent in src/agents/agent-pi.ts It orchestrates:

1. System Prompt Construction: src/agents/system-prompt.ts assembles prompts from workspace files (IDENTITY.md, SKILLS.md, MEMORY.md)
2. Tool Creation: src/tools/registry.ts provides tools based on policy resolution
3. Memory Search: src/memory/manager.ts handles semantic search via memory_search tool
4. Model Provider Calls: Integrates with Anthropic, OpenAI, Gemini, etc. via pi-ai SDK
5. Session Persistence: src/config/sessions/store.ts writes JSONL transcripts

Tool Policy Resolution Chain:

Global tools.allow/deny
  → tools.byProvider[provider]
    → agents.list[agentId].tools
      → session-specific overrides (groups)
        → sandbox.tools (if sandboxed)

Deny always wins. Tool groups like group:fs, group:runtime expand to multiple tools.

Sources: src/agents/agent-pi.ts src/agents/system-prompt.ts src/tools/index.ts docs/tools/index.md1-227

---

Memory System

OpenClaw provides semantic memory search over workspace Markdown files and session transcripts via a hybrid vector + BM25 index.

Architecture:

• Backend: MemoryIndexManager in src/memory/manager.ts111-1128
• Storage: SQLite database with sqlite-vec extension (vector tables) + FTS5 (keyword search)
• Embedding Providers: OpenAI, Gemini, Voyage, or local node-llama-cpp
• Chunking: 400-token chunks with 80-token overlap
• Hybrid Search: Combines vector similarity (70% weight) and BM25 keyword (30% weight)

Configuration Example:

Memory Sources:

1. memory: MEMORY.md + memory/*.md in workspace
2. sessions: Session transcripts from ~/.openclaw/agents/<agentId>/sessions/*.jsonl

Tools:

• memory_search(query): Semantic search with hybrid ranking
• memory_get(path): Read specific memory file by path

Alternative Backend: QMD (memory.backend = "qmd") uses external qmd CLI for BM25 + vector + reranking.

Sources: src/memory/manager.ts1-1128 src/agents/memory-search.ts1-250 docs/concepts/memory.md1-250

---

Channel System

Channels connect the Gateway to messaging platforms. OpenClaw includes built-in channels and supports extension channels via plugins.

Built-in Channels:

• WhatsApp (Baileys), Telegram (grammY), Discord (discord.js), Slack (Bolt), Signal (signal-cli), Google Chat, BlueBubbles (iMessage), iMessage (legacy), WebChat

Extension Channels (npm plugins):

• Matrix (@openclaw/matrix), Zalo (@openclaw/zalo), Zalo Personal (@openclaw/zalouser), MS Teams (@openclaw/msteams)

Channel Lifecycle:

Access Control (dmPolicy):

• pairing (default): Require one-time approval code
• allowlist: Only users in allowFrom array
• open: Allow all DMs (requires allowFrom: ["*"])
• disabled: Ignore all DMs

Sources: src/channels/ docs/channels/ README.md336-399

---

Tool System

Tools expose capabilities to agents. The system includes:

Core Tools (always available unless denied):

• File I/O: read, write, edit, apply_patch
• Execution: exec, bash, process
• Sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• Memory: memory_search, memory_get
• Web: web_search, web_fetch
• UI: browser, canvas
• Automation: cron, gateway
• Messaging: message
• Nodes: nodes (device control)
• Media: image (understanding)

Tool Profiles (base allowlists):

• minimal: session_status only
• coding: File I/O + execution + sessions + memory
• messaging: Messaging tools + session tools
• full: No restrictions

Tool Groups (shorthands):

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: All session tools
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas

Policy Example:

Sources: src/tools/ src/config/types.tools.ts1-350 docs/tools/index.md1-227

---

Sandbox System

The Sandbox System isolates agent tool execution in Docker containers to reduce security risk.

Configuration:

Modes:

• off: No sandboxing (all tools on host)
• non-main: Sandbox non-DM sessions (groups, channels)
• all: Sandbox all sessions

Scopes:

• session: One container per session (isolated)
• agent: One container per agent (shared across sessions)
• shared: One container shared by all agents

Workspace Access:

• none: No workspace mount
• ro: Read-only workspace
• rw: Read-write workspace

Image: Default is openclaw-sandbox:latest. Build with scripts/sandbox-setup.sh.

Sources: src/agents/sandbox/ docs/gateway/sandboxing.md1-120

---

Extension and Plugin Model

OpenClaw supports extensions via npm packages that declare channel or capability plugins.

Plugin Metadata (package.json):

Plugin Discovery:

1. Core scans node_modules/@openclaw/* and extensions/*/package.json
2. Loads extensions via src/plugins/loader.ts
3. Merges plugin schemas into OpenClawSchema via src/config/schema.ts209-248

Channel Extensions:

• extensions/matrix/package.json1-37: Matrix protocol
• extensions/zalo/package.json1-36: Zalo Bot API
• extensions/zalouser/package.json1-38: Zalo personal accounts
• extensions/msteams/package.json1-32: Microsoft Teams

Capability Extensions:

• extensions/voice-call/package.json1-20: Twilio/Telnyx voice calls
• extensions/memory-lancedb/package.json1-21: LanceDB memory backend

Plugin SDK: Exported via dist/plugin-sdk/ (openclaw/plugin-sdk in package exports).

Sources: extensions/ src/plugins/ src/config/schema.ts91-165

---

Data Flow: Message Processing

Key Functions:

• Normalization: src/channels/envelope.ts
• Session Key: src/config/sessions.ts
• Agent Execution: src/agents/agent-pi.ts
• Tool Registry: src/tools/registry.ts
• Sandbox Context: src/agents/sandbox/context.ts

Sources: src/gateway/router.ts src/channels/ src/agents/agent-pi.ts

---

Key File Structure

openclaw/
├── src/
│   ├── gateway/           # Gateway server, RPC protocol, router
│   ├── config/            # Schema (zod-schema.ts), validation, I/O
│   ├── agents/            # Agent runtime, system prompt, sandbox
│   ├── channels/          # Built-in channels (telegram, discord, etc.)
│   ├── memory/            # Memory index manager, embeddings, hybrid search
│   ├── tools/             # Tool registry, built-in tools (exec, read, etc.)
│   ├── sessions/          # Session management, transcript store
│   ├── cli/               # CLI commands (program.ts, agent-cli.ts, etc.)
│   └── infra/             # Infrastructure (env, errors, ports, dotenv)
├── extensions/            # Extension plugins (matrix, zalo, msteams)
│   ├── matrix/
│   ├── zalo/
│   ├── zalouser/
│   ├── msteams/
│   └── voice-call/
├── docs/                  # Documentation (configuration, channels, tools)
├── ui/                    # Control UI (Lit web components)
├── apps/                  # Native apps (macos, ios, android)
├── skills/                # Bundled skills (markdown files)
├── scripts/               # Build and maintenance scripts
└── openclaw.json          # User configuration file (~/.openclaw/)

Configuration Paths:

• Config: ~/.openclaw/openclaw.json
• State dir: ~/.openclaw/ (or $OPENCLAW_STATE_DIR)
• Workspace: ~/.openclaw/workspace/ (or agents.defaults.workspace)
• Sessions: ~/.openclaw/agents/<agentId>/sessions/*.jsonl
• Memory DB: ~/.openclaw/agents/<agentId>/memory.sqlite

Sources: src/ extensions/ README.md309-311

---

Summary

OpenClaw is a hub-and-spoke AI gateway where:

• The Gateway (port 18789) is the central control plane
• Agents execute AI turns via runEmbeddedPiAgent with tool support
• Channels normalize messaging platform protocols into unified envelopes
• Configuration is schema-validated and hot-reloadable
• Memory provides semantic search over workspace Markdown and transcripts
• Sandboxing isolates tool execution in Docker containers
• Extensions add new channels and capabilities via npm plugins

All system state lives in files: config in openclaw.json, sessions in *.jsonl transcripts, memory in Markdown + SQLite, and workspace context in IDENTITY.md, SKILLS.md, etc.

Sources: README.md1-498 package.json1-217 src/config/zod-schema.ts95-470