Troubleshoot OpenClaw Nodes: Fix Connection & Errors Fast

We’ve all been there: your dashboard shows a node is online and the connection looks green, but the second you try to run a tool, everything hits a brick wall. It is frustrating when a node is visible in your status list but refuses to actually do its job.

If you are staring at a node that seems connected but fails every command, this guide will help you find the bottleneck and fix it.

Command ladder

When things go sideways, you need to see what the gateway and the node think is happening. Start with these general status checks to get a clear picture of your environment.

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

Once you have the general state, run these node-specific checks to see the details for the specific device giving you trouble.

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

You are looking for these four healthy signals:

The node is visible in your status output.
The node is connected and paired for the node role.
The nodes describe output includes the specific capability you want to use.
Exec approvals show the expected mode or allowlist.

Foreground requirements

If you are working with mobile nodes, keep in mind that certain features like canvas.*, camera.*, and screen.* only work when the app is active. On iOS and Android, these are foreground-only operations.

You can use these commands to check the current state and try a quick fix:

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

If your logs show NODE_BACKGROUND_UNAVAILABLE, the fix is simple. Just bring the node app to the foreground on the device and try your request again.

Permissions matrix

Permissions are often the reason a command fails even when the node is connected. Use this table to verify that you have granted the right access for each platform.

Capability	iOS	Android	macOS node app	Typical failure code
`camera.snap`, `camera.clip`	Camera (+ mic for clip audio)	Camera (+ mic for clip audio)	Camera (+ mic for clip audio)	`*_PERMISSION_REQUIRED`
`screen.record`	Screen Recording (+ mic optional)	Screen capture prompt (+ mic optional)	Screen Recording	`*_PERMISSION_REQUIRED`
`location.get`	While Using or Always (depends on mode)	Foreground/Background location based on 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

It is easy to mix these up, but they are two different gates you have to pass. Pairing is about identity and trust, while approvals are about what the node is allowed to do locally.

Device pairing: This determines if the node can connect to the gateway at all.
Gateway node command policy: This checks if the RPC command ID is allowed by your gateway settings.
Exec approvals: This determines if the node can run a specific shell command on its local host.

Use these commands to check both sides of the fence:

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

If pairing is missing, you must approve the node device first. If nodes describe is missing a command, check your gateway node command policy and confirm the node declared that command when it connected. If pairing is fine but system.run fails, you need to fix the exec approvals or the allowlist on that specific node.

Remember that node pairing is an identity gate, not a per-command approval surface. For system.run, the policy lives in the node’s own exec approvals file, which you can view with openclaw approvals get --node ....

Common node error codes

When a command fails, the error code usually points you directly to the solution. Here are the ones you will see most often:

NODE_BACKGROUND_UNAVAILABLE: The app is in the background; bring it to the foreground.
CAMERA_DISABLED: The camera toggle is turned off in the node settings.
*_PERMISSION_REQUIRED: The OS permission is missing or was denied by the user.
LOCATION_DISABLED: The location mode is currently turned off.
LOCATION_PERMISSION_REQUIRED: The requested location mode has not been granted.
LOCATION_BACKGROUND_UNAVAILABLE: The app is backgrounded and only has “While Using” permissions.
SYSTEM_RUN_DENIED: approval required: The exec request needs an explicit approval.
SYSTEM_RUN_DENIED: allowlist miss: The command is blocked by allowlist mode.

On Windows node hosts, shell-wrapper forms like cmd.exe /c ... will trigger an allowlist miss in allowlist mode unless you approve them via the ask flow.

Fast recovery loop

When you need to get things back on track quickly, follow this loop to find the problem.

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

If you are still stuck after checking the logs, try these four steps:

Re-approve the device pairing.
Re-open the node app to bring it to the foreground.
Re-grant the necessary OS permissions in the device settings.
Recreate or adjust your exec approval policy.

Next steps

AI Setup Assistant

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.