Architecture Overview
OpenClaw's architecture is built around a single core principle: all messages from every messaging platform converge into one AI Agent runtime. The Gateway serves as the central hub -- responsible for connections, routing, and management.
Full Architecture Diagram
Core System Layers
OpenClaw is organized into five main layers:
1. Gateway Control Plane
The Gateway is the nerve center of the entire system. It runs a WebSocket service through which all clients (CLI, native apps, Web UI) and channels (Telegram, Discord, etc.) communicate.
Key responsibilities:
| Responsibility | Source File | Description |
|---|---|---|
| WebSocket Server | src/gateway/server.impl.ts | WS server built on the ws library |
| Authentication | src/gateway/auth.ts | Token/Password/Tailscale auth |
| Method Dispatch | src/gateway/server-methods.ts | Route requests to appropriate handlers |
| Session Management | src/gateway/session-utils.ts | Session state, persistence, patching |
| Config Hot-Reload | src/gateway/config-reload.ts | chokidar watching + incremental reload |
2. Channel Abstraction Layer
Each messaging platform is a "channel," unified through the ChannelPlugin interface and complemented by lightweight ChannelDock metadata.
3. Agent Runtime
The Agent runtime handles interaction with AI models, processes tool calls, and manages streaming output. The core entry point is subscribeEmbeddedPiSession().
Execution flow:
4. Plugin System
The plugin system manages the registration of tools, channels, hooks, and HTTP routes through a central registry. It supports hot-loading and lifecycle management.
Plugin registration types:
| Type | Description |
|---|---|
PluginToolRegistration | Register Agent tools (factory pattern) |
PluginChannelRegistration | Register channel plugin + dock metadata |
PluginHookRegistration | Register lifecycle hooks |
PluginHttpRegistration | Register HTTP routes |
PluginServiceRegistration | Register background services |
5. CLI
The CLI is built with Commander.js and uses a dependency injection pattern (createDefaultDeps()) to inject channel send functions into commands.
Request-Response Protocol
The Gateway defines a standard request-response-event frame format:
Authorization check levels:
- Role check -- operator vs node
- Scope check -- admin, read, write, approvals, pairing
- Method-level permission -- each method declares required scopes
Data Flow: Sending a Message
The complete message-sending flow spans multiple layers:
Hot-Reload Strategy
The Gateway watches for configuration file changes via chokidar and determines how to handle them according to predefined rules:
| Reload Type | Description | Examples |
|---|---|---|
restart | Full Gateway restart required | Plugin config, Gateway core config |
hot | Runtime hot-reload | Hooks, Cron, Browser, Channel config |
none | Ignore change | Identity config, Wizard, Logging, Models |
Changes are debounced with a 300ms delay to batch rapid, successive file modifications.
Summary
- Gateway is the hub: WebSocket control plane + method dispatch + authentication
- Channels unify different platforms through a Plugin + Dock dual-layer abstraction
- Agent runtime handles AI interaction, tool calls, and streaming output
- Plugins provide pluggable tools, channels, hooks, and HTTP routes
- CLI uses Commander.js + dependency injection as the primary user-facing interface
Next: Project Structure