node-connect

Connexion Nœud (Node Connect)

Objectif : corriger un client exact face à une passerelle exacte, puis prouver la connexion fraîche de ce client.

1. Verrouiller la cible

Enregistrez l'environnement/profil cible, le binaire OpenClaw, la racine de configuration/état, l'URL/port de la passerelle et le service avant de modifier quoi que ce soit.

• Utilisez le wrapper/profil de déploiement nommé pour chaque commande de configuration, journal, service, périphérique et nœud.
• Ne dérivez jamais vers un openclaw nu, un environnement de preuve ou un déploiement nommé similaire.
• Si l'exécutable global est obsolète, invoquez la cible via son propriétaire.
• Vérifiez que le statut, la configuration, les logs et l'identité du processus décrivent la même passerelle.

Identifiez la passerelle cible avant de modifier l'appairage ou l'authentification.

2. Classifier le client

Classez à partir de la requête et du journal de la passerelle avant de choisir les commandes :

• Navigateur Control UI : l'utilisateur dit navigateur, tableau de bord, Control UI ou webchat ; les logs montrent client=openclaw-control-ui ou mode=webchat.
• Mobile/nœud natif : l'application officielle montre Connect, Scan QR ou code de configuration ; les logs/métadonnées de requête montrent un client natif ou role=node.

Un téléphone peut être l'un ou l'autre client. N'utilisez pas openclaw qr ou openclaw nodes status pour un navigateur de téléphone ; ces commandes appartiennent à l'appairage mobile/nœud natif.

3. Observer la tentative échouée

Exécutez ces commandes via la cible verrouillée :

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

Faites réessayer le client une fois pendant que les logs sont actifs. Corrélez son ID client, mode, plateforme, adresse, résultat d'authentification, ID de périphérique, utilisateur et code de fermeture. Ignorez les autres périphériques appairés.

Interprétez la première transition échouée :

• Aucune tentative de passerelle correspondante : problème de route, DNS, TLS, origine ou proxy.
• token_missing, password_missing, non-concordance ou échec d'identité Tailscale : l'authentification a échoué avant l'appairage, donc une liste d'attente vide est attendue.
• pairing required : le routage et l'authentification ont réussi ; approuvez la demande exacte en attente.
• authenticated user connected / webchat connected : correspond au client exact ; si suivi de 1006, préservez l'authentification/l'appairage et inspectez le cycle de vie, le transport, le proxy ou la reconnexion.
• 1006 sans aucun journal de connexion au niveau application ne prouve pas l'authentification/l'appairage ; inspectez la transition de poignée de main antérieure.

4. Prouver la route

Choisissez une topologie : même machine, LAN, tailnet, ou proxy inverse public. Ne les mélangez pas.

• Le navigateur Control UI a besoin de HTTPS ou localhost pour l'identité du périphérique navigateur. Une URL LAN/Tailnet HTTP simple distante n'est pas un substitut valide.
• gateway.tailscale.mode=off signifie qu'OpenClaw ne gère pas Serve/Funnel. Cela ne prouve pas que Tailscale ou une route Serve gérée en externe est absente.
• Lorsque Tailscale est impliqué, inspectez l'état en temps réel plutôt que de l'inférer de la configuration OpenClaw :

tailscale status --json
tailscale serve status --json

Faites correspondre l'URL du client à la route d'écoute/proxy atteignant la passerelle verrouillée.

5A. Branche navigateur Control UI

Restaurez l'authentification du navigateur avant de chercher une demande d'appairage :

• Pour l'authentification par jeton/mot de passe, saisissez l'identifiant dans les paramètres Control UI. Ne mettez jamais de secrets permanents dans le chat, les logs ou les URL.
• Préférez openclaw dashboard sur l'hôte de la passerelle pour un transfert signé unique. Utilisez --no-open uniquement lorsque l'opérateur peut récupérer le presse-papiers de cet hôte, et gardez le navigateur/presse-papiers de l'hôte en dehors des outils de l'agent. Ne capturez jamais dashboard --json : cela peut exposer le transfert et les identifiants partagés. Ne relayez, ne réécrivez et n'envoyez jamais une URL de transfert en boucle locale vers un téléphone distant.
• Pour Tailscale Serve, vérifiez la route en direct et l'identité transférée. Activez gateway.auth.allowTailscale uniquement pour cette frontière de confiance prévue. Une authentification Control UI via Tailscale vérifiée avec l'identité du périphérique navigateur peut ignorer l'appairage.

Après la réussite de l'authentification :

• Réessayez ; n'inférez jamais l'appairage à partir de la tentative pré-authentification. L'authentification par jeton/mot de passe peut révéler pairing required ; une identité Tailscale vérifiée peut l'ignorer.
• Si les logs disent pairing required, ré- listez les périphériques et approuvez l'ID de demande exact.
• Une connexion réussie via Tailscale vérifié peut correctement ne créer aucune ligne en attente ou de périphérique appairé.
• Après un 1006 répété, préservez l'authentification/l'appairage et inspectez les preuves de reconnexion.

5B. Branche mobile/nœud natif

Inspectez la route native via la cible verrouillée sans exposer l'identifiant de configuration :

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

Pour une CLI contrôlant une passerelle distante, ajoutez --remote avant --json ; cela sélectionne gateway.remote.url et les identifiants distants. Si le filtre de masquage n'est pas disponible, n'exécutez pas le QR JSON brut dans une sortie visible par l'agent.

Vérifiez gatewayUrl et urlSource. Le code de configuration est équivalent à un mot de passe : demandez à l'opérateur de le copier depuis Control UI → Périphériques → Appairer un périphérique, ou exécutez openclaw qr --setup-code-only dans un terminal en dehors des outils de l'agent et collez-le directement dans l'application officielle. Ne le relayez jamais via la sortie de l'agent/chat/outil. Générez un nouveau code après une correction d'URL/auth ou une expiration.

Si l'application signale pairing required :

openclaw devices list
openclaw devices approve --latest   # aperçu uniquement ; se ferme sans approbation
openclaw devices approve <requestId>
openclaw nodes status

--latest ne fait qu'afficher un aperçu de la demande actuelle ; ne le traitez jamais comme une approbation. Ré- listez immédiatement avant la commande d'ID exact car les tentatives répétées peuvent remplacer la demande. N'approuvez jamais par position, âge ou similarité.

6. Corréler et terminer

Avant l'approbation, faites correspondre les faits disponibles : demande, clé publique/périphérique, client, mode/rôle, plateforme, adresse, utilisateur et heure de tentative.

Déclarez le succès uniquement après qu'une nouvelle tentative effectuée après le changement final prouve tous les contrôles applicables :

• le client exact atteint la passerelle verrouillée ;
• l'authentification prévue réussit ;
• le navigateur termine les requêtes initiales, ou le nœud natif apparaît dans openclaw nodes status ;
• l'approbation a utilisé l'ID de demande exact ; et
• aucune panne immédiate d'authentification, d'appairage ou de reconnexion ne suit.

Un QR/code de configuration, un navigateur lancé, une liste d'attente vide, une approbation, le nombre de périphériques appairés ou un ping Tailscale ne prouve qu'une seule transition.

Signalez le diagnostic, la branche routage/auth choisie, les preuves du client exact, et toute transition échouée restante.