> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Nodes A **node** is a companion device (macOS/iOS/Android/headless) that connects to the Gateway **WebSocket** (same port as operators) with `role: "node"` and exposes a command surface (e.g. `canvas.*`, `camera.*`, `device.*`, `notifications.*`, `system.*`) via `node.invoke`. Protocol details: [Gateway protocol](/gateway/protocol). Legacy transport: [Bridge protocol](/gateway/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 `openclaw nodes …` works against this Mac). In remote gateway mode, browser automation is handled by the CLI node host (`openclaw node run` or the installed node service), not by the native app node. Nodes are **peripherals**, not gateways: they don't run the gateway service, and channel messages (Telegram, WhatsApp, etc.) land on the gateway, not on nodes. Troubleshooting runbook: [/nodes/troubleshooting](/nodes/troubleshooting) ## Pairing + status WS nodes use **device pairing**. A node presents a device identity during `connect`; the Gateway creates a device pairing request for `role: node`. Approve via the devices CLI (or UI). ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices list openclaw devices approve openclaw devices reject openclaw nodes status openclaw nodes describe --node ``` Pending pairing requests expire 5 minutes after the device's last retry — a device that keeps reconnecting keeps its one pending request (and `requestId`) alive instead of minting a new prompt every few minutes; see [Gateway-owned pairing](/gateway/pairing) for the full request/approve/token lifecycle. If a node retries with changed auth details (role/scopes/public key), the prior pending request is superseded and a new `requestId` is created — clients get a `device.pair.resolved` event for the superseded request, and you should re-run `openclaw devices list` before approving. * `nodes status` marks a node as **paired** when its device pairing role includes `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 role that pairing approval never granted. * `node.pair.*` (CLI: `openclaw nodes pending/approve/reject/remove/rename`) is a separate, gateway-owned node pairing store that tracks the node's approved command/capability surface across reconnects. It does **not** gate the WS `connect` handshake — device pairing does that. * `openclaw nodes remove --node ` removes a node pairing. For a device-backed node it revokes the device's `node` role in `devices/paired.json` and disconnects that device's node-role sessions: a mixed-role device keeps its row and only loses the `node` role, while a node-only device row is deleted. It also clears any matching entry from the separate node pairing store. `operator.pairing` may remove non-operator node rows on other devices; a device-token caller revoking its own node role on a mixed-role device additionally needs `operator.admin`. * Approval scope follows 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` ## Version skew and upgrade order The Gateway accepts authenticated node clients across an N-1 protocol window. The current v4 Gateway therefore accepts v3 nodes when the connection declares both `role: "node"` and `client.mode: "node"`. Operator and UI sessions must still use the current protocol. For staged fleet upgrades, upgrade the Gateway first, then upgrade each node. An N-1 node remains visible and manageable while it is upgraded; the Gateway logs `legacy node protocol accepted` with an upgrade recommendation. Pairing, device authentication, command allowlists, and exec approvals still apply. Plugin-owned capabilities and commands stay hidden until the node upgrades to the current protocol. Nodes older than N-1 require an out-of-band upgrade before reconnecting. ## 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 `exec` calls to the **node host** when `host=node` is selected. | Role | Responsibility | | ------------ | ---------------------------------------------------------------- | | Gateway host | Receives messages, runs the model, routes tool calls. | | Node host | Executes `system.run`/`system.which` on the node machine. | | Approvals | Enforced on the node host via `~/.openclaw/exec-approvals.json`. | Approval note: * Approval-backed node runs bind exact request context. The exec path prepares a canonical `systemRunPlan` before approval; once granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields, and re-validates the working directory before running. * 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw node run --host --port 18789 --display-name "Build Node" ``` `node run` also accepts `--context-path` (Gateway WS context path), `--tls`, `--tls-fingerprint `, and `--node-id` (overriding it clears the pairing token). ### Remote gateway via SSH tunnel (loopback bind) If the Gateway binds to loopback (`gateway.bind=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 theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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="" openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node" ``` Notes: * `openclaw node run` supports token or password auth. * Env vars are preferred: `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`. * Config fallback is `gateway.auth.token` / `gateway.auth.password`. * In local mode, node host intentionally ignores `gateway.remote.token` / `gateway.remote.password`. * In remote mode, `gateway.remote.token` / `gateway.remote.password` are eligible per remote precedence rules. * If active local `gateway.auth.*` SecretRefs are configured but unresolved, node-host auth fails closed. * Node-host auth resolution only honors `OPENCLAW_GATEWAY_*` env vars. ### Start a node host (service) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw node install --host --port 18789 --display-name "Build Node" openclaw node start openclaw node restart ``` `node install` also accepts `--context-path`, `--tls`, `--tls-fingerprint`, `--node-id`, `--runtime ` (default: node), and `--force` to reinstall. `node status`, `node stop`, and `node uninstall` are also available. ### Pair + name On the gateway host: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw devices list openclaw devices approve openclaw nodes status ``` If the node retries with changed auth details, re-run `openclaw devices list` and approve the current `requestId`. Naming options: * `--display-name` on `openclaw node run` / `openclaw node install` (persists in `~/.openclaw/node.json` on the node, alongside the node id, token, and gateway connection info). * `openclaw nodes rename --node --name "Build Node"` (gateway override). ### Allowlist the commands Exec approvals are **per node host**. Add allowlist entries from the gateway: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw approvals allowlist add --node "/usr/bin/uname" openclaw approvals allowlist add --node "/usr/bin/sw_vers" ``` Approvals live on the node host at `~/.openclaw/exec-approvals.json`. ### Point exec at the node Configure defaults (gateway config): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set tools.exec.host node openclaw config set tools.exec.security allowlist openclaw config set tools.exec.node "" ``` Or per session: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /exec host=node security=allowlist node= ``` Once set, any `exec` call with `host=node` runs on the node host (subject to the node allowlist/approvals). `host=auto` will not implicitly choose the node on its own, but an explicit per-call `host=node` request is allowed from `auto`. If you want node exec to be the default for the session, set `tools.exec.host=node` or `/exec host=node ...` explicitly. Related: * [Node host CLI](/cli/node) * [Exec tool](/tools/exec) * [Exec approvals](/tools/exec-approvals) ### Local model inference A desktop or server node can expose chat-capable models from an Ollama server running on that node. Agents use the Ollama plugin's `node_inference` tool to discover installed models and run a bounded prompt remotely; the Gateway does not need direct network access to Ollama. See [Ollama node-local inference](/providers/ollama#node-local-inference) for setup, model filtering, and direct verification commands. ## Invoking commands Low-level (raw RPC): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes invoke --node --command canvas.eval --params '{"javaScript":"location.href"}' ``` `nodes invoke` blocks `system.run` and `system.run.prepare`; those commands only run through the `exec` tool with `host=node` (see above). Higher-level helpers exist for the common "give the agent a MEDIA attachment" workflows (canvas, camera, screen, location, below). ## Command policy Node commands must pass two gates before they can be invoked: 1. The node must declare the command in its WebSocket `connect.commands` list. 2. The gateway's platform-and-approval-derived allowlist must include the declared command. Default allowlists by platform (before plugin defaults and `allowCommands`/`denyCommands` overrides): | Platform | Commands allowed by default | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iOS | `camera.list`, `location.get`, `device.info`, `device.status`, `contacts.search`, `calendar.events`, `reminders.list`, `photos.latest`, `motion.activity`, `motion.pedometer`, `system.notify` | | Android | `camera.list`, `location.get`, `notifications.list`, `notifications.actions`, `system.notify`, `device.info`, `device.status`, `device.permissions`, `device.health`, `device.apps`, `contacts.search`, `calendar.events`, `callLog.search`, `reminders.list`, `photos.latest`, `motion.activity`, `motion.pedometer` | | macOS | `camera.list`, `location.get`, `device.info`, `device.status`, `contacts.search`, `calendar.events`, `reminders.list`, `photos.latest`, `motion.activity`, `motion.pedometer`, `system.notify` | | Windows | `camera.list`, `location.get`, `device.info`, `device.status`, `system.notify` | | Linux | `system.notify` (node host commands like `system.run` are approval-gated, see below) | `canvas.*` commands (`canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`) are a plugin default on iOS, Android, macOS, Windows, and unknown platforms (not Linux); all of them are foreground-restricted on iOS. `talk.ptt.start`, `talk.ptt.stop`, `talk.ptt.cancel`, and `talk.ptt.once` are allowed by default for any node that advertises the `talk` capability or declares `talk.*` commands, independent of platform label. Desktop host commands (`system.run`, `system.run.prepare`, `system.which`, `browser.proxy`, `screen.snapshot` on macOS/Windows) are not part of the static platform-default table above. They become available once the operator approves a pairing request that declares them, after which the node's approved command set carries them forward on reconnect. Dangerous or privacy-heavy commands still require explicit opt-in with `gateway.nodes.allowCommands`, even if a node declares them: `camera.snap`, `camera.clip`, `screen.record`, `contacts.add`, `calendar.add`, `reminders.add`, `sms.send`, `sms.search`. `gateway.nodes.denyCommands` 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 `node.invoke`, CLI helpers, and dedicated agent tools share the same plugin permission boundary. Dangerous plugin node commands still require explicit `gateway.nodes.allowCommands` 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. ## Config (`openclaw.json`) Node-related settings live under `gateway.nodes` and `tools.exec`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { nodes: { // Auto-approve first-time node pairing from trusted networks (CIDR list). // Disabled when unset. Only applies to first-time role:node requests // with no requested scopes; does not auto-approve upgrades. pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, // Opt into dangerous/privacy-heavy node commands (camera.snap, etc.). allowCommands: ["camera.snap", "screen.record"], // Block exact command names even if defaults or allowCommands include them. denyCommands: ["camera.clip"], }, }, tools: { exec: { // Default exec host: "node" routes all exec calls to a paired node. host: "node", // Security mode for node exec: allow only approved/allowlisted commands. security: "allowlist", // Pin exec to a specific node (id or name). Omit to allow any node. node: "build-node", }, }, } ``` Use exact node command names. `denyCommands` removes a command even when a platform default or `allowCommands` entry would otherwise allow it. See [Gateway configuration reference](/gateway/configuration-reference#gateway) for gateway node pairing and command-policy field details. Per-agent exec node override: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "main", tools: { exec: { node: "build-node" } }, }, ], }, } ``` ## Screenshots (canvas snapshots) If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format, base64 }`. CLI helper (writes to a temp file and prints the saved path): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes canvas snapshot --node --format png openclaw nodes canvas snapshot --node --format jpg --max-width 1200 --quality 0.9 ``` ### Canvas controls ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes canvas present --node --target https://example.com openclaw nodes canvas hide --node openclaw nodes canvas navigate https://example.com --node openclaw nodes canvas eval --node --js "document.title" ``` Notes: * `canvas present` accepts URLs or local file paths (`--target`), plus optional `--x/--y/--width/--height` for positioning. * `canvas eval` accepts inline JS (`--js`) or a positional arg. ### A2UI (Canvas) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes canvas a2ui push --node --text "Hello" openclaw nodes canvas a2ui push --node --jsonl ./payload.jsonl openclaw nodes canvas a2ui reset --node ``` Notes: * Mobile nodes use a bundled app-owned A2UI page for action-capable rendering. * Only A2UI v0.8 JSONL is supported (v0.9/createSurface is rejected). * iOS and Android render remote Gateway Canvas pages, but A2UI button actions are dispatched only from the bundled app-owned A2UI page. Gateway-hosted HTTP/HTTPS A2UI pages are render-only on those mobile clients. ## Photos + videos (node camera) Photos (`jpg`): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes camera list --node openclaw nodes camera snap --node # default: both facings (2 MEDIA lines) openclaw nodes camera snap --node --facing front openclaw nodes camera snap --node --device-id --max-width 1200 --quality 0.9 --delay-ms 2000 ``` Video clips (`mp4`): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes camera clip --node --duration 10s openclaw nodes camera clip --node --duration 3000 --no-audio ``` Notes: * The node must be **foregrounded** for `canvas.*` and `camera.*` (background calls return `NODE_BACKGROUND_UNAVAILABLE`). * Nodes clamp clip duration to keep the base64 payload manageable (see [Camera capture](/nodes/camera) for exact per-platform limits). The `nodes` agent tool additionally caps requested `durationMs` at 300000 (5 minutes) before forwarding the call; the node itself enforces the tighter limit. * Android will prompt for `CAMERA`/`RECORD_AUDIO` permissions when possible; denied permissions fail with `*_PERMISSION_REQUIRED`. ## Screen recordings (nodes) Supported nodes expose `screen.record` (mp4). Example: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes screen record --node --duration 10s --fps 10 openclaw nodes screen record --node --duration 10s --fps 10 --no-audio ``` Notes: * `screen.record` availability depends on node platform. * The `nodes` agent tool caps requested `durationMs` at 300000 (5 minutes); the node may enforce a tighter limit to bound the returned payload. * `--no-audio` disables microphone capture on supported platforms. * Use `--screen ` to select a display when multiple screens are available (0 = primary). ## Location (nodes) Nodes expose `location.get` when Location is enabled in settings. CLI helper: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes location get --node openclaw nodes location get --node --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. * Full parameter/response shape and error codes: [Location command](/nodes/location-command). ## SMS (Android nodes) Android nodes can expose `sms.send` and `sms.search` when the user grants **SMS** permission and the device supports telephony. Both commands are dangerous-by-default: the gateway operator must also add them to `gateway.nodes.allowCommands` before they can be invoked (see [Command policy](#command-policy)). For read-only SMS search, opt in explicitly in `openclaw.json`: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { nodes: { allowCommands: ["sms.search"], }, }, } ``` Add `sms.send` separately only when the node should also be able to send messages. Android permission and Gateway command authorization are independent; granting the phone permission does not edit Gateway policy. Low-level invoke: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes invoke --node --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}' ``` Notes: * `sms.search` may be declared before `READ_SMS` is granted so an invocation can return a permission diagnostic; reading messages still requires that Android permission. * Wi-Fi-only devices without telephony will not advertise `sms.send`. * A `requires explicit gateway.nodes.allowCommands opt-in` error means the phone declared the command but the Gateway operator has not authorized it. ## Device and personal data commands iOS, Android, and macOS nodes advertise several read-only data commands by default (see the [Command policy](#command-policy) table); Android additionally exposes a larger family gated by its own in-app settings. Available families: * `device.status`, `device.info` — iOS, Android, macOS, Windows. * `device.permissions`, `device.health`, `device.apps` — Android only; `device.apps` requires Installed Apps sharing enabled in Android Settings and returns launcher-visible apps by default. * `notifications.list`, `notifications.actions` — Android only. * `photos.latest` — iOS, Android, macOS. * `contacts.search` — iOS, Android, macOS (read-only default); `contacts.add` is dangerous and needs `gateway.nodes.allowCommands`. * `calendar.events` — iOS, Android, macOS (read-only default); `calendar.add` is dangerous and needs `gateway.nodes.allowCommands`. * `reminders.list` — iOS, Android, macOS (read-only default); `reminders.add` is dangerous and needs `gateway.nodes.allowCommands`. * `callLog.search` — Android only. * `motion.activity`, `motion.pedometer` — iOS, Android, macOS; capability-gated by available sensors. Example invokes: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes invoke --node --command device.status --params '{}' openclaw nodes invoke --node --command device.apps --params '{"limit":10}' openclaw nodes invoke --node --command notifications.list --params '{}' openclaw nodes invoke --node --command photos.latest --params '{"limit":1}' ``` ## System commands (node host / mac node) The macOS node exposes `system.run`, `system.notify`, and `system.execApprovals.get/set`. The headless node host exposes `system.run`, `system.which`, and `system.execApprovals.get/set`. Examples: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw nodes notify --node --title "Ping" --body "Gateway ready" openclaw nodes invoke --node --command system.which --params '{"name":"git"}' ``` Notes: * `system.run` returns stdout/stderr/exit code in the payload. * Shell execution now goes through the `exec` tool with `host=node`; `nodes` remains the direct-RPC surface for explicit node commands. * `nodes invoke` does not expose `system.run` or `system.run.prepare`; those stay on the exec path only. * The exec path prepares a canonical `systemRunPlan` before approval. Once an approval is granted, the gateway forwards that stored plan, not any later caller-edited command/cwd/session fields. * `system.notify` respects notification permission state on the macOS app; supports `--priority ` and `--delivery `. * Unrecognized node `platform` / `deviceFamily` metadata uses a conservative default allowlist that excludes `system.run` and `system.which`. If you intentionally need those commands for an unknown platform, add them explicitly via `gateway.nodes.allowCommands`. * `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`. * For shell wrappers (`bash|sh|zsh ... -c/-lc`), request-scoped `--env` values are reduced to an explicit allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). * For allow-always decisions in allowlist mode, known dispatch wrappers (`env`, `flock`, `nice`, `nohup`, `stdbuf`, `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 `cmd.exe /c` require approval (allowlist entry alone does not auto-allow the wrapper form). * Node hosts ignore `PATH` overrides in `--env` and strip a large, maintained set of interpreter/shell startup variables (for example `NODE_OPTIONS`, `PYTHONPATH`, `BASH_ENV`, `DYLD_*`, `LD_*`) before running a command. If you need extra PATH entries, configure the node host service environment (or install tools in standard locations) instead of passing `PATH` via `--env`. * On macOS node mode, `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 `SYSTEM_RUN_DENIED`. * On headless node host, `system.run` is gated by exec approvals (`~/.openclaw/exec-approvals.json`); on macOS specifically, see the exec-host routing env vars under [Headless node host](#headless-node-host-cross-platform) below. ## Exec node binding When multiple nodes are available, you can bind exec to a specific node. This sets the default node for `exec host=node` (and can be overridden per agent). Global default: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config set tools.exec.node "node-id-or-name" ``` Per-agent override: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config get agents.list openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name" ``` Unset to allow any node: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw config unset tools.exec.node openclaw config unset 'agents.list[0].tools.exec.node' ``` ## Permissions map Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by permission name (e.g. `screenRecording`, `accessibility`, `location`) with boolean values (`true` = granted). ## Headless node host (cross-platform) OpenClaw can run a **headless node host** (no UI) that connects to the Gateway WebSocket and exposes `system.run` / `system.which`. This is useful on Linux/Windows or for running a minimal node alongside a server. Start it: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw node run --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 `~/.openclaw/node.json`. * Exec approvals are enforced locally via `~/.openclaw/exec-approvals.json` (see [Exec approvals](/tools/exec-approvals)). * On macOS, the headless node host executes `system.run` locally by default. Set `OPENCLAW_NODE_EXEC_HOST=app` to route `system.run` through the companion app exec host; add `OPENCLAW_NODE_EXEC_FALLBACK=0` to require the app host and fail closed if it is unavailable. * Add `--tls` / `--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 `openclaw nodes …` works against this Mac). * In remote mode, the app opens an SSH tunnel for the Gateway port and connects to `localhost`.