> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway-Owned Pairing

# 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)

```bash theme={"dark"}
wednesdayai nodes pending
wednesdayai nodes approve <requestId>
wednesdayai nodes reject <requestId>
wednesdayai nodes status
wednesdayai nodes rename --node <id|name|ip> --name "Living Room iPad"
```

`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](https://docs.wednesdayai.dev/next/admin/gateway/identity)).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.