OpenClaw Node-Fehler beheben: Schritt-für-Schritt-Anleitung

Kennst du das? Dein Node wird im Status als aktiv angezeigt, alles sieht auf den ersten Blick gut aus, aber sobald du einen Befehl sendest, passiert einfach nichts oder du läufst in Fehlermeldungen. Das ist extrem nervig, liegt aber meistens an einer Kleinigkeit in der Konfiguration oder fehlenden Berechtigungen.

In diesem Guide zeige ich dir, wie du systematisch vorgehst, um das Problem schnell zu lösen. Nutze diese Seite immer dann, wenn ein Node zwar im Status sichtbar ist, aber die Node-Tools fehlschlagen.

Befehlskette

Zuerst solltest du die allgemeine Infrastruktur prüfen. Arbeite dich von oben nach unten durch:

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

Danach führst du die Node-spezifischen Checks aus:

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

Gute Zeichen sind:

Der Node ist verbunden und für die Rolle node gepairt.
nodes describe listet die Capability auf, die du gerade aufrufen willst.
Die Exec Approvals zeigen den erwarteten Modus oder die passende allowlist.

Vordergrund-Anforderungen

Die Capabilities canvas.*, camera.* und screen.* funktionieren auf iOS- und Android-Nodes nur im Vordergrund.

Hier ist ein schneller Check und Fix:

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

Wenn du den Fehler NODE_BACKGROUND_UNAVAILABLE siehst, musst du die Node App einfach in den Vordergrund holen und es noch einmal versuchen.

Berechtigungsmatrix

In dieser Tabelle siehst du, welche Berechtigungen auf welcher Plattform nötig sind:

Capability	iOS	Android	macOS node app	Typischer Fehlercode
`camera.snap`, `camera.clip`	Camera (+ mic für clip audio)	Camera (+ mic für clip audio)	Camera (+ mic für clip audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording (+ mic optional)	Screen capture prompt (+ mic optional)	Screen Recording	`*_PERMISSION_REQUIRED`
`location.get`	While Using oder Always (je nach Modus)	Foreground/Background location je nach Modus	Location permission	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (node host path)	n/a (node host path)	Exec approvals erforderlich	`SYSTEM_RUN_DENIED`

Pairing vs. Approvals

Es ist wichtig, dass du diese drei Hürden nicht verwechselst:

Device pairing: Darf dieser Node überhaupt eine Verbindung zum Gateway aufbauen?
Gateway node command policy: Erlaubt die RPC-Policy den Befehl (gesteuert über gateway.nodes.allowCommands / denyCommands und Plattform-Defaults)?
Exec approvals: Darf der Node einen spezifischen Shell-Befehl lokal ausführen?

Schnelle Checks dafür:

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

Wenn das Pairing fehlt, musst du zuerst das Node-Device approven. Falls in nodes describe ein Befehl fehlt, prüfe die Gateway Node Command Policy und ob der Node den Befehl beim Verbinden korrekt deklariert hat. Wenn das Pairing steht, aber system.run fehlschlägt, musst du die Exec Approvals oder die allowlist auf diesem Node anpassen.

Das Node-Pairing ist ein Identitäts-Check, keine Berechtigung für einzelne Befehle. Für system.run liegt die Policy direkt auf dem Node in der Exec-Approval-Datei (openclaw approvals get --node ...), nicht im Pairing-Datensatz des Gateways.

Häufige Node-Fehlercodes

NODE_BACKGROUND_UNAVAILABLE → Die App läuft im Hintergrund; hol sie in den Vordergrund.
CAMERA_DISABLED → Die Kamera ist in den Node-Einstellungen deaktiviert.
*_PERMISSION_REQUIRED → Eine OS-Berechtigung fehlt oder wurde abgelehnt.
LOCATION_DISABLED → Der Location-Modus ist ausgeschaltet.
LOCATION_PERMISSION_REQUIRED → Der angeforderte Location-Modus wurde nicht genehmigt.
LOCATION_BACKGROUND_UNAVAILABLE → Die App ist im Hintergrund, hat aber nur die “While Using”-Berechtigung.
SYSTEM_RUN_DENIED: approval required → Der Exec-Request braucht eine explizite Freigabe.
SYSTEM_RUN_DENIED: allowlist miss → Der Befehl wird durch den allowlist-Modus blockiert. Auf Windows-Hosts werden Shell-Wrapper wie cmd.exe /c ... im allowlist-Modus als “miss” gewertet, außer sie wurden über den Ask-Flow genehmigt.

Schneller Recovery-Loop

Wenn gar nichts mehr geht, geh diese Schritte durch:

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

Immer noch Probleme? Dann probier das:

Device-Pairing erneut durchführen.
Node App neu öffnen (Vordergrund).
OS-Berechtigungen neu vergeben.
Exec-Approval-Policy neu erstellen oder anpassen.

Nächste Schritte

Noch Fragen? Frag den AI Setup Assistant.

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.