docs: document trusted CIDR node auto-approval

steipete · steipete · commit 2cd2732ab669 · 2026-04-25T06:46:26.000+01:00
diff --git a/docs/cli/devices.md b/docs/cli/devices.md
@@ -66,6 +66,12 @@ request. Review the `Requested` vs `Approved` columns in `openclaw devices list`
 or use `openclaw devices approve --latest` to preview the exact upgrade before
 approving it.
 
+If the Gateway is explicitly configured with
+`gateway.nodes.pairing.autoApproveCidrs`, first-time `role: node` requests from
+matching client IPs can be approved before they appear in this list. That policy
+is disabled by default and never applies to operator/browser clients or upgrade
+requests.
+
 ```
 openclaw devices approve
 openclaw devices approve <requestId>
@@ -127,6 +133,8 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 
 - Token rotation returns a new token (sensitive). Treat it like a secret.
 - These commands require `operator.pairing` (or `operator.admin`) scope.
+- `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
+  fresh node device pairing only; it does not change CLI approval authority.
 - Token rotation stays inside the approved pairing role set and approved scope
   baseline for that device. A stray cached token entry does not grant a new
   rotate target.
diff --git a/docs/cli/node.md b/docs/cli/node.md
@@ -123,6 +123,25 @@ openclaw devices list
 openclaw devices approve <requestId>
 ```
 
+On tightly controlled node networks, the Gateway operator can explicitly opt in
+to auto-approving first-time node pairing from trusted CIDRs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This is disabled by default. It only applies to fresh `role: node` pairing with
+no requested scopes. Operator/browser clients, Control UI, WebChat, and role,
+scope, metadata, or public-key upgrades still require manual approval.
+
 If the node retries pairing with changed auth details (role/scopes/public key),
 the previous pending request is superseded and a new `requestId` is created.
 Run `openclaw devices list` again before approval.
diff --git a/docs/cli/nodes.md b/docs/cli/nodes.md
@@ -42,6 +42,9 @@ filter to nodes that connected within a duration (e.g. `24h`, `7d`).
 Approval note:
 
 - `openclaw nodes pending` only needs pairing scope.
+- `gateway.nodes.pairing.autoApproveCidrs` can skip the pending step only for
+  explicitly trusted, first-time `role: node` device pairing. It is off by
+  default and does not approve upgrades.
 - `openclaw nodes approve <requestId>` inherits extra scope requirements from the
   pending request:
   - commandless request: pairing only
diff --git a/docs/gateway/configuration-examples.md b/docs/gateway/configuration-examples.md
@@ -501,6 +501,28 @@ Save to `~/.openclaw/openclaw.json` and you can DM the bot from that number.
 }
 ```
 
+### Trusted node network auto-approval
+
+Keep device pairing manual unless you control the network path. For a dedicated
+lab or tailnet subnet, you can opt in to first-time node device auto-approval
+with exact CIDRs or IPs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
+      },
+    },
+  },
+}
+```
+
+This remains off when unset. It only applies to fresh `role: node` pairing with
+no requested scopes. Operator/browser clients and role, scope, metadata, or
+public-key upgrades still require manual approval.
+
 ### Secure DM mode (shared inbox / multi-user DMs)
 
 If more than one person can DM your bot (multiple entries in `allowFrom`, pairing approvals for multiple people, or `dmPolicy: "open"`), enable **secure DM mode** so DMs from different senders don’t share one context by default:
