node-connect

Node Connect

Objetivo: corregir un cliente exacto contra un Gateway exacto y luego probar la conexión fresca de ese cliente.

1. Bloquear el objetivo

Registre el entorno/perfil objetivo, el binario de OpenClaw, la raíz de configuración/estado, la URL/puerto del Gateway y el servicio antes de cambiar nada.

• Utilice el envoltorio/perfil de despliegue con nombre para cada comando de configuración, registro, servicio, dispositivo y nodo.
• Nunca derive a un openclaw desnudo, entorno de prueba o despliegue con nombre similar.
• Si el ejecutable global está obsoleto, invoque el objetivo a través de su propietario.
• Verifique que el estado, la configuración, los registros y la identidad del proceso describan el mismo Gateway.

Identifique el Gateway objetivo antes de cambiar el emparejamiento o la autenticación.

2. Clasificar el cliente

Clasifique a partir de la solicitud y el registro del Gateway antes de elegir comandos:

• Navegador de la UI de control: el usuario dice navegador, dashboard, UI de control o webchat; los registros muestran client=openclaw-control-ui o mode=webchat.
• Móvil/nodo nativo: la aplicación oficial muestra Conectar, Escanear QR o código de configuración; los registros/metadatos de la solicitud muestran un cliente nativo o role=node.

Un teléfono puede ser cualquiera de los dos clientes. No use openclaw qr ni openclaw nodes status para un navegador de teléfono; esos pertenecen al emparejamiento móvil/nodo nativo.

3. Observar el intento fallido

Ejecute lo siguiente a través del objetivo bloqueado:

openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode

Haga que el cliente reintente una vez mientras los registros están en vivo. Correlacione su ID de cliente, modo, plataforma, dirección, resultado de autenticación, ID de dispositivo, usuario y código de cierre. Ignore otros dispositivos emparejados.

Interprete la primera transición fallida:

• Sin intento de Gateway coincidente: problema de ruta, DNS, TLS, origen o proxy.
• token_missing, password_missing, discrepancia o fallo de identidad de Tailscale: la autenticación falló antes del emparejamiento, por lo que una lista de pendientes vacía es esperada.
• pairing required: la ruta y la autenticación tuvieron éxito; apruebe la solicitud pendiente exacta.
• authenticated user connected / webchat connected: coincida con el cliente exacto; si va seguido de 1006, preserve la autenticación/emparejamiento e inspeccione el ciclo de vida, transporte, proxy o reconexión.
• 1006 sin ninguno de los registros de conexión a nivel de aplicación no prueba la autenticación/emparejamiento; inspeccione la transición de enlace anterior.

4. Probar la ruta

Elija una topología: misma máquina, LAN, tailnet o proxy inverso público. No las mezcle.

• La UI de control de navegador necesita HTTPS o localhost para la identidad del dispositivo del navegador. Una URL remota de Tailnet/LAN con HTTP plano no es un sustituto válido.
• gateway.tailscale.mode=off significa que OpenClaw no está gestionando Serve/Funnel. No prueba que Tailscale o una ruta Serve gestionada externamente esté ausente.
• Cuando Tailscale está involucrado, inspeccione el estado en vivo en lugar de inferirlo de la configuración de OpenClaw:

tailscale status --json
tailscale serve status --json

Haga coincidir la URL del cliente con el oyente/ruta de proxy que llega al Gateway bloqueado.

5A. Carril del navegador UI de control

Restaure la autenticación del navegador antes de buscar una solicitud de emparejamiento:

• Para autenticación por token/contraseña, ingrese la credencial en la configuración de la UI de control. Nunca ponga secretos permanentes en chat, registros o URL.
• Prefiera openclaw dashboard en el host del Gateway para una transferencia firmada de un solo uso. Use --no-open solo cuando el operador pueda recuperar el portapapeles de ese host, y mantenga el navegador/portapapeles del host fuera de las herramientas del agente. Nunca capture dashboard --json: puede exponer la transferencia y las credenciales compartidas. Nunca retransmita, reescriba o envíe una URL de transferencia de bucle local a un teléfono remoto.
• Para Tailscale Serve, verifique la ruta en vivo y la identidad reenviada. Habilite gateway.auth.allowTailscale solo para ese límite de confianza pretendido. La autenticación verificada de la UI de control de Tailscale con identidad de dispositivo del navegador puede saltarse el emparejamiento.

Después de que la autenticación tenga éxito:

• Reintente; nunca infiera el emparejamiento del intento previo a la autenticación. La autenticación por token/contraseña puede revelar pairing required; la identidad verificada de Tailscale puede saltarlo.
• Si los registros dicen pairing required, vuelva a listar los dispositivos y apruebe el ID de solicitud exacto.
• Una conexión exitosa verificada por Tailscale puede crear correctamente cero filas de dispositivo pendiente o emparejado.
• Después de un 1006 repetido, preserve la autenticación/emparejamiento e inspeccione la evidencia de reconexión.

5B. Carril móvil/nodo nativo

Inspeccione la ruta nativa a través del objetivo bloqueado sin exponer la credencial de configuración:

openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'

Para una CLI que controla un Gateway remoto, agregue --remote antes de --json; selecciona gateway.remote.url y las credenciales remotas. Si el filtro de redacción no está disponible, no ejecute JSON QR sin procesar en la salida visible del agente.

Verifique gatewayUrl y urlSource. El código de configuración es equivalente a una contraseña: haga que el operador lo copie desde UI de control → Dispositivos → Emparejar dispositivo, o ejecute openclaw qr --setup-code-only en una terminal fuera de las herramientas del agente y péguelo directamente en la aplicación oficial. Nunca lo retransmita a través de la salida del agente/chat/herramienta. Genere un código nuevo después de una corrección de URL/autenticación o expiración.

Si la aplicación informa pairing required:

openclaw devices list
openclaw devices approve --latest   # solo vista previa; sale sin aprobación
openclaw devices approve <requestId>
openclaw nodes status

--latest solo muestra una vista previa de la solicitud actual; nunca lo trate como aprobación. Vuelva a listar inmediatamente antes del comando de ID exacto porque los reintentos pueden reemplazar la solicitud. Nunca apruebe por posición, antigüedad o similitud.

6. Correlacionar y finalizar

Antes de la aprobación, haga coincidir los hechos disponibles de solicitud, clave pública del dispositivo, cliente, modo/rol, plataforma, dirección, usuario y tiempo de reintento.

Declare el éxito solo después de que un nuevo intento realizado después del cambio final pruebe todas las comprobaciones aplicables:

• el cliente exacto llega al Gateway bloqueado;
• la autenticación prevista tiene éxito;
• el navegador completa las solicitudes iniciales, o el nodo nativo aparece en openclaw nodes status;
• la aprobación usó el ID de solicitud exacto; y
• no sigue inmediatamente ningún fallo de autenticación, emparejamiento o reconexión.

Un código QR/de configuración, un navegador lanzado, una lista de pendientes vacía, una aprobación, un recuento de dispositivos emparejados o un ping de Tailscale prueba solo una transición.

Informe el diagnóstico, la ruta/carril de autenticación elegido, la evidencia del cliente exacto y cualquier transición fallida restante.