Appairage du Node

Le jumelage des Node comporte deux couches, toutes deux stockées dans l’enregistrement de l’appareil jumelé au sein de la base de données d’état SQLite du Gateway :

• Jumelage de l’appareil (rôle node) contrôle la négociation connect. Voir Approbation automatique des appareils par CIDR de confiance ci-dessous et Jumelage des canaux.
• Approbation des capacités du Node (node.pair.*) contrôle les capacités/commandes déclarées qu’un Node connecté peut exposer. Le Gateway constitue la source de vérité ; les interfaces utilisateur (application macOS, Control UI) sont des frontends qui approuvent ou rejettent les demandes en attente.

L’ancien stockage autonome du jumelage des Node (nodes/paired.json avec un jeton propre à chaque Node, retiré du chemin de connexion en janvier 2026) n’existe plus : au démarrage, les Gateway intègrent une fois les lignes restantes aux enregistrements des appareils, puis archivent les anciens fichiers avec le suffixe .migrated. La prise en charge de l’ancien pont TCP a été supprimée.

Fonctionnement de l’approbation des capacités

1. Un Node se connecte au WS du Gateway (le jumelage de l’appareil contrôle cette étape).
2. Le Gateway compare l’ensemble déclaré des capacités/commandes à l’ensemble approuvé ; les ensembles nouveaux ou élargis enregistrent une demande en attente dans l’enregistrement de l’appareil et émettent node.pair.requested.
3. Vous approuvez ou rejetez la demande (CLI ou interface utilisateur).
4. Jusqu’à l’approbation, les commandes du Node restent filtrées ; l’approbation expose l’ensemble déclaré, sous réserve de la politique habituelle relative aux commandes.

Les demandes en attente expirent automatiquement 5 minutes après la dernière nouvelle tentative du Node — un Node qui se reconnecte activement conserve sa demande en attente unique au lieu de générer une nouvelle demande (et une nouvelle invite d’approbation) à chaque tentative.

Flux de travail CLI (adapté aux environnements sans interface graphique)

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 affiche les Node jumelés/connectés et leurs capacités.

Surface d’API (protocole du Gateway)

Événements :

• node.pair.requested - émis lors de la création d’une nouvelle demande en attente.
• node.pair.resolved - émis lorsqu’une demande est approuvée, rejetée ou expirée.

Méthodes :

• node.pair.list - répertorie les Node en attente et jumelés (operator.pairing).
• node.pair.approve - approuve une demande en attente.
• node.pair.reject - rejette une demande en attente.
• node.pair.remove - supprime un Node jumelé. Cela révoque le rôle node de l’appareil dans le stockage des appareils jumelés, supprime avec lui la surface approuvée du Node et invalide/déconnecte les sessions de cet appareil associées au rôle Node. Un appareil à rôles multiples (par exemple, qui possède également operator) conserve sa ligne et perd uniquement le rôle node ; la ligne d’un appareil ayant uniquement le rôle Node est supprimée. Autorisation : operator.pairing peut supprimer les lignes de Node sans rôle opérateur ; un appelant utilisant un jeton d’appareil qui révoque son propre rôle Node sur un appareil à rôles multiples a également besoin de operator.admin.
• node.rename - renomme le nom d’affichage d’un Node jumelé visible par l’opérateur.

Supprimées dans la version 2026.7 : node.pair.request et node.pair.verify. Les demandes en attente sont créées par le Gateway lui-même lors des connexions des Node, et le jeton autonome propre à chaque Node qu’elles utilisaient n’existe plus ; l’authentification du Node utilise le jeton de jumelage de l’appareil.

Remarques :

• Les reconnexions avec une surface inchangée réutilisent la demande en attente ; les demandes répétées actualisent les métadonnées stockées du Node ainsi que le dernier instantané autorisé des commandes déclarées afin que l’opérateur puisse les consulter.
• Les niveaux de portée de l’opérateur et les vérifications effectuées lors de l’approbation sont résumés dans Portées de l’opérateur.
• node.pair.approve utilise les commandes déclarées dans la demande en attente pour imposer des portées d’approbation supplémentaires :
  • demande sans commande : operator.pairing
  • demande de commande autre qu’une commande d’exécution : operator.pairing + operator.write
  • demande system.run / system.run.prepare / system.which : operator.pairing + operator.admin

Contrôle des commandes du Node (2026.3.31+)

Lorsqu’un Node se connecte pour la première fois, le jumelage est demandé automatiquement. Jusqu’à l’approbation de cette demande, toutes les commandes en attente provenant de ce Node sont filtrées et ne sont pas exécutées. Une fois le jumelage approuvé, les commandes déclarées du Node deviennent disponibles, sous réserve de la politique habituelle relative aux commandes.

Cela signifie que :

• Les Node qui s’appuyaient auparavant uniquement sur le jumelage de l’appareil pour exposer des commandes doivent désormais également effectuer le jumelage du Node.
• Les commandes mises en file d’attente avant l’approbation du jumelage sont abandonnées, et non différées.

Limites de confiance des événements du Node (2026.3.31+)

Les résumés provenant des Node et les événements de session associés sont limités à la surface de confiance prévue. Les flux déclenchés par des notifications ou par des Node qui s’appuyaient auparavant sur un accès plus large aux outils de l’hôte ou de la session peuvent nécessiter des ajustements. Ce renforcement empêche les événements des Node d’obtenir un accès aux outils au niveau de l’hôte au-delà de ce que permet la limite de confiance du Node.

Les mises à jour persistantes de présence des Node respectent la même limite d’identité : l’événement node.presence.alive est accepté uniquement depuis des sessions d’appareils Node authentifiées et ne met à jour les métadonnées de jumelage que si l’identité de l’appareil/du Node est déjà jumelée. Une valeur client.id autodéclarée ne suffit pas pour enregistrer l’état de dernière activité.

Approbation automatique des appareils vérifiée par SSH (par défaut)

Le premier jumelage d’un appareil avec role: node depuis une adresse privée/CGNAT est approuvé automatiquement lorsque le Gateway peut prouver la propriété de la machine par SSH : il se reconnecte à l’hôte demandant le jumelage (BatchMode, StrictHostKeyChecking=yes), y exécute openclaw node identity --json et n’approuve la demande que si l’identifiant de l’appareil distant et la clé publique correspondent exactement à la demande en attente. C’est la correspondance de la clé qui sécurise ce mécanisme : la seule accessibilité ne déclenche jamais l’approbation ; les autres utilisateurs du même NAT, les autres utilisateurs d’un hôte partagé et l’usurpation sur le réseau local suivent donc tous le flux d’invite habituel.

Activée par défaut. Conditions requises pour son déclenchement :

• L’utilisateur exécutant le processus du Gateway (ou sshVerify.user) peut se connecter en SSH à l’hôte du Node sans interaction (clés/agent ; Tailscale SSH fonctionne également), et la clé de l’hôte est déjà approuvée.
• openclaw est résolu dans le PATH distant pour l’exécution non interactive de sh -lc.
• L’adresse IP de connexion est une adresse privée, ULA, link-local ou CGNAT directe (sans proxy et hors local loopback), ou correspond à sshVerify.cidrs lorsque cette option est définie.
• Même niveau d’admissibilité minimal que pour l’approbation par CIDR de confiance : uniquement un nouveau jumelage de Node sans portée ; les mises à niveau, les navigateurs, Control UI et WebChat affichent toujours une invite.

Pendant l’exécution d’une vérification, le client Node reçoit l’instruction de continuer à réessayer (wait_then_retry) plutôt que de se mettre en pause dans l’attente d’une approbation manuelle ; si la vérification échoue, la tentative suivante revient au flux d’invite habituel. Les cibles ayant échoué font l’objet d’un court délai d’attente (5 minutes après une non-correspondance de clé).

Les appareils approuvés enregistrent approvedVia: "ssh-verified" et leur première surface de capacités déclarée est approuvée au cours de la même étape — la correspondance de la clé prouve déjà que le Node s’exécute sous le compte de l’opérateur sur une machine qui lui appartient, ce qui correspond à l’affirmation établie par une approbation manuelle des capacités. Les extensions ultérieures de la surface affichent toujours une invite.

Renforcement ou désactivation :

{  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"] },      },    },  },}

Approbation automatique (application macOS)

L’application macOS peut tenter une approbation silencieuse des demandes de capacités des Node lorsque :

• la demande est marquée silent (le Gateway marque la première surface de capacités comme silencieuse lorsque le jumelage de l’appareil a été approuvé sans interaction), et
• l’application peut vérifier une connexion SSH à l’hôte du Gateway en utilisant le même utilisateur.

Si l’approbation silencieuse échoue, l’application revient à l’invite habituelle Approve/Reject.

Approbation automatique des appareils par CIDR de confiance

Le jumelage d’appareils WS pour role: node reste manuel par défaut. Pour les réseaux privés de Node où le Gateway fait déjà confiance au chemin réseau, les opérateurs peuvent l’activer avec des CIDR explicites ou des adresses IP exactes :

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

Limite de sécurité :

• Désactivée lorsque gateway.nodes.pairing.autoApproveCidrs n’est pas défini.
• Il n’existe aucun mode d’approbation automatique globale pour le réseau local ou les réseaux privés ; l’approbation automatique vérifiée par SSH (ci-dessus) exige une correspondance cryptographique de la clé de l’appareil, jamais la seule proximité réseau.
• Seule une nouvelle demande de jumelage d’appareil avec role: node et sans portée demandée est admissible.
• Les clients opérateur, navigateur, Control UI et WebChat restent soumis à une approbation manuelle.
• Les mises à niveau du rôle, de la portée, des métadonnées et de la clé publique restent manuelles.
• Les chemins d’en-têtes de proxy de confiance via le local loopback du même hôte ne sont pas admissibles, car des appelants locaux peuvent les usurper.

Nettoyage lors du remplacement d’un jumelage silencieux

Les approbations non interactives enregistrent leur provenance dans la ligne de l’appareil jumelé : les approbations par politique locale sur le même hôte comme silent, les approbations de Node par CIDR de confiance comme trusted-cidr et les approbations de Node vérifiées par SSH comme ssh-verified. Les clients dont le répertoire d’état est éphémère (répertoires personnels temporaires, conteneurs, bacs à sable propres à chaque exécution) génèrent une nouvelle paire de clés d’appareil à chaque exécution, et chaque exécution effectue silencieusement un nouveau jumelage en tant que nouvel appareil — sans nettoyage, la liste des appareils jumelés s’allonge d’une ligne obsolète à chaque exécution.

Lorsque le Gateway approuve silencieusement le jumelage d’un appareil local, il retire les anciens enregistrements approuvés comme silent qui appartiennent au même groupe de clients (correspondance de clientId, clientMode et du nom d’affichage) et qui ne sont pas actuellement connectés. Les clients locaux s’exécutent sur l’hôte du Gateway lui-même ; la clé du groupe ne peut donc pas correspondre à une autre machine. Les lignes retirées perdent immédiatement leurs jetons ; toute entrée correspondante de l’ancien jumelage de Node est effacée et un événement de suppression node.pair.resolved est diffusé.

Limites :

• Seuls les enregistrements dont la dernière approbation a été effectuée localement sur le même hôte (silent) sont admissibles, à la fois comme déclencheurs et comme cibles. Les jumelages par CIDR de confiance et vérifiés par SSH concernent plusieurs hôtes, pour lesquels les métadonnées d’affichage ne constituent pas une identité de machine ; ils ne sont donc jamais supprimés automatiquement — utilisez le nettoyage de Control UI ou openclaw nodes remove pour ceux-ci.
• Les jumelages approuvés par le propriétaire et ceux effectués par code QR/code de configuration (amorçage) ne sont jamais supprimés automatiquement. Les enregistrements approuvés avant l’existence des données de provenance restent protégés, même après une nouvelle approbation silencieuse ultérieure du même identifiant d’appareil.
• Les appareils actuellement connectés sont ignorés ; les sessions locales simultanées utilisant des répertoires d’état distincts conservent ainsi leurs jetons tant qu’elles sont actives. Les enregistrements approuvés au cours de la dernière minute sont également ignorés afin que des négociations de jumelage simultanées ne puissent pas se retirer mutuellement avant l’enregistrement de leurs connexions.
• Les clients concernés sont locaux par construction ; ils se jumellent donc de nouveau silencieusement lors de leur prochaine connexion.

Approbation automatique des mises à niveau des métadonnées

Lorsqu’un appareil déjà jumelé se reconnecte avec uniquement des modifications de métadonnées non sensibles (par exemple le nom d’affichage ou des indications sur la plateforme du client), OpenClaw traite cela comme une metadata-upgrade. L’approbation automatique silencieuse est limitée : elle s’applique uniquement aux reconnexions locales de confiance hors navigateur qui ont déjà prouvé la possession d’identifiants locaux ou partagés, notamment les reconnexions d’applications natives sur le même hôte après une modification des métadonnées de version du système d’exploitation. Les clients navigateur/Control UI et les clients distants utilisent toujours le flux explicite de nouvelle approbation. Les mises à niveau de portée (de lecture à écriture/administration) et les modifications de clé publique ne sont pas admissibles à l’approbation automatique des metadata-upgrade ; elles restent des demandes explicites de nouvelle approbation.

Assistants de jumelage par code QR

/pair qr affiche la charge utile d’appairage sous forme de média structuré afin que les clients mobiles et les navigateurs puissent la scanner directement.

La suppression d’un appareil élimine également toutes les demandes d’appairage en attente obsolètes associées à l’identifiant de cet appareil, afin que nodes pending n’affiche aucune ligne orpheline après une révocation.

Localité et en-têtes transférés

L’appairage du Gateway ne considère une connexion comme local loopback que si le socket brut et toutes les indications fournies par un proxy en amont concordent. Si une requête arrive sur local loopback, mais contient des indications dans les en-têtes Forwarded, X-Forwarded-* ou X-Real-IP, celles-ci invalident la déclaration de localité local loopback et le processus d’appairage exige une approbation explicite au lieu de traiter silencieusement la requête comme une connexion provenant du même hôte. Consultez Authentification par proxy de confiance pour connaître la règle équivalente relative à l’authentification de l’opérateur.

Stockage (local et privé)

L’état de l’appairage réside dans les enregistrements des appareils appairés, au sein de la base de données d’état SQLite partagée située dans le répertoire d’état du Gateway (par défaut, ~/.openclaw) :

• ~/.openclaw/state/openclaw.sqlite (appareils appairés avec authentification de l’appareil, surfaces de nœud approuvées, demandes de surface en attente, demandes d’appairage d’appareil en attente et jetons d’amorçage)

Si vous redéfinissez OPENCLAW_STATE_DIR, la base de données est déplacée avec ce répertoire. Les Gateways mis à niveau depuis des versions utilisant des stockages JSON les importent au démarrage et conservent les archives devices/*.json.migrated et nodes/*.json.migrated.

Remarques de sécurité :

• Les jetons d’appareil sont des secrets ; considérez la base de données d’état comme sensible.
• La rotation d’un jeton d’appareil utilise openclaw devices rotate / device.token.rotate.

Comportement du transport

• Le transport est sans état ; il ne stocke pas les appartenances.
• Si le Gateway est hors ligne ou si l’appairage est désactivé, les nœuds ne peuvent pas s’appairer.
• En mode distant, l’appairage s’effectue dans le stockage du Gateway distant.

Voir aussi

• Appairage des canaux
• CLI des nœuds
• CLI des appareils