Vai al contenuto principale

​
Risoluzione dei problemi dei nodi

Usa questa pagina quando un nodo è visibile nello stato ma gli strumenti del nodo falliscono.

​
Sequenza di comandi

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Poi esegui i controlli specifici del nodo: 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
Segnali di corretto funzionamento:
  • Il nodo è connesso e associato per il ruolo node.
  • nodes describe include la capability che stai chiamando.
  • Le approvazioni exec mostrano la modalità/allowlist prevista.

​
Requisiti di primo piano

canvas.*, camera.* e screen.* funzionano solo in primo piano sui nodi iOS/Android. Controllo e correzione rapidi: 
openclaw nodes describe --node <idOrNameOrIp>
openclaw nodes canvas snapshot --node <idOrNameOrIp>
openclaw logs --follow
Se vedi NODE_BACKGROUND_UNAVAILABLE, porta l’app del nodo in primo piano e riprova.

​
Matrice dei permessi

CapabilityiOSAndroidapp nodo macOSCodice di errore tipico
camera.snap, camera.clipFotocamera (+ microfono per audio clip)Fotocamera (+ microfono per audio clip)Fotocamera (+ microfono per audio clip)*_PERMISSION_REQUIRED
screen.recordRegistrazione schermo (+ microfono facoltativo)Prompt di cattura schermo (+ microfono facoltativo)Registrazione schermo*_PERMISSION_REQUIRED
location.getDurante l’uso o Sempre (dipende dalla modalità)Posizione in primo piano/sfondo in base alla modalitàPermesso posizioneLOCATION_PERMISSION_REQUIRED
system.runn/d (percorso host del nodo)n/d (percorso host del nodo)Approvazioni exec richiesteSYSTEM_RUN_DENIED

​
Pairing versus approvazioni

Questi sono gate diversi:
  1. Pairing del dispositivo: questo nodo può connettersi al gateway?
  2. Policy dei comandi nodo del gateway: l’ID comando RPC è consentito da gateway.nodes.allowCommands / denyCommands e dai valori predefiniti della piattaforma?
  3. Approvazioni exec: questo nodo può eseguire localmente uno specifico comando shell?
Controlli rapidi: 
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
Se manca il pairing, approva prima il dispositivo del nodo. Se in nodes describe manca un comando, controlla la policy dei comandi nodo del gateway e se il nodo ha effettivamente dichiarato quel comando alla connessione. Se il pairing è corretto ma system.run fallisce, correggi le approvazioni exec/l’allowlist su quel nodo. Il pairing del nodo è un gate di identità/fiducia, non una superficie di approvazione per singolo comando. Per system.run, la policy per nodo si trova nel file delle approvazioni exec di quel nodo (openclaw approvals get --node ...), non nel record di pairing del gateway. Per le esecuzioni host=node supportate da approvazione, il gateway vincola inoltre l’esecuzione al systemRunPlan canonico preparato. Se un chiamante successivo modifica comando/cwd o metadati della sessione prima che l’esecuzione approvata venga inoltrata, il gateway rifiuta l’esecuzione come mancata corrispondenza dell’approvazione invece di fidarsi del payload modificato.

​
Codici di errore comuni dei nodi

  • NODE_BACKGROUND_UNAVAILABLE → l’app è in background; portala in primo piano.
  • CAMERA_DISABLED → interruttore fotocamera disabilitato nelle impostazioni del nodo.
  • *_PERMISSION_REQUIRED → permesso del sistema operativo mancante/negato.
  • LOCATION_DISABLED → la modalità posizione è disattivata.
  • LOCATION_PERMISSION_REQUIRED → la modalità posizione richiesta non è stata concessa.
  • LOCATION_BACKGROUND_UNAVAILABLE → l’app è in background ma esiste solo il permesso Durante l’uso.
  • SYSTEM_RUN_DENIED: approval required → la richiesta exec richiede approvazione esplicita.
  • SYSTEM_RUN_DENIED: allowlist miss → comando bloccato dalla modalità allowlist. Sugli host nodo Windows, le forme wrapper della shell come cmd.exe /c ... sono trattate come mancate corrispondenze dell’allowlist in modalità allowlist, a meno che non vengano approvate tramite il flusso ask.

​
Ciclo di recupero rapido

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
Se sei ancora bloccato:
  • Riapprova il pairing del dispositivo.
  • Riapri l’app del nodo (in primo piano).
  • Concedi di nuovo i permessi del sistema operativo.
  • Ricrea/regola la policy di approvazione exec.
Correlati: