Dépannage des nœuds OpenClaw

Votre nœud s’affiche appairé et connecté, les statistiques d’hôte remontent, et la passerelle ne journalise rien d’alarmant. Puis camera.snap renvoie un code de permission, computer.act refuse avec COMPUTER_DISABLED, ou exec répond SYSTEM_RUN_DENIED. La connexion n’est que la première de quatre vérifications distinctes, et les trois autres restent invisibles dans une ligne de statut. Voici le runbook amont de dépannage des nœuds : les quatre barrières, le piège du service Linux qui coupe un nœud dès que vous quittez SSH, et ce que signifie vraiment chaque code d’erreur.

Les quatre barrières qu’une commande de nœud doit franchir

• L’appairage de l’appareil décide si ce nœud peut se connecter à la passerelle. Le nœud présente une identité d’appareil signée à la connexion, la passerelle crée une demande d’appairage pour le rôle node, et vous l’approuvez avec openclaw devices approve sur l’identifiant de demande d’appareil. Cela admet l’identité, rien d’autre.
• L’approbation de la surface de commandes décide quelles commandes cette identité admise peut exposer. La surface déclarée arrive comme une demande en attente séparée, listée par openclaw nodes pending et approuvée par openclaw nodes approve sur un identifiant de demande de nœud qui n’est pas celui de l’appareil. Une surface initiale non approuvée n’expose aucune commande effective : un nœud correctement appairé et connecté peut donc rester là sans répondre à rien.
• La politique de commandes de nœud de la passerelle décide si l’identifiant de commande RPC est autorisé, à partir des valeurs par défaut de la plateforme, de gateway.nodes.commands.allow et de gateway.nodes.commands.deny. Les commandes sensibles pour la vie privée comme camera.snap, camera.clip, screen.record et desktop.stream exigent une entrée allow persistante, même quand le nœud les déclare, et une entrée deny l’emporte toujours sur une valeur par défaut de plateforme comme sur une entrée allow.
• Les approbations d’exécution décident si le nœud peut lancer localement une commande shell précise. Pour system.run, la liste d’autorisation et la politique de demande vivent dans les approbations d’exécution de ce nœud, lues avec openclaw approvals get sur le nœud, pas dans la fiche d’appairage. Les permissions de plateforme et les exigences de premier plan s’appliquent encore, une fois les quatre barrières franchies.

L’appairage de l’appareil admet l’identité ; l’approbation de la surface limite les commandes sur sa fiche d’appareil appairé.

Pourquoi un nœud appairé peut n’exposer aucune commande

Les deux identifiants de demande sont le piège. Approuver l’appareil n’approuve pas la surface : une fois l’appairage approuvé, vous redémarrez ou relancez le nœud, et cette reconnexion crée la demande de surface distincte que vous approuvez ensuite par identifiant de demande de nœud. L’enrôlement vérifié par SSH et l’enrôlement d’amorçage émis par un administrateur peuvent approuver automatiquement la première surface, mais l’approbation d’appareil par réseau de confiance, non : une plage CIDR auto-approuvée vous donne donc un nœud connecté avec une liste de commandes vide. Les extensions suivent la même règle : une extension en attente ne conserve que les commandes déjà approuvées, encore déclarées et toujours conformes à la politique de la passerelle. Si openclaw nodes describe ne montre pas la commande que vous appelez, vérifiez d’abord la politique de commandes de la passerelle, puis si le nœud a réellement déclaré cette commande à la connexion.

Le piège du lingering sous Linux

• Sous Linux, openclaw node install crée un service systemd au niveau utilisateur, et l’instance systemd utilisateur est détruite à la fin de votre dernière session de login. Le service du nœud s’arrête donc dès que vous quittez SSH, alors qu’il indiquait enabled et running pendant tout le temps où vous étiez connecté.
• Vérifiez avec loginctl show-user $USER -p Linger. Si la réponse est Linger=no, lancez sudo loginctl enable-linger $USER, redémarrez avec openclaw node restart, puis déconnectez-vous et confirmez depuis une autre machine avec openclaw nodes status. L’installateur affiche déjà un avertissement portant cette commande de récupération quand il détecte que le lingering est désactivé.
• Ne mélangez pas un service au niveau utilisateur et un service au niveau système pour le même nœud. Le garde-fou de portée dupliquée qui empêche deux gestionnaires de posséder le même nom d’unité est appliqué aux unités de passerelle, parce que deux superviseurs sur le même port se SIGTERM mutuellement dans une boucle de redémarrage, mais l’installateur ne l’applique pas aux services de nœud : une unité résiduelle dans l’autre portée laisse alors le nœud dans un état ambigu. Supprimez-en une complètement avant de basculer.

La première barrière et la quatrième ont leur propre page : L’appairage dans OpenClaw couvre le cycle de demande, d’approbation et d’expiration derrière l’admission de l’appareil, et Les approbations d’exécution d’OpenClaw couvre le vocabulaire de liste d’autorisation, de demande et de mode qui décide si une commande shell a le droit de tourner sur l’hôte du nœud.

Chaque code d’erreur de nœud et son correctif

NODE_BACKGROUND_UNAVAILABLE signifie que l’application est en arrière-plan : les commandes camera et screen ne fonctionnent qu’au premier plan sur les nœuds iOS et Android, ramenez donc l’application devant puis réessayez. CAMERA_DISABLED et LOCATION_DISABLED sont des interrupteurs côté nœud plutôt que des autorisations du système : la capacité est désactivée dans les réglages du nœud. Tout code terminant par PERMISSION_REQUIRED correspond à une permission du système d’exploitation manquante ou refusée, et LOCATION_BACKGROUND_UNAVAILABLE est le cas plus étroit où l’application est en arrière-plan alors que seul While Using a été accordé. COMPUTER_DISABLED signifie que Allow Computer Control est désactivé dans l’application macOS : activez-le, puis approuvez la mise à jour d’appairage qui suit. ACCESSIBILITY_REQUIRED signifie que l’Accessibilité n’a pas été accordée au bundle OpenClaw courant dans les Réglages Système de macOS, et le même exécutant a aussi besoin de l’Enregistrement de l’écran. SYSTEM_RUN_DENIED arrive en deux variantes : approval required veut dire que la demande d’exécution attend une approbation explicite, alors que allowlist miss veut dire que le mode liste d’autorisation a bloqué la commande, et sur les hôtes de nœud Windows les formes enveloppées par le shell comme cmd.exe /c comptent comme des échecs de liste d’autorisation tant qu’elles ne sont pas approuvées par le flux de demande. Pour un poste de travail qui n’agit pas du tout, L’usage de l’ordinateur dans OpenClaw couvre le côté fournisseur, permissions et politique d’outils, et Nœuds OpenClaw et Remote Hands présente ce qu’est un appareil appairé et ce qu’on peut lui demander.

Sur Diali

Diali héberge OpenClaw, un assistant par client : le côté passerelle de ces quatre barrières tourne sur notre infrastructure, tandis que le nœud reste sur du matériel qui vous appartient. La configuration d’exécution est générée depuis le tableau de bord et remplacée à chaque version, et l’état de l’agent, y compris les fiches d’appareil appairé qui portent une surface de nœud approuvée, vit sur un volume persistant, avec des instantanés quotidiens et une restauration en un clic grâce à l’option Sauvegardes (incluse avec Max). OpenClaw hébergé sur Diali détaille ce que le runtime hébergé inclut et Tarifs Diali ce qu’il coûte.

• Connecté, c’est la barrière une sur quatre : appairage, surface, politique, exécution.
• L’identifiant de demande d’appareil et celui de nœud sont deux identifiants distincts.
• Linger=no veut dire que votre nœud Linux meurt à la déconnexion SSH.