Fix managed Gateway updates across CLI and service Node skew by amknight · Pull Request #84043 · openclaw/openclaw

amknight · 2026-05-19T07:55:42Z

Summary

Fixes openclaw update silently switching the gateway to the wrong Node binary when users have multiple Node installations (nvm/fnm/volta/brew).

The bug

After gateway install bakes a specific node path into the service unit, if the user's PATH changes (e.g. switching nvm versions), openclaw update would use the new PATH node for all follow-up commands — rewriting the service unit with the wrong binary and breaking the gateway on next restart.

Fixes (3 commits)

Service node for redirected roots: When the shell root differs from the service root, extract and use the service's baked node for all follow-up commands. Validate it against the target release's engines.node before proceeding.
Service node for same roots: Independently detect when the current node differs from the service's baked node even when package roots match. Warn the user and use the service's node.
Pin install target: Set honorPackageRoot when the node override is active so the package install stays pinned to the service's global prefix (prevents PATH-visible npm from redirecting the install to a different prefix).

Verification

114 unit tests pass (6 new: redirected root, same-root node mismatch, no-owning-npm pinning, preflight engine check, follow-up command plumbing ×2)
Docker E2E (scripts/e2e/multi-node-update-docker.sh): before fix the baked node switches from node-A to node-B; after fix the unit file is byte-identical
oxfmt --check clean, git diff --check clean

clawsweeper · 2026-05-19T07:56:59Z

Codex review: passed.

Workflow note: Future ClawSweeper reviews update this same comment in place.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Summary
The PR pins managed Gateway package updates, runtime preflight, post-install doctor, post-core update, service refresh, and restart follow-ups to the Node binary and package root baked into the Gateway service.

Reproducibility: yes. source-level. Current main validates and follows up with the shell process Node in the same-root skew case, and the PR body provides a concrete two-Node Docker reproduction, though I did not execute it in this read-only pass.

PR rating
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Summary: Strong focused coverage and a credible Docker reproduction make this likely mergeable, with final confidence gated by exact-head packaged update validation.

Rank-up moves:

Run node scripts/run-vitest.mjs src/cli/update-cli.test.ts or the equivalent targeted CI lane for the final head.
Run scripts/e2e/multi-node-update-docker.sh or a Testbox/Crabbox packaged update lane against the final head.

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

PR egg
✨ Hatched: 🌱 uncommon Frosted Crabkin

        .--^^^^--.           
     .-'  o    o  '-.        
    /       \__/      \      
   |    /\  ____  /\   |     
   |   /  \/____\/  \  |     
    \  \_.------._/  /       
     '._  `----'  _.'        
        '-.____.-'           
       _/|_|  |_|\_          
      /__|      |__\         
       .-----------.         
      '-------------'

Rarity: 🌱 uncommon.
Trait: watches the merge queue.
Share on X: post this hatch
Copy: My PR egg hatched a 🌱 uncommon Frosted Crabkin in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
How to hatch it: reach status: 👀 ready for maintainer look or status: 🚀 automerge armed; that usually means sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Real behavior proof
Not applicable: The external contributor proof gate does not apply because this is a MEMBER PR with the protected maintainer label; the PR body still describes targeted unit tests and Docker before/after packaged-update proof for maintainer validation.

Risk before merge
Why this matters: - The branch intentionally makes the service-baked Node authoritative; if that Node is too old, missing, or no longer operator-maintained, openclaw update may fail until the user upgrades or reinstalls the managed service runtime.

Package root and Node runner selection affect global install placement, post-install doctor, post-core plugin sync, service refresh, and restart health, so a regression could leave the managed Gateway stopped or still pointed at the wrong runtime.
This read-only pass did not execute the targeted unit tests or Docker multi-node E2E; final merge should rely on exact-head CI, Testbox/Crabbox, or maintainer-run packaged update proof.

Maintainer options:

Validate the packaged multi-node update path (recommended)
Run the targeted update CLI tests plus the Docker multi-node update reproduction against the exact head before merge.
Accept the service-Node authority policy
Maintainers can intentionally accept that users with an obsolete baked service Node must repair that runtime before openclaw update proceeds.
Pause if packaged proof fails
If the Docker or packaged update lane shows a service restart or prefix drift regression, pause this PR and repair that path before merging.

Next step before merge
No repair lane is needed because there are no discrete review findings; exact-head automerge can rely on CI or packaged-update proof if maintainers accept the compatibility and availability risk.

Security
Cleared: No concrete security or supply-chain regression found; the diff changes CLI update logic, docs, changelog, tests, and an isolated Docker E2E script without new dependencies, workflow permissions, or secret handling.

Review details

Best possible solution:

Land after exact-head targeted update tests and the multi-node packaged update reproduction pass, keeping the service Node/root as the canonical runtime with the new operator-facing warnings.

Do we have a high-confidence way to reproduce the issue?

Yes, source-level. Current main validates and follows up with the shell process Node in the same-root skew case, and the PR body provides a concrete two-Node Docker reproduction, though I did not execute it in this read-only pass.

Is this the best way to solve the issue?

Yes. Using the service-baked Node and package root for managed Gateway update follow-ups matches the service unit contract and is narrower than adding another fallback; the remaining question is exact-head packaged validation, not a code-shape blocker.

Label justifications:

P1: A wrong Node during managed Gateway updates can break the user's running Gateway after an otherwise normal openclaw update.
merge-risk: 🚨 compatibility: The PR can change upgrade behavior for users whose managed service is baked to an older or different Node than their shell runtime.
merge-risk: 🚨 availability: The changed install, service refresh, and restart paths can leave the managed Gateway unavailable if runtime or package-root selection regresses.

What I checked:

Current-main bug path: Current main checks the target package engine against the shell process Node, so a service baked with a different Node is not validated before package update follow-up commands run. (src/cli/update-cli/update-command.ts:947, 3d96111a5afe)
Current-main install target gap: Current main only honors the existing package root when a service-root redirect exists, leaving same-root/different-Node installs able to resolve the PATH-visible package manager prefix. (src/cli/update-cli/update-command.ts:3117, 3d96111a5afe)
PR service Node detection: The PR extracts the Node runner from service program arguments and separately detects same-root Node mismatch by comparing realpaths against the current runner. (src/cli/update-cli/update-command.ts:1266, 5607e441f642)
PR preflight and install routing: The PR passes the managed service Node into package engine preflight and sets honorPackageRoot when either root redirect or service-node override is active. (src/cli/update-cli/update-command.ts:3185, 5607e441f642)
PR follow-up routing: The same managed service Node is threaded into the fresh post-core process and restart/service refresh paths, covering the follow-up commands that can rewrite or restart the Gateway service. (src/cli/update-cli/update-command.ts:3385, 5607e441f642)
Regression tests: The PR adds targeted update CLI tests for redirected roots, service Node engine preflight, same-root Node mismatch, follow-up command Node selection, and no-owning-npm prefix pinning. (src/cli/update-cli.test.ts:2829, 5607e441f642)

Likely related people:

@steipete: Heavy contributor across the update CLI, Gateway service, install/update docs, and release surfaces; history includes the core auto-updater and restart/update flow foundations. (role: feature-history owner; confidence: high; commits: f442a3539f19, 2c85b1b40945, 50a2481652b6; files: src/cli/update-cli/update-command.ts, docs/install/updating.md, src/infra/update-global.ts)
@vincentkoc: Recent history connects this person to package-manager installs, Gateway service env refresh, and post-core self-update process work in the same update path. (role: recent update-path contributor; confidence: high; commits: 5a7aba94a2bf, 45d9b2069264, a24af4910018; files: src/cli/update-cli/update-command.ts, src/cli/update-cli.test.ts, src/infra/update-global.ts)
@joshavant: Current-main blame on the central update-command and package update files points to e996159, which carried the current implementation snapshot. (role: recent area contributor; confidence: medium; commits: e99615973810; files: src/cli/update-cli/update-command.ts, src/cli/update-cli.test.ts, src/infra/update-global.ts)
@jayeshp19: Introduced the owning npm prefix behavior that this PR extends with honorPackageRoot for same-root/different-Node installs. (role: adjacent package-update owner; confidence: medium; commits: eb4b6f7024d3; files: src/infra/update-global.ts, src/cli/update-cli/update-command.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3d96111a5afe.

amknight · 2026-05-19T09:19:07Z

/clawsweeper re-review

clawsweeper · 2026-05-19T09:21:00Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Superseded
Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26088183678
Updated: 2026-05-19T09:27:16.845Z

amknight · 2026-05-19T11:15:01Z

/clawsweeper re-review

clawsweeper · 2026-05-19T11:16:50Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Superseded
Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26093695917
Updated: 2026-05-19T11:19:39.314Z

Decouple the managed service node runner resolution from the root redirect so it covers the common case where the package root is unchanged but the user's PATH-resolved node differs from the node baked into the gateway service unit (e.g. switching nvm/fnm/brew node after gateway install). Add resolveManagedServiceNodeRunnerOverride() which always compares process.execPath against the service unit's baked node path. When they differ, the update uses the service's node for all follow-up commands (doctor, gateway install, gateway restart, post-core plugin sync). Add Docker E2E reproduction script and two unit tests for the same-root-different-node scenario.

…thout owning npm When the package root matches between shell and service but the node binaries differ, set honorPackageRoot so resolveGlobalInstallTarget pins the install to the service root's inferred global prefix. Without this, PATH-visible npm root -g could resolve to the switched Node-B prefix, silently moving the package away from the service unit's entrypoint. Also harden the Docker E2E script: validate the unit file was created before continuing, capture update exit codes, and exit non-zero when bug indicators are found.

amknight · 2026-05-19T19:58:00Z

/clawsweeper automerge

clawsweeper · 2026-05-19T19:59:46Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=5607e441f642483bf662f51b581a9bb8b1e31db7)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-05-19T20:44:30Z
Merge commit: c81271ee6e3a

What merged:

The PR pins managed Gateway package updates, runtime preflight, post-install doctor, post-core update, service refresh, and restart follow-ups to the Node binary and package root baked into the Gateway service.
Reproducibility: yes. source-level. Current main validates and follows up with the shell process Node in the ... body provides a concrete two-Node Docker reproduction, though I did not execute it in this read-only pass.

Automerge notes:

PR branch already contained follow-up commit before automerge: fix(update): detect service node mismatch even when package roots match
PR branch already contained follow-up commit before automerge: fix(update): pin package install to service root when nodes differ wi…

The automerge loop is complete.

Automerge progress:

2026-05-19 19:59:45 UTC review queued 5607e441f642 (queued)

2026-05-19 20:07:51 UTC review passed 5607e441f642 (structured ClawSweeper verdict: pass (sha=5607e441f642483bf662f51b581a9bb8b1e31...)

2026-05-19 20:44:32 UTC merged 5607e441f642 (merged by ClawSweeper automerge)

Summary: - The PR pins managed Gateway package updates, runtime preflight, post-install doctor, post-core update, service refresh, and restart follow-ups to the Node binary and package root baked into the Gateway service. - Reproducibility: yes. source-level. Current main validates and follows up with the shell process Node in the ... body provides a concrete two-Node Docker reproduction, though I did not execute it in this read-only pass. Automerge notes: - PR branch already contained follow-up commit before automerge: fix(update): detect service node mismatch even when package roots match - PR branch already contained follow-up commit before automerge: fix(update): pin package install to service root when nodes differ wi… Validation: - ClawSweeper review passed for head 5607e441f642483bf662f51b581a9bb8b1e31db7. - Required merge gates passed before the squash merge. Prepared head SHA: 5607e441f642483bf662f51b581a9bb8b1e31db7 Review: openclaw/openclaw#84043 (comment) Co-authored-by: Alex Knight <15041791+amknight@users.noreply.github.com> Co-authored-by: Alex Knight <aknight@atlassian.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: amknight Co-authored-by: amknight <15041791+amknight@users.noreply.github.com>

…w#84043) Summary: - The PR pins managed Gateway package updates, runtime preflight, post-install doctor, post-core update, service refresh, and restart follow-ups to the Node binary and package root baked into the Gateway service. - Reproducibility: yes. source-level. Current main validates and follows up with the shell process Node in the ... body provides a concrete two-Node Docker reproduction, though I did not execute it in this read-only pass. Automerge notes: - PR branch already contained follow-up commit before automerge: fix(update): detect service node mismatch even when package roots match - PR branch already contained follow-up commit before automerge: fix(update): pin package install to service root when nodes differ wi… Validation: - ClawSweeper review passed for head 5607e44. - Required merge gates passed before the squash merge. Prepared head SHA: 5607e44 Review: openclaw#84043 (comment) Co-authored-by: Alex Knight <15041791+amknight@users.noreply.github.com> Co-authored-by: Alex Knight <aknight@atlassian.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: amknight Co-authored-by: amknight <15041791+amknight@users.noreply.github.com>

amknight requested a review from a team as a code owner May 19, 2026 07:55

openclaw-barnacle Bot added docs Improvements or additions to documentation app: web-ui App: web-ui gateway Gateway runtime cli CLI command changes size: S maintainer Maintainer-authored PR labels May 19, 2026

openclaw-barnacle Bot added size: M and removed size: S labels May 19, 2026

amknight changed the title ~~Fix update restart health across protocol skew~~ Fix managed Gateway updates across CLI and service Node skew May 19, 2026

clawsweeper Bot added merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 availability 🚨 May cause crashes, hangs, restart loops, stalls, or process outages. labels May 19, 2026

openclaw-barnacle Bot added scripts Repository scripts docker Docker and sandbox tooling size: L and removed size: M labels May 19, 2026

openclaw-barnacle Bot added size: XL and removed size: L labels May 19, 2026

amknight force-pushed the ak/fix-update-protocol-skew branch from e288f61 to e72dd34 Compare May 19, 2026 11:18

amknight and others added 3 commits May 19, 2026 21:27

fix update managed service node runtime

971f82d

amknight force-pushed the ak/fix-update-protocol-skew branch from e72dd34 to 5607e44 Compare May 19, 2026 11:29

openclaw-barnacle Bot removed app: web-ui App: web-ui gateway Gateway runtime labels May 19, 2026

clawsweeper Bot added the clawsweeper:automerge Maintainer opted this PR into bounded ClawSweeper-reviewed automerge label May 19, 2026

clawsweeper Bot added status: 🚀 automerge armed This PR is in ClawSweeper's automerge lane. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 19, 2026

clawsweeper Bot merged commit c81271e into main May 19, 2026
119 of 121 checks passed

clawsweeper Bot deleted the ak/fix-update-protocol-skew branch May 19, 2026 20:44

This was referenced May 20, 2026

fix(ui): resolve stale gateway URL under nginx reverse-proxy multi-instance setups #69647

Closed

Post-restart suggestion to run openclaw doctor --non-interactive is not always actionable in heartbeat / approval-constrained contexts #69755

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix managed Gateway updates across CLI and service Node skew#84043

Fix managed Gateway updates across CLI and service Node skew#84043
clawsweeper[bot] merged 3 commits into
mainfrom
ak/fix-update-protocol-skew

amknight commented May 19, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 19, 2026 •

edited

Loading

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 •

edited

Loading

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 •

edited

Loading

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

amknight commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

The bug

Fixes (3 commits)

Verification

Uh oh!

clawsweeper Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amknight commented May 19, 2026

Uh oh!

clawsweeper Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

amknight commented May 19, 2026 •

edited

Loading

clawsweeper Bot commented May 19, 2026 •

edited

Loading

clawsweeper Bot commented May 19, 2026 •

edited

Loading

clawsweeper Bot commented May 19, 2026 •

edited

Loading

clawsweeper Bot commented May 19, 2026 •

edited

Loading