adolf/docs/cli/nodes.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw nodes` (status, pairing, invoke, camera/canvas/screen/location/notify)	You're managing paired nodes (cameras, screen, canvas) You need to approve requests or invoke node commands	Nodes

openclaw nodes

Manage paired nodes (devices) and invoke node capabilities.

Related: Nodes overview - Camera nodes - Image nodes

Common options on every subcommand: --url <url>, --token <token>, --timeout <ms> (default 10000), --json.

Status

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

status and list both accept --connected (only connected nodes) and --last-connected <duration> (e.g. 24h, 7d; only nodes that connected within the duration). list shows pending and paired nodes in separate tables, with paired rows including the most recent connect age (Last Connect); status shows one merged table with per-node capability and version detail. describe prints one node's capabilities, permissions, and effective/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 drive the gateway-owned node.pair.* store, separate from device pairing (openclaw devices approve) that gates the node's WS connect handshake. See Nodes for how the two relate.

• remove revokes the node's paired-role entry. For a device-backed node this revokes the node role in the device pairing store and disconnects its node-role sessions: a mixed-role device keeps its row and only loses the node role, a node-only device row is deleted. It also clears any matching legacy gateway-owned node pairing record.
• pending only needs operator.pairing scope.
• gateway.nodes.pairing.autoApproveCidrs can skip the pending step for explicitly trusted, first-time role: node device pairing. Off by default; does not approve role upgrades.
• approve scope requirements follow the pending request's declared commands:
  • commandless request: operator.pairing
  • non-exec node commands: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin
• remove scope: operator.pairing can remove non-operator node rows; a device-token caller revoking its own node role on a mixed-role device additionally needs operator.admin.

Invoke

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

Flags:

• --command <command> (required): e.g. canvas.eval.
• --params <json>: JSON object string (default {}).
• --invoke-timeout <ms>: node invoke timeout (default 15000).
• --idempotency-key <key>: optional idempotency key.

system.run and system.run.prepare are blocked here; use the exec tool with host=node for shell execution instead. system.which is allowed through 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

• notify sends a local notification on a node (macOS only). Requires --title or --body. Options: --sound <name>, --priority <passive|active|timeSensitive>, --delivery <system|overlay|auto> (default system), --invoke-timeout <ms> (default 15000).
• push sends an APNs test push to an iOS node. Options: --title <text> (default OpenClaw), --body <text>, --environment <sandbox|production> to override the detected APNs environment.
• location get fetches the node's current location. Options: --max-age <ms> (reuse a cached fix), --accuracy <coarse|balanced|precise>, --location-timeout <ms> (default 10000), --invoke-timeout <ms> (default 20000).
• screen record captures a short clip and prints the saved path (or writes JSON with --json). Options: --screen <index> (default 0), --duration <ms|10s> (default 10000), --fps <fps> (default 10), --no-audio, --out <path>, --invoke-timeout <ms> (default 120000).

Camera and Canvas commands have their own docs: Camera nodes, Canvas. Canvas is implemented by the bundled experimental Canvas plugin; core keeps openclaw nodes canvas as a compatibility mount point.

Related

• CLI reference
• Nodes