Nodes & Device Integration

+15 Mana ✨

Introduction

OpenClaw nodes are companion devices that connect to your gateway over WebSocket, extending its reach into the physical world. Think of them as peripherals rather than gateways: they do not run agents themselves but expose device-specific capabilities that agents can invoke remotely. This lesson covers what nodes are, which platforms are supported, and how the pairing handshake works.

Key Concepts

  • Node: A companion device that connects to a gateway via WebSocket and exposes local capabilities such as screenshots, camera, GPS, and system execution.
  • Gateway: The central OpenClaw server that runs agents and orchestrates tool calls, including forwarding requests to paired nodes.
  • Pairing Request: The handshake process where a device presents its identity to a gateway, requesting a node role, which must be explicitly approved.
  • WebSocket Connection: The persistent, bidirectional channel between a node and its gateway that carries capability invocations and results.
  • Invoke Interface: The standardized JSON-RPC-style protocol nodes implement so that agents can call capabilities uniformly across platforms.

Real World Context

Imagine you are building an AI assistant that monitors a security camera, takes screenshots of a desktop application for automated QA, or reads GPS coordinates from a phone to provide location-aware responses. Without nodes, you would need custom integrations for each device. Nodes give agents a single invoke interface that works whether the device is a macOS menubar app, an Android phone, or a headless Linux box.

Deep Dive

Nodes connect to the gateway over a WebSocket channel. When a node starts for the first time, it generates an identity key pair and presents its public identity to the gateway. The gateway does not automatically trust new devices. Instead, it creates a pairing request with the role set to node.

You approve pairing requests through the CLI. First, list pending requests:

bash
openclaw devices list

This command prints a table of devices that have requested pairing, showing their device name, platform, and request ID. To approve a specific device:

bash
openclaw devices approve <requestId>

After approval, the node establishes a persistent WebSocket connection and registers its capabilities with the gateway. From that point forward, any agent running on the gateway can invoke those capabilities.

The following platforms are supported as nodes:

text
- macOS    : menubar app or headless daemon
- iOS      : mobile app (background-capable)
- Android  : mobile app (background-capable)
- Headless : Linux or Windows service (no GUI required)

Each platform exposes a subset of capabilities depending on hardware. For example, a headless Linux server cannot provide camera or GPS but can still run system exec commands and screen recordings of virtual displays.

The invoke interface is the contract every node implements. When an agent needs a capability, the gateway serializes the request and forwards it over the WebSocket. The node executes the action locally and streams the result back. This means the gateway never needs direct access to the device hardware.

json
{
  "method": "invoke",
  "params": {
    "capability": "canvas.screenshot",
    "args": { "format": "png" }
  }
}

The JSON above shows a typical invoke payload. The capability field identifies which node capability to call, and args carries the parameters. The node processes this locally and returns the result over the same WebSocket channel.

It is important to remember that nodes are peripherals, not gateways. They do not run agents, they do not make decisions, and they do not store conversation history. Their sole purpose is to execute capability invocations on behalf of the gateway.

Common Pitfalls

  • Forgetting to approve pairing requests: Nodes will not connect until you explicitly run openclaw devices approve. Check openclaw devices list if a node appears offline.
  • Assuming all platforms have all capabilities: A headless Linux node cannot take photos or read GPS. Always check the capability matrix for the target platform before designing agent workflows.
  • Treating nodes as independent agents: Nodes do not run agents or make autonomous decisions. They are passive peripherals that respond to gateway invocations.

Best Practices

  • Name your nodes descriptively during pairing so you can identify them easily in multi-device setups (e.g., office-macbook, warehouse-android).
  • Audit pending pairing requests regularly with openclaw devices list to ensure no unauthorized devices are waiting for approval.
  • Use headless nodes for server environments where GUI capabilities are unnecessary but system exec is valuable.

Summary

  • Nodes are companion devices that connect to a gateway via WebSocket and expose local hardware capabilities.
  • Supported platforms include macOS (menubar/headless), iOS, Android, and headless Linux/Windows.
  • Pairing requires explicit approval through the CLI using openclaw devices list and openclaw devices approve <requestId>.
  • The invoke interface provides a uniform JSON-RPC-style contract for calling capabilities across all node platforms.
  • Nodes are peripherals, not gateways: they execute commands but do not run agents or store state.
✓ Completed