@clawboo/gateway-client is the WebSocket client the SPA and the server use to talk to a Gateway.
@clawboo/gateway-proxy is its server half: the same-origin WebSocket proxy the browser connects through, the
device identity that signs the Gateway handshake, the optional access gate and the always-on Origin and Host
guard.
Use this page when you change how Clawboo talks to OpenClaw or touch dashboard access control. The operator’s
view of the same controls is on Security model.
The Ed25519 device identity only proves this Clawboo install to the OpenClaw Gateway. Who may open the dashboard
is decided by the access gate (off unless
STUDIO_ACCESS_TOKEN is set) and the Origin and Host guard.The Gateway client
GatewayClient connects to a Gateway, correlates requests and responses, delivers event frames to onEvent
subscribers, and reconnects with backoff when a connection that was open drops. call(method, params) sends any
RPC, and typed groups cover the common ones: agents (list, create, files), sessions, config and chat.
connect(url, options) negotiates OpenClaw’s protocol range and takes these options:
tokenorpasswordfor the Gateway’s own auth.caps, the capabilities the connection declares. The default,GATEWAY_BROWSER_CAPS, declares exec approvals. The server’s own connection declarestool-eventsandexec-approvals.signConnect, for a caller that signs the connect frame with its own identity, andwebSocketImplandorigin, for a caller outside the browser. The server passes thewspackage’s constructor and the Gateway host as the origin.disableDeviceAuth. The client can sign the connect frame itself in a secure browser context, with an Ed25519 key kept inlocalStorage, but the dashboard turns that off because the proxy signs for it.
GatewayResponseError carries the Gateway’s error code (the pairing flow keys off NOT_PAIRED), and
isAuthConnectError and authRetryAfterMs tell a caller whether and when to retry an auth failure.
The package is browser-safe: it uses the global WebSocket and does not depend on ws. The SPA uses it for the
live connection, events and the pairing flow. On the server it backs the shared Gateway connection in
apps/web/server/lib/agentSource/registry.ts, the OpenClaw capability source, and the Permissions tab routes.
@clawboo/events and @clawboo/adapter-openclaw import its types.
Exec approvals
The Gateway keeps every agent’s exec posture and its standing command grants in one fleet-wide document, reachable only throughexec.approvals.get and exec.approvals.set. The package’s exec helpers follow four rules, and any
new code that touches the document must too:
- Treat
exec.approvals.getas a write. The Gateway re-saves the document when it answers, and an unparseable stored document would be replaced with a fail-closed default for every agent. Code that only reads grants reads OpenClaw’s stored row directly and read-only, asopenclawExecAllowlistRead.tsdoes. - Write under compare-and-swap.
mutateExecApprovalsDoc(client, mutate)reads the document, appliesmutate, and writes it back against the base hash, re-runningmutateon a fresh read after a conflict.upsertExecApprovalPolicyuses it to set one agent’s posture while keeping its grants. - Filter rows, never rebuild them. A grant that loses its
argPatternin a round trip stops matching the command it was made for.revokeExecAllowlistEntriesremoves rows by content fingerprint (execAllowlistEntryKey), refuses a row that also lives in the wildcard bucket, and checks the Gateway’s post-write reply before it reportsrevoked. - Patch sessions with
execHostonly. OpenClaw refuses the retiredexecSecurityandexecAsksession fields, soresolveExecPatchParams()returns onlyexecHost.
classifyExecAllowlistEntry, isEffectiveExecGrant and affectsEnforcement say what one stored row means. The user
side is Review and revoke command permissions.
The proxy and device identity
createGatewayProxy({ loadUpstreamSettings }) serves the WebSocket at /api/gateway/ws. The browser opens a
same-origin socket, and the proxy opens the upstream Gateway connection for it, fills in the Gateway token and a
device signature on the connect frame, and then forwards frames both ways with a bounded buffer and a keepalive.
The browser never sees the Gateway token.
loadOrCreateProxyDeviceIdentity() keeps one Ed25519 keypair in proxy-device-identity.json in Clawboo’s state
folder, with the folder limited to your user and the file re-tightened on every load. signConnectParams signs a
connect frame with it. The server’s own Gateway connection reuses the same identity through the client’s
signConnect hook, so the dashboard and the server count as one paired device.
The access gate
createAccessGate({ token, basePath, authorizeRuntime }) is off unless STUDIO_ACCESS_TOKEN is set. When it is on:
- Opening the dashboard with
?access_token=<token>sets an HttpOnlyclawboo_accesscookie, scoped to the base path and markedSecureover TLS, then redirects to remove the token from the address bar. - Every
/api/*request and every Gateway WebSocket upgrade needs that cookie. The comparison is constant-time, and the path check ignores case. - The one exception is an
/api/mcp/*call from a runtime the server started.authorizeRuntimeadmits it only when it carries a valid attach token, came straight to the loopback port, and was not forwarded.isForwardedRequestlooks forForwarded,X-Forwarded-*andX-Real-IP, and those headers can only take access away.
A-Z a-z 0-9 . _ ~ - would break the cookie, so createAccessGate throws on one.
The server checks first with findUnsupportedTokenChar (the allowed set is ACCESS_TOKEN_CHARSET): it logs
SECURITY: refusing to start and exits 1 on every bind, and CLAWBOO_ALLOW_INSECURE=1 does not skip it. A
non-loopback bind with no token also refuses to start, unless CLAWBOO_ALLOW_INSECURE=1. Generate the
token with openssl rand -hex 24. When a forwarded request reaches a server with no token, the server logs a
one-time warning (proxyExposureWarning.ts).
The Origin and Host guard
createOriginGuard({ port, bindHost, allowedOrigins, allowedHosts }) runs on every /api/* request and WebSocket
upgrade, whether or not the access gate is on. It closes cross-site WebSocket hijacking, DNS rebinding and
cross-site requests on a default install with no configuration. A request passes when:
- its
Hostis a loopback name, the bind host, or listed inCLAWBOO_ALLOWED_HOSTS; - its
Origin, when present, is a loopback origin on the API port, the bind host, the Vite dev server in development, or listed inCLAWBOO_ALLOWED_ORIGINS; - its
Sec-Fetch-Site, when present, issame-origin,same-siteornone.
403 with Cross-origin request blocked. The two environment lists only widen the allowed
set, so a reverse proxy or a LAN address must be listed in them. The guard is not authentication: a non-browser
client can send any headers it likes, which is why a non-loopback bind needs the access gate.
Test it
Runpnpm --filter @clawboo/gateway-client test and pnpm --filter @clawboo/gateway-proxy test. The dashboard’s
end-to-end suite runs against a mock Gateway; see Testing strategy.
Related
- Security model: the access model, tokens and safe exposure.
- Reach Clawboo from another machine: tunnels, proxies and the environment lists in practice.
- Gateway connection internals: how Gateway frames flow into the dashboard.
- OpenClaw: pairing, the Gateway connection and OpenClaw setup.
- @clawboo/mcp: the attach token the access gate checks.