OpenClaw Architecture

This page explains how OpenClaw is built and how it runs. If you’re wondering how OpenClaw works or what the Gateway is, we start with the Gateway—the single process that holds all channel connections and the control plane—and an architecture diagram. If you need to run OpenClaw remotely or expose it safely, Network model covers loopback-first defaults and options (SSH, Tailscale, ports). If you care about where messages go and how context is kept, Agent loop and Session model describe the flow from message to response and how sessions (main, group, isolated) are chosen. If you’re looking for where OpenClaw stores config, prompts, and memories, Workspace structure lists paths and what lives there. To run different agents for different channels or contacts, Multi-agent routing explains one Gateway with many workspaces. Streaming and Protocol and communication round out how replies are delivered and how clients and agents talk to the Gateway. For changing behaviour, ports, or session rules, see Configuration and Sessions.

The Gateway (openclaw gateway) is the only process that holds channel sessions and serves the control plane. It manages WhatsApp, Telegram, Discord, iMessage (and other plugins), handles session routing, serves the Control UI and the Canvas host for WebViews, and coordinates agents. Run it once per machine: openclaw gateway (or start it via your installation method). Only one process should own the WhatsApp Web session on a host to avoid conflicts. The Gateway listens on ws://127.0.0.1:18789 by default and serves the Canvas at http://<host>:18793/__openclaw__/canvas/—see Network model for remote access.

WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://<gateway-host>:18793
  │                           │    /__openclaw__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (openclaw …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (OpenClaw.app)
              ├─ iOS node via Gateway WS + pairing
              └─ Android node via Gateway WS + pairing

By default the Gateway binds to localhost only: WebSocket at ws://127.0.0.1:18789, so only processes on the same machine can connect. That keeps credentials and control off the network. For remote access (e.g. your phone or another machine), use an SSH tunnel to 18789, or Tailscale and --bind tailnet with auth tokens—details in the Security guide. The Canvas HTTP server (port 18793, path /__openclaw__/canvas/) serves assets for node WebViews; if you expose the Gateway host, ensure that port is only reachable where you intend. Ports and bind addresses can be overridden in configuration.

When a message hits a channel, the Gateway routes it to a session (main, group, or isolated). The agent loads context and skills for that session, sends the conversation to the LLM, runs any tools the model requests, streams the reply back to the channel, and writes conversation and memory into the workspace. That cycle—receive → route → context + LLM + tools → stream → persist—is the agent loop. You don’t “enable” it; it’s how every message is handled. Session types and routing decide which workspace and agent run; see Sessions and Configuration to tune behaviour.

Messages are grouped into sessions. Direct messages usually share one main session; each group chat gets its own session; you can also define isolated sessions for specific contacts or security. Per session you can set activation (e.g. always reply vs. only when @mentioned), queue behaviour for concurrent messages, and context rules. Groups can run in Docker sandboxes for isolation. Configuring sessions and activation is done in configuration and explained in the Sessions guide. You get separate context and history per session, so group chats don’t leak into DMs and you can give different groups different agents or workspaces.

OpenClaw keeps state in files. Config: ~/.clawdbot/moltbot.json (path kept for backward compatibility). Credentials: ~/.clawdbot/credentials/. Workspace root: ~/clawd/ by default—prompts (AGENTS.md, SOUL.md, TOOLS.md), skills under ~/clawd/skills/<skill>/SKILL.md, daily memory files (Markdown), and session state. Because everything is on disk, you can edit config and prompts in a normal editor, search memories with Raycast or Obsidian, and back up or version-control the workspace. Paths and roots are configurable; see Configuration. For what to back up and how to restore, see Workspace Backup & Restore.

You can point different channels, contacts, or groups at different agents. Each agent has its own workspace (and thus its own prompts, skills, and memories). So one agent might handle a support channel with a dedicated workspace and skills, while another handles DMs with a different personality and tools. Routing is configured per channel, account/peer, or group; the Sessions guide and Configuration cover how to set it up. You get multiple specialized agents without running multiple Gateways—one Gateway, many workspaces.

Replies are streamed in chunks so you see output as it’s generated rather than waiting for the full response. On Telegram, typing indicators and draft updates can stream too; tool results stream as they’re ready. Markdown is normalized so formatting works across channels. This is default behaviour; no extra setup. If a channel doesn’t support streaming, the Gateway still sends content in blocks for consistency. See Features for channel-specific behaviour.

Clients (CLI, macOS app, iOS/Android nodes, Control UI) connect to the Gateway over WebSocket (default port 18789). The WebSocket API is used for real-time messages, session management, node pairing, and dashboard updates. Agents (e.g. on a Pi or same machine) talk to the Gateway via RPC for tool calls, context and memory reads/writes, and session operations. So: channels → Gateway → session routing and agent loop; agents ↔ Gateway over RPC; clients ↔ Gateway over WebSocket. For binding to a different port or enabling remote access, see Network model and Configuration.