OpenClaw Nodes: Run Real Device Tools Without Moving the Gateway

A good agent does not need to live on every machine it can use. That is the point of OpenClaw nodes.

A node is a companion device: macOS, iOS, Android, or a headless host that connects to the Gateway WebSocket with role: "node". Once paired, it exposes a command surface such as canvas.*, camera.*, location.get, system.*, and platform-specific device commands through node.invoke. The Gateway still owns the agent loop, sessions, channels, and replies. The node is the peripheral.

That distinction sounds small until you operate a real setup. If your Slack message arrives, the Gateway receives it. If your agent needs a camera snapshot from a phone, the Gateway asks the node. If your build should run on another Mac, the Gateway forwards the command to a node host. The node does useful local work, but it does not become the agent's brain.

The operator mental model: one owner, many peripherals

OpenClaw's docs are explicit: nodes are peripherals, not Gateways. Telegram, WhatsApp, Slack, and other channel messages land on the Gateway, not on the node. A paired node extends what the Gateway can see or do on another device.

That is the model I want in production because it gives you clean blame lines. If a reply is wrong, inspect the Gateway session and model context. If a camera tool fails, inspect node pairing, foreground state, and OS permissions. If a remote command is denied, inspect node-host exec approvals. Do not collapse all of those into “OpenClaw is broken.” They are different gates.

This also keeps multi-device setups sane. Your office iMac can run the Gateway, your phone can provide camera or location when explicitly enabled, and a separate build box can expose system.run under approvals. The agent gets one control plane instead of a pile of ad hoc scripts.

Pair the node before you trust it

WebSocket nodes use device pairing. During connect, the node presents a device identity and the Gateway creates a pairing request for the node role. Approve the current request before expecting node commands to work.

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

There is one detail worth remembering: if a node retries with changed auth details, such as role, scopes, or public key, the previous pending request is superseded and a new requestId is created. Re-run openclaw devices list before approving. Approving an old request is not the same as approving the device that is currently trying to connect.

openclaw nodes status tells you whether the node is connected and paired for the node role. openclaw nodes describe tells you which capabilities are advertised. In operator terms, status answers “is it there?” and describe answers “what can it safely do?”

Canvas is for visible web state, not secret magic

When a node is showing the Canvas WebView, canvas.snapshot can return a screenshot as media. The helper commands can present a URL or local target, capture a snapshot, navigate, or evaluate JavaScript in the Canvas.

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

This is useful when the agent needs visible state from a device surface instead of guessing from logs. But on mobile nodes, canvas.* is foreground-only. If the app is backgrounded, calls can return NODE_BACKGROUND_UNAVAILABLE. That is not a model failure. It is the node protecting a user-controlled surface.

For buyer/operator workflows, I like Canvas for QA checks, kiosk workflows, internal dashboards, and controlled “look at this screen” tasks. I do not like using it as a substitute for proper APIs when an API exists. Canvas is excellent evidence. It is a fragile integration boundary if you make it carry your whole business process.

Camera tools are gated, bounded, and practical

OpenClaw nodes can capture photos and short video clips from iOS, Android, and the macOS app. The command family is camera.*. Photos are jpg; clips are mp4 and can include audio. The CLI helpers write decoded media to temporary files and print MEDIA:<path>, which is convenient for agent attachments.

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

The defaults are intentionally bounded. Camera photos are recompressed to keep the base64 payload under 5 MB. Clips are clamped to a maximum of 60 seconds to avoid oversized payloads. On iOS and Android, camera commands are foreground-only. Android also needs runtime CAMERA permission, and RECORD_AUDIO if a clip includes audio. The macOS app has a user setting under Settings → General → Allow Camera, and it defaults off.

Those constraints are not annoying paperwork. They are the difference between “an agent can inspect a machine label when I ask” and “an agent has ambient camera access I forgot existed.” For revenue work, trust is the product. Camera access should be explicit, visible, and easy to disable.

Mid-run operator check: if you are selling an AI operator workflow, map every real-world sense to a permission and a failure code before launch. Want the complete production checklist? Get ClawKit — $9.99.

Location should stay opt-in and narrow

location.get is a node command. The docs mark it off by default. Android exposes an in-app selector for Off or While Using, plus a separate Precise Location toggle. iOS and macOS may expose While Using or Always in system prompts or Settings, but the OS still decides the actual grant.

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

The command can request accuracy and timing parameters such as desiredAccuracy, maxAgeMs, and timeoutMs. The response includes latitude, longitude, accuracy in meters, timestamp, and related fields when available. Stable errors include LOCATION_DISABLED, LOCATION_PERMISSION_REQUIRED, LOCATION_BACKGROUND_UNAVAILABLE, LOCATION_TIMEOUT, and LOCATION_UNAVAILABLE.

That makes the safe product shape obvious: call location only when the user enabled it and understands the scope. If a logistics assistant needs “where is this field device right now?” that can be valuable. If a generic chat assistant quietly asks for precise GPS because it might be useful, that is creepy and brittle.

Node hosts make remote execution explicit

A headless node host is the cleaner way to let the Gateway run commands on another machine. The model still talks to the Gateway. The Gateway forwards system.run or system.which to the selected node host when node execution is chosen.

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from node"

Exec approvals are enforced on the node host via its local approval file. That matters. The machine executing the command owns the approval gate. If you run a build on a separate host, the permissions and allowlist belong on that host, not just in your mental model on the Gateway machine.

The docs also separate device pairing from exec approvals. Pairing answers whether the node can connect. Exec approvals answer whether that node may run a shell command. A paired node can still deny system.run with SYSTEM_RUN_DENIED. That is exactly what you want for a tool that can touch files, install packages, or run deployment scripts.

Screen recording and device commands should be treated as capabilities

Some nodes expose screen.record for short mp4 recordings. Availability depends on platform, recordings are clamped to 60 seconds, and microphone capture can be disabled with --no-audio on supported platforms. On iOS and Android, screen and camera style commands are foreground-sensitive and permission-sensitive.

Android nodes can also advertise extra command families when the matching capability is enabled: device status, notifications, photos, contacts, calendar, call logs, SMS search, and motion commands. The important word is “advertise.” Do not assume every Android node has every command. Ask nodes describe, then call only what the node says it can do.

For operators, this creates a useful product pattern. You can design workflows around capabilities instead of device brands. “If this node has camera and notifications, run inspection.” “If this node has system.run and approvals, run build.” “If this node has no location capability, skip location cleanly.” That is much better than writing brittle scripts for one device you happened to test.

A practical troubleshooting ladder

When node tools fail, do not start by changing config. Run the ladder.

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

Healthy signals are simple: the Gateway is up, the node is connected and paired for role node, nodes describe includes the capability you are calling, and exec approvals show the expected mode or allowlist. If canvas.*, camera.*, or screen.* returns NODE_BACKGROUND_UNAVAILABLE, bring the node app to the foreground. If camera returns CAMERA_DISABLED, turn on the user setting. If a permission error appears, fix the OS permission. If system.run is denied, adjust approvals instead of re-pairing the device.

This is the checklist that saves time: pairing, capability, foreground, permission, approval, logs. In that order. Each layer is a different contract.

Design node workflows as trust contracts

The best OpenClaw node workflows are not “give the agent everything.” They are specific trust contracts: this phone can provide a foreground camera snapshot; this Mac can run allowlisted build commands; this Android device can report notifications when the capability is enabled; this location command is off unless the user deliberately turns it on.

That framing is good engineering and good sales. Developers get a clear architecture: one Gateway, many nodes, explicit capabilities. Operators get predictable failure modes instead of haunted automation. Buyers get confidence that the system can reach real devices without turning every device into an unsupervised agent host.

If you remember one thing, remember this: a node extends the Gateway; it does not replace it. Pair it, describe it, check the advertised capabilities, respect foreground and permission gates, and keep exec approvals local to the machine doing the work.

Want the complete guide? Get ClawKit — $9.99