Skip to main content

Gateway-owned pairing (Option B)

In Gateway-owned pairing, the Gateway is the source of truth for which nodes are allowed to join. UIs (macOS app, future clients) are just frontends that approve or reject pending requests. Important: WS nodes use device pairing (role node) during connect. node.pair.* is a separate pairing store and does not gate the WS handshake. Only clients that explicitly call node.pair.* use this flow.

Concepts

  • Pending request: a node asked to join; requires approval.
  • Paired node: approved node with an issued auth token.
  • Transport: the Gateway WS endpoint forwards requests but does not decide membership. (Legacy TCP bridge support is deprecated/removed.)

How pairing works

  1. A node connects to the Gateway WS and requests pairing.
  2. The Gateway stores a pending request and emits node.pair.requested.
  3. You approve or reject the request (CLI or UI).
  4. On approval, the Gateway issues a new token (tokens are rotated on re‑pair).
  5. The node reconnects using the token and is now “paired”.
Pending requests expire automatically after 5 minutes.

CLI workflow (headless friendly)

nodes status shows paired/connected nodes and their capabilities. A pure node (a device paired with only the node role) has no person, and wednesdayai devices link refuses it. Devices that also hold operator (apps such as WednesdayAI Glass) link like any other device, either with wednesdayai devices link <deviceId> --identity <name> after approval or by binding the identity into the setup code with --identity so the first connect links it. The person is stored on the device’s pairing record and is permanent until the device is deregistered: wednesdayai devices unlink is the same as wednesdayai devices remove (the record, its tokens and its person go together, then its connections close), and pairing again is the only way back, as a new device record (see Identities).

API surface (gateway protocol)

Events:
  • node.pair.requested — emitted when a new pending request is created.
  • node.pair.resolved — emitted when a request is approved/rejected/expired.
Methods:
  • node.pair.request — create or reuse a pending request.
  • node.pair.list — list pending + paired nodes.
  • node.pair.approve — approve a pending request (issues token).
  • node.pair.reject — reject a pending request.
  • node.pair.verify — verify { nodeId, token }.
Notes:
  • node.pair.request is idempotent per node: repeated calls return the same pending request.
  • Approval always generates a fresh token; no token is ever returned from node.pair.request.
  • Requests may include silent: true as a hint for auto-approval flows.
Device methods (same gateway, device pairing store):
  • device.bootstrap.issue — issue a bootstrap enrolment token for a setup code. Requires operator.admin. Params { profile: { roles, scopes }, identity?, codeChallenge? }, result { token, setupId, expiresAtMs }. openclaw qr calls this method when a gateway owns storage and issues the token locally from the session database otherwise.

Auto-approval (macOS app)

The macOS app can optionally attempt a silent approval when:
  • the request is marked silent, and
  • the app can verify an SSH connection to the gateway host using the same user.
If silent approval fails, it falls back to the normal “Approve/Reject” prompt.

Storage

Device and node pairing state lives in the session database (SQLite worker or Postgres, whichever the configuration selects), not in JSON files. The database owns these tables: pairing_devices, pairing_device_tokens, pairing_device_requests, pairing_bootstrap_tokens, pairing_device_archive, pairing_nodes, pairing_node_requests, pairing_node_archive and pairing_store_meta (import receipt). The first process that opens the session database (the gateway, or a CLI command when no gateway runs) imports the legacy JSON files once: devices/paired.json, devices/pending.json, devices/bootstrap.json, devices/archived.json, nodes/paired.json, nodes/pending.json and nodes/archived.json under the state directory (default ~/.openclaw; OPENCLAW_STATE_DIR moves it). After the import commits, each imported file moves into devices/.imported-<timestamp>/ or nodes/.imported-<timestamp>/. A JSON file added or changed afterwards is ignored with a warning: the database is the source of truth. A file that fails to parse aborts startup, so a partial import is never written. Paired records carry firstRegisteredAtMs and lastActiveAtMs. A record inactive longer than gateway.devices.staleAfterDays (default 90) shows as stale in openclaw nodes status. CLI commands route automatically: with a gateway running they call the gateway RPC; when no gateway owns storage, devices list/approve/reject/remove, devices rotate, devices revoke, nodes pending, nodes approve, nodes reject and nodes rename open the session database locally and apply the change directly. devices clear, devices prune, devices link, devices unlink and the device.supersede confirmation need a running gateway (live connection state and config writes). Security notes:
  • Tokens are secrets; treat the session database as sensitive.
  • Rotating a token requires re-approval (or deleting the node entry).

Rollback

To go back to a version that still reads JSON files:
  1. Stop the gateway.
  2. Copy the files from the newest devices/.imported-<ts>/ and nodes/.imported-<ts>/ back into devices/ and nodes/.
  3. Install the older version.
Pairings and tokens created after the upgrade are lost; records imported at upgrade time come back from the restored files. Re-upgrading later keeps the database (the import receipt is already stored) and ignores the restored files.

Transport behavior

  • The transport is stateless; it does not store membership.
  • If the Gateway is offline or pairing is disabled, nodes cannot pair.
  • If the Gateway is in remote mode, pairing still happens against the remote Gateway’s store.