Node Troubleshooting Guide

Use this page when a node appears in the status view but node tools are not working.

Command ladder

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

After that, execute node specific checks:

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

Indicators of a healthy state:

The node is connected and paired for the node role.
The capability you are invoking is listed in nodes describe.
Execution approvals display the expected mode or allowlist.

Foreground requirements

On iOS and Android nodes, canvas.*, camera.*, and screen.* only work while the app is in the foreground.

Rapid verification and remedy:

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

When NODE_BACKGROUND_UNAVAILABLE appears, bring the node application to the foreground and attempt the operation again.

Permissions matrix

Capability	iOS	Android	macOS node app	Typical failure code
`camera.snap`, `camera.clip`	Camera (plus microphone for clip audio)	Camera (plus microphone for clip audio)	Camera (plus microphone for clip audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording (microphone optional)	Screen capture prompt (microphone optional)	Screen Recording	`*_PERMISSION_REQUIRED`
`computer.act`	n/a	n/a	Accessibility plus Screen Recording	`COMPUTER_DISABLED`, `ACCESSIBILITY_REQUIRED`
`location.get`	While Using or Always (depends on mode)	Foreground or Background location per mode	Location permission	`LOCATION_PERMISSION_REQUIRED`
`system.run`	n/a (node host path)	n/a (node host path)	Exec approvals required	`SYSTEM_RUN_DENIED`

Pairing versus approvals

Three separate layers determine whether a node command will succeed:

Device pairing: can this node establish a connection to the gateway?
Gateway node command policy: does the RPC command ID fall within the allowed set defined by gateway.nodes.commands.allow / gateway.nodes.commands.deny and platform defaults?
Exec approvals: can this node run a particular shell command locally?

Node pairing serves as an identity and trust gate, not a per command authorization mechanism. For system.run, the node specific policy resides in that node's exec approvals file (openclaw approvals get --node ...), not in the gateway pairing record.

Rapid checks:

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

Pairing is absent: authorize the node device first.
nodes describe is missing a command: review the gateway node command policy and confirm the node actually declared that command when it connected.
Pairing is fine but system.run fails: correct the exec approvals or allowlist on that node.

For host=node runs that require approval, the gateway also ties execution to the prepared canonical systemRunPlan. If a later caller changes the command, working directory, or session metadata before forwarding the approved run, the gateway rejects the execution as an approval mismatch and does not trust the altered payload.

Common node error codes

Code	Meaning
`NODE_BACKGROUND_UNAVAILABLE`	The app is running in the background; move it to the foreground.
`CAMERA_DISABLED`	Camera toggle is turned off in node settings.
`*_PERMISSION_REQUIRED`	The operating system permission is missing or was denied.
`LOCATION_DISABLED`	Location mode is switched off.
`LOCATION_PERMISSION_REQUIRED`	The requested location mode was not granted.
`LOCATION_BACKGROUND_UNAVAILABLE`	The app is in the background but only a While Using permission is available.
`COMPUTER_DISABLED`	Turn on Allow Computer Control in the macOS app, then approve the pairing update.
`ACCESSIBILITY_REQUIRED`	Grant Accessibility to the current OpenClaw app bundle in macOS System Settings.
`SYSTEM_RUN_DENIED: approval required`	The exec request needs explicit approval.
`SYSTEM_RUN_DENIED: allowlist miss`	The command is blocked by the allowlist mode. On Windows node hosts, shell wrapper forms like `cmd.exe /c ...` are treated as allowlist misses in allowlist mode unless approved through the ask flow.

Fast recovery loop

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

If the problem persists:

Re approve the device pairing.
Re open the node application (bring it to the foreground).
Re grant the operating system permissions.
Recreate or adjust the exec approval policy.

For computer control, also confirm that a vision capable agent exposes the computer tool, screen.snapshot succeeds with Screen Recording permission, and /phone status shows the temporary or persistent gateway authorization you intended. A gateway.nodes.commands.deny entry always takes precedence over gateway.nodes.commands.allow.