From e7b78016adaab06e994fbbf707ae0be9211ac4a5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Thu, 16 Apr 2026 00:42:20 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@489404d75ea1112ff50d9432486dd92c449c972b --- .openclaw-sync/source.json | 4 +-- docs/gateway/protocol.md | 55 +++++++++++++++++++++++++++++++++++--- 2 files changed, 53 insertions(+), 6 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 8e4f2d03c..a80a855ed 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "4ffa6218c41123c14a29d6ff0f97883f85623255", - "syncedAt": "2026-04-16T00:35:56.885Z" + "sha": "489404d75ea1112ff50d9432486dd92c449c972b", + "syncedAt": "2026-04-16T00:42:20.399Z" } diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 319b6448b..e27d7de48 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -73,10 +73,24 @@ Gateway → Client: "type": "res", "id": "…", "ok": true, - "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } } + "payload": { + "type": "hello-ok", + "protocol": 3, + "server": { "version": "…", "connId": "…" }, + "features": { "methods": ["…"], "events": ["…"] }, + "snapshot": { "…": "…" }, + "policy": { + "maxPayload": 26214400, + "maxBufferedBytes": 52428800, + "tickIntervalMs": 15000 + } + } } ``` +`server`, `features`, `snapshot`, and `policy` are all required by the schema +(`src/gateway/protocol/schema/frames.ts`). `auth` and `canvasHostUrl` are optional. + When a device token is issued, `hello-ok` also includes: ```json @@ -492,13 +506,36 @@ implemented in `src/gateway/server-methods/*.ts`. ## Versioning -- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`. +- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema/protocol-schemas.ts`. - Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches. - Schemas + models are generated from TypeBox definitions: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` +### Client constants + +The reference client in `src/gateway/client.ts` uses these defaults. Values are +stable across protocol v3 and are the expected baseline for third-party clients. + +| Constant | Default | Source | +| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | +| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | +| Request timeout (per RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| Preauth / connect-challenge timeout | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | +| Initial reconnect backoff | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| Max reconnect backoff | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| Fast-retry clamp after device-token close | `250` ms | `src/gateway/client.ts` | +| Force-stop grace before `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| `stopAndWait()` default timeout | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| Default tick interval (pre `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | +| Tick-timeout close | code `4000` when silence exceeds `tickIntervalMs * 2` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | + +The server advertises the effective `policy.tickIntervalMs`, `policy.maxPayload`, +and `policy.maxBufferedBytes` in `hello-ok`; clients should honor those values +rather than the pre-handshake defaults. + ## Auth - Shared-secret gateway auth uses `connect.params.auth.token` or @@ -518,8 +555,18 @@ implemented in `src/gateway/server-methods/*.ts`. approved scope set for that token. This preserves read/probe/status access that was already granted and avoids silently collapsing reconnects to a narrower implicit admin-only scope. -- Normal connect auth precedence is explicit shared token/password first, then - explicit `deviceToken`, then stored per-device token, then bootstrap token. +- Client-side connect auth assembly (`selectConnectAuth` in + `src/gateway/client.ts`): + - `auth.password` is orthogonal and is always forwarded when set. + - `auth.token` is populated in priority order: explicit shared token first, + then an explicit `deviceToken`, then a stored per-device token (keyed by + `deviceId` + `role`). + - `auth.bootstrapToken` is sent only when none of the above resolved an + `auth.token`. A shared token or any resolved device token suppresses it. + - Auto-promotion of a stored device token on the one-shot + `AUTH_TOKEN_MISMATCH` retry is gated to **trusted endpoints only** — + loopback, or `wss://` with a pinned `tlsFingerprint`. Public `wss://` + without pinning does not qualify. - Additional `hello-ok.auth.deviceTokens` entries are bootstrap handoff tokens. Persist them only when the connect used bootstrap auth on a trusted transport such as `wss://` or loopback/local pairing.