Emparejamiento gestionado por el Gateway (Opción B)

En el emparejamiento gestionado por el Gateway, el Gateway es la fuente de verdad sobre qué nodos pueden unirse. Las interfaces (app de macOS, futuros clientes) son simplemente 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 a node.pair.* usan este flujo.

Conceptos

• Solicitud pendiente: un nodo solicitó unirse; requiere aprobación.
• Nodo emparejado: nodo aprobado con un token de autenticación emitido.
• Transporte: el endpoint WS del Gateway reenvía las solicitudes pero no decide la membresía. (El soporte del puente TCP heredado está obsoleto/eliminado.)

Cómo funciona el emparejamiento

1. Un nodo se conecta al WS del Gateway y solicita el 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 queda “emparejado”.

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

Flujo de trabajo CLI (compatible con modo headless)

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 muestra los nodos emparejados/conectados y sus capacidades.

Superficie de API (protocolo del gateway)

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 reutilizar 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: las llamadas repetidas devuelven la misma solicitud pendiente.
• La aprobación siempre genera un token nuevo; nunca se devuelve un token desde node.pair.request.
• Las solicitudes pueden incluir silent: true como indicación para flujos de aprobación automática.

Aprobación automática (app de macOS)

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

• la solicitud está marcada como silent, y
• la app puede verificar una conexión SSH al host del gateway usando el mismo usuario.

Si la aprobación silenciosa falla, vuelve al prompt normal de “Aprobar/Rechazar”.

Almacenamiento (local, privado)

El estado de emparejamiento se almacena en 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 él.

Notas de seguridad:

• Los tokens son secretos; trata paired.json como información sensible.
• Rotar un token requiere re-aprobación (o eliminar la entrada del nodo).

Comportamiento del transporte

• El transporte es sin estado; 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 se realiza contra el almacén del Gateway remoto.