Nodes

A node is a companion device (macOS/iOS/Android/headless) that connects to the Gateway WebSocket (same port as operators) with

and exposes a command surface (e.g. , , , , ) via . Protocol details: Gateway protocol.

Legacy transport: Bridge protocol (TCP JSONL; historical only for current nodes).

macOS can also run in node mode: the menubar app connects to the Gateway’s WS server and exposes its local canvas/camera commands as a node (so

works against this Mac). In remote gateway mode, browser automation is handled by the CLI node host ( or the installed node service), not by the native app node.

Notes:

• Nodes are peripherals, not gateways. They don’t run the gateway service.
• Telegram/WhatsApp/etc. messages land on the gateway, not on nodes.
• Troubleshooting runbook: /nodes/troubleshooting

Pairing + status

WS nodes use device pairing. Nodes present a device identity during

; the Gateway creates a device pairing request for . Approve via the devices CLI (or UI).

Quick CLI:

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

If a node retries with changed auth details (role/scopes/public key), the prior pending request is superseded and a new

is created. Re-run before approving.

Notes:

• text

  Copy

  nodes status
  marks a node as paired when its device pairing role includes
  text

  Copy

  node
  .
• The device pairing record is the durable approved-role contract. Token rotation stays inside that contract; it cannot upgrade a paired node into a different role that pairing approval never granted.
• text

  Copy

  node.pair.*
  (CLI:
  text

  Copy

  openclaw nodes pending/approve/reject/remove/rename
  ) is a separate gateway-owned node pairing store; it does not gate the WS
  text

  Copy

  connect
  handshake.
• text

  Copy

  openclaw nodes remove --node <id|name|ip>
  deletes stale entries from that separate gateway-owned node pairing store.
• Approval scope follows the pending request's declared commands:
  • commandless request:
    text

    Copy

    operator.pairing
  • non-exec node commands:
    text

    Copy

    operator.pairing
    +
    text

    Copy

    operator.write
  • text

    Copy

    system.run
    /
    text

    Copy

    system.run.prepare
    /
    text

    Copy

    system.which
    :
    text

    Copy

    operator.pairing
    +
    text

    Copy

    operator.admin

Remote node host (system.run)

Use a node host when your Gateway runs on one machine and you want commands to execute on another. The model still talks to the gateway; the gateway forwards

calls to the node host when is selected.

What runs where

• Gateway host: receives messages, runs the model, routes tool calls.
• Node host: executes
  text

  Copy

  system.run
  /
  text

  Copy

  system.which
  on the node machine.
• Approvals: enforced on the node host via
  text

  Copy

  ~/.openclaw/exec-approvals.json
  .

Approval note:

• Approval-backed node runs bind exact request context.
• For direct shell/runtime file executions, OpenClaw also best-effort binds one concrete local file operand and denies the run if that file changes before execution.
• If OpenClaw cannot identify exactly one concrete local file for an interpreter/runtime command, approval-backed execution is denied instead of pretending full runtime coverage. Use sandboxing, separate hosts, or an explicit trusted allowlist/full workflow for broader interpreter semantics.

Start a node host (foreground)

On the node machine:

bash
Copy
openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

Remote gateway via SSH tunnel (loopback bind)

If the Gateway binds to loopback (

, default in local mode), remote node hosts cannot connect directly. Create an SSH tunnel and point the node host at the local end of the tunnel.

Example (node host -> gateway host):

bash
Copy
# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Notes:

• text

  Copy

  openclaw node run
  supports token or password auth.
• Env vars are preferred:
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  /
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  .
• Config fallback is
  text

  Copy

  gateway.auth.token
  /
  text

  Copy

  gateway.auth.password
  .
• In local mode, node host intentionally ignores
  text

  Copy

  gateway.remote.token
  /
  text

  Copy

  gateway.remote.password
  .
• In remote mode,
  text

  Copy

  gateway.remote.token
  /
  text

  Copy

  gateway.remote.password
  are eligible per remote precedence rules.
• If active local
  text

  Copy

  gateway.auth.*
  SecretRefs are configured but unresolved, node-host auth fails closed.
• Node-host auth resolution only honors
  text

  Copy

  OPENCLAW_GATEWAY_*
  env vars.

Start a node host (service)

bash
Copy
openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node start
openclaw node restart

Pair + name

On the gateway host:

bash
Copy
openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

If the node retries with changed auth details, re-run

and approve the current .

Naming options:

• text

  Copy

  --display-name
  on
  text

  Copy

  openclaw node run
  /
  text

  Copy

  openclaw node install
  (persists in
  text

  Copy

  ~/.openclaw/node.json
  on the node).
• text

  Copy

  openclaw nodes rename --node <id|name|ip> --name "Build Node"
  (gateway override).

Allowlist the commands

Exec approvals are per node host. Add allowlist entries from the gateway:

bash
Copy
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

Approvals live on the node host at

.

Point exec at the node

Configure defaults (gateway config):

bash
Copy
openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

Or per session:

text
Copy
/exec host=node security=allowlist node=<id-or-name>

Once set, any

call with runs on the node host (subject to the node allowlist/approvals).

will not implicitly choose the node on its own, but an explicit per-call request is allowed from . If you want node exec to be the default for the session, set or explicitly.

Related:

• Node host CLI
• Exec tool
• Exec approvals

Invoking commands

Low-level (raw RPC):

bash
Copy
openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

Higher-level helpers exist for the common “give the agent a MEDIA attachment” workflows.

Command policy

Node commands must pass two gates before they can be invoked:

1. The node must declare the command in its WebSocket
   text

   Copy

   connect.commands
   list.
2. The gateway's platform policy must allow the declared command.

Windows and macOS companion nodes allow safe declared commands such as

, , , and by default. Dangerous or privacy-heavy commands such as , , and still require explicit opt-in with . always wins over defaults and extra allowlist entries.

Plugin-owned node commands can add a Gateway node-invoke policy. That policy runs after the allowlist check and before forwarding to the node, so raw

, CLI helpers, and dedicated agent tools share the same plugin permission boundary. Dangerous plugin node commands still require explicit opt-in.

After a node changes its declared command list, reject the old device pairing and approve the new request so the gateway stores the updated command snapshot.

Screenshots (canvas snapshots)

If the node is showing the Canvas (WebView),

returns .

CLI helper (writes to a temp file and prints

):

bash
Copy
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas controls

bash
Copy
openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Notes:

• text

  Copy

  canvas present
  accepts URLs or local file paths (
  text

  Copy

  --target
  ), plus optional
  text

  Copy

  --x/--y/--width/--height
  for positioning.
• text

  Copy

  canvas eval
  accepts inline JS (
  text

  Copy

  --js
  ) or a positional arg.

A2UI (Canvas)

bash
Copy
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

Notes:

• Only A2UI v0.8 JSONL is supported (v0.9/createSurface is rejected).

Photos + videos (node camera)

Photos (

):

bash
Copy
openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

Video clips (

):

bash
Copy
openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

Notes:

• The node must be foregrounded for
  text

  Copy

  canvas.*
  and
  text

  Copy

  camera.*
  (background calls return
  text

  Copy

  NODE_BACKGROUND_UNAVAILABLE
  ).
• Clip duration is clamped (currently
  text

  Copy

  <= 60s
  ) to avoid oversized base64 payloads.
• Android will prompt for
  text

  Copy

  CAMERA
  /
  text

  Copy

  RECORD_AUDIO
  permissions when possible; denied permissions fail with
  text

  Copy

  *_PERMISSION_REQUIRED
  .

Screen recordings (nodes)

Supported nodes expose

(mp4). Example:

bash
Copy
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

Notes:

• text

  Copy

  screen.record
  availability depends on node platform.
• Screen recordings are clamped to
  text

  Copy

  <= 60s
  .
• text

  Copy

  --no-audio
  disables microphone capture on supported platforms.
• Use
  text

  Copy

  --screen <index>
  to select a display when multiple screens are available.

Location (nodes)

Nodes expose

when Location is enabled in settings.

CLI helper:

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

Notes:

• Location is off by default.
• “Always” requires system permission; background fetch is best-effort.
• The response includes lat/lon, accuracy (meters), and timestamp.

SMS (Android nodes)

Android nodes can expose

when the user grants SMS permission and the device supports telephony.

Low-level invoke:

bash
Copy
openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

Notes:

• The permission prompt must be accepted on the Android device before the capability is advertised.
• Wi-Fi-only devices without telephony will not advertise
  text

  Copy

  sms.send
  .

Android device + personal data commands

Android nodes can advertise additional command families when the corresponding capabilities are enabled.

Available families:

• text

  Copy

  device.status
  ,
  text

  Copy

  device.info
  ,
  text

  Copy

  device.permissions
  ,
  text

  Copy

  device.health
• text

  Copy

  notifications.list
  ,
  text

  Copy

  notifications.actions
• text

  Copy

  photos.latest
• text

  Copy

  contacts.search
  ,
  text

  Copy

  contacts.add
• text

  Copy

  calendar.events
  ,
  text

  Copy

  calendar.add
• text

  Copy

  callLog.search
• text

  Copy

  sms.search
• text

  Copy

  motion.activity
  ,
  text

  Copy

  motion.pedometer

Example invokes:

bash
Copy
openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

Notes:

• Motion commands are capability-gated by available sensors.

System commands (node host / mac node)

The macOS node exposes

, , and . The headless node host exposes , , and .

Examples:

bash
Copy
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

Notes:

• text

  Copy

  system.run
  returns stdout/stderr/exit code in the payload.
• Shell execution now goes through the
  text

  Copy

  exec
  tool with
  text

  Copy

  host=node
  ;
  text

  Copy

  nodes
  remains the direct-RPC surface for explicit node commands.
• text

  Copy

  nodes invoke
  does not expose
  text

  Copy

  system.run
  or
  text

  Copy

  system.run.prepare
  ; those stay on the exec path only.
• The exec path prepares a canonical
  text

  Copy

  systemRunPlan
  before approval. Once an approval is granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields.
• text

  Copy

  system.notify
  respects notification permission state on the macOS app.
• Unrecognized node
  text

  Copy

  platform
  /
  text

  Copy

  deviceFamily
  metadata uses a conservative default allowlist that excludes
  text

  Copy

  system.run
  and
  text

  Copy

  system.which
  . If you intentionally need those commands for an unknown platform, add them explicitly via
  text

  Copy

  gateway.nodes.allowCommands
  .
• text

  Copy

  system.run
  supports
  text

  Copy

  --cwd
  ,
  text

  Copy

  --env KEY=VAL
  ,
  text

  Copy

  --command-timeout
  , and
  text

  Copy

  --needs-screen-recording
  .
• For shell wrappers (
  text

  Copy

  bash|sh|zsh ... -c/-lc
  ), request-scoped
  text

  Copy

  --env
  values are reduced to an explicit allowlist (
  text

  Copy

  TERM
  ,
  text

  Copy

  LANG
  ,
  text

  Copy

  LC_*
  ,
  text

  Copy

  COLORTERM
  ,
  text

  Copy

  NO_COLOR
  ,
  text

  Copy

  FORCE_COLOR
  ).
• For allow-always decisions in allowlist mode, known dispatch wrappers (
  text

  Copy

  env
  ,
  text

  Copy

  nice
  ,
  text

  Copy

  nohup
  ,
  text

  Copy

  stdbuf
  ,
  text

  Copy

  timeout
  ) persist inner executable paths instead of wrapper paths. If unwrapping is not safe, no allowlist entry is persisted automatically.
• On Windows node hosts in allowlist mode, shell-wrapper runs via
  text

  Copy

  cmd.exe /c
  require approval (allowlist entry alone does not auto-allow the wrapper form).
• text

  Copy

  system.notify
  supports
  text

  Copy

  --priority <passive|active|timeSensitive>
  and
  text

  Copy

  --delivery <system|overlay|auto>
  .
• Node hosts ignore
  text

  Copy

  PATH
  overrides and strip dangerous startup/shell keys (
  text

  Copy

  DYLD_*
  ,
  text

  Copy

  LD_*
  ,
  text

  Copy

  NODE_OPTIONS
  ,
  text

  Copy

  PYTHON*
  ,
  text

  Copy

  PERL*
  ,
  text

  Copy

  RUBYOPT
  ,
  text

  Copy

  SHELLOPTS
  ,
  text

  Copy

  PS4
  ). If you need extra PATH entries, configure the node host service environment (or install tools in standard locations) instead of passing
  text

  Copy

  PATH
  via
  text

  Copy

  --env
  .
• On macOS node mode,
  text

  Copy

  system.run
  is gated by exec approvals in the macOS app (Settings → Exec approvals). Ask/allowlist/full behave the same as the headless node host; denied prompts return
  text

  Copy

  SYSTEM_RUN_DENIED
  .
• On headless node host,
  text

  Copy

  system.run
  is gated by exec approvals (
  text

  Copy

  ~/.openclaw/exec-approvals.json
  ).

Exec node binding

When multiple nodes are available, you can bind exec to a specific node. This sets the default node for

(and can be overridden per agent).

Global default:

bash
Copy
openclaw config set tools.exec.node "node-id-or-name"

Per-agent override:

bash
Copy
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Unset to allow any node:

bash
Copy
openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

Permissions map

Nodes may include a

map in / , keyed by permission name (e.g. , ) with boolean values ( = granted).

Headless node host (cross-platform)

OpenClaw can run a headless node host (no UI) that connects to the Gateway WebSocket and exposes

/ . This is useful on Linux/Windows or for running a minimal node alongside a server.

Start it:

bash
Copy
openclaw node run --host <gateway-host> --port 18789

Notes:

• Pairing is still required (the Gateway will show a device pairing prompt).
• The node host stores its node id, token, display name, and gateway connection info in
  text

  Copy

  ~/.openclaw/node.json
  .
• Exec approvals are enforced locally via
  text

  Copy

  ~/.openclaw/exec-approvals.json
  (see Exec approvals).
• On macOS, the headless node host executes
  text

  Copy

  system.run
  locally by default. Set
  text

  Copy

  OPENCLAW_NODE_EXEC_HOST=app
  to route
  text

  Copy

  system.run
  through the companion app exec host; add
  text

  Copy

  OPENCLAW_NODE_EXEC_FALLBACK=0
  to require the app host and fail closed if it is unavailable.
• Add
  text

  Copy

  --tls
  /
  text

  Copy

  --tls-fingerprint
  when the Gateway WS uses TLS.

Mac node mode

• The macOS menubar app connects to the Gateway WS server as a node (so
  text

  Copy

  openclaw nodes …
  works against this Mac).
• In remote mode, the app opens an SSH tunnel for the Gateway port and connects to
  text

  Copy

  localhost
  .