warning

Node pairing is a trust and identity flow plus token issuance. It does **not** pin the live node command surface per node.

• Live node commands come from what the node declares on connect after the gateway's global node command policy (
  text

  Copy

  gateway.nodes.allowCommands
  and
  text

  Copy

  denyCommands
  ) is applied.
• Per-node
  text

  Copy

  system.run
  allow and ask policy lives on the node in
  text

  Copy

  exec.approvals.node.*
  , not in the pairing record.

Node command gating (2026.3.31+)

When a node connects for the first time, pairing is requested automatically. Until the pairing request is approved, all pending node commands from that node are filtered and will not execute. Once trust is established through pairing approval, the node's declared commands become available subject to the normal command policy.

This means:

• Nodes that were previously relying on device pairing alone to expose commands must now complete node pairing.
• Commands queued before pairing approval are dropped, not deferred.

Node event trust boundaries (2026.3.31+)

Node-originated summaries and related session events are restricted to the intended trusted surface. Notification-driven or node-triggered flows that previously relied on broader host or session tool access may need adjustment. This hardening ensures that node events cannot escalate into host-level tool access beyond what the node's trust boundary permits.

Durable node presence updates follow the same identity boundary. The

event is accepted only from authenticated node device sessions and updates pairing metadata only when the device/node identity is already paired. Self-declared values are not enough to write last-seen state.

Auto-approval (macOS app)

The macOS app can optionally attempt a silent approval when:

• the request is marked
  text

  Copy

  silent
  , and
• the app can verify an SSH connection to the gateway host using the same user.

If silent approval fails, it falls back to the normal “Approve/Reject” prompt.

Trusted-CIDR device auto-approval

WS device pairing for

remains manual by default. For private node networks where the Gateway already trusts the network path, operators can opt in with explicit CIDRs or exact IPs:

json5
Copy
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Security boundary:

• Disabled when
  text

  Copy

  gateway.nodes.pairing.autoApproveCidrs
  is unset.
• No blanket LAN or private-network auto-approve mode exists.
• Only fresh
  text

  Copy

  role: node
  device pairing with no requested scopes is eligible.
• Operator, browser, Control UI, and WebChat clients stay manual.
• Role, scope, metadata, and public-key upgrades stay manual.
• Same-host loopback trusted-proxy header paths are not eligible because that path can be spoofed by local callers.

Metadata-upgrade auto-approval

When an already paired device reconnects with only non-sensitive metadata changes (for example, display name or client platform hints), OpenClaw treats that as a

. Silent auto-approval is narrow: it applies only to trusted non-browser local reconnects that already proved possession of local or shared credentials, including same-host native app reconnects after OS version metadata changes. Browser/Control UI clients and remote clients still use the explicit re-approval flow. Scope upgrades (read to write/admin) and public key changes are not eligible for metadata-upgrade auto-approval — they stay as explicit re-approval requests.

QR pairing helpers

renders the pairing payload as structured media so mobile and browser clients can scan it directly.

Deleting a device also sweeps any stale pending pairing requests for that device id, so

does not show orphaned rows after a revoke.

Locality and forwarded headers

Gateway pairing treats a connection as loopback only when both the raw socket and any upstream proxy evidence agree. If a request arrives on loopback but carries

/ / headers that point at a non-local origin, that forwarded-header evidence disqualifies the loopback locality claim. The pairing path then requires explicit approval instead of silently treating the request as a same-host connect. See Trusted Proxy Auth for the equivalent rule on operator auth.

Storage (local, private)

Pairing state is stored under the Gateway state directory (default

):

• text

  Copy

  ~/.openclaw/nodes/paired.json
• text

  Copy

  ~/.openclaw/nodes/pending.json

If you override

, the folder moves with it.

Security notes:

• Tokens are secrets; treat
  text

  Copy

  paired.json
  as sensitive.
• Rotating a token requires re-approval (or deleting the node entry).

Transport behavior

• The transport is stateless; it does not store membership.
• If the Gateway is offline or pairing is disabled, nodes cannot pair.
• If the Gateway is in remote mode, pairing still happens against the remote Gateway’s store.

Related

• Channel pairing
• Nodes
• Devices CLI