@clawboo/gateway-client


Version	`0.1.1`
Purity	browser-safe (the `ws` dep is for Node injection only; see `webSocketImpl`)
Purpose	A WebSocket client for the OpenClaw Gateway: UUID-keyed request/response correlation, event subscription, reconnect lifecycle, and a typed RPC surface for agents / sessions / config / chat.
Workspace deps	`@clawboo/logger`
External deps	`@noble/ed25519`, `ws`

The client owns reconnection after a connection that opened then dropped (800 ms → 15 s backoff). It negotiates the OpenClaw connect protocol (minProtocol: 3, maxProtocol: 4) and signs the connect frame with Ed25519 device auth in the browser (via crypto.subtle), or through an injected signConnect hook for Node callers. The device-auth module is internal and not re-exported.

Public API

Classes

Export	Signature	Contract
`GatewayClient`	`new GatewayClient()`	The WS client. Lifecycle: `connect(url, opts?)` / `disconnect()`. RPC: `call<T>(method, params?, timeoutMs = 60_000)`. Subscriptions: `onStatus(handler)`, `onEvent(handler)`, `on(event, handler)` (each returns an unsubscribe fn). Getter `status`; `getLastHello()`. Typed namespaces `agents` / `sessions` / `config` / `chat` (below).

GatewayClient typed RPC namespaces (instance fields, not separate exports):

Member	Signature	Contract
`agents.list`	`() => Promise<AgentsListResult>`	RPC `agents.list`.
`agents.create`	`(config: AgentCreateConfig) => Promise<AgentCreateResult>`	RPC `agents.create` with a 2-minute timeout (the Gateway resolves the default model, which can be slow on Windows).
`agents.delete`	`(id: string) => Promise<void>`	RPC `agents.delete` with param `{ agentId: id }`.
`agents.files.read`	`(agentId, name) => Promise<string>`	Calls RPC `agents.files.get`; returns `res.file.content` or `''` when missing.
`agents.files.set`	`(agentId, name, content) => Promise<void>`	RPC `agents.files.set`, 2-minute timeout.
`sessions.list`	`(agentId: string) => Promise<Session[]>`	RPC `sessions.list`.
`sessions.send`	`(agentId, message) => Promise<void>`	RPC `sessions.send`, delivers a message to the agent’s main session.
`sessions.patch`	`(key, updates) => Promise<SessionPatchResult>`	RPC `sessions.patch` (model / thinkingLevel / execHost). `execSecurity` and `execAsk` are RETIRED: they remain in the v4 schema but any request carrying either, `null` included, is refused with guidance to set `permissionMode` instead.
`sessions.abort`	`(key, runId?) => Promise<{ ok; abortedRunId?; status? }>`	Heavy session-level abort; `runId` optional (Gateway resolves the active run from `key`). `status: 'no-active-run'` is a benign no-op.
`config.get`	`() => Promise<GatewayConfig>`	RPC `config.get`.
`config.patch`	`(updates: Partial<GatewayConfig>, baseHash?, replacePaths?) => Promise<void>`	RPC `config.patch`, wire-encoded via `encodeConfigPatchParams` (`{ raw, baseHash, replacePaths }`). `replacePaths` is DERIVED from `updates` when omitted, so callers need not declare it; pass it only to override that. Without it a patch that shortens an array is refused.
`chat.abort`	`(sessionKey, runId) => Promise<{ ok; abortedRunId?; status? }>`	Surgical per-run cancel, the Stop-button primitive.

Functions

Export	Signature	Contract
`parseGatewayFrame`	`(raw: string) => Frame \| null`	`JSON.parse` a wire frame; returns `null` on parse failure.
`buildAgentMainSessionKey`	`(agentId: string, mainKey: string) => string`	Builds `agent:<agentId>:<mainKey>` (defaults `mainKey` to `'main'` when blank).
`parseAgentIdFromSessionKey`	`(sessionKey: string) => string \| null`	Extracts the agent id from an `agent:<id>:` key; `null` on no match.
`isSameSessionKey`	`(a: string, b: string) => boolean`	True when both trim to the same non-empty string.
`isGatewayDisconnectLikeError`	`(err: unknown) => boolean`	True for “gateway not connected”/“client stopped” messages or a `Gateway closed (1012)` reason.
`isAuthError`	`(msg: string \| null) => boolean`	Heuristic: true when the message reads as auth / unauthorized / forbidden / invalid-token / token-missing.
`resolveProxyGatewayUrl`	`() => string`	Same-origin `ws(s)://<host>/api/gateway/ws`; falls back to `ws://localhost:18790/api/gateway/ws` when `window` is undefined (SSR/Node).
`isLocalGatewayUrl`	`(url: string) => boolean`	True when the URL host is `localhost` / `127.0.0.1` / `::1` / `0.0.0.0`.
`encodeConfigPatchParams`	`(updates: Partial<GatewayConfig>, baseHash?: string, replacePaths?: string[]) => { raw: string; baseHash?; replacePaths? }`	Encodes a partial config into the `config.patch` envelope: `raw` = `JSON.stringify(updates)`, optional optimistic-concurrency `baseHash` from a prior `config.get`, and `replacePaths` naming every array being replaced. From OpenClaw 2026.9 a patch that would SHORTEN an array is refused unless its path is declared, so `replacePaths` is derived from the payload by `collectArrayPaths` rather than hand-listed at each call site. Object maps such as `mcp.servers` are skipped: they merge RFC 7386 style, where a key is removed by sending it as null.
`formatGatewayError`	`(error: unknown) => string`	Renders an error for display; `GatewayResponseError` → `Gateway error (<code>): <message>` (adds a `doctor --fix` hint on invalid-config).
`resolveGatewayAutoRetryDelayMs`	`(params: AutoRetryDelayParams) => number \| null`	Auto-reconnect backoff (`2s × 1.5^attempt`, capped 30s, max 20 attempts); `null` to stop on manual disconnect / non-retryable code / auth error.
`syncGatewaySessionSettings`	`(params: SyncSessionSettingsParams) => Promise<SessionPatchResult>`	Builds a `sessions.patch` payload from the provided settings (at least one required) and calls it through the injected `GatewayClientLike`.

Types & interfaces

Export	Kind	Contract
`ReqFrame`	type	Request frame: `{ type: 'req'; id; method; params }`.
`ResFrame`	type	Response frame: `{ type: 'res'; id; ok; payload?; error? }`.
`EventFrame`	type	Event frame: `{ type: 'event'; event; payload?; seq?; stateVersion? }`.
`Frame`	type	`ReqFrame \| ResFrame \| EventFrame`.
`GatewayStateVersion`	type	`{ presence: number; health: number }`.
`GatewayHelloOk`	type	The `hello-ok` connect response: protocol, features, snapshot, auth (deviceToken/role/scopes), policy.
`AgentStatus`	type	`'idle' \| 'running' \| 'error' \| 'sleeping'`.
`Agent`	interface	`{ id; name; status?; sessionKey?; model?; createdAt? }`.
`AgentListEntry`	interface	`{ id; name?; identity? }` (identity carries theme/emoji/avatar).
`AgentsListResult`	interface	`{ defaultId; mainKey; scope?; agents: AgentListEntry[] }`.
`AgentCreateConfig`	interface	`{ name; workspace }`, the only fields `agents.create` accepts.
`AgentCreateResult`	interface	`{ agentId; name; workspace? }`.
`Session`	interface	`{ key; agentId; createdAt?; updatedAt? }`.
`GatewayConfig`	interface	`{ path?; gateway?: { url?; token? }; [key: string]: unknown }`, loose; mirrors the on-disk config.
`ConnectionStatus`	type	`'disconnected' \| 'connecting' \| 'connected' \| 'reconnecting'`.
`GatewayDeviceField`	interface	Signed device fields on a connect frame: `{ id; publicKey; signature; signedAt; nonce? }`.
`ConnectOptions`	interface	Connect args: `clientName?`, `clientVersion?`, `token?`, `password?`, `authScopeKey?`, `disableDeviceAuth?`, `platform?`, `mode?`, `instanceId?`, `signConnect?` (Node device-auth hook), `origin?` (Node-only WS Origin), `webSocketImpl?`.
`WebSocketLikeCtor`	type	`new (url: string, options?: { origin?: string }) => WebSocket`, a constructor compatible with both the DOM global and the `ws` package.
`SessionPatchResult`	type	`{ ok: true; key; entry?; resolved? }`.
`GatewayClientLike`	type	`{ call<T>(method, params?): Promise<T> }`, the minimal forward-reference used by helper params.
`SyncSessionSettingsParams`	type	Input for `syncGatewaySessionSettings`: `{ client; sessionKey; model?; thinkingLevel?; execHost?; execSecurity?; execAsk? }`.
`AutoRetryDelayParams`	type	Input for `resolveGatewayAutoRetryDelayMs`: `{ status; didAutoConnect; wasManualDisconnect; gatewayUrl; errorMessage; connectErrorCode; attempt }`.
`GatewayErrorPayload`	type	`{ code; message; details?; retryable?; retryAfterMs? }`.

Errors

Export	Kind	Contract
`GatewayResponseError`	class	`extends Error`; constructed from a `GatewayErrorPayload`. Exposes read-only `code`, `details?`, `retryable?`, `retryAfterMs?`. SPA code branches on `err.code === 'NOT_PAIRED'` for the device-pairing flow.

Constants

Export	Kind	Contract
`GATEWAY_BROWSER_CLIENT_ID`	const	`'webchat-ui'`, the client id a browser connection sends at connect. The server-side connection sends `cli` instead, because the browser-UI ids also require a browser `Origin` header a Node connection cannot send (`CONTROL_UI_ORIGIN_NOT_ALLOWED`).
`GATEWAY_BROWSER_CAPS`	const	`readonly ['exec-approvals']`, the capabilities a browser connection declares. Declaring `exec-approvals` is what makes that socket an approval surface: the Gateway registers an approval route per run only for connections that declared it, and a run with no such route is denied outright (`exec denied: Headless runs cannot wait for interactive exec approval`) rather than queued. The server-side connection passes its own `caps` (`['tool-events', 'exec-approvals']`) explicitly and is unaffected by this default.
`EXEC_ALLOWLIST_CWD_BOUND_PREFIX`	const	`'sha256:cwd-argv:v1:'`, the only `argPattern` form an `allow-always` row is read as live in. A hand-typed pattern on such a row classifies as `inert-allow-always`.
`EXEC_ALLOWLIST_NODE_MARKER_PREFIX`	const	`'=node-command:'`, the companion row an operator’s “Always” mints alongside the grant. It authorizes nothing on its own, and the grant is read as depending on it, so both rows are removed together.
`EXEC_ALLOWLIST_EXACT_COMMAND_PREFIX`	const	`'=command:'`, the other marker form. A row carrying it is read as granting one exact command by itself.

Exec approvals policy

The Gateway keeps each agent’s exec approval posture, and the standing grants under it, in a store of its own, which it exposes over the wire only through exec.approvals.get and exec.approvals.set. Three modules cover it: execApprovals.ts writes the posture, execAllowlist.ts reads what a stored row means, and execRevoke.ts removes grants. All three are on the barrel because the server and the browser SPA are separate build targets and both need them.

clawboo treats exec.approvals.get as a WRITE rather than a read. On clawboo’s reading of OpenClaw, that call re-serialises the document and saves it back, so issuing it against a stored document that cannot be parsed would replace every agent’s policy with a fail-closed default. Anything that only needs to READ the grants should read OpenClaw’s stored row directly instead; see Data and state.

Export	Kind	Contract
`resolveExecPatchParams`	function	`() => { execHost: 'gateway' }`. The session-level exec fields `sessions.patch` still accepts. `execSecurity` and `execAsk` are RETIRED: they survive in the v4 schema, but a request carrying either, `null` included, is refused, so only `execHost` is sent. `permissionMode` is not offered as a replacement here because it also sets the session’s filesystem boundary.
`ExecAllowlistEntry`	type	`{ id?; pattern; argPattern?; source?; lastUsedAt?; [key: string]: unknown }`, one standing grant as the Gateway writes it. The index signature is deliberate: the Gateway owns this document, and a closed shape invites a caller to map over the rows and write back entries stripped of `argPattern`, which stop matching the command they were minted for.
`AgentApprovalPolicy`	type	`{ security?; ask?; allowlist? }`, one agent bucket inside the document.
`GatewayApprovalsDoc`	type	`{ version: 1; socket?; defaults?; agents? }`, the whole fleet permissions document. `socket` and `defaults` are carried across a rewrite rather than rebuilt.
`ApprovalsGetResult`	type	`{ path; exists; hash; file? }`, the `exec.approvals.get` / `exec.approvals.set` payload. `hash` is the base hash a compare-and-swap write quotes back.
`ExecApprovalsMutationOutcome`	interface	`{ wrote; attempts; result? }`. `result` is the Gateway’s own account of the document AFTER the write, which is what lets a caller prove a change landed without calling `exec.approvals.get` again (that call is itself a write).
`mutateExecApprovalsDoc`	function	`(client, mutate, opts?: { attempts? }) => Promise<ExecApprovalsMutationOutcome>`. Reads the document, runs `mutate` on it, and writes it back under the base-hash compare-and-swap (default 3 attempts). On a conflict `mutate` is re-run against the FRESH read rather than the computed payload being re-sent, so a concurrent write is not erased. `mutate` returns `null` to write nothing. A reply that is not a policy snapshot throws instead of being treated as an empty document.
`upsertExecApprovalPolicy`	function	`(client, agentId, execAsk) => Promise<void>`. Writes one Boo’s exec posture. `execAsk: 'off'` removes the two posture fields and keeps the allowlist, so standing grants survive Run Freely. An emptied bucket is dropped, since absent and empty resolve the same way.
`ExecAllowlistClass`	type	A tagged union of the eight ways one stored row is read: `bound-grant`, `node-marker`, `exact-command-grant`, `inert-allow-always`, `path-rule`, `arg-rule`, `catch-all`, `inert`.
`ClassifiableEntry`	interface	`{ pattern?; argPattern?; source?; [key: string]: unknown }`, the minimum an entry needs for the classifier.
`isCwdBoundArgPattern`	function	`(value: unknown) => boolean`. True when the value is a string starting `sha256:cwd-argv:v1:`.
`classifyExecAllowlistEntry`	function	`(entry: ClassifiableEntry) => ExecAllowlistClass`. A transcription of the branches the enforcing matcher was observed taking, written in that same order so the two can be compared clause by clause when OpenClaw changes.
`isEffectiveExecGrant`	function	`(entry: ClassifiableEntry) => boolean`. Whether this row can let a command through ON ITS OWN. False for `node-marker`.
`affectsEnforcement`	function	`(entry: ClassifiableEntry) => boolean`. Whether removing this row could change what the Boo can run. Broader than `isEffectiveExecGrant` by exactly the companion markers, and it is the question a revoke button needs answered.
`execAllowlistEntryKey`	function	`(entry: ClassifiableEntry) => string`. A content fingerprint over `pattern`, `argPattern` and `source`, NUL-joined. Not the entry `id`: ids are minted during normalisation for rows that lack one, so a revoke keyed on an id can miss, or hit a neighbour.
`ExecRevokeOutcome`	type	A tagged union of five outcomes: `revoked`, `already-absent`, `blocked-wildcard`, `no-such-agent`, `not-verified`. `not-verified` is the one that is not a no-op: the write landed and the rows are still there.
`removeExecAllowlistEntries`	function	`(doc, agentId, keys) => { next; removed }`. Pure. Rows are filtered, never mapped, so no surviving entry is rebuilt. An emptied allowlist is kept rather than deleted, because dropping the bucket would hand the Boo’s posture back to the document defaults.
`revokeExecAllowlistEntries`	function	`(client, { agentId, keys }) => Promise<ExecRevokeOutcome>`. `agentId` is OpenClaw’s id and `keys` are `execAllowlistEntryKey` fingerprints. It refuses the whole request when any key also lives in the `agents['*']` bucket, since that copy would keep granting, and it checks the removal against the Gateway’s post-write reply before reporting `revoked`.

The runtime constants above are the barrel’s only ones. The connect protocol range (minProtocol: 3, maxProtocol: 4), the retry constants, and the close codes stay private to client.ts / helpers.ts.

Used by

apps/web/src/stores/connection.ts, holds the live GatewayClient instance (ConnectionStatus superset adds an 'error' state).
apps/web/src/features/connection/{GatewayBootstrap,GatewayConnectScreen,useGatewayEvents}.tsx?, connect/reconnect lifecycle and event subscription; GatewayResponseError.code drives the NOT_PAIRED pairing branch.
apps/web/server/lib/agentSource/registry.ts, the server-side OpenClawAgentSource connection injects WebSocketLikeCtor + signConnect for Node device auth.
apps/web/server/lib/capabilitySource/openclaw.ts, uses encodeConfigPatchParams for the config.patch envelope.
apps/web/server/lib/agentSource/openclawExecAllowlistRead.ts, uses classifyExecAllowlistEntry + execAllowlistEntryKey to read a Boo’s standing grants out of OpenClaw’s own state database rather than through the Gateway.
apps/web/server/api/execAllowlist.ts and apps/web/server/lib/agentSource/execApprovalPolicy.ts, the routes behind the Permissions tab: revokeExecAllowlistEntries and upsertExecApprovalPolicy.
packages/events/src/{index,bridge,types}.ts, consumes the EventFrame / AgentStatus / ConnectionStatus types in the Bridge → Policy → Handler pipeline.
packages/adapters/openclaw/src/{adapter,mapFrame,types}.ts, maps EventFrame / AgentsListResult / SessionPatchResult into the normalized RuntimeEvent stream.

Source

Barrel: packages/gateway-client/src/index.ts. Modules: types.ts (frame + domain + connect types), errors.ts (GatewayResponseError), client.ts (the GatewayClient class), helpers.ts (frame/session/url/error/retry helpers, plus the two connect constants), execApprovals.ts (the Gateway-held exec policy, read-modify-write under compare-and-swap), execAllowlist.ts (what one stored grant means, plus the three pattern prefixes), execRevoke.ts (removing grants, and proving it). device-auth.ts is internal and not re-exported.

Reference

REST API

Packages

@clawboo/gateway-client

Public API

Classes

Functions

Types & interfaces

Errors

Constants

Exec approvals policy

Used by

Source

See also

​Public API

​Classes

​Functions

​Types & interfaces

​Errors

​Constants

​Exec approvals policy

​Used by

​Source

​See also

Public API

Classes

Functions

Types & interfaces

Errors

Constants

Exec approvals policy

Used by

Source

See also