From 2cd2732ab6695a4b3220ce41166b74aca7097c5f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 25 Apr 2026 06:46:04 +0100 Subject: [PATCH] docs: document trusted CIDR node auto-approval --- docs/cli/devices.md | 8 ++++++++ docs/cli/node.md | 19 +++++++++++++++++++ docs/cli/nodes.md | 3 +++ docs/gateway/configuration-examples.md | 22 ++++++++++++++++++++++ 4 files changed, 52 insertions(+) diff --git a/docs/cli/devices.md b/docs/cli/devices.md index 7a509cef493..03c90af1748 100644 --- 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 @@ -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 index b15b8dfb131..b0cf80e2d96 100644 --- a/docs/cli/node.md +++ b/docs/cli/node.md @@ -123,6 +123,25 @@ openclaw devices list openclaw devices approve ``` +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 index df23c6ffc2e..6c46ef19cdf 100644 --- 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 ` 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 index 4899b3fe521..9d31945e0ab 100644 --- 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: