docs(gateway): document gateway.tools.byNode (ClawSweeper P2)

anagnorisis2peripeteia · anagnorisis2peripeteia · commit 7a6f52c149a0 · 2026-06-16T15:23:11.000+01:00
Add config-help entries (schema.help.ts) for gateway.tools.byNode and its per-node
allow/deny, and a Gateway tool policy section in the configuration reference:
restriction-only, authenticated-node keyed (unforgeable), fail-closed empty allow,
nodeId discovered via /whoami or nodes list.
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
@@ -627,6 +627,25 @@ See [Inferred commitments](/concepts/commitments).
 
 </Accordion>
 
+### Gateway tool policy (`gateway.tools`)
+
+Gateway-level tool exposure, applied independently of agent/tool profiles for coarse production hardening:
+
+- `gateway.tools.allow` / `gateway.tools.deny`: explicit allow/deny lists applied at the gateway. `deny` wins.
+- `gateway.tools.byNode`: per-node tool restriction keyed by the **authenticated** node id that hosts a turn. When an agent turn is driven through a node (a node-originated `agent.request`), that node's `allow`/`deny` are applied to the turn. **Restriction-only** — it can narrow the toolset, never escalate — and the node id comes from the node's cryptographically-paired connection, so a client cannot forge it. An explicitly-present (even empty) `allow` is **fail-closed** (`allow: []` ⇒ no tools); an absent `allow` means "no allow restriction". Find a node's id from its bridge `/whoami` or `openclaw nodes list`.
+
+```json5
+gateway: {
+  tools: {
+    // Confine turns driven through a specific node (e.g. a node hosting a
+    // browser) to just browser + memory tools:
+    byNode: {
+      "<authenticated-node-id>": { allow: ["browser", "memory_search", "memory_get"] },
+    },
+  },
+}
+```
+
 ### OpenAI-compatible endpoints
 
 - Admin HTTP RPC: off by default as the `admin-http-rpc` plugin. Enable the plugin to register `POST /api/v1/admin/rpc`. See [Admin HTTP RPC](/plugins/admin-http-rpc).
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
@@ -98,6 +98,10 @@ export const FIELD_HELP: Record<string, string> = {
     "Explicit gateway-level tool allowlist when you want a narrow set of tools available at runtime. Use this for locked-down environments where tool scope must be tightly controlled.",
   "gateway.tools.deny":
     "Explicit gateway-level tool denylist to block risky tools even if lower-level policies allow them. Use deny rules for emergency response and defense-in-depth hardening.",
+  "gateway.tools.byNode":
+    "Per-node tool restriction keyed by the AUTHENTICATED node id that hosts a turn (a node-originated agent.request). RESTRICTION-ONLY: a node's allow/deny narrows the toolset for the turns that node drives and can never escalate it. The node id comes from the node's cryptographically-paired connection, so a client cannot forge it. An explicitly-present (even empty) allow is FAIL-CLOSED (empty allow => no tools); an absent allow means 'no allow restriction'. Discover a node's id from its bridge /whoami response or `openclaw nodes list`. Example: confine a node that hosts a browser to browser + memory tools.",
+  "gateway.tools.byNode.*":
+    "Allow/deny policy for one authenticated node id. `allow` = the only tools that node's turns may use (empty array = no tools, fail-closed); `deny` = tools removed from that node's turns. Restriction-only; never grants a tool the base policy denies.",
   "gateway.handshakeTimeoutMs":
     "Pre-auth Gateway WebSocket handshake timeout in milliseconds. Use higher values on loaded or low-powered hosts where local clients can connect during startup warmup. OPENCLAW_HANDSHAKE_TIMEOUT_MS still takes precedence.",
   "gateway.channelHealthCheckMinutes":
