Your node is connected. It shows as paired in openclaw nodes status. But when you try to use the camera, screen recording, or canvas tools, the request fails with NODE_BACKGROUND_UNAVAILABLE. Nothing is broken, and the node is not offline. This is an intentional restriction, and the fix depends on which platform the node runs on.
This guide explains why the error exists, what changes on mobile versus macOS, and the two extra checks when the obvious fix is not enough.
Why this happens
On iOS and Android, the OpenClaw node app needs to be in the foreground to access the camera, capture the screen, or draw on the canvas. This is an operating system restriction, not an OpenClaw limitation: both platforms restrict background access to the camera and screen capture for privacy and security reasons. When the node app is minimized or the screen is locked, those capabilities are simply unavailable. The node stays connected and keeps responding to the gateway, but it cannot fulfill tool requests that need hardware access.
The error code is the feature. OpenClaw could fail silently when a background tool call is refused, but instead it returns a named reason that tells you exactly which state to change: the app is running, just not where the operating system needs it. That explicit refusal is what makes the fix a thirty-second action rather than a debugging session. When you see the code, you already know the answer, foreground the app.
A practical workflow note for anyone using a phone or tablet as a camera node while working on a laptop: the device needs to stay awake and in the foreground for the whole capture, so disable auto-lock or set a long screen timeout before a scheduled clip, and keep the OpenClaw app as the active app rather than switching away to check something. Screen-off is the same as backgrounded from the tool’s point of view.
The fix on iOS and Android
Open the OpenClaw node app so it is the active foreground app, then retry the tool call. That is the whole fix on mobile: the error clears as soon as the app has foreground focus. For camera clips that need a few seconds of recording, keep the app open and in the foreground for the duration of the capture, because losing focus mid-clip can abort it.
Permissions matter on top of foreground state. On iOS, open Settings, find the OpenClaw app entry, and set the camera permission to Allow rather than Ask every time. On Android, do the same through App Info. A permission set to ask-every-time makes tool calls unreliable even when the app is in front, because each call can stall waiting for a prompt nobody is there to answer.
The fix on macOS nodes
The macOS node app does not have the same strict foreground requirement. Camera and screen tools on a Mac only need the relevant OS permissions granted under System Settings, Privacy and Security: Camera for photos and clips, Screen Recording for screen capture. If you hit this error on a Mac node, check permissions rather than foreground state. The platform map shows the whole picture:
Which tools are affected
The split is consistent: anything that reads hardware sensors or the display is foreground-restricted on mobile, while location and plain connectivity work in the background. If location calls fail in the background, the usual cause is a permission level below Always, not the foreground rule.
Checking node status and capabilities
Start from the node list, then drill into the specific node. On this host right now the node list is empty, which is itself a useful reading of the command:
When a node is present, the describe command shows what it can actually do:
user@host:~$ openclaw nodes describe --node <nameOrId> # Lists capabilities and flags missing permissions.
Connected does not mean hardware-ready: the node has to report the capability, and the describe output is where a missing permission or an unadvertised tool shows up.
The second layer: gateway allow and deny lists
Camera, screen, and contact tools are privacy-heavy, and OpenClaw treats them specially at the gateway layer on top of the platform rules. Commands like camera.snap, camera.clip, and screen.record require explicit opt-in through gateway.nodes.allowCommands, and gateway.nodes.denyCommands always wins over defaults and allowlist entries. If a tool fails with a permission-style error even with the app foregrounded and OS permissions granted, check the gateway node config: the tool may be denied there regardless of what the node can do.
If the tool succeeds on one device but fails on another, compare the two paths: foreground state, OS permission level, and the gateway allow list each need to match on the working device. The difference between the two usually names the exact fix in one step.
Verifying a fix
After any change, retry the exact tool call while watching the log for the outcome:
Watch the log line during the retry: a clean run means the platform state was the problem, while a repeated refusal points at the gateway allow or deny list. If the error persists on mobile with the app in front and permissions on Allow, reinstall the node app’s pairing or check for an OS-level restriction like Screen Time or a managed profile.
When a camera or screen tool refuses on a desktop node with everything granted, and the gateway allow list is clear, the remaining suspects are pairing state and OS-level restrictions like Screen Time or managed-device profiles. Re-pairing the node is a two-minute check that clears a surprising share of stale-capability problems, because the gateway can hold a capability snapshot from before a permission change.
Related fixes
Node and gateway behavior sits inside the wider troubleshooting cluster on this site, and the workspace-file series that defines agent behavior ties together under The Complete OpenClaw Guide.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting: your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.
About The Author
