Emparejamiento Propiedad del Gateway

En el emparejamiento propiedad del Gateway, el Gateway es la fuente de verdad para qué nodos tienen permitido unirse. Las UIs (app macOS, futuros clientes) son solo frontends que aprueban o rechazan solicitudes pendientes.

''Importante:'' Los nodos WS usan ''emparejamiento de dispositivo'' (rol ''node'') durante ''connect''. ''node.pair.*'' es un almacén de emparejamiento separado y ''no'' controla el handshake WS. Solo los clientes que llaman explícitamente ''node.pair.*'' usan este flujo.

- Solicitud pendiente: un nodo pidió unirse; requiere aprobación.

- Nodo emparejado: nodo aprobado con un token de auth emitido.

- Transporte: el endpoint WS del Gateway reenvía solicitudes pero no decide membresía. (El soporte de puente TCP legacy está deprecado/removido.)

1. Un nodo se conecta al WS del Gateway y solicita emparejamiento.

2. El Gateway almacena una ''solicitud pendiente'' y emite ''node.pair.requested''.

3. Apruebas o rechazas la solicitud (CLI o UI).

4. Al aprobar, el Gateway emite un nuevo token (los tokens se rotan al re-emparejar).

5. El nodo se reconecta usando el token y ahora está "emparejado".

Las solicitudes pendientes expiran automáticamente después de 5 minutos.

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

''nodes status'' muestra nodos emparejados/conectados y sus capacidades.

Eventos:

- ''node.pair.requested'' — emitido cuando se crea una nueva solicitud pendiente.

- ''node.pair.resolved'' — emitido cuando una solicitud es aprobada/rechazada/expirada.

Métodos:

- ''node.pair.request'' — crear o reusar una solicitud pendiente.

- ''node.pair.list'' — listar nodos pendientes + emparejados.

- ''node.pair.approve'' — aprobar una solicitud pendiente (emite token).

- ''node.pair.reject'' — rechazar una solicitud pendiente.

- ''node.pair.verify'' — verificar ''{ nodeId, token }''.

Notas:

- ''node.pair.request'' es idempotente por nodo: llamadas repetidas devuelven la misma solicitud pendiente.

- La aprobación ''siempre'' genera un token fresco; ningún token es devuelto desde ''node.pair.request''.

- Las solicitudes pueden incluir ''silent: true'' como pista para flujos de auto-aprobación.

La app macOS puede opcionalmente intentar una aprobación silenciosa cuando:

- la solicitud está marcada ''silent'', y

- la app puede verificar una conexión SSH al host del gateway usando el mismo usuario.

Si la aprobación silenciosa falla, retrocede al prompt normal de "Aprobar/Rechazar".

El estado de emparejamiento se almacena bajo el directorio de estado del Gateway (por defecto ''~/.openclaw''):

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

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

Si sobrescribes ''OPENCLAW_STATE_DIR'', la carpeta ''nodes/'' se mueve con ella.

Notas de seguridad:

- Los tokens son secretos; trata ''paired.json'' como sensible.

- Rotar un token requiere re-aprobación (o eliminar la entrada del nodo).

- El transporte es stateless; no almacena membresía.

- Si el Gateway está offline o el emparejamiento está deshabilitado, los nodos no pueden emparejarse.

- Si el Gateway está en modo remoto, el emparejamiento aún ocurre contra el almacén del Gateway remoto.