🏗️ Architecture
How OpenClaw works under the hood. From message to response.
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ YOUR PHONE │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Telegram │ │ WhatsApp │ │ Discord │ │ Matrix │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
│ │ │ │
└─────────────┴──────┬──────┴─────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GATEWAY (your machine) │
│ ws://127.0.0.1:18789 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Channels │ │ Sessions │ │ Cron │ │
│ │ Manager │ │ Manager │ │ Scheduler │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┴────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────┐ │
│ │ Agent Runtime │◄──── Workspace Files │
│ │ + Tool Router │ (SOUL.md, etc.) │
│ └───────┬───────┘ │
└──────────────────────────┼───────────────────────────────────────┘
│
▼
┌───────────────┐
│ AI Provider │
│ (Claude, GPT, │
│ OpenAI...) │
└───────────────┘
Core Components
Gateway
The central process that runs on your machine. It:
- Manages all channel connections
- Routes messages to the right session
- Handles the WebSocket control plane
- Runs cron jobs and heartbeats
- Serves the web UI on port 18789
openclaw gateway status
Sessions
Each conversation is a session with its own context:
- Main session: Your primary DM chat
- Isolated sessions: Groups, cron jobs
- Sub-agents: Spawned for background work
Sessions maintain conversation history and can share the workspace.
Agent Runtime
The runtime that processes requests, model calls, tools, memory, and sub-agent orchestration. It:
- Reads your workspace files for context
- Has access to tools (file ops, exec, web)
- Streams responses back to channels
- Runs in RPC mode for tool calling
Workspace
Your agent's home directory (~/.openclaw/workspace/):
- SOUL.md — Core personality
- USER.md — Info about you
- MEMORY.md — Long-term context
- memory/ — Daily logs
- brain/ — Second brain docs
Message Flow
What happens when you send a message:
Message Received
You send "Check my calendar" via Telegram
Gateway Routes
Gateway identifies your session and loads context
Context Built
Workspace files (SOUL.md, etc.) are loaded as system prompt
Agent Processes
The agent runtime calls the AI provider with your message + context
Tools Execute
Agent uses tools (gog skill) to check your Google Calendar
Response Streams
Response streams back to Telegram as the agent types
Key Concepts
🔐 Loopback-First
Gateway WebSocket defaults to localhost only. Use Tailscale or SSH tunnels for remote access. Security by default.
📡 One Gateway Per Host
Use account IDs/profiles for channel isolation where supported. For browser-backed channels such as WhatsApp Web, keep ownership clear so two gateways do not fight over the same paired session.
🧠 Context Injection
Workspace files are injected as system prompt context. The agent reads them every turn to maintain personality and memory.
🔄 Session Isolation
DMs share a main session. Groups get isolated sessions. Cron jobs run in isolated sessions to avoid context pollution.
🛠️ Tool Streaming
Tools execute as the agent works. File reads, web fetches, and commands stream results back to the conversation.
📦 Skills = Instructions
Skills are just markdown files with instructions. They tell the agent how to use external tools — no code required.
Network Topology
🏠 Local Mode (Default)
Gateway binds to 127.0.0.1:18789. Only accessible from the same machine. Most secure.
🌐 Tailscale Mode
Gateway binds to Tailscale interface. Accessible from your Tailnet. Requires token auth.
openclaw gateway --bind tailnet --token xxx
🔗 Remote via SSH
SSH tunnel to forward the local port. Works with any server.
ssh -L 18789:localhost:18789 user@server