Node Troubleshooting Guide

Use this page when a node shows up in status but node tools won't work.

Node goes offline after SSH logout (Linux)

On Linux, openclaw node install sets up a systemd service at the user level. The systemd --user instance gets torn down once your final login session closes, so the node service halts the moment you sign out, even though it appeared healthy (enabled + running) during your connection.

Check lingering:

loginctl show-user "$USER" -p Linger

If it returns Linger=no, turn it on (sudo might be needed):

sudo loginctl enable-linger "$USER"

After that, restart the node service and confirm it survives logout:

openclaw node restart
# log out, then from another machine:
openclaw nodes status

When lingering is off, openclaw node install emits a warning that includes this recovery command. Don't run a user-level service and a system-level service for the same node at the same time. The duplicate-scope guard, which stops two managers from operating the same unit name, applies only to gateway units (two supervisors on the same port SIGTERM each other in a restart loop); for node services, the installer doesn't raise this guard, so a leftover unit in the other scope can leave the node in an unclear state. Remove one completely before switching.

Command ladder

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

Then run node-specific checks:

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 contains the capability you're invoking.
Exec approvals show the expected mode/allowlist.

Foreground requirements

camera.* and screen.* work only in the foreground on iOS/Android nodes.

Quick check and fix:

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

If you encounter NODE_BACKGROUND_UNAVAILABLE, bring the node app to the foreground and try again.

Permissions matrix

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`
`computer.act`	n/a	n/a	Accessibility + Screen Recording	`COMPUTER_DISABLED`, `ACCESSIBILITY_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

Three separate gates decide whether a node command succeeds:

Device pairing: can this node reach the gateway?
Gateway node command policy: is the RPC command ID allowed by gateway.nodes.commands.allow / gateway.nodes.commands.deny and platform defaults?
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:

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 changes 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

Code	Meaning
`NODE_BACKGROUND_UNAVAILABLE`	App is backgrounded; bring it to the foreground.
`CAMERA_DISABLED`	Camera toggle disabled in node settings.
`*_PERMISSION_REQUIRED`	OS permission missing/denied.
`LOCATION_DISABLED`	Location mode is off.
`LOCATION_PERMISSION_REQUIRED`	Requested location mode not granted.
`LOCATION_BACKGROUND_UNAVAILABLE`	App is backgrounded but only While Using permission exists.
`COMPUTER_DISABLED`	Enable 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`	Exec request needs explicit approval.
`SYSTEM_RUN_DENIED: allowlist miss`	Command 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

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.

When controlling the computer, confirm that the node-level Computer Control switch is turned on, its pairing update has been accepted, an agent with vision support offers the computer tool, and screen.snapshot works with Screen Recording permission granted. A gateway.nodes.commands.deny setting takes precedence over any platform default or gateway.nodes.commands.allow.