skip to content

On an OpenClaw Gateway, how does an operator client differ from a role: node device, and how is each one approved?

level: middleimportance: should knowfreq 6%

answer

  1. who steers versus who lends hardware
  2. role declared in connect
  3. scopes versus caps and commands
  4. devices approve, then nodes approve
  5. not the DM pairing command

basics

~20 s

Operator clients such as the CLI and Control UI steer the Gateway within granted operator scopes; node devices connect with role: node and offer commands like camera.snap or system.run. Both pair by device identity; nodes also need their command surface approved.

solid answer

~40 s

Both connect to the same WebSocket and declare a `role` in `connect`. An operator (CLI, Control UI, macOS app, automation) asks for scopes such as `operator.read`, `operator.write` or `operator.admin` and uses the control plane. A node (macOS, iOS, Android or headless host) declares `caps`, `commands` and `permissions`, which the Gateway treats as claims against its own allowlists. Every client carries a device identity; a new one needs pairing approval with `openclaw devices approve <requestId>`, after which the Gateway issues a device token. Nodes add a second step, `openclaw nodes approve <requestId>`, for their command surface, and sensitive commands such as `system.run` need `operator.admin` to approve. Same-host loopback connects can be auto-approved, and SSH-verified nodes are auto-approved by default. `openclaw pairing approve` is for chat senders, not devices.

go deeper

for a junior

Recall the two roles: operators such as the CLI and dashboard control the Gateway, nodes such as a phone offer device commands, and both are approved before they can act.

for a middle

Explain how role, scopes, caps and commands are declared in connect, why the Gateway treats node declarations as claims, and the two approval steps a node goes through.

for a senior

Show judgment about auto-approval paths, the admin scope needed for sensitive node commands, mixed-role devices, and removing a node that should no longer be trusted.

for a principal

Weigh node pairing as granting remote execution on a device: which auto-approval defaults a team keeps, who holds operator.admin, and how device trust is reviewed.

## Two kinds of client on one socket Every client of the OpenClaw Gateway uses the same WebSocket server and the same `connect` handshake, but it declares a **role** there, and the role decides what the connection is for. | | Operator client | Node device | | --- | --- | --- | | Declares | `role: "operator"` plus operator scopes | `role: "node"` plus caps, commands and permissions | | Typical examples | the CLI, the Control UI, the macOS app, automations | macOS, iOS, Android and headless hosts | | Purpose | control the Gateway: status, chat, sessions, config, approvals | lend the agent a device: camera, screen, location, command execution | | Authority comes from | its granted operator scopes | the command surface an operator approved | | Approved with | `openclaw devices approve <requestId>` | `openclaw devices approve`, then `openclaw nodes approve <requestId>` | A third role, `worker`, is a Gateway-launched cloud execution host on a separate, closed protocol; it is not something an operator pairs by hand. ## Operators: the control plane An operator connection asks for scopes from a closed set: `operator.read`, `operator.write`, `operator.admin`, `operator.approvals`, `operator.questions`, `operator.pairing`, `operator.talk` and `operator.talk.secrets`. Method scope is the first gate. Some prefixes, such as `config.*`, `exec.approvals.*`, `wizard.*` and `update.*`, always need `operator.admin`. The `hello-ok` reply reports the scopes actually granted to the socket, which can be fewer than requested. ## Nodes: devices the agent can use A node declares what it offers at connect time: - **`caps`** - broad categories such as `camera`, `canvas`, `screen`, `location`, `voice` and `talk`. - **`commands`** - the allowlist of invokable commands, for example `camera.snap`, `screen.record`, `location.get` or `system.run`. - **`permissions`** - granular toggles such as `camera.capture` or `screen.record`. The Gateway treats all of these as **claims** and enforces its own server-side allowlists. A node that declares `system.run` has not thereby been given shell access; an operator still has to approve that command surface. ## How pairing works All WebSocket clients, operators and nodes alike, include a **device identity** in `connect`. A device the Gateway has not seen produces a pairing request; once approved, the Gateway issues a **device token** for later connects. 1. **Device pairing** gates the handshake itself. `openclaw devices list` shows pending requests next to what each device already has, and `openclaw devices approve <requestId>` approves one. Approving a `node` role needs `operator.admin`; `operator.pairing` is enough for operator devices whose requested scopes stay within the approver's own. 2. **Node command approval** is a second, separate request for a node. After the device is approved, the node reconnects and creates a request that `openclaw nodes pending` lists; `openclaw nodes approve <requestId>` approves its command surface. The ID differs from the device request ID. 3. **Scope at approval time** follows the declared commands: a commandless request needs `operator.pairing`, ordinary commands add `operator.write`, and sensitive ones such as `system.run` or `browser.proxy` add `operator.admin`. Some approvals happen without you: - **Same-host loopback** connects can be auto-approved to keep local use smooth; tailnet and LAN connects, even to the same host, still need explicit approval. - **`gateway.nodes.pairing.sshVerify`** is on by default and auto-approves a first-time node whose device key the Gateway verifies over SSH to the node host. - **`gateway.nodes.pairing.autoApproveCidrs`** can approve first-time nodes from listed networks; it is off by default and never applies to operator or browser clients. ## What trips people up - **`openclaw pairing approve` is a different system.** It approves pairing codes from people messaging the bot in a chat; devices and nodes use `openclaw devices` and `openclaw nodes`. - **A device can hold both roles.** The phone app's setup-code bootstrap returns a node token plus one bounded operator token, and removing the node role from such a mixed-role device keeps its record for the other role. - **Gateway auth still applies.** Pairing is about device identity; `gateway.auth` applies to every connection, local or remote. - **Pairing a node is granting power.** The trust model lists node pairing and node commands as operator-level remote execution on the paired device. Approve a node the way you would hand over a shell, and remove it with `openclaw nodes remove --node <id>` when it is no longer yours to trust. In the home-server picture, the laptop CLI and the browser dashboard are operators that steer the Gateway, while the phone, once paired as a node, is a set of sensors and actions the agent may call on.

  • Why is approving an OpenClaw node that declares system.run treated more strictly than one that only offers a camera?
    Because node commands run on the paired device with operator-level authority. Approval scope follows the declared commands: ordinary commands need `operator.pairing` plus `operator.write`, while `system.run`, `browser.proxy` and the other sensitive commands need `operator.pairing` plus `operator.admin`. The stricter rule keeps a pairing-only operator from quietly granting shell access on a device.
  • When does an OpenClaw node get paired without anyone running devices approve?
    When `gateway.nodes.pairing.sshVerify`, on by default, verifies the node's device key over SSH to its host, or when `gateway.nodes.pairing.autoApproveCidrs`, off by default, lists the node's network. Both cover only first-time `role: node` requests, never operator or browser clients; turn both off for manual-only pairing.

  • Nodes are just another kind of operator with fewer scopes.
  • Whatever commands a node declares become callable as soon as it connects.
  • Use openclaw pairing approve to let a new phone node join the Gateway.
  • Connecting over loopback skips Gateway auth, so local clients need no secret.
  • Approving a node's device request by hand also approves every command it declared.