Emparejamiento de Node

El emparejamiento de Node tiene dos capas, ambas almacenadas en el registro del dispositivo emparejado en la base de datos de estado SQLite del Gateway:

• El emparejamiento de dispositivos (rol node) controla el protocolo de enlace connect. Consulta Aprobación automática de dispositivos mediante CIDR de confianza más abajo y Emparejamiento de canales.
• La aprobación de capacidades de Node (node.pair.*) controla qué capacidades/comandos declarados puede exponer un Node conectado. El Gateway es la fuente de verdad; las interfaces de usuario (aplicación para macOS, interfaz de control) son frontends que aprueban o rechazan las solicitudes pendientes.

El anterior almacén independiente de emparejamiento de Node (nodes/paired.json con un token por Node, retirado de la ruta de conexión en enero de 2026) ha desaparecido: los gateways incorporan una vez durante el inicio cualquier fila restante a los registros de dispositivos y archivan los archivos heredados con el sufijo .migrated. Se ha eliminado la compatibilidad con el puente TCP heredado.

Cómo funciona la aprobación de capacidades

1. Un Node se conecta al WS del Gateway (el emparejamiento de dispositivos controla este paso).
2. El Gateway compara la superficie de capacidades/comandos declarada con la aprobada; las superficies nuevas o ampliadas almacenan una solicitud pendiente en el registro del dispositivo y emiten node.pair.requested.
3. Apruebas o rechazas la solicitud (mediante la CLI o la interfaz de usuario).
4. Hasta que se apruebe, los comandos de Node permanecen filtrados; la aprobación expone la superficie declarada, sujeta a la política de comandos habitual.

Las solicitudes pendientes caducan automáticamente 5 minutos después del último reintento del Node: un Node que se reconecta activamente mantiene activa su única solicitud pendiente en lugar de generar una solicitud nueva (y un aviso de aprobación) por cada intento.

Flujo de trabajo de la CLI (apto para entornos sin interfaz gráfica)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status muestra los Nodes emparejados/conectados y sus capacidades.

Superficie de la API (protocolo del Gateway)

Eventos:

• node.pair.requested: se emite cuando se crea una nueva solicitud pendiente.
• node.pair.resolved: se emite cuando una solicitud se aprueba, se rechaza o caduca.

Métodos:

• node.pair.list: enumera los Nodes pendientes y emparejados (operator.pairing).
• node.pair.approve: aprueba una solicitud pendiente.
• node.pair.reject: rechaza una solicitud pendiente.
• node.pair.remove: elimina un Node emparejado. Esto revoca el rol node del dispositivo en el almacén de dispositivos emparejados, elimina con él la superficie de Node aprobada e invalida/desconecta las sesiones con rol de Node de ese dispositivo. Un dispositivo con varios roles (por ejemplo, uno que también tenga operator) conserva su fila y solo pierde el rol node; la fila de un dispositivo que solo tenga el rol de Node se elimina. Autorización: operator.pairing puede eliminar filas de Nodes que no sean operadores; un llamador con token de dispositivo que revoque su propio rol de Node en un dispositivo con varios roles necesita además operator.admin.
• node.rename: cambia el nombre para mostrar de un Node emparejado que ve el operador.

Eliminados en 2026.7: node.pair.request y node.pair.verify. Ahora, el propio Gateway crea las solicitudes pendientes durante las conexiones de Nodes, y el token independiente por Node que usaban ya no existe; la autenticación del Node utiliza el token de emparejamiento del dispositivo.

Notas:

• Las reconexiones con una superficie sin cambios reutilizan la solicitud pendiente; las solicitudes repetidas actualizan los metadatos almacenados del Node y la instantánea más reciente de los comandos declarados incluidos en la lista de permitidos para que el operador pueda verlos.
• Los niveles de ámbito del operador y las comprobaciones realizadas durante la aprobación se resumen en Ámbitos del operador.
• node.pair.approve usa los comandos declarados de la solicitud pendiente para exigir ámbitos de aprobación adicionales:
  • solicitud sin comandos: operator.pairing
  • solicitud de comandos que no sean de ejecución: operator.pairing + operator.write
  • solicitud de system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Control de comandos de Node (2026.3.31+)

Cuando un Node se conecta por primera vez, el emparejamiento se solicita automáticamente. Hasta que se apruebe esa solicitud, todos los comandos pendientes de ese Node se filtran y no se ejecutan. Una vez aprobado el emparejamiento, los comandos declarados del Node quedan disponibles, sujetos a la política de comandos habitual.

Esto significa lo siguiente:

• Los Nodes que antes dependían únicamente del emparejamiento de dispositivos para exponer comandos ahora también deben completar el emparejamiento de Node.
• Los comandos puestos en cola antes de la aprobación del emparejamiento se descartan, no se posponen.

Límites de confianza de los eventos de Node (2026.3.31+)

Los resúmenes originados por Nodes y los eventos de sesión relacionados se restringen a la superficie de confianza prevista. Es posible que deban ajustarse los flujos activados por notificaciones o por Nodes que antes dependían de un acceso más amplio a las herramientas del host o de la sesión. Este refuerzo evita que los eventos de Node escalen a un acceso a herramientas en el ámbito del host más allá de lo permitido por el límite de confianza del Node.

Las actualizaciones persistentes de presencia de Nodes siguen el mismo límite de identidad: el evento node.presence.alive solo se acepta desde sesiones autenticadas de dispositivos Node, y solo actualiza los metadatos de emparejamiento cuando la identidad del dispositivo/Node ya está emparejada. Un valor client.id autodeclarado no basta para escribir el estado de última actividad.

Aprobación automática de dispositivos verificada mediante SSH (predeterminada)

El emparejamiento inicial de dispositivos con role: node desde una dirección privada/CGNAT se aprueba automáticamente cuando el Gateway puede demostrar mediante SSH la propiedad de la máquina: se conecta de vuelta al host que solicita el emparejamiento (BatchMode, StrictHostKeyChecking=yes), ejecuta allí openclaw node identity --json y solo aprueba cuando el identificador del dispositivo remoto y la clave pública coinciden exactamente con la solicitud pendiente. La coincidencia de la clave es lo que hace que esto sea seguro: la mera conectividad nunca da lugar a una aprobación, por lo que otros usuarios que compartan la NAT, otros usuarios del mismo host y la suplantación en la LAN recurren al aviso normal.

Está habilitada de forma predeterminada. Requisitos para que se active:

• El usuario del proceso del Gateway (o sshVerify.user) puede conectarse mediante SSH al host del Node de forma no interactiva (claves/agente; Tailscale SSH también funciona), y la clave del host ya es de confianza.
• openclaw se resuelve en el PATH remoto para sh -lc no interactivo.
• La IP de conexión es una dirección directa (sin proxy y no local loopback) privada, ULA, de vínculo local o CGNAT, o coincide con sshVerify.cidrs cuando está configurado.
• El mismo requisito mínimo que para la aprobación mediante CIDR de confianza: solo emparejamientos nuevos de Nodes sin ámbitos; las actualizaciones, los navegadores, la interfaz de control y WebChat siempre solicitan aprobación.

Mientras se ejecuta una comprobación, se indica al cliente Node que siga reintentando (wait_then_retry) en lugar de ponerse en pausa para una aprobación manual; si la comprobación falla, el siguiente intento recurre al flujo normal de solicitud de aprobación. Los destinos fallidos entran en un breve período de espera (5 minutos después de una discrepancia de claves).

Los dispositivos aprobados registran approvedVia: "ssh-verified" y su primera superficie de capacidades declarada se aprueba en el mismo paso: la coincidencia de claves ya demuestra que el Node se ejecuta con la cuenta del operador en una máquina de su propiedad, lo cual constituye la misma afirmación que una aprobación manual de capacidades. Las ampliaciones posteriores de la superficie siguen solicitando aprobación.

Para reforzarlo o deshabilitarlo:

{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

Aprobación automática (aplicación para macOS)

La aplicación para macOS puede intentar una aprobación silenciosa de las solicitudes de capacidades de Node cuando:

• la solicitud está marcada como silent (el Gateway marca como silenciosa la primera superficie de capacidades cuando el emparejamiento del dispositivo se aprobó de forma no interactiva), y
• la aplicación puede verificar una conexión SSH con el host del Gateway mediante el mismo usuario.

Si la aprobación silenciosa falla, recurre al aviso normal Approve/Reject.

Aprobación automática de dispositivos mediante CIDR de confianza

El emparejamiento de dispositivos WS para role: node sigue siendo manual de forma predeterminada. En las redes privadas de Nodes donde el Gateway ya confía en la ruta de red, los operadores pueden habilitarlo mediante CIDR explícitos o direcciones IP exactas:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Límite de seguridad:

• Se deshabilita cuando gateway.nodes.pairing.autoApproveCidrs no está configurado.
• No existe ningún modo general de aprobación automática para la LAN o las redes privadas; la aprobación automática verificada mediante SSH (descrita anteriormente) requiere una coincidencia criptográfica de la clave del dispositivo, nunca únicamente la localidad de la red.
• Solo son válidas las solicitudes nuevas de emparejamiento de dispositivos con role: node y sin ámbitos solicitados.
• Los clientes de operador, navegador, interfaz de control y WebChat siguen requiriendo aprobación manual.
• Las actualizaciones de rol, ámbito, metadatos y clave pública siguen requiriendo aprobación manual.
• Las rutas de encabezados de proxy de confianza mediante local loopback en el mismo host no son válidas, porque los llamadores locales pueden suplantarlas.

Limpieza de emparejamientos silenciosos reemplazados

Las aprobaciones no interactivas registran su procedencia en la fila del dispositivo emparejado: las aprobaciones mediante políticas locales del mismo host como silent, las aprobaciones de Nodes mediante CIDR de confianza como trusted-cidr y las aprobaciones de Nodes verificadas mediante SSH como ssh-verified. Los clientes cuyo directorio de estado es efímero (directorios personales temporales, contenedores y entornos aislados por ejecución) generan un nuevo par de claves del dispositivo en cada ejecución, y cada ejecución vuelve a emparejarse silenciosamente como un dispositivo completamente nuevo; sin limpieza, la lista de dispositivos emparejados crece en una fila obsoleta por ejecución.

Cuando el Gateway aprueba silenciosamente un emparejamiento de dispositivo local, retira los registros antiguos aprobados mediante silent que pertenecen al mismo clúster de clientes (con coincidencia de clientId, clientMode y nombre para mostrar) y que no están conectados en ese momento. Los clientes locales se ejecutan en el propio host del Gateway, por lo que la clave del clúster no puede coincidir con una máquina diferente. Las filas retiradas pierden sus tokens inmediatamente; se elimina cualquier entrada heredada coincidente de emparejamiento de Node y se difunde un evento de eliminación node.pair.resolved.

Límites:

• Solo son válidos, tanto como desencadenantes como objetivos, los registros cuya aprobación más reciente proceda del mismo host local (silent). Los emparejamientos mediante CIDR de confianza y los verificados mediante SSH abarcan varios hosts, donde los metadatos de visualización no identifican a una máquina, por lo que nunca se eliminan automáticamente; utiliza la limpieza de la interfaz de control o openclaw nodes remove para ellos.
• Los emparejamientos aprobados por el propietario y mediante QR/código de configuración (bootstrap) nunca se eliminan automáticamente. Los registros aprobados antes de que existiera la información de procedencia permanecen protegidos, incluso tras una aprobación silenciosa posterior del mismo identificador de dispositivo.
• Los dispositivos conectados actualmente se omiten, por lo que las sesiones locales simultáneas con directorios de estado independientes conservan sus tokens mientras están activas. También se omiten los registros aprobados durante el último minuto, de modo que los protocolos de enlace de emparejamiento simultáneos no puedan retirarse mutuamente antes de que se registren sus conexiones.
• Los clientes afectados son locales por definición, por lo que vuelven a emparejarse silenciosamente en su siguiente conexión.

Aprobación automática de actualizaciones de metadatos

Cuando un dispositivo ya emparejado se vuelve a conectar únicamente con cambios de metadatos no confidenciales (por ejemplo, el nombre para mostrar o indicaciones sobre la plataforma del cliente), OpenClaw lo trata como una metadata-upgrade. La aprobación automática silenciosa es limitada: se aplica únicamente a reconexiones locales de confianza que no provengan de navegadores y que ya hayan demostrado la posesión de credenciales locales o compartidas, incluidas las reconexiones de aplicaciones nativas en el mismo host después de cambios en los metadatos de la versión del sistema operativo. Los clientes de navegador/interfaz de control y los clientes remotos siguen utilizando el flujo explícito de nueva aprobación. Las ampliaciones de ámbito (de lectura a escritura/administración) y los cambios de clave pública no son válidos para la aprobación automática de metadata-upgrade; siguen siendo solicitudes explícitas de nueva aprobación.

Utilidades de emparejamiento mediante QR

/pair qr representa la carga útil de emparejamiento como contenido multimedia estructurado para que los clientes móviles y de navegador puedan escanearla directamente.

Al eliminar un dispositivo, también se borran las solicitudes de emparejamiento pendientes obsoletas correspondientes a ese identificador de dispositivo, por lo que nodes pending no muestra filas huérfanas después de una revocación.

Localidad y encabezados reenviados

El emparejamiento del Gateway considera que una conexión es local loopback solo cuando tanto el socket sin procesar como cualquier indicio del proxy ascendente coinciden. Si una solicitud llega mediante local loopback, pero contiene indicios en los encabezados Forwarded, cualquier X-Forwarded-* o X-Real-IP, dichos indicios de encabezados reenviados invalidan la afirmación de localidad local loopback, y la ruta de emparejamiento requiere aprobación explícita en lugar de tratar silenciosamente la solicitud como una conexión desde el mismo host. Consulta Autenticación mediante proxy de confianza para conocer la regla equivalente aplicable a la autenticación del operador.

Almacenamiento (local y privado)

El estado de emparejamiento se guarda en los registros de dispositivos emparejados de la base de datos de estado SQLite compartida, dentro del directorio de estado del Gateway (de forma predeterminada, ~/.openclaw):

• ~/.openclaw/state/openclaw.sqlite (dispositivos emparejados con autenticación de dispositivo, superficies de Node aprobadas, solicitudes de superficies pendientes, solicitudes de emparejamiento de dispositivos pendientes y tokens de arranque)

Si sobrescribes OPENCLAW_STATE_DIR, la base de datos se traslada con él. Los Gateways actualizados desde versiones que usaban almacenes JSON los importan al iniciarse y conservan los archivos devices/*.json.migrated y nodes/*.json.migrated.

Notas de seguridad:

• Los tokens de dispositivo son secretos; trata la base de datos de estado como información confidencial.
• Para rotar un token de dispositivo, se utiliza openclaw devices rotate / device.token.rotate.

Comportamiento del transporte

• El transporte no mantiene estado; no almacena la pertenencia.
• Si el Gateway está desconectado o el emparejamiento está deshabilitado, los nodos no pueden emparejarse.
• En modo remoto, el emparejamiento se realiza con el almacén del Gateway remoto.

Contenido relacionado

• Emparejamiento de canales
• CLI de nodos
• CLI de dispositivos