No history yet

Gateway Architecture

The Fat Gateway Model

OpenClaw’s architecture deviates from simple API wrappers. It implements a 'Fat Gateway' model, a persistent control plane that acts as the central nervous system for all agentic operations. This isn't a stateless proxy but a long-running Node.js daemon that manages state, orchestrates workflows, and enforces determinism.

Local-first Gateway — single control plane for sessions, channels, tools, and events.

The gateway runs on Node.js 22+, leveraging modern features like the permission model and stable Web Streams API for efficient I/O. Its primary role is to create a durable, stateful bridge between the outside world (messaging platforms, APIs) and the internal reasoning loops of the language model.

Protocol and Communication

Communication with the gateway is handled exclusively through JSON-RPC 2.0, a lightweight remote procedure call protocol. This choice facilitates bi-directional event streaming over a single connection, typically a WebSocket. Rather than a simple request-response pattern, the gateway pushes events to connected clients (like a CLI or a web UI) and receives tool execution commands in return.

// Example: Event sent from Gateway to Client
{
  "jsonrpc": "2.0",
  "method": "session.event.received",
  "params": {
    "sessionId": "sid-12345",
    "event": {
      "type": "message.new",
      "payload": {
        "text": "Book a flight to SFO for next Tuesday."
      }
    }
  }
}

// Example: Command sent from Client to Gateway
{
  "jsonrpc": "2.0",
  "method": "tool.execute",
  "params": {
    "sessionId": "sid-12345",
    "toolName": "calendar.create_event",
    "arguments": {
      "summary": "Flight to SFO",
      "date": "2024-09-10T09:00:00-07:00"
    }
  },
  "id": 1
}

This event-driven architecture allows the gateway to manage long-running, asynchronous tasks without blocking the main thread. It can handle multiple concurrent sessions, each with its own context and state, while providing real-time feedback to any connected interface.

Message Serialization and State

A key challenge in agentic systems is managing concurrency and preventing race conditions that lead to non-deterministic behavior. OpenClaw solves this through a . Each session, or related group of operations, is assigned to a specific 'lane'. All messages within a single lane are processed serially in a First-In, First-Out (FIFO) order.

This architecture ensures that even with hundreds of concurrent sessions, each one behaves as if it has exclusive access to the agent's reasoning process, guaranteeing that state transitions remain predictable and auditable.

This serialization is crucial. It prevents a scenario where, for example, a tool's result arrives and is processed before the model has even finished its initial thought process. The gateway acts as a traffic controller, ensuring a logical, step-by-step progression for each independent workflow. This internal handshake between the gateway, the runtime, and model providers is what provides OpenClaw with its robust and reliable execution model.

Let's check your understanding of the Gateway architecture.

Quiz Questions 1/5

What architectural model best describes OpenClaw's control plane?

Quiz Questions 2/5

What communication protocol is used exclusively for interacting with the OpenClaw gateway?