OpenClaw Architecture: How It Works Under the Hood

The Gateway (the central daemon)

The gateway is one long-lived process per host. It owns every messaging surface, maintaining live connections to each channel (WhatsApp, Telegram, Discord, Slack, Signal, WebChat, and more). It exposes a WebSocket API (default port 18789) that every client connects to, validates inbound frames against JSON Schemas, and emits typed events — agent, chat, presence, health, heartbeat, and cron. It also hosts an HTTP server for the WebChat UI and Canvas.

The Agent Runtime (embedded)

The agent runtime lives inside the gateway. It runs the agent attempt loop, adapts each provider's streaming format, handles context compaction and model selection, and wires up sessions. Conversations are persisted as sessions; direct chats collapse into a shared main session, while groups stay isolated so context never bleeds between rooms.

Channels & Channel Plugins

Channels are how the agent talks to the outside world. Several are built in (Discord, Telegram, Slack, Signal, iMessage, IRC, WhatsApp, WebChat, Google Chat). Many more ship as bundled plugins (Feishu, LINE, Matrix, Mattermost, Microsoft Teams, QQ, Nostr, and others), and a few install separately (WeChat, Voice Call). Each channel is configured under channels.* in ~/.openclaw/openclaw.jsonwith fields like dmPolicy and allowFrom, and multiple channels can run at once.

Models & Providers

OpenClaw is provider-agnostic. It speaks to 35+ providers — Anthropic, OpenAI, Google, xAI, DeepSeek, MiniMax, Groq, Ollama, vLLM — plus any OpenAI-compatible or Anthropic-compatible endpoint, and subscription OAuth flows like OpenAI Codex. Defaults live under agents.defaults.model and providers.*, and credentials are stored per-agent in auth-profiles.json.

Skills

Skills are Markdown instruction files (SKILL.md) that teach the agent how to do a specific job. They load from ~/.openclaw/skills/ and can be installed from ClawHub. See the best OpenClaw skills roundup for examples.

Plugins (the extension system)

Plugins are npm packages installed with openclaw plugins install <pkg>. A plugin declares itself via an openclaw.plugin.json manifest and can register new channels, tools, or runtimes. This is how channels like Slack and Mattermost plug in without changing the core.

MCP Servers

OpenClaw supports the Model Context Protocol natively. MCP servers give the agent tools — Notion, Google Workspace, Playwright, search APIs, and more. MCP is a protocol for tools; skills are Markdown instructions. They complement each other.

Browser Relay & Automation

OpenClaw includes a Playwright-based browser automation capability and a browser relay that lets the agent drive a real browser for tasks that need a live session. Sandboxing and command execution round out the tool surface.

Clients / Control UIs

Everything connects back to the gateway's WebSocket API: the built-in WebChat, the macOS menu-bar companion, iOS and Android mobile nodes, the Windows Hub app, and the openclaw CLI. The gateway is the hub; clients are spokes.

Where Config Lives

• Main config: ~/.openclaw/openclaw.json
• Sessions: ~/.openclaw/agents/<agentId>/sessions/
• Auth: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Skills: ~/.openclaw/skills/
• Workspace: ~/.openclaw/workspace/
• In Docker/hosted: /app/openclaw.json or /home/node/.openclaw/openclaw.json

How It Fits Together

A message arrives on a channel → the gateway validates and routes it → the embedded runtime picks a model, runs the agent loop, and calls tools (skills, MCP, browser) → the reply streams back out the same channel, while events fan out to every connected client. One daemon, many surfaces.

What's Next?

• OpenClaw Gateway — the daemon and its Web UI
• OpenClaw + Codex — provider auth in practice
• OpenClaw Browser Relay — the browser layer
• OpenClaw Skills — the skills system