From 4ceb01f9edd8b7aba5b68af5aacd55ecd0d75e8a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 1 Apr 2026 18:02:06 +0900 Subject: [PATCH] docs(gateway): document node pairing repair flow --- CHANGELOG.md | 1 + docs/gateway/pairing.md | 9 +++++++++ docs/nodes/troubleshooting.md | 5 +++++ 3 files changed, 15 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf4bf8ab460..f131f3cdba6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,7 @@ Docs: https://docs.openclaw.ai - Subagents/tasks: keep subagent completion and cleanup from crashing when task-registry writes fail, so a corrupt or missing task row no longer takes down the gateway during lifecycle finalization. Thanks @vincentkoc. - Sandbox/browser: compare browser runtime inspection against `agents.defaults.sandbox.browser.image` so `openclaw sandbox list --browser` stops reporting healthy browser containers as image mismatches. (#58759) Thanks @sandpile. - Exec/approvals: resume the original agent session after an approved async exec finishes, so external completion followups continue the task instead of waiting for a new user turn. (#58860) Thanks @Nanako0129. +- Gateway/node pairing: create repair pairing requests when a paired node reconnects with allowlisted commands missing from its approved node record, refresh stale pending repair metadata, and surface paired node command metadata in `nodes status`/`describe` even while the node is offline. Fixes #58824. ## 2026.3.31 diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index 2e51d643d83..e70d36fd543 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -65,10 +65,19 @@ Notes: - `node.pair.request` is idempotent per node: repeated calls return the same pending request. +- Repeated requests for the same pending node also refresh the stored node + metadata and allowlisted command set, so reconnect-driven repair flows do not + stay stuck on stale pending data. - Approval **always** generates a fresh token; no token is ever returned from `node.pair.request`. - Requests may include `silent: true` as a hint for auto-approval flows. +If a node is already paired but reconnects while declaring allowlisted commands +that are missing from its approved node record, the gateway creates a repair +pairing request. The current connection stays fail-closed on the previously +approved command set until that repair request is approved and the node +reconnects again. + ## Auto-approval (macOS app) The macOS app can optionally attempt a **silent approval** when: diff --git a/docs/nodes/troubleshooting.md b/docs/nodes/troubleshooting.md index c8ba10bac49..406d81c748b 100644 --- a/docs/nodes/troubleshooting.md +++ b/docs/nodes/troubleshooting.md @@ -76,6 +76,11 @@ openclaw approvals allowlist add --node "/usr/bin/uname" If pairing is missing, approve the node device first. If pairing is fine but `system.run` fails, fix exec approvals/allowlist. +If `nodes describe` shows the node connected but the expected command is missing, +the approved node-pair record may be stale. In that case, reconnecting the node +should create a repair pairing request; approve it, then reconnect once more so +the gateway can expose the refreshed command set. + ## Common node error codes - `NODE_BACKGROUND_UNAVAILABLE` → app is backgrounded; bring it foreground.