Nodes

Companion nodes extend the OpenClaw Gateway with device-local surfaces including voice, canvas, camera, screen capture, location, browser, and host commands. They connect over the same WebSocket control plane used by operator clients and CLI tools but declare role: "node" during the handshake. This lets agents access local device features while the Gateway remains the single source of truth for sessions, routing, and delivery.

Nodes appear alongside other surfaces in discovery, session context, and tool calls. The Gateway records declared capabilities and uses them for routing node.invoke calls and populating UI lists.

Connection and role

Nodes follow the standard Gateway WebSocket handshake. The first frame must be a connect request that includes:

  • role: "node"
  • Device identity
  • caps, commands, and permissions declarations

After a successful handshake the server returns a hello-ok response with discovery metadata. See the Gateway protocol for the exact frame shapes, challenge signing requirements, and hello-ok.features fields.

Direct loopback connections can auto-approve in some flows. Non-local connections (LAN, Tailscale, remote) always require explicit pairing approval.

Pairing and device tokens

New device identities must be paired before they can connect or receive work.

  • Pairing is device-based for the node role.
  • The Gateway issues a device token on successful pairing. Subsequent connects reuse the token.
  • Tokens can be rotated with device.token.rotate or revoked with device.token.revoke.
  • All connects must sign the connect.challenge nonce. v3 signatures also bind platform and device family.

Core pairing methods include:

  • node.pair.request
  • node.pair.list
  • node.pair.approve
  • node.pair.reject
  • node.pair.remove
  • node.pair.verify

Use the CLI for management:

openclaw nodes list
openclaw nodes describe <id>
openclaw nodes rename <id> <name>

Pairing approval is also available through the Control UI and direct RPC calls. The legacy openclaw devices … command performs the same operations.

Capability declaration and relay

At connect time nodes declare their surfaces in the connect payload. The Gateway uses these declarations to:

  • Populate node.list and node.describe
  • Route node.invoke calls
  • Surface capabilities to agents and the Control UI

After connect, a node can refresh its surface with node.pluginSurface.refresh.

The Gateway relays remote capability surfaces (canvas, camera, screen capture, location, voice, browser, and host-command families) over the same WS/RPC channel used by operator clients. Nodes appear in discovery, session, and tool contexts alongside other surfaces.

Invoking capabilities and pending work

  • node.invoke requests a capability on a specific paired node.
  • Results return via node.invoke.result.
  • Nodes can emit events with node.event (notably node.presence.alive).

Invocations are scoped to the paired device identity. The Gateway enforces role and scope checks before forwarding.

Offline or disconnected nodes can receive work through the pending queue:

  • node.pending.enqueue
  • node.pending.pull
  • node.pending.ack
  • node.pending.drain

The Gateway holds work until the node reconnects and explicitly pulls it. Ack semantics prevent duplicate delivery.

Platform notes

  • iOS nodes support device pairing, voice trigger forwarding, and the Canvas surface.
  • Android nodes support WS pairing, Connect/Chat/Voice tabs, Canvas, camera, screen capture, and Android device commands.
  • macOS and headless nodes follow the same role: "node" contract and capability declaration rules.

Companion apps for Windows, macOS, iOS, and Android nodes are referenced during openclaw onboard.

Security and trust

  • Device identity + signed challenge + token are required for every node connection.
  • Non-local connects require explicit approval even when using Tailscale or LAN transport.
  • Gateway auth settings (gateway.auth.*) apply to all connections.

Review network exposure patterns and auth configuration before pairing remote nodes. See Network concepts and Gateway configuration for bind modes, Tailscale options, and auth requirements.

CLI and management

The openclaw nodes command (and legacy openclaw devices) is the primary interface for pairing, listing, describing, and renaming nodes. Pairing approvals can also be performed through the Control UI or direct RPC.

For full command syntax and options, see the CLI reference.

Updated June 17, 2026