OpenClaw
An open-source, self-hosted autonomous AI agent that operates through messaging platforms you already use — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, and more. Model-agnostic, built in TypeScript, with a hub-and-spoke architecture separating a Gateway control plane from sandboxed agent runtimes. Created by Peter Steinberger.
Architecture
Hub-and-Spoke Design
OpenClaw splits into two primary components:
Gateway — a Node.js WebSocket server (127.0.0.1:18789, loopback-only) that acts as the single control plane. Connects to all messaging platforms via channel adapters, manages session state and access control, and routes messages to the agent runtime. Exactly one Gateway runs per host.
Agent Runtime — executes AI interactions in a four-phase pattern per turn:
| Phase | Function |
|---|---|
| Session Resolution | Maps messages to sessions — DMs get full capabilities, group chats are sandboxed |
| Context Assembly | Loads session history from JSON, builds system prompts from workspace files (AGENTS.md, SOUL.md, TOOLS.md), runs semantic memory search |
| Model + Tool Execution | Streams to the configured model, intercepts tool calls, executes tools (in Docker sandbox for untrusted sessions), feeds results back |
| State Persistence | Persists session state to disk as append-only event logs with branching support |
The core agent loop itself is handled by the Pi agent framework — OpenClaw's value is in everything around the loop: channel normalization, session management, memory, security, and sandboxing.
Channel Adapter Pattern
Each messaging platform has a dedicated adapter implementing a common interface:
| Responsibility | What It Does |
|---|---|
| Authentication | QR codes (WhatsApp), tokens (Telegram/Discord), OAuth (Slack) |
| Inbound Parsing | Normalizes messages, attachments, and reply context into a common format |
| Access Control | Allowlists, DM pairing codes, group mention requirements |
| Outbound Formatting | Converts markdown, respects platform message limits, uploads media |
Adding a new channel means writing one adapter without touching any agent logic. Supported platforms include WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, Google Chat, and Matrix.
Model Provider System
OpenClaw is model-agnostic with support for 14+ providers using a provider/model reference format (e.g., anthropic/claude-opus-4-6):
| Category | Providers |
|---|---|
| Cloud | Anthropic, OpenAI, Google Gemini, Mistral, xAI, Groq, Cerebras |
| Routing | OpenRouter, GitHub Copilot, Hugging Face Inference |
| Local | Ollama, vLLM, LM Studio — any OpenAI-compatible endpoint |
Custom providers are configured via models.providers in openclaw.json. Authentication uses environment variables or OAuth flows.
Tool System
Tools are organized into groups with a cascading permission resolution chain where deny always wins:
| Group | Tools |
|---|---|
| Filesystem | read, write, edit, apply_patch |
| Runtime | exec, bash, process |
| Memory | memory_search, memory_get |
| Sessions | sessions_list, sessions_history, sessions_send, sessions_spawn |
| Web | web_search, web_fetch |
| UI | browser, canvas |
| Other | cron, gateway, nodes, image, message |
Permission Resolution Chain
Permissions cascade through six layers, each only able to narrow access:
- Tool profile base allowlist (
minimal,coding,messaging,full) - Global
allow/denyrules - Provider-specific policies
- Agent-level overrides
- Group/session-specific restrictions
- Sandbox tool policies
Execution Contexts
Tools can execute in three contexts:
- sandbox — Docker container (ephemeral, isolated filesystem)
- gateway — the Gateway host machine
- node — a paired remote device (macOS/iOS/Android)
Skills System
Skills are reusable playbooks — pure documentation, not executable code — that teach the agent how to combine tools for specific tasks.
A skill is a directory containing a SKILL.md file with YAML frontmatter (name, description, dependencies, required binaries) and markdown instructions. Skills are loaded from workspace, agent, and bundled directories.
The key design principle: tools provide capabilities, skills provide knowledge. Installing the Obsidian skill teaches OpenClaw how to organize notes, but without the write tool enabled, it cannot write files. This separation is deliberate.
Skills are snapshotted at session start. Only relevant skills for the current turn are injected into the system prompt to avoid prompt bloat.
Memory Architecture
Memory is built on plain Markdown files stored on disk as the authoritative source. Nothing persists in RAM alone.
| File | Purpose | Loaded When |
|---|---|---|
memory/YYYY-MM-DD.md | Daily logs, append-only running context | Today's and yesterday's at session start |
MEMORY.md | Long-term durable facts, decisions, preferences | Private sessions only |
SOUL.md | Personality, tone, values, non-negotiable constraints | Always |
AGENTS.md | Core operational instructions | Always |
TOOLS.md | User-specific tool conventions | Always |
Semantic Search (Hybrid BM25 + Vector)
Memory retrieval combines two approaches:
- Vector similarity (70% weight) for semantic matching
- BM25 keyword matching (30% weight) for exact tokens
- MMR post-processing reduces redundant results (lambda: 0.7)
- Temporal decay with 30-day half-life — evergreen files like
MEMORY.mdskip decay
Indexes stored in SQLite at ~/.openclaw/memory/<agentId>.sqlite, with optional sqlite-vec for accelerated vector queries.
Context Compaction
When a session approaches the context window limit, OpenClaw triggers a silent agentic turn that prompts the model to write durable memories to disk before compaction. The flush uses a NO_REPLY option so users see nothing.
Session-Based Trust
Session identifiers encode trust levels:
| Pattern | Trust Level | Access |
|---|---|---|
agent:<id>:main | Operator | Full host access |
agent:<id>:<channel>:dm:<id> | Untrusted | Docker-sandboxed |
agent:<id>:<channel>:group:<id> | Untrusted | Docker-sandboxed |
Unknown senders must go through a DM pairing code approval flow before messages are processed. Open public access requires explicit opt-in.
Agent-to-Agent Communication
Sessions can communicate via sessions_send, sessions_history, and sessions_spawn — enabling multi-agent coordination without switching chat surfaces. Each session has its own lane with serial execution by default. Parallelism is opt-in.
Patterns Used
| Pattern | How It's Used |
|---|---|
| ReAct | Core agent loop — reason, call tools, observe results, repeat |
| Tool Router | Model selects from 20+ tools via function calling |
| Router | Channel adapters normalize messages from any platform into a common format |
| File-Based Memory | MEMORY.md, SOUL.md, daily logs — all plain Markdown on disk |
| Vector Store | Hybrid BM25 + vector semantic search over memory files |
| Human-in-the-Loop | DM pairing codes, cascading deny-always-wins permission chain |
| Hierarchical Agent | Sessions can spawn sub-sessions for delegated tasks |
| Conversation Summarization | Silent compaction flushes memories to disk before context compression |
| Code Execution | Docker sandbox for untrusted session tool execution |