From aaa173a4a7b6baba03d18ed49b0825852e539a5f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 12:18:32 +0100 Subject: [PATCH] docs: clarify node exec approval binding --- docs/gateway/security/index.md | 4 ++++ docs/nodes/troubleshooting.md | 5 +++++ 2 files changed, 9 insertions(+) diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index a9f8da4229d..c829a5a999a 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -399,6 +399,10 @@ If a macOS node is paired, the Gateway can invoke `system.run` on that node. Thi - The per-node `system.run` policy is the node's own exec approvals file (`exec.approvals.node.*`), which can be stricter or looser than the gateway's global command-ID policy. - A node running with `security="full"` and `ask="off"` is following the default trusted-operator model. Treat that as expected behavior unless your deployment explicitly requires a tighter approval or allowlist stance. - Approval mode binds exact request context and, when possible, one concrete local script/file operand. If OpenClaw cannot identify exactly one direct local file for an interpreter/runtime command, approval-backed execution is denied rather than promising full semantic coverage. +- For `host=node`, approval-backed runs also store a canonical prepared + `systemRunPlan`; later approved forwards reuse that stored plan, and gateway + validation rejects caller edits to command/cwd/session context after the + approval request was created. - If you don’t want remote execution, set security to **deny** and remove node pairing for that Mac. This distinction matters for triage: diff --git a/docs/nodes/troubleshooting.md b/docs/nodes/troubleshooting.md index 11c14528779..e6a47ae5c9d 100644 --- a/docs/nodes/troubleshooting.md +++ b/docs/nodes/troubleshooting.md @@ -80,6 +80,11 @@ If pairing is fine but `system.run` fails, fix exec approvals/allowlist on that Node pairing is an identity/trust gate, not a per-command approval surface. For `system.run`, the per-node policy lives in that node's exec approvals file (`openclaw approvals get --node ...`), not in the gateway pairing record. +For approval-backed `host=node` runs, the gateway also binds execution to the +prepared canonical `systemRunPlan`. If a later caller mutates command/cwd or +session metadata before the approved run is forwarded, the gateway rejects the +run as an approval mismatch instead of trusting the edited payload. + ## Common node error codes - `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground.