Network#

OpenClaw centers on a single Gateway process that owns all channel connections, session routing, and control-plane traffic. Clients (CLI, Control UI, companion apps) and nodes reach the Gateway over WebSocket; HTTP surfaces share the same port.

Core model#

The Gateway is the single source of truth. It listens for inbound channel events, runs the agent runtime, persists sessions, and delivers outbound messages. All operator and node traffic flows through one long-running process per host.

Default endpoint: ws://127.0.0.1:18789 (loopback). The same port also serves:

Health and readiness probes
OpenAI-compatible HTTP endpoints (when enabled)
Control UI and WebChat
Plugin-registered routes

See Gateway protocol for the exact connect handshake, request/response/event frames, and role handling. See HTTP API for the HTTP surfaces.

Binding and exposure#

Start the Gateway with explicit bind options:

openclaw gateway
openclaw gateway --port 18789 --bind lan --verbose
openclaw gateway --bind tailnet --port 18789

Supported --bind values: loopback (default), lan, tailnet, auto, or a custom host. Use --port to change the listen port (default 18789).

Equivalent configuration in ~/.openclaw/openclaw.json:

{
  "gateway": {
    "port": 18789,
    "bind": "lan",
    "customBindHost": "0.0.0.0"
  }
}

Loopback is the recommended starting point. Non-loopback binds require explicit authentication (token or password) or a correctly configured trusted proxy. Direct local loopback connects can auto-approve in some pairing flows; LAN, tailnet, and remote connections require explicit approval.

In Docker, the default bridge network makes the Gateway unreachable from the host unless you use --bind lan (or --network host) and configure auth. See Deployment and Linux server for container and VPS specifics.

Tailscale modes#

Tailscale exposure is controlled under gateway.tailscale:

{
  "gateway": {
    "tailscale": {
      "mode": "serve"   // "off" | "serve" | "funnel"
    },
    "bind": "loopback",
    "auth": {
      "mode": "password"
    }
  }
}

off (default): no Tailscale exposure.
serve: expose over Tailscale.
funnel: public exposure via Tailscale Funnel (requires password auth).

Serve and funnel modes mandate loopback bind. Identity-bearing Tailscale connections can satisfy auth when gateway.auth.allowTailscale is enabled.

Pairing and device identity#

Every WebSocket client presents a device identity on connect. New devices and nodes must be explicitly paired.

Operator clients (CLI, apps, Control UI) use the standard connect flow.
Companion nodes declare role: "node" plus caps, commands, and permissions at connect time. The Gateway issues a device token on successful pairing; subsequent reconnects reuse the token.

Manage nodes with:

openclaw nodes list
openclaw nodes pair approve ...

See Nodes for node-specific surfaces (canvas, camera, voice, host commands) and pending-work queues.

For channel DMs, the default policy is pairing. Unknown senders receive a short code; approve with:

openclaw pairing approve <channel> <code>

Per-channel overrides exist under channels.<id>.dmPolicy. Run openclaw doctor to surface risky DM or group policies.

Health, readiness, and discovery#

Built-in probes (no auth required on loopback):

GET /healthz — liveness
GET /readyz — readiness

Local discovery uses Bonjour/mDNS when the bind and network permit. Remote access is typically handled via SSH tunnels or Tailscale rather than direct public binds.

One Gateway per host#

Run a single Gateway per host for normal use. For isolation, run multiple Gateways with separate profiles (--profile) and ports. Treat the Gateway as the source of truth for state and workspace; back up ~/.openclaw regularly on servers.