Node-Fehlerbehebung

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

Befehlsleiter

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

Dann node-spezifische Prüfungen:

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

Gesunde Signale:

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

Vordergrund-Anforderungen

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

Schnellcheck und Behebung:

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

Wenn du NODE_BACKGROUND_UNAVAILABLE siehst, bringe die Node-App in den Vordergrund und versuche es erneut.

Berechtigungsmatrix

Fähigkeit	iOS	Android	macOS-Node-App	Typischer Fehlercode
`camera.snap`, `camera.clip`	Kamera (+ Mikro für Clip-Audio)	Kamera (+ Mikro für Clip-Audio)	Kamera (+ Mikro für Clip-Audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Bildschirmaufnahme (+ Mikro optional)	Bildschirmaufnahme-Abfrage (+ Mikro optional)	Bildschirmaufnahme	`*_PERMISSION_REQUIRED`
`location.get`	Bei Nutzung oder Immer (je nach Modus)	Vordergrund-/Hintergrund-Standort je nach Modus	Standortberechtigung	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (Node-Host-Pfad)	n/a (Node-Host-Pfad)	Exec-Genehmigungen erforderlich	`SYSTEM_RUN_DENIED`

Kopplung versus Genehmigungen

Das sind unterschiedliche Prüfungen:

Gerätekopplung: Kann sich dieser Node mit dem Gateway verbinden?
Exec-Genehmigungen: Darf dieser Node einen bestimmten Shell-Befehl ausführen?

Schnellchecks:

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

Wenn die Kopplung fehlt, genehmige zuerst das Node-Gerät. Wenn die Kopplung stimmt, aber system.run fehlschlägt, behebe die Exec-Genehmigungen/Allowlist.

Häufige Node-Fehlercodes

NODE_BACKGROUND_UNAVAILABLE → App ist im Hintergrund; bringe sie in den Vordergrund.
CAMERA_DISABLED → Kamera-Schalter in den Node-Einstellungen deaktiviert.
*_PERMISSION_REQUIRED → OS-Berechtigung fehlt/verweigert.
LOCATION_DISABLED → Standortmodus ist aus.
LOCATION_PERMISSION_REQUIRED → angeforderter Standortmodus nicht erteilt.
LOCATION_BACKGROUND_UNAVAILABLE → App ist im Hintergrund, aber nur „Bei Nutzung”-Berechtigung vorhanden.
SYSTEM_RUN_DENIED: approval required → Exec-Anfrage benötigt explizite 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 Fehlschläge behandelt, sofern nicht über den Ask-Flow genehmigt.

Schnelle Wiederherstellungsschleife

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

Wenn es immer noch hakt:

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

Verwandte Themen: