Neura Market Logo

openclaw nodes CLI reference: manage paired devices and trigger capabilities

Reference for the openclaw nodes command: status, pairing, invoke, and capabilities for camera, canvas, screen, location, and notify. For developers and operators managing node devices.

Read this when

  • You're managing paired nodes (cameras, screen, canvas)
  • You need to approve requests or invoke node commands

openclaw nodes

Manage devices that are paired as nodes and trigger their capabilities.

See also: Nodes overview, Active computer presence, Camera nodes, Image nodes

Every subcommand shares these flags: --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>

Both status and list accept --connected (limits to currently connected nodes) and --last-connected <duration> (for example 24h, 7d; only nodes that established a connection inside the given window). list displays pending and paired nodes as separate tables, where paired rows show the time since their most recent connection (Last Connect); status presents a single combined table with each node's capabilities, version, and last input information. On a macOS node that is connected, last input is reported only after the user turns on Active computer detection and grants Accessibility; the most recent row is flagged with active. Refer to Active computer presence. describe outputs a single node's capabilities, permissions, activity, and both effective and 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 operations manage the gateway-owned node.pair.* store, which is distinct from device pairing (openclaw devices approve) that controls the node's WS connect handshake. For an explanation of how the two interact, see [Nodes](/nodes.

  • remove removes the node's paired role entry. For a device-backed node this deletes the node role from the device pairing store and terminates its node role sessions: a mixed-role device keeps its row and only loses the node role, while a node-only device row is removed entirely. It also deletes any corresponding legacy gateway-owned node pairing record.
  • pending requires only operator.pairing scope.
  • gateway.nodes.pairing.autoApproveCidrs can bypass the pending stage for explicitly trusted, first-time role: node device pairing. Disabled by default; does not authorize role upgrades.
  • 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 first capability surface is approved at the same time. See Node pairing.
  • approve scope requirements depend on the commands declared in the pending request:
    • request without commands: operator.pairing
    • standard node commands: operator.pairing + operator.write
    • admin-sensitive commands (system.run, system.run.prepare, system.which, browser.proxy, fs.listDir, and system.execApprovals.get/set): operator.pairing + operator.admin
  • remove scope: operator.pairing can delete node rows that are not operator owned; 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 canvas.eval.
  • --params <json>: a string representing a JSON object, with {} as the default.
  • --invoke-timeout <ms>: the timeout period for node invocations, defaulting to 15000.
  • --idempotency-key <key>: an optional key for idempotency.

Within this context, system.run and system.run.prepare are not permitted; to run shell commands, use the exec tool together with host=node. However, system.which is 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
  • notify triggers a local notification on a node that has system.notify declared, covering macOS, iOS, Android, and direct watchOS nodes. For direct watchOS delivery, OpenClaw must be running. This requires either --title or --body. Configurable options: --sound <name>, --priority <passive|active|timeSensitive>, --delivery <system|overlay|auto> (system by default), --invoke-timeout <ms> (15000 by default).
  • push sends a test push notification via APNs to an iOS node. Options include: --title <text> (defaults to OpenClaw), --body <text>, and --environment <sandbox|production> for manually specifying the APNs environment.
  • location get retrieves the node's current geographical position. Options: --max-age <ms> (uses a previously cached fix), --accuracy <coarse|balanced|precise>, --location-timeout <ms> (10000 is the default), --invoke-timeout <ms> (20000 is the default).
  • screen record records a brief video clip and outputs the file path, or writes JSON when --json is used. Options: --screen <index> (default 0), --duration <ms|10s> (default 10000), --fps <fps> (default 10), --no-audio, --out <path>, --invoke-timeout <ms> (default 120000).

Separate documentation exists for Camera and Canvas commands: refer to Camera nodes and Canvas. Canvas functionality is provided by the bundled experimental Canvas plugin; the core retains openclaw nodes canvas as a compatibility mount point.