openclaw/packages/gateway-client

@openclaw/gateway-client

Reference WebSocket client for the OpenClaw Gateway protocol. It provides the connection state machine used by OpenClaw's own Node and browser clients: challenge-based authentication, typed protocol frames, request correlation, timeouts, reconnect backoff, device-token handling, and event delivery.

The current wire protocol is version 4. General clients must advertise exactly v4 with minProtocol: 4 and maxProtocol: 4. See the Gateway protocol specification for the complete handshake, authentication, role, scope, and method contracts. Exact node identities (role: "node" plus mode: "node") and probe clients can use v3. The built-in node host starts with an exact v4 envelope, then retries an exact v3 envelope after a v3 Gateway rejects v4. If that legacy probe reaches an upgraded v4 Gateway, the client reconnects with the full v4 envelope before reporting readiness. Other exact node identities default to [3, 4]. Explicit bounds override these defaults; [3, 4] on the built-in node host selects the same bounded negotiation.

Versioning

Package versions follow the OpenClaw calendar release train: YYYY.M.PATCH, including the OpenClaw prerelease suffix when applicable. The package version is separate from the Gateway's current wire protocol number reported in hello-ok.

Install

Use the verified stable release with exact pins:

npm install --save-exact @openclaw/gateway-client@2026.8.1 @openclaw/gateway-protocol@2026.8.1

See the canonical installation guide for package/wire-version rules and recovery from reserved 0.0.0 artifacts. Test it with the Gateway version you deploy; the root openclaw CLI has its own package versions and dist-tags.

This release declares Node.js >=22.19.0. Node consumers use the ws transport included as a runtime dependency. Browser consumers provide their platform WebSocket through the browser-safe protocol client surface.

For device-authenticated Node connections, supply deviceIdentity (or hostDeps.loadOrCreateDeviceIdentity) and the hostDeps.signDevicePayload and hostDeps.publicKeyRawBase64UrlFromPem callbacks. The host also owns device-token storage through GatewayClientHostDeps; the package does not load OpenClaw's local identity or credentials automatically.

Token storage callbacks may return their existing synchronous result or a Promise. The client waits for token loading before sending connect, and for issued-token persistence before calling onHelloOk. An accepted hello creates a persistence obligation that survives disconnect or stop; bootstrap credentials retire after that persistence succeeds. Readiness still belongs to the current connection. stop() requests shutdown synchronously; stopAndWait() also waits for accepted token operations to settle, even when transport closure times out. A reconnect waits for earlier token operations before reading the token again.

Accepted asynchronous persistence failures reach onConnectError even after the connection retires. If that callback is absent or throws, stopAndWait() rejects with the first undelivered persistence error after draining accepted work. A later connection can still load credentials; a reported failure does not poison its storage queue. Synchronous callback exceptions retain their existing connect-error behavior.

Hosts should honor the optional expectedToken storage condition. A string compares the existing row before writing or clearing; null on a store means insert only when no row exists. Omission preserves unconditional storage behavior. This prevents an older receipt or cleanup from replacing another client's newer token. Close cleanup waits for pending persistence and, if its result is uncertain, conditionally clears only the sampled and received tokens. Cleanup before any token observation retains its existing unconditional behavior. An observed empty cache does not permit unconditional cleanup.

When storage callbacks receive signal or assertCurrent, check them immediately before admission and before committing a write. These callbacks stay local to the host; do not send them to a worker. Loads use the current connection lifetime; cleanup uses the client lifetime. Accepted hello persistence is independent of transport lifetime and retains the host's normal storage admission checks.

Entry points

• @openclaw/gateway-client exports the Node GatewayClient, device-auth helpers, readiness helpers, and timeout utilities.
• @openclaw/gateway-client/browser exports the browser-safe protocol client, browser device-auth lifecycle, reconnect policy, and lightweight protocol constants. Its module graph does not import Node built-ins or ws.
• @openclaw/gateway-client/readiness exports helpers that delay client startup until the event loop can process Gateway IO.
• @openclaw/gateway-client/timeouts exports timeout constants and safe timer resolution helpers.
• @openclaw/gateway-client/websocket-data converts every Node ws raw-data shape to UTF-8 text.

Node quickstart

import { GatewayClient } from "@openclaw/gateway-client";
import { PROTOCOL_VERSION } from "@openclaw/gateway-protocol/version";

const connected = Promise.withResolvers<void>();
const client = new GatewayClient({
  url: "ws://127.0.0.1:18789",
  token: process.env.OPENCLAW_GATEWAY_TOKEN,
  minProtocol: PROTOCOL_VERSION, // v4
  maxProtocol: PROTOCOL_VERSION, // v4
  onHelloOk: () => connected.resolve(),
  onConnectError: (error) => connected.reject(error),
  onEvent: (event) => {
    console.log(event.event, event.payload);
  },
});

client.start();
await connected.promise;

const status = await client.request("status", {});
console.log(status);

client.stop();

The client waits for the Gateway's connect.challenge event before sending its connect request. It includes the challenge nonce in device authentication and does not fall back to a pre-challenge handshake. onHelloOk fires only after the Gateway accepts a compatible connection, so requests should wait for that callback.

This loopback example uses the default gateway-client / backend identity. It is not a device-pairing example. UI clients should declare their actual mode and supply the device-auth host callbacks described above; see device identity and pairing.

For remote connections, prefer wss://. The Node client also accepts plaintext ws:// by default for loopback, private/link-local/CGNAT IP addresses, and .local or .ts.net hostnames. This allowlist does not provide encryption: authentication material and Gateway traffic must not cross an untrusted network without transport security.

Browser clients

Import @openclaw/gateway-client/browser when the host owns the WebSocket adapter and device-key storage. The browser entry includes GatewayProtocolClient and GatewayBrowserDeviceAuthLifecycle; it deliberately omits the Node transport, TLS fingerprint handling, and private-network address policy.

The host is responsible for:

• creating a GatewayProtocolSocket adapter around the browser WebSocket;
• loading and storing browser device identity and issued device tokens;
• signing the challenge-bound device payload;
• using the Gateway challenge ts as the device proof's signedAt value;
• supplying the client identity, role, scopes, and authentication selection;
• choosing close and reconnect behavior for product-specific errors.

The shared protocol client still owns frame parsing, request correlation, challenge ordering, timeout cleanup, sequence-gap detection, and reconnect scheduling.

Both the Node and browser entries export isGatewayProtocolResponseError(error). It recognizes correlated Gateway response errors; constructed errors and local transport timeouts return false. Both entries use the same implementation.

Defaults and reconnect behavior

The Node client starts with a 30 second request timeout, a 15 second connect-challenge timeout, and exponential reconnect delays from 1 second to 30 seconds with a multiplier of 2. Server-provided startup retry hints may override the next delay.

The canonical defaults table and the server policy fields that can replace pre-handshake values are documented in the Gateway protocol specification.

Use the ./timeouts entry point when a host must align readiness or watchdog budgets with these defaults. Use the ./readiness entry point when startup must wait for an event-loop probe before opening the socket.

Bundled internals

The retry supervisor and the small @openclaw/net-policy/ip implementation are inlined into the published JavaScript and declarations. They are implementation details, not public exports or supported API surfaces. ipaddr.js remains an external dependency because the inlined IP helpers use its public runtime and types.

ws, @openclaw/gateway-protocol, and ipaddr.js remain external in the published distribution. Consumers should import protocol types and constants from @openclaw/gateway-protocol, not from bundled implementation paths.

Contract notes

• The client is inert at module import and construction time. start() opens the socket; stop() closes it and rejects pending requests.
• A request uses request(method, params) after hello-ok. Passing timeoutMs: null creates an intentionally unbounded request.
• Finite request deadlines reject with GatewayProtocolRequestTimeoutError, whose CLIENT_TIMEOUT code, method, deadline, and send-boundary flag remain distinct from authoritative Gateway response errors.
• Device identity persistence, signing, proxy routing, TLS formatting, and logging stay host-owned through GatewayClientHostDeps.
• Protocol changes are additive first. Incompatible changes require an explicit wire-version decision and coordinated server/client follow-through.