Passer au contenu principal

​
nodes/troubleshooting.md

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

​
Échelle de commandes

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Ensuite, exécutez des 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 appairé pour le rôle node.
  • nodes describe inclut la capacité que vous appelez.
  • Les approbations exec affichent le mode/la liste d’autorisation attendus.

​
Exigences de premier plan

canvas.*, camera.* et screen.* sont uniquement disponibles au premier plan sur les nœuds iOS/Android. Vérification et correction rapides : 
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
Si vous voyez NODE_BACKGROUND_UNAVAILABLE, ramenez l’app du nœud au premier plan et réessayez.

​
Matrice des autorisations

CapacitéiOSAndroidApp de nœud macOSCode d’échec typique
camera.snap, camera.clipCaméra (+ micro pour l’audio des clips)Caméra (+ micro pour l’audio des clips)Caméra (+ micro pour l’audio des clips)*_PERMISSION_REQUIRED
screen.recordEnregistrement de l’écran (+ micro facultatif)Invite de capture d’écran (+ micro facultatif)Enregistrement de l’écran*_PERMISSION_REQUIRED
location.getLors de l’utilisation ou Toujours (selon le mode)Localisation au premier plan/en arrière-plan selon le modeAutorisation de localisationLOCATION_PERMISSION_REQUIRED
system.runn/a (chemin de l’hôte du nœud)n/a (chemin de l’hôte du nœud)Approbations exec requisesSYSTEM_RUN_DENIED

​
Appairage versus approbations

Il s’agit de verrous différents :
  1. Appairage de l’appareil : ce nœud peut-il se connecter à la Gateway (passerelle) ?
  2. Approbations exec : ce nœud peut-il exécuter une commande shell spécifique ?
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’appairage est manquant, approuvez d’abord l’appareil du nœud. Si l’appairage est correct mais que system.run échoue, corrigez les approbations exec/la liste d’autorisation.

​
Codes d’erreur courants des nœuds

  • NODE_BACKGROUND_UNAVAILABLE → l’app est en arrière-plan ; mettez-la au premier plan.
  • CAMERA_DISABLED → le basculement de la caméra est désactivé dans les paramètres du nœud.
  • *_PERMISSION_REQUIRED → autorisation du système d’exploitation manquante/refusée.
  • LOCATION_DISABLED → le mode de localisation est désactivé.
  • LOCATION_PERMISSION_REQUIRED → le mode de localisation demandé n’est pas accordé.
  • LOCATION_BACKGROUND_UNAVAILABLE → l’app est en arrière-plan mais seule l’autorisation « Lors de l’utilisation » existe.
  • SYSTEM_RUN_DENIED: approval required → la requête exec nécessite une approbation explicite.
  • SYSTEM_RUN_DENIED: allowlist miss → la commande est bloquée par le mode de liste d’autorisation.

​
Boucle de récupération rapide

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
Si le problème persiste :
  • Réapprouvez l’appairage de l’appareil.
  • Ré-ouvrir l’application du nœud (au premier plan).
  • Réaccordez les autorisations du système d’exploitation.
  • Recréez/ajustez la politique d’approbation exec.
Liens connexes :