Agents

OpenClaw Agents Overview

4 min read

Browse more in Agents.

All agents guides →

This guide walks you through the OpenClaw gateway architecture so you can design and configure agents that talk to the right clients, nodes, and channels. You will see how the Gateway, WebSocket protocol, and device pairing model fit together, and what that means for your agent configuration and routing.

By the end, you will know where your agents actually run, how they receive events, and how to connect them safely over local and remote setups.

Setup flow

Prerequisites

  • ✓A running OpenClaw Gateway on a host where you can execute `openclaw gateway`.
  • ✓Access to at least one control-plane client (macOS app, CLI, or web UI) that can open a WebSocket connection to the Gateway on `127.0.0.1:18789` or your configured bind host.
  • ✓Network access to the Gateway host over loopback, SSH tunnel, VPN, or Tailscale so you can connect WebSocket clients and nodes.
  • ✓A basic understanding of WebSocket JSON APIs so the request/response and event shapes for `agent` and `chat` make sense.

Steps

  1. 1

    Start the OpenClaw Gateway in foreground

    Run the Gateway in the foreground so you can see logs while you experiment with agent events and connections. This process owns all messaging surfaces and exposes the WebSocket API your agents depend on.

    bash
    openclaw gateway
  2. 2

    Connect a control-plane client over WebSocket

    1:18789`). These clients send `agent` and `send` requests and subscribe to events that drive your agents.

    bash
    ssh -N -L 18789:127.0.0.1:18789 user@host
  3. 3

    Understand the WebSocket wire protocol for agent calls

    Every client and node must start with a `connect` frame, then use typed JSON requests and events. When you trigger an agent run, it flows through this `{type:"req"}` / `{type:"res"}` pattern, and your client listens for `agent` and `chat` events.

    text
    {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  4. 4

    Include node role and capabilities for device-based agents

    When you want agents to control local capabilities like canvas, camera, or screen recording, connect that device as a Node with `role: node`. The node advertises its commands so the Gateway can route agent tool calls correctly.

    text
    Nodes must include `role: "node"` plus caps/commands/permissions in `connect`.
  5. 5

    Serve the canvas and A2UI hosts for agent UIs

    The Gateway also serves HTTP endpoints that agents can treat as their workspace UI. When you design agents that edit or render UI, they target the canvas host and A2UI paths exposed on the same port as the Gateway.

    text
    /__openclaw__/canvas/
/__openclaw__/a2ui/
  6. 6

    Secure agent access with gateway auth and pairing

    Every WebSocket client and node includes a device identity and must pass gateway auth. This protects your agents from untrusted callers and ensures only paired devices can send `agent` requests or receive sensitive events.

    text
    gateway.auth.allowTailscale: true
gateway.auth.mode: "trusted-proxy"
gateway.auth.mode: "none"

Configuration

OptionDescriptionExample
gateway.auth.allowTailscaleEnables identity-bearing modes such as Tailscale Serve so the Gateway can satisfy auth from request headers instead of shared-secret tokens.true
gateway.auth.modeControls how the Gateway authenticates WebSocket connections, including trusted-proxy and none for private ingress.trusted-proxy

Troubleshooting

WebSocket connection closes immediately when the first frame is not `connect`.

The Gateway requires a handshake; any non-JSON or non-`connect` first frame is a hard close. Fix your client to send a JSON `connect` frame as the very first message before any `agent` or `send` requests.

Agent or send requests are retried and cause duplicate side effects.

Side-effecting methods like `send` and `agent` require idempotency keys so the Gateway can dedupe retries. Update your client to include an idempotency key per request so the server's short-lived cache can filter duplicates.

Remote WebChat or CLI cannot reach the Gateway over the internet.

The Gateway binds locally by default and remote setups should connect through SSH, Tailscale, or VPN. 1:18789`.

bash
ssh -N -L 18789:127.0.0.1:18789 user@host

New device cannot send agent requests because pairing is not approved.

All WebSocket clients and nodes include a device identity and new IDs require pairing approval. Approve the device in the pairing flow so the Gateway issues a device token, then reconnect so it can send `agent` and `chat` traffic.

Frequently asked questions

Powered by Mem0

Add persistent memory to OpenClaw

Official Mem0 plugin for OpenClaw keeps context across chats and tools. Smaller prompts, lower cost, better continuity for your agents.

Read the official Mem0 guideOpen Mem0

More in Agents

Agents

Skills and Plugins in OpenClaw