PR #78682: fix(doctor): emit one Gateway runtime note instead of three (#78676)

• Repository: openclaw/openclaw
• Author: hclsys
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78682

Description (problem / solution / changelog)

Problem

On a host where the system Node is below 22.14 but a version-manager Node (nvm v22.22.2) is in use, openclaw doctor prints three consecutive ◇ Gateway runtime panels, one of which falsely claims "System Node 22 LTS or Node 24 not found" while the first panel already announced the daemon is using the nvm Node.

Traced in the issue to src/commands/doctor-gateway-services.ts lines 425-433: when !systemNodePath (system Node below threshold), two sequential notes fired:

1. renderSystemNodeWarning(systemNodeInfo) → "System Node 20.x is below required 22.14+…"
2. Unconditional hardcoded note → "System Node 22 LTS (22.14+) or Node 24 not found…"

The second note contradicts the first: the system Node was found, just too old. The "not found" text only makes sense when resolveSystemNodeInfo returned null.

Fixes #78676.

Fix

Collapse the two notes into one via null-coalescing:

// before
const warning = renderSystemNodeWarning(systemNodeInfo);
if (warning) {
  note(warning, "Gateway runtime");
}
note(
  "System Node 22 LTS (22.14+) or Node 24 not found. Install via Homebrew/apt/choco…",
  "Gateway runtime",
);

// after
const warning = renderSystemNodeWarning(systemNodeInfo)
  ?? "System Node 22 LTS (22.14+) or Node 24 not found. Install via Homebrew/apt/choco…";
note(warning, "Gateway runtime");

• When systemNodeInfo is null: renderSystemNodeWarning returns null → fallback "not found" text fires. One note.
• When systemNodeInfo.supported === false: renderSystemNodeWarning returns the "below required" message → no fallback. One note.

Audit A — existing helper check

No separate deduplication helper exists. The renderSystemNodeWarning function itself is already the canonical message renderer; wiring it through ?? is the minimal composable approach.

Audit B — shared caller check

renderSystemNodeWarning is called in 3 files (doctor-gateway-services.ts, daemon-install-runtime-warning.ts, runtime-paths.ts). This change only touches the doctor-gateway-services.ts call site and does not alter the function signature or behavior.

Audit C — rival PR scan

No rival PR open for #78676 at scout time.

Real behavior proof

New tests in doctor-gateway-services.test.ts:

• "emits exactly one Gateway runtime note when system Node is below minimum" — asserts mocks.note called once with "Gateway runtime" title and message containing "below the required Node 22.14+"
• "emits the not-found note when resolveSystemNodeInfo returns null" — asserts one "Gateway runtime" note containing "not found"

All 26 tests pass. pnpm -s tsgo:core clean.

Co-authored-by: hclsys

Changed files

• CHANGELOG.md (modified, +2/-0)
• src/commands/doctor-gateway-services.test.ts (modified, +87/-0)
• src/commands/doctor-gateway-services.ts (modified, +44/-28)

PR #78688: fix(doctor): collapse duplicate Gateway runtime panels and stop false…

• Repository: openclaw/openclaw
• Author: YB0y
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/78688

Description (problem / solution / changelog)

Summary

• Problem: openclaw doctor emits three Gateway runtime panels for a single Node-version condition. Panel 2 is a strict-subset duplicate of Panel 1 (renderSystemNodeWarning(systemNodeInfo) re-fired without selectedNodePath). Panel 3 unconditionally claims "System Node 22 LTS (22.14+) or Node 24 not found" whenever the system Node is unsupported — even when Panel 1 in the same run announced "Using ~/.nvm/versions/node/v22.22.2/bin/node for the daemon."
• Why it matters: This is the typical Linux/dev-machine layout (system Node old, version-manager Node 22 fine). Every doctor run shows three overlapping notes ending in a factually wrong one. Users following Panel 3's advice ("Install Node 22 LTS via Homebrew/apt/choco") may shadow or wipe a working nvm Node 22 chain that doctor itself just reported as in-use.
• What changed: In src/commands/doctor-gateway-services.ts, drop the local renderSystemNodeWarning(systemNodeInfo) re-emit (Panel 2 — emitDaemonInstallRuntimeWarning at daemon-install-helpers.ts already covers it via Panel 1, with full selectedNodePath context), and gate the "not found" note on resolvePreferredNodePath({ runtime: "node" }) returning undefined rather than on !systemNodePath. The "not found" message now only fires when no Node 22+ is reachable anywhere — system Node, current process, or any version manager.
• What did NOT change (scope boundary): renderSystemNodeWarning itself, resolveSystemNodeInfo, resolvePreferredNodePath, the existing emit at daemon-install-helpers.ts (Panel 1, which is correct), the wording of the "not found" string, the needsNodeRuntimeMigration audit signal, and the Bun-runtime path (still skipped by emitNodeRuntimeWarning's runtime !== "node" early return).

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #78676
• Related #78682 (parallel attempt by another contributor; collapses Panels 2 + 3 only — the Panel 1 ↔ Panel 2 duplicate persists in their fix because they keep renderSystemNodeWarning(systemNodeInfo) firing on the doctor side, where emitDaemonInstallRuntimeWarning is already producing the same warning. This PR drops Panel 2 entirely and gates Panel 3 on resolvePreferredNodePath, taking the bug scenario from 3 panels to 1.)
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Triple Gateway runtime panel emission with contradictory "Node 22 LTS or Node 24 not found" message in openclaw doctor — see #78676.
• Real environment tested: Ubuntu 24.04 (Linux 6.8.0-110-generic). System Node /usr/bin/node reports v20.20.2 (below 22.14, the audit-triggering case). Version-manager Node ~/.nvm/versions/node/v22.22.2/bin/node is on PATH. OpenClaw source checkout at this branch tip rebased onto upstream 1f822d7c22. Local commit SHA on this run: 69d3253 (matches the 🦞 OpenClaw 2026.5.6 (69d3253) banner in the capture below).
• Exact steps or command run after this patch:
  1. export PATH="$HOME/.nvm/versions/node/v22.22.2/bin:$PATH"
  2. pnpm openclaw doctor --non-interactive
• Evidence after fix (terminal capture, redacted to the relevant panels):

🦞 OpenClaw 2026.5.6 (69d3253)

┌  OpenClaw doctor
│
…
◇  Gateway service config ─────────────────────────────────────────────────╮
│  Gateway service entrypoint resolves to a source checkout:               │
│  /home/orin/Gittensor/Test/openclaw.                                     │
│  Run `openclaw doctor --fix` from the intended package install, or       │
│  reinstall the gateway service with `openclaw gateway install --force`.  │
├──────────────────────────────────────────────────────────────────────────╯
│
◇  Gateway runtime ───────────────────────────────────────────────────────╮
│  System Node 20.20.2 at /usr/bin/node is below the required Node        │
│  22.14+. Using /home/orin/.nvm/versions/node/v22.22.2/bin/node for the  │
│  daemon. Install Node 24 (recommended) or Node 22 LTS from nodejs.org   │
│  or Homebrew.                                                           │
├─────────────────────────────────────────────────────────────────────────╯
│
◇  Gateway service config ─────────────────────────────────────────────────╮
│  - Gateway service PATH includes version managers or package managers;   │
│    recommend a minimal PATH.                                             │
│    (/home/orin/.nvm/versions/node/v22.22.2/bin,                          │
…

• Observed result after fix: Exactly one ◇ Gateway runtime panel in the doctor output, containing the "Using <version-manager-path> for the daemon" context. No duplicate panel. No spurious "Node 22 LTS or Node 24 not found" panel. The next section (Gateway service config) is unrelated and unaffected by this PR.
• Before evidence: see the verbatim three-panel capture in the issue body of #78676 (same host, same /usr/bin/node v20.20.2 + nvm v22.22.2 layout).
• What was not tested:
  • macOS Homebrew Node fallback (no macOS host available locally; the same resolvePreferredNodePath helper is what buildGatewayInstallPlan already uses to pick the runtime, so its cross-platform behavior is exercised in the broader install path).
  • Windows + nvm-windows / WSL.
  • asdf, fnm, volta version managers (only nvm reproduced on this host).

Root Cause (if applicable)

• Root cause: Two stacked bugs in maybeRepairGatewayServiceConfig (src/commands/doctor-gateway-services.ts):
  1. renderSystemNodeWarning(systemNodeInfo) was called without selectedNodePath, even though buildGatewayInstallPlan (run earlier in the same function via buildExpectedGatewayServicePlan) had already invoked emitDaemonInstallRuntimeWarning with the resolved programArguments[0] as selectedNodePath. Two Gateway runtime panels with the same first sentence resulted, the second one a strict subset of the first.
  2. The "not found" note was gated on !systemNodePath, computed as systemNodeInfo?.supported ? systemNodeInfo.path : null — i.e., only the system Node binary, ignoring version-managed Node entirely. The note fired whenever the system Node was below 22.14, regardless of whether a version-manager Node 22+ was already in use.
• Missing detection / guardrail: No regression test asserted "this function should not emit a Gateway runtime note when emitDaemonInstallRuntimeWarning already covered the runtime case." The two new tests in this PR lock in that contract.
• Contributing context (if known): The doctor-side renderSystemNodeWarning call predates emitDaemonInstallRuntimeWarning being added to buildGatewayInstallPlan. After that helper started covering the runtime warning, the doctor-side call became redundant but was never removed.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/commands/doctor-gateway-services.test.ts (two new it(...) cases inside the existing maybeRepairGatewayServiceConfig describe block).
• Scenario the test should lock in:
  1. needsNodeRuntimeMigration=true, resolveSystemNodeInfo returns an unsupported { path: "/usr/bin/node", version: "20.20.2", supported: false }, resolvePreferredNodePath returns the nvm Node 22 path → expect zero Gateway runtime notes from maybeRepairGatewayServiceConfig.
  2. Same audit/system-node fixtures, but resolvePreferredNodePath returns undefined → expect exactly one Gateway runtime note containing "not found".
• Why this is the smallest reliable guardrail: the bug is purely about which note(...) calls fire and with what gate. A unit test driving note calls through the existing mock surface is sufficient; a seam or e2e test would add scaffolding without catching anything the unit cannot.
• Existing test that already covers this (if any): None — doctor-gateway-services.test.ts had no coverage of the Gateway runtime panel emission paths before this PR.
• If no new test is added, why not: N/A (added).

User-visible / Behavior Changes

In the reported configuration (system Node below 22.14 + version-manager Node 22+ in use):

• Before: three ◇ Gateway runtime panels per openclaw doctor run — the third claiming "Node 22 LTS or Node 24 not found" while the first showed the daemon was using nvm Node 22.
• After: one ◇ Gateway runtime panel per run, with the correct "Using <version-manager-path> for the daemon" context.

When no Node 22+ is reachable anywhere (system, current process, or any version manager), the existing "Node 22 LTS or Node 24 not found" message still fires — its content and wording are unchanged, only the gate is corrected.

No config or default behavior changes elsewhere.

Diagram (if applicable)

Bug scenario: system Node 20 + nvm Node 22 in use

Before:
openclaw doctor
  └── Gateway runtime  (Panel 1 — "Using ~/.nvm/...node for the daemon. ...")
  └── Gateway runtime  (Panel 2 — same as Panel 1 minus the "Using" sentence)
  └── Gateway runtime  (Panel 3 — "Node 22 LTS or Node 24 not found"  ← contradicts Panel 1)

After:
openclaw doctor
  └── Gateway runtime  (Panel 1 — unchanged; "Using ~/.nvm/...node for the daemon. ...")

No-Node-22-anywhere scenario:

Before:                       After:
  Gateway runtime (Panel 1)     Gateway runtime (Panel 1)
  Gateway runtime (Panel 2)     Gateway runtime ("not found"; gated on resolvePreferredNodePath === undefined)
  Gateway runtime (Panel 3)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A — the change is a wording / dedup adjustment in a diagnostics output path.

Repro + Verification

Environment

• OS: Ubuntu 24.04 (Linux 6.8.0-110-generic)
• Runtime/container: Node v22.22.2 via nvm (system /usr/bin/node is v20.20.2 — the unsupported case the bug describes)
• Model/provider: claude-cli runtime (default agent); the bug is independent of model dispatch
• Integration/channel (if any): N/A — pre-runtime diagnostics path
• Relevant config (redacted): default-shape config with a single claude-cli auth profile; no special doctor or gateway flags

Steps

1. Ensure system Node is below 22.14 (e.g., /usr/bin/node reports v20.20.2) and a version-manager Node ≥ 22.14 is on PATH (e.g., ~/.nvm/versions/node/v22.22.2/bin/node).
2. From a source checkout: pnpm install --frozen-lockfile.
3. pnpm openclaw doctor --non-interactive and observe the Gateway runtime panel section.

Expected

• Exactly one ◇ Gateway runtime panel, containing the "Using <version-manager-path> for the daemon" context.
• No "Node 22 LTS or Node 24 not found" line in this scenario.

Actual (after this patch — matches expected)

• One ◇ Gateway runtime panel with the "Using …nvm…" context (verbatim capture in the Real-behavior-proof section above).
• Doctor proceeds to its normal next sections without the spurious "not found" note.

Evidence

• Failing test/log before + passing after — pnpm test src/commands/doctor-gateway-services.test.ts reports 26 passed (24 pre-existing + 2 new). Without the source change, the new tests fail (Panel 2 still fires unconditionally).
• Trace/log snippets
• Screenshot/recording — fenced terminal capture from pnpm openclaw doctor --non-interactive is in the Real-behavior-proof section above.
• Perf numbers (if relevant) — N/A.

Human Verification (required)

• Verified scenarios:
  • System Node 20.20.2 + nvm Node 22.22.2 in use → 1 panel after fix (3 panels before fix), captured in this PR body.
  • pnpm test src/commands/doctor-gateway-services.test.ts → 26/26 pass on Node 22.22.2.
  • pnpm check:changed → green on touched lanes (core test typecheck + extension test typecheck).
  • pnpm exec oxfmt --check --threads=1 src/commands/doctor-gateway-services.ts src/commands/doctor-gateway-services.test.ts → clean.
• Edge cases checked:
  • "No Node 22+ anywhere" path — the existing "not found" message still fires (covered by the second new unit test).
  • Bun-runtime path — emitDaemonInstallRuntimeWarning early-returns on runtime !== "node" (existing behavior, unchanged).
• What you did not verify:
  • macOS Homebrew Node fallback (no macOS host available locally — same resolvePreferredNodePath helper drives buildGatewayInstallPlan's runtime pick, exercised in the broader install path).
  • Windows + nvm-windows / WSL.
  • asdf, fnm, volta version managers (only nvm reproduced).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A.

Risks and Mitigations

• Risk: The new gate uses resolvePreferredNodePath from daemon/runtime-paths.js, which performs a which/where PATH lookup. On a host where the lookup raises (rare — already exercised by the existing install path), the doctor branch could differ in error shape.
  • Mitigation: buildGatewayInstallPlan (which fires earlier in the same function via buildExpectedGatewayServicePlan) already calls resolvePreferredNodePath indirectly through resolveDaemonInstallRuntimeInputs. If that resolution would error, doctor would have errored before reaching the new gate. The new call is therefore a no-op-cost duplicate on a happy path and equally fail-fast on a sad path.
• Risk: The "not found" message no longer fires in the Bun-runtime + nvm Node 22 case (audit flags Bun migration, system Node old, but a usable Node 22 exists). The user keeps the actionable Bun → Node migration prompt from the regular audit issues path; the redundant "Node not found" prompt is suppressed.
  • Mitigation: This is the intended behavior — Panel 3 should not claim "not found" when a Node 22+ binary is reachable. The audit's gatewayRuntimeBun issue still surfaces through the standard audit.issues.length flow further down the same function.

Changed files

• src/commands/doctor-gateway-services.test.ts (modified, +82/-1)
• src/commands/doctor-gateway-services.ts (modified, +10/-8)