Gateway 管理的配对

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.

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

1. A node connects to the Gateway WS and requests pairing.

2. The Gateway stores a ''pending request'' and emits ''node.pair.requested''.

3. CLI 或 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".

待处理请求在 5 分钟 后自动过期。

openclaw nodes pending
openclaw nodes approve '<requestId>'
openclaw nodes reject '<requestId>'
openclaw nodes status
openclaw nodes rename --node '<id|name|ip>' --name "Living Room iPad"

''nodes status'' 是、配对済见/连接済见的节点和那个能力宣言显示执行。

活动：

- ''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'' — 待定中的请求创建或再利用执行。

- ''node.pair.list'' — 待定中 + 配对済见节点一覧显示执行。

- ''node.pair.approve'' — 待定中的请求批准执行（令牌発行）。

- ''node.pair.reject'' — 待定中的请求拒绝执行。

- ''node.pair.verify'' — ''{ nodeId, token }'' 验证执行。

注意：

- ''node.pair.request'' is idempotent per node: repeated calls return the same pending request.

- 批准時是''常在''新令牌但生成被。''node.pair.request'' 是令牌返不会执行。

- Requests may include ''silent: true'' as a hint for auto-approval flows.

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.

如果静默批准失败，它会回退到正常的"批准/拒绝"提示。

配对状态是 Gateway 状态目录（默认 ''~/.openclaw''）在被保存：

- ''~/.openclaw/nodes/paired.json''

- ''~/.openclaw/nodes/pending.json''

If you override ''OPENCLAW_STATE_DIR'', the ''nodes/'' folder moves with it.

Security notes:

- Tokens are secrets; treat ''paired.json'' as sensitive.

- Rotating a token requires re-approval (or deleting the node entry).

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