ContextQMD
Back to Openclaw

Node troubleshooting

docs/nodes/troubleshooting.md

2026.7.16.2 KB
Original Source

Use this page when a node is visible in status but node tools fail.

Command ladder

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

Then run node-specific checks:

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

Healthy signals:

  • Node is connected and paired for role node.
  • nodes describe includes the capability you're calling.
  • Exec approvals show the expected mode/allowlist.

Foreground requirements

canvas.*, camera.*, and screen.* are foreground-only on iOS/Android nodes.

Quick check and fix:

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

If you see NODE_BACKGROUND_UNAVAILABLE, bring the node app to the foreground and retry.

Permissions matrix

CapabilityiOSAndroidmacOS node appTypical failure code
camera.snap, camera.clipCamera (+ mic for clip audio)Camera (+ mic for clip audio)Camera (+ mic for clip audio)*_PERMISSION_REQUIRED
screen.recordScreen Recording (+ mic optional)Screen capture prompt (+ mic optional)Screen Recording*_PERMISSION_REQUIRED
location.getWhile Using or Always (depends on mode)Foreground/Background location based on modeLocation permissionLOCATION_PERMISSION_REQUIRED
system.runn/a (node host path)n/a (node host path)Exec approvals requiredSYSTEM_RUN_DENIED

Pairing versus approvals

Three separate gates control whether a node command succeeds:

  1. Device pairing: can this node connect to the gateway?
  2. Gateway node command policy: is the RPC command ID allowed by gateway.nodes.allowCommands / denyCommands and platform defaults?
  3. Exec approvals: can this node run a specific shell command locally?

Node pairing is an identity/trust gate, not a per-command approval surface. For system.run, the per-node policy lives in that node's exec approvals file (openclaw approvals get --node ...), not in the gateway pairing record.

Quick checks:

bash
openclaw devices list
openclaw nodes status
openclaw approvals get --node <idOrNameOrIp>
openclaw approvals allowlist add --node <idOrNameOrIp> "/usr/bin/uname"
  • Pairing missing: approve the node device first.
  • nodes describe missing a command: check the gateway node command policy and whether the node actually declared that command on connect.
  • Pairing fine but system.run fails: fix exec approvals/allowlist on that node.

For approval-backed host=node runs, the gateway also binds execution to the prepared canonical systemRunPlan. If a later caller mutates the command, cwd, or session metadata before the approved run is forwarded, the gateway rejects the run as an approval mismatch instead of trusting the edited payload.

Common node error codes

CodeMeaning
NODE_BACKGROUND_UNAVAILABLEApp is backgrounded; bring it to the foreground.
CAMERA_DISABLEDCamera toggle disabled in node settings.
*_PERMISSION_REQUIREDOS permission missing/denied.
LOCATION_DISABLEDLocation mode is off.
LOCATION_PERMISSION_REQUIREDRequested location mode not granted.
LOCATION_BACKGROUND_UNAVAILABLEApp is backgrounded but only While Using permission exists.
SYSTEM_RUN_DENIED: approval requiredExec request needs explicit approval.
SYSTEM_RUN_DENIED: allowlist missCommand blocked by allowlist mode. On Windows node hosts, shell-wrapper forms like cmd.exe /c ... are treated as allowlist misses in allowlist mode unless approved via the ask flow.

Fast recovery loop

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

If still stuck:

  • Re-approve device pairing.
  • Re-open the node app (foreground).
  • Re-grant OS permissions.
  • Recreate/adjust the exec approval policy.