OpenClaw node troubleshooting

Your node shows as paired and connected, host stats are flowing, and the gateway is not logging anything alarming. Then camera.snap comes back with a permission code, computer.act refuses with COMPUTER_DISABLED, or exec answers SYSTEM_RUN_DENIED. Connection is only the first of four separate checks, and the other three are invisible in a status line. This is the upstream node troubleshooting runbook: the four gates, the Linux service trap that drops a node the moment you log out of SSH, and what each error code actually means.

The four gates a node command has to pass

• Device pairing decides whether this node may connect to the gateway at all. The node presents a signed device identity on connect, the gateway raises a pairing request for role node, and you approve it with openclaw devices approve against the device request ID. That admits the identity and nothing else.
• Node command surface approval decides which commands the admitted identity may expose. The declared surface arrives as its own pending request, listed by openclaw nodes pending and approved with openclaw nodes approve against a node request ID that is not the device request ID. An initial unapproved surface exposes no effective commands, so a correctly paired, connected node can sit there answering nothing.
• Gateway node command policy decides whether the RPC command ID is allowed at all, from the platform defaults plus gateway.nodes.commands.allow and gateway.nodes.commands.deny. Privacy-heavy commands such as camera.snap, camera.clip, screen.record and desktop.stream need a one-time persistent allow entry even when the node declares them, and a deny entry always overrides both a platform default and an allow entry.
• Exec approvals decide whether the node may run one specific shell command locally. For system.run the allowlist and ask policy live in that node's exec approvals, read with openclaw approvals get against the node, not in the pairing record. Platform permissions and foreground requirements still apply after all four gates agree.

Device pairing admits the identity; surface approval limits the commands on its paired-device record.

Why a paired node can still expose nothing

The two request IDs are the trap. Approving the device does not approve the surface: after pairing is approved you restart or rerun the node, and that reconnect creates the separate surface request you then approve by node request ID. SSH-verified enrolment and administrator-minted bootstrap enrolment can approve the first surface automatically, but trusted-network device approval does not, so an auto-approved CIDR range hands you a connected node with an empty command list. Expansions follow the same rule: a pending expansion retains only the commands that were already approved, are still declared, and still pass gateway policy. If openclaw nodes describe is missing the command you are calling, check the gateway command policy first, then whether the node actually declared that command on connect.

The Linux lingering trap

• On Linux, openclaw node install creates a user-level systemd service, and the systemd user instance is torn down when your last login session ends. The node service therefore stops the moment you log out of SSH, even though it reported enabled and running the whole time you were connected.
• Check it with loginctl show-user $USER -p Linger. If that reads Linger=no, run sudo loginctl enable-linger $USER, restart with openclaw node restart, then log out and confirm from another machine with openclaw nodes status. The installer already prints a warning carrying this recovery command when it detects that lingering is disabled.
• Do not mix a user-level service with a system-level one for the same node. The duplicate-scope guard that stops two managers owning the same unit name is enforced for gateway units, because two supervisors on the same port SIGTERM each other in a restart loop, but the installer does not raise that guard for node services, so a leftover unit in the other scope leaves the node in an ambiguous state. Remove one fully before switching.

The first gate and the fourth have pages of their own: OpenClaw pairing covers the request, approval and expiry lifecycle behind device admission, and OpenClaw exec approvals covers the allowlist, ask and mode vocabulary that decides whether a shell command is allowed to run on the node host at all.

Every node error code and its fix

NODE_BACKGROUND_UNAVAILABLE means the app is backgrounded; camera and screen commands are foreground-only on iOS and Android nodes, so bring the app forward and retry. CAMERA_DISABLED and LOCATION_DISABLED are node-side toggles rather than operating system grants: the capability is switched off in node settings. Anything ending in PERMISSION_REQUIRED is a missing or denied operating system permission, and LOCATION_BACKGROUND_UNAVAILABLE is the narrower case where the app is backgrounded but only While Using was ever granted. COMPUTER_DISABLED means Allow Computer Control is off in the macOS app: enable it, then approve the pairing update that follows. ACCESSIBILITY_REQUIRED means Accessibility has not been granted to the current OpenClaw app bundle in macOS System Settings, and the same fulfiller needs Screen Recording as well. SYSTEM_RUN_DENIED arrives in two flavours: approval required means the exec request needs an explicit approval, while allowlist miss means allowlist mode blocked the command, and on Windows node hosts shell-wrapper forms such as cmd.exe /c count as allowlist misses unless they are approved through the ask flow. For a desktop that will not act at all, OpenClaw computer use covers the provider, permission and tool-policy side, and OpenClaw nodes and Remote Hands is the overview of what a paired device is and what it may be asked to do.

On Diali

Diali hosts OpenClaw, one assistant per customer, so the gateway side of these four gates runs on our infrastructure while the node itself stays on hardware you own. The runtime configuration is generated from the dashboard and replaced at each release, and agent state, including the paired-device records that carry an approved node surface, lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Hosted OpenClaw on Diali sets out what the hosted runtime includes and Diali pricing what it costs.

• Connected is gate one of four: pairing, surface, policy, exec approvals.
• The device request ID and the node request ID are different IDs.
• Linger=no means your Linux node dies at SSH logout.