Nodes and media

Nodes

A node is a companion device (macOS/iOS/watchOS/Android/headless) that connects to the Gateway with role: "node" and exposes a command surface (e.g. camera.*, device.*, notifications.*, system.*) via node.invoke. Most nodes use the Gateway WebSocket on the operator port. The optional direct Apple Watch node uses signed HTTPS polling on that same port because watchOS blocks generic low-level networking for ordinary apps. Protocol details: Gateway protocol.

macOS can also run in node mode: the menu bar app connects to the Gateway's WS server as one node (so openclaw nodes … works against this Mac). The app adds native widget-panel, camera, screen, notification, and computer-control commands to the same node-host command surface used by openclaw node run. Do not start a second CLI node on that Mac; the app runs the matching CLI node-host runtime as an internal worker and remains the sole Gateway connection and node identity. The app's Instances UI shows each device under a friendly hardware name; see Device model database for how Apple model identifiers are vendored and mapped.

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

Node pages

Set up a node:

Node pairing and status - Approve a node, read its status and host stats, and upgrade a fleet in order.
Run a node host - Foreground, service, SSH-tunnel, and headless hosts, their identity state, and system commands.

Give a node work:

Run commands on a node - Allowlist commands, point exec at a node, invoke raw RPC, and bind a target.
Node-hosted MCP servers and skills - Publish MCP tools, skills, and local model inference from the node machine.
Host OpenClaw sessions on a node - Worker session hosting, device placement, capacity, and container isolation.
Node session catalogs - Codex, Claude, OpenCode, and Pi sessions discovered on the Gateway and paired nodes.
Node file transfers - Terminal uploads and the File Transfer plugin's directory listing, fetch, and write tools.

Govern and invoke device capabilities:

Node command policy - Platform default allowlists, dangerous-command opt-ins, and the gateway.nodes config.
Node device commands - Widget panel, camera, screen recording, location, SMS, and device data helpers.

Node capabilities in depth:

Active computer presence - Which Mac the Gateway treats as active, and where node alerts land.
Camera capture - Per-platform photo and clip limits and the capture pipeline.
Computer use - Desktop control on a paired node, and the gates around it.
Location command - Full parameter and response shape for location.get.
Talk mode - Live voice conversation on a node.
Voice wake - Wake-word capture on a node.
Media understanding - How the agent reads node-captured media.
Media playback - Playing audio and video through a node.
Image and media support - Image formats and attachment handling.
Audio and voice notes - Audio capture and voice-note handling.
Node troubleshooting - Pairing, foreground, permission, and tool failures.
openclaw nodes - CLI reference for listing, inspecting, and managing nodes.