OpenClaw Nodes CLI Reference

`openclaw nodes`

Handle paired nodes (devices) and trigger their capabilities.

Every subcommand shares these flags: --url <url>, --token <token>, --timeout <ms> (each command picks its own default), --json.

Status

openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
openclaw nodes list
openclaw nodes describe --node <idOrNameOrIp>

Both status and list take --connected (restricts to connected nodes) or --last-connected <duration> (for instance 24h, 7d; only nodes that connected within that window). With list, pending and paired nodes appear in separate tables, and paired rows show the age of the most recent connection under Last Connect; status merges everything into one table, adding per-node capability, version, and last-input details. A connected macOS node only reports last input once the user turns on Active computer detection and grants Accessibility; the newest entry gets flagged active. Check Active computer presence for details. Running describe outputs a single node's capabilities, permissions, activity, and effective or pending invoke commands.

Pairing

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name <displayName>

These commands operate on the gateway-owned node.pair.* store, which is separate from device pairing (openclaw devices approve) that controls the node's WS connect handshake. See Nodes for how the two interact.

remove removes the node's paired-role entry. For a device-backed node, this drops the node role from the device pairing store and terminates its node-role sessions: a mixed-role device keeps its row but loses only the node role, while a node-only device row gets deleted. Any matching legacy gateway-owned node pairing record is also cleared.
pending requires only the operator.pairing scope.
gateway.nodes.pairing.autoApproveCidrs may bypass the pending step for explicitly trusted, first-time role: node device pairing. Disabled by default; role upgrades are never auto-approved.
gateway.nodes.pairing.sshVerify (enabled by default) automatically approves first-time role: node device pairing when the gateway can verify the device key over SSH to the node host; the initial capability surface is approved in that same step. Refer to Node pairing.
approve scope needs depend on the commands declared in the pending request:
- no commands: operator.pairing
- standard node commands: operator.pairing + operator.write
- admin-sensitive commands (system.run, system.run.prepare, system.which, browser.proxy, browser.proxy.upload.v1, fs.listDir, and system.execApprovals.get/set): operator.pairing + operator.admin
Those needs classify node commands relayed through node.invoke. The top-level Gateway fs.listDir RPC calls for operator.write when browsing hosts inside the workspace and operator.admin if nodeId is set.
remove scope: operator.pairing can delete non-operator node rows; a device-token caller revoking its own node role on a mixed-role device also needs operator.admin.

Invoke

openclaw nodes invoke --node <id> --command system.which --params '{"bins":["uname"]}'

Flags:

--command <command> (mandatory): for instance, device.info.
--params <json>: a JSON object string, with {} as the default.
--invoke-timeout <ms>: timeout for node invocation, defaulting to 15000.
--timeout <ms>: Gateway transport timeout, defaulting to 30000.
--idempotency-key <key>: an optional key for idempotency.

Within this context, system.run and system.run.prepare are disallowed; instead, turn to the exec tool paired with host=node when shell execution is needed. system.which remains permitted via invoke.

Notify, push, location, screen

openclaw nodes notify --node <id> --title "Build" --body "Done" --priority timeSensitive
openclaw nodes push --node <id> --title "OpenClaw" --environment sandbox
openclaw nodes location get --node <id> --accuracy precise
openclaw nodes screen record --node <id> --duration 10s --fps 10 --out ./clip.mp4

With notify, a local notification gets delivered to any node advertising system.notify, covering macOS, iOS, Android, and watchOS nodes connected directly. For direct watchOS delivery, OpenClaw must be running. Access requires either --title or --body. Available options: --sound <name>, --priority <passive|active|timeSensitive>, --delivery <system|overlay|auto> (set to system by default), and --invoke-timeout <ms> (set to 15000 by default).
An APNs test push is sent to an iOS node through push. Options include --title <text> (defaulting to OpenClaw), --body <text>, and --environment <sandbox|production>, which overrides the automatically detected APNs environment. Accepted deliveries exit with code 0; when APNs returns a typed rejection, the full text or JSON diagnostic is preserved and the exit code is non-zero.
The node's current position is retrieved by location get. Options: --max-age <ms> (reuse a cached fix), --accuracy <coarse|balanced|precise>, --location-timeout <ms> (default 10000), and --invoke-timeout <ms> (default 20000).
A brief clip is recorded by screen record, which then prints the destination path, or writes JSON when --json is supplied. Options: --screen <index> (default 0), --duration <ms|10s> (default 10000), --fps <fps> (default 10), --no-audio, --out <path>, and --invoke-timeout <ms> (default 120000).
Explicit screen output paths are placed in a staging area next to the target and swapped in only once the write completes fully; if the write fails, any pre-existing file stays untouched.

Separate documentation covers camera and macOS widget-panel commands: Camera nodes, Widget panel. The bundled experimental Canvas plugin registers openclaw nodes canvas along with the remaining present, hide, and navigate subcommands.