Node troubleshooting

Utilisez cette page lorsqu’un nœud est visible dans l’état mais que les outils du nœud échouent.

Échelle de commande

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Exécutez ensuite les vérifications spécifiques au nœud :

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

Signaux sains :

Le nœud est connecté et apparié pour le rôle node.
nodes describe inclut la capacité que vous appelez.
Les approbations Exec affichent le mode/la liste d’autorisation attendus.

Conditions préalables au premier plan

canvas.*, camera.* et screen.* ne fonctionnent qu’au premier plan sur les nœuds iOS/Android.

Vérification et correction rapide :

openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow

Si vous voyez NODE_BACKGROUND_UNAVAILABLE, amenez l’application du nœud au premier plan et réessayez.

Matrice des autorisations

Capacité	iOS	Android	Application de nœud macOS	Code d’échec typique
`camera.snap`, `camera.clip`	Caméra (+ micro pour l’audio du clip)	Caméra (+ micro pour l’audio du clip)	Caméra (+ micro pour l’audio du clip)	`*_PERMISSION_REQUIRED`
`screen.record`	Enregistrement d’écran (+ micro en option)	Invite de capture d’écran (+ micro en option)	Enregistrement d’écran	`*_PERMISSION_REQUIRED`
`location.get`	Pendant l’utilisation ou Toujours (dépend du mode)	Localisation Premier plan/Arrière-plan selon le mode	Autorisation de localisation	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (chemin d’hôte du nœud)	n/a (chemin de l’hôte du nœud)	Approbations Exec requises	`SYSTEM_RUN_DENIED`

Appariement par rapport aux approbations

Il s’agit de différentes barrières :

Appareil d’appariement : ce nœud peut-il se connecter à la passerelle ?
Stratégie de commande de nœud de Gateway : l’ID de commande RPC est-il autorisé par gateway.nodes.allowCommands / denyCommands et les valeurs par défaut de la plateforme ?
Approbations Exec : ce nœud peut-il exécuter une commande shell spécifique localement ?

Vérifications rapides :

openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"

Si l’appariement est manquant, approuvez d’abord l’appareil du nœud. Si nodes describe manque une commande, vérifiez la stratégie de commande de nœud de passerelle et si le nœud a réellement déclaré cette commande lors de la connexion. Si l’appariement est correct mais que system.run échoue, corrigez les approbations/listes d’autorisation Exec sur ce nœud.

L’appairage de nœud est une passerelle d’identité/de confiance, et non une surface d’approbation par commande. Pour system.run, la stratégie par nœud réside dans le fichier d’approbations exec de ce nœud (openclaw approvals get --node ...), et non dans l’enregistrement d’appairage de la passerelle.

Pour les exécutions host=node soutenues par une approbation, la passerelle lie également l’exécution au systemRunPlan canonique préparé. Si un appelant ultérieur modifie la commande/le répertoire de travail ou les métadonnées de session avant que l’exécution approuvée soit transmise, la passerelle rejette l’exécution en tant qu’inadéquation d’approbation au lieu de faire confiance à la charge utile modifiée.

Codes d’erreur de nœud courants

NODE_BACKGROUND_UNAVAILABLE → l’application est en arrière-plan ; passez-la au premier plan.
CAMERA_DISABLED → le basculement de l’appareil photo est désactivé dans les paramètres du nœud.
*_PERMISSION_REQUIRED → autorisation OS manquante/refusée.
LOCATION_DISABLED → le mode de localisation est désactivé.
LOCATION_PERMISSION_REQUIRED → le mode de localisation demandé n’a pas été accordé.
LOCATION_BACKGROUND_UNAVAILABLE → l’application est en arrière-plan mais seule l’autorisation « Pendant l’utilisation » existe.
SYSTEM_RUN_DENIED: approval required → la requête d’exécution nécessite une approbation explicite.
SYSTEM_RUN_DENIED: allowlist miss → commande bloquée par le mode de liste verte. Sur les hôtes de nœud Windows, les formulaires d’enveloppe de shell tels que cmd.exe /c ... sont traités comme des absences de la liste verte en mode liste verte, sauf s’ils sont approuvés via le flux de demande (ask flow).

Boucle de récupération rapide

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow

Si toujours bloqué :

Réapprouver l’appairage de l’appareil.
Rouvrir l’application de nœud (premier plan).
Redonner les autorisations OS.
Recréer/ajuster la stratégie d’approbation d’exécution.