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 (rolenode) 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
- A node connects to the Gateway WS and requests pairing.
- The Gateway stores a pending request and emits
node.pair.requested. - You approve or reject the request (CLI or UI).
- On approval, the Gateway issues a new token (tokens are rotated on re‑pair).
- The node reconnects using the token and is now “paired”.
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.
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 }.
node.pair.requestis 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: trueas a hint for auto-approval flows.
device.bootstrap.issue— issue a bootstrap enrolment token for a setup code. Requiresoperator.admin. Params{ profile: { roles, scopes }, identity?, codeChallenge? }, result{ token, setupId, expiresAtMs }.openclaw qrcalls 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.
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:- Stop the gateway.
- Copy the files from the newest
devices/.imported-<ts>/andnodes/.imported-<ts>/back intodevices/andnodes/. - Install the older version.
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.