OpenClaw Nodes: Pairing, Permissions, and Troubleshooting

The inspected Gateway remembered three paired OpenClaw node records. Two were approved and still advertised browser, file, and system command metadata. None was connected. The pending queue was empty.

That is the state operators routinely misread: paired is not the same as usable. Pairing says the Gateway recognizes an identity and its approved role. A successful tool call also needs a live transport, an advertised command, Gateway policy, device state, OS permission, and sometimes a separate exec approval.

I reproduced the distinction on OpenClaw 2026.7.1-2 with nodes list, nodes status, nodes pending, and nodes describe. No pairing, permission, command policy, or remote device state was changed during the inspection.

Paired was true; usable was false

The first four commands produced a compact contradiction:

openclaw config validate --json
openclaw nodes list --json
openclaw nodes status --json
openclaw nodes pending --json

Configuration validation passed without warnings. The node inventory contained three paired records, two with approvalState: "approved", and zero with connected: true. nodes pending returned an empty array. Several records also shared one display name, so the friendly name was not a safe selector or a proof of identity.

nodes describe on one approved record still returned its last advertised command surface—browser.proxy, system.run, system.run.prepare, and system.which—while also reporting connected: false. That metadata is valuable for diagnosis, but it is not a live capability test.

A node row is an inventory record. Treat connected as reachability, commands as the advertised surface, and approval state as historical authorization. Do not collapse them into one green badge.

Requirements for one successful node call

The official troubleshooting guide describes three gates: device pairing, Gateway node-command policy, and exec approvals. Real camera, screen, location, and computer-control calls add two device-side conditions, while every call depends on a live connection. The useful mental model is therefore an intersection, not a sequence that pairing completes forever.

This separation explains why “remove and pair again” is often the wrong first repair. Re-pairing can repair identity or an approved command-surface update. It cannot foreground an app, grant Screen Recording, connect a sleeping machine, or fix an exec allowlist miss.

Pairing has two stores for different jobs

Current OpenClaw documentation makes a distinction that older runbooks often miss. Device pairing authenticates the signed identity and grants the node role. A separate Gateway-owned node pairing store remembers the approved command and capability surface across reconnects.

The second store does not authenticate transport. Likewise, rotating a device token cannot silently upgrade the role or command authority that an operator never approved. If a reconnecting node changes its role, scopes, public key, or declared command surface, the Gateway can supersede the pending request and issue a new request ID.

This matters operationally in two places:

• Pending approvals expire. A request expires five minutes after the device stops retrying. Approve the current request from devices list, not an ID copied from an old terminal.
• Removal is role-aware. Removing a device-backed node revokes its node role and disconnects node-role sessions. A mixed-role device can keep its operator row while losing only node authority.

When several stale records share a display name, use the stable node ID shown by status. Renaming helps humans, but a label is not an authorization primitive.

Capability is negotiated at connection time

A node does not become a universal remote simply because it paired. It advertises capabilities and command IDs when it connects. Platform defaults differ, and plugin-owned commands may remain hidden across version skew until the node upgrades.

OpenClaw 2026.7.1 documents an N-1 protocol window: upgrade the Gateway first, then the nodes. An N-1 node can remain visible while it is upgraded, but commands added by plugins stay unavailable until the node speaks the current protocol. Anything older requires an out-of-band upgrade before reconnecting.

That gives nodes describe a precise role. It is the answer to “what surface did this identity most recently declare?” It is not the answer to “why did my camera call fail?” until status also says connected.

Privacy controls fail closed on the device

Camera, screen, computer-control, and location commands have a second authority boundary: the device owner and operating system. Gateway approval cannot manufacture an OS permission.

For camera capture, the current platform defaults are intentionally uneven. iOS treats a missing Camera setting as enabled, Android fresh installs default the Camera toggle to off, and the macOS companion defaults Allow Camera to off. Android and iOS require the app to be foregrounded for camera work; a background request returns NODE_BACKGROUND_UNAVAILABLE. Missing permissions return a more specific *_PERMISSION_REQUIRED code.

Those failures are not transport flakiness. They identify the boundary that rejected the operation. Retrying the same call in a loop is both noisy and useless. Bring the app forward, enable the feature toggle, or grant the requested OS permission—then retry once.

Privacy-heavy commands such as camera.snap, camera.clip, and screen.record also require explicit Gateway opt-in. A command in denyCommands wins even when it also appears in allowCommands. That precedence is worth testing; it is easier to reason about than relying on a broad allowlist and operator memory.

Remote exec takes a different route

A headless node host can expose system.run, system.run.prepare, and system.which, but raw nodes invoke deliberately does not provide the two run commands. Remote shell work goes through the normal exec tool with host=node.

That route preserves the node’s local approval policy in ~/.openclaw/exec-approvals.json. Pairing approves the node role and declared command family; it does not approve arbitrary shell text. The Gateway prepares a canonical systemRunPlan, binds approval to that request, forwards the stored plan, and rejects later edits to command, working directory, or session metadata.

The trade-off is deliberate friction. A permissive node with broad filesystem and runtime access is convenient, but it moves the side effect onto another machine without reducing responsibility. Allowlist one stable executable or workflow when possible. Use ask mode for exceptions. Treat full mode as a host-level trust decision, not a pairing shortcut.

Troubleshooting by rejecting boundary

A useful error message names the control that said no. Preserve that code before restarting services or deleting state: it tells you whether the next inspection belongs on the Gateway, the transport, the node app, the operating system, or the node host's exec policy.

A five-minute recovery sequence

When a node-backed tool fails, preserve evidence before changing state. The sequence below narrows the fault without capturing media, invoking remote code, or deleting a pairing.

1. Confirm Gateway health and config validity. If the control plane is unhealthy, node symptoms are downstream noise.
2. List status by stable ID. Record paired, connected, approval state, platform, and version. Do not choose among duplicate display names by guess.
3. Describe the intended node. Check that the exact capability and command are advertised. If the node is disconnected, label the result historical.
4. Inspect the relevant policy. For privacy-heavy RPC commands, review Gateway allow/deny policy. For shell execution, read the node-local exec approval.
5. Check device conditions. Foreground mobile apps and verify only the OS permission required for the intended capability.
6. Run one harmless acceptance test. Prefer device.info, device.status, system.which, or a capability list over camera capture or a write operation.

openclaw status
openclaw nodes status
openclaw nodes describe --node <stable-node-id>
openclaw approvals get --node <stable-node-id>
# Then run one low-impact command the node actually advertises.

If the node remains disconnected, repair the service or network path before touching authorization. If it reconnects but advertises the wrong surface, compare versions and the current pairing request. Remove and re-pair only when identity or approved role/command state is the thing you intend to replace.

Proof needs one success and one refusal

A green status row is not the end of node validation. Prove one intended action and one neighboring action that should remain blocked.

• The expected stable node ID is paired and currently connected.
• nodes describe contains only the command families the workload needs.
• A low-impact intended command succeeds through the same agent/tool route used in production.
• A privacy-heavy command outside policy is rejected by Gateway policy.
• A shell command outside the node allowlist is rejected without execution.
• Foreground-only behavior and OS permissions are documented for mobile operators.
• Gateway and node versions stay inside the supported protocol window.
• Stale or duplicate display names are documented or cleaned up by stable ID during a maintenance window.

The inspected inventory was not broken because it contained paired records. It was simply not live: three remembered identities, two approved command surfaces, zero connections. Reading those fields separately turned an ambiguous “node unavailable” symptom into a transport-state diagnosis without revoking a device or widening permissions.

For the adjacent boundaries, see the OpenClaw approvals teardown, the Gateway operating guide, and the security-audit field note. If you want a persistent agent without maintaining remote-node identity, connectivity, and approval state yourself, deploy an AI agent on GolemWorkers.

Documentation behind the node boundary model

• OpenClaw Nodes — device versus node pairing stores, status semantics, version skew, command advertisement, Gateway policy, and node-host execution.
• OpenClaw node troubleshooting — the command ladder, pairing-versus-approval gates, permissions matrix, failure codes, and recovery loop.
• OpenClaw camera capture — platform defaults, foreground requirements, permission errors, and Gateway opt-in for privacy-heavy commands.
• OpenClaw Gateway pairing — device request lifecycle, role approval, expiry, and identity behavior.
• OpenClaw exec approvals — node-local execution policy, allowlist matching, ask mode, and approval binding.