Node-Problembehandlung

Verwenden Sie diese Seite, wenn ein Node im Status sichtbar ist, Node-Tools aber fehlschlagen.

Befehlsleiter

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Führen Sie dann für den Node spezifische Prüfungen aus:

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

Gesunde Signale:

• Node ist verbunden und für die Rolle node gekoppelt.
• nodes describe enthält die Fähigkeit, die Sie aufrufen.
• Exec-Genehmigungen zeigen den erwarteten Modus/die erwartete Allowlist.

Anforderungen an den Vordergrund

canvas.*, camera.* und screen.* sind auf iOS-/Android-Nodes nur im Vordergrund verfügbar.

Schnellprüfung und Behebung:

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

Wenn Sie NODE_BACKGROUND_UNAVAILABLE sehen, bringen Sie die Node-App in den Vordergrund und versuchen Sie es erneut.

Berechtigungsmatrix

Kopplung versus Genehmigungen

Dies sind unterschiedliche Sperren:

1. Gerätekopplung: Kann dieser Node eine Verbindung zum Gateway herstellen?
2. Gateway-Richtlinie für Node-Befehle: Ist die RPC-Befehls-ID durch gateway.nodes.allowCommands / denyCommands und Plattformstandards erlaubt?
3. Exec-Genehmigungen: Kann dieser Node lokal einen bestimmten Shell-Befehl ausführen?

Schnellprüfungen:

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

Wenn die Kopplung fehlt, genehmigen Sie zuerst das Node-Gerät. Wenn in nodes describe ein Befehl fehlt, prüfen Sie die Gateway-Richtlinie für Node-Befehle und ob der Node diesen Befehl beim Verbinden tatsächlich deklariert hat. Wenn die Kopplung in Ordnung ist, system.run aber fehlschlägt, korrigieren Sie die Exec-Genehmigungen/Allowlist auf diesem Node.

Node-Kopplung ist eine Identitäts-/Vertrauenssperre, keine Genehmigungsfläche pro Befehl. Für system.run befindet sich die Pro-Node-Richtlinie in der Exec-Genehmigungsdatei dieses Nodes (openclaw approvals get --node ...), nicht im Gateway-Kopplungsdatensatz.

Bei genehmigungsgestützten host=node-Ausführungen bindet das Gateway die Ausführung außerdem an den vorbereiteten kanonischen systemRunPlan. Wenn ein späterer Aufrufer command/cwd oder Sitzungsmetadaten verändert, bevor die genehmigte Ausführung weitergeleitet wird, lehnt das Gateway die Ausführung als Genehmigungsabweichung ab, statt der bearbeiteten Nutzlast zu vertrauen.

Häufige Node-Fehlercodes

• NODE_BACKGROUND_UNAVAILABLE → App läuft im Hintergrund; bringen Sie sie in den Vordergrund.
• CAMERA_DISABLED → Kameraschalter in den Node-Einstellungen deaktiviert.
• *_PERMISSION_REQUIRED → OS-Berechtigung fehlt/wurde verweigert.
• LOCATION_DISABLED → Standortmodus ist ausgeschaltet.
• LOCATION_PERMISSION_REQUIRED → angeforderter Standortmodus nicht gewährt.
• LOCATION_BACKGROUND_UNAVAILABLE → App läuft im Hintergrund, aber es existiert nur die Berechtigung Beim Verwenden.
• SYSTEM_RUN_DENIED: approval required → Exec-Anfrage benötigt ausdrückliche Genehmigung.
• SYSTEM_RUN_DENIED: allowlist miss → Befehl durch Allowlist-Modus blockiert. Auf Windows-Node-Hosts werden Shell-Wrapper-Formen wie cmd.exe /c ... im Allowlist-Modus als Allowlist-Fehltreffer behandelt, sofern sie nicht über den Anfrageablauf genehmigt wurden.

Schnelle Wiederherstellungsschleife

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

Wenn Sie weiterhin festhängen:

• Gerätekopplung erneut genehmigen.
• Node-App erneut öffnen (Vordergrund).
• OS-Berechtigungen erneut gewähren.
• Exec-Genehmigungsrichtlinie neu erstellen/anpassen.

Verwandt

• Nodes-Übersicht
• Kamera-Nodes
• Standortbefehl
• Exec-Genehmigungen
• Gateway-Kopplung
• Gateway-Fehlerbehebung
• Channel-Fehlerbehebung