Architecture

How OpenClaw's Gateway, agent runtime, tools, plugins, sessions, nodes, memory, model providers, and protocols fit together.

OpenClaw is a layered agent platform. The Gateway owns ingress, auth, routing, events, and control surfaces. The agent runtime owns prompts, tools, memory, models, and execution. Plugins and nodes extend the system outward.

System Overview

Gateway

The Gateway is a long-running control-plane process. It:

• serves the Control UI
• exposes WebSocket and HTTP surfaces
• manages auth and device pairing
• connects chat channels
• routes inbound messages to sessions and agents
• emits events
• tracks health and usage
• coordinates nodes and paired clients

The default local port is usually 18789.

Wire Protocol

Gateway clients use JSON frames over WebSocket. The common shape is:

• connect first
• request/response frames for RPC-style calls
• event frames for server-pushed updates
• auth in the connection handshake
• idempotency for side-effecting methods where needed

The exact protocol evolves, so treat docs and generated schemas as the source of truth when building clients.

Agent Runtime

The runtime builds each turn from:

• session state
• workspace context
• system prompt and runtime preface
• selected model provider
• visible tools
• active skills
• memory recall
• channel/runtime policy

The agent loop is still the familiar pattern:

1. receive input
2. route to agent/session
3. assemble context
4. call model
5. execute tools
6. observe results
7. respond or continue
8. persist session and memory state

Tools, Skills, Plugins

These are different architecture layers:

• tools are callable actions
• skills are prompt-level workflow instructions
• plugins are runtime extensions that can add tools, channels, providers, hooks, media, and skills

This separation lets OpenClaw add capability without stuffing every behavior into the core runtime.

Sessions and Memory

Sessions preserve the conversation and tool history. Compaction summarizes long context. Long-term memory is file-backed in the workspace through MEMORY.md and memory/YYYY-MM-DD*.md; memory search, QMD, active memory, dreaming, and memory wiki add retrieval and curation paths around that file layer.

Session state is agent-scoped. Multi-agent setups should keep agent directories separate unless shared recall is explicitly intended.

Channels

Channels are ingress and egress adapters. The Gateway normalizes Telegram, WhatsApp, Slack, Discord, iMessage, Signal, WebChat, and other surfaces into routing events and message delivery calls.

Channel behavior is not identical:

• group activation differs
• media support differs
• delivery formatting differs
• account/bot login differs
• plugin installation differs

Nodes

Nodes are paired device surfaces. They can expose camera, screen, location, Canvas, voice, and platform-specific actions.

Architecturally, a node is a remote capability provider attached to the Gateway. It should be treated as part of the same operator trust boundary once paired.

Model Providers

Providers are selected through provider-qualified model refs and credential profiles. The runtime must reconcile:

• provider IDs
• model catalog entries
• auth profiles
• tool schema compatibility
• fallback behavior
• usage reporting

Provider-specific replay and tool-schema behavior is a real operational concern for long sessions.

ACP and MCP

OpenClaw can participate in coding-agent ecosystems in two different roles:

• ACP bridge: an editor or ACP client talks to OpenClaw, and OpenClaw forwards work into a Gateway session.
• ACP agents: OpenClaw launches external harnesses such as Codex, Claude Code, Gemini CLI, or similar backends through an ACPX-style path.
• MCP: external clients can reach OpenClaw channel conversations or OpenClaw can use MCP-style capability surfaces depending on configuration.

Do not conflate these. One is OpenClaw as server/bridge, one is OpenClaw as orchestrator of external harnesses, and one is tool/context protocol integration.

Sandboxing

Sandboxing applies to tool execution, not the Gateway process itself. Backends include Docker, SSH, and OpenShell where configured. The main design question is not "is sandbox on?" but "which sessions, which tools, which workspace access, and which escape paths?"

Design Principles