Keep the local WSL OpenClawGateway version in lock-step with the Windows Tray app

[iamalin]

Summary / Requirement

When the Windows Tray app provisions an OpenClawGateway in the local WSL environment, that gateway's version must be able to follow the Tray app through compatibility upgrades. Today the gateway version is frozen at install time and never moves again, even after the Tray app itself auto-updates. This can leave the Tray app running against a gateway version it was never built or tested against.

We want the local WSL gateway to stay in lock-step with the Tray app: the Tray app requires one specific gateway version (the one it ships with), detects when the installed gateway does not match, and drives an in-place upgrade to bring them into alignment.

Context / Background

Current behavior:

• During first-run onboarding, the Setup Engine installs a pinned gateway/CLI version into a dedicated WSL distro (OpenClawGateway). The version comes from a compile-time constant (the "LKG" — Last Known Good — version) baked into the Tray build.
• After that install, the Tray app never tracks, compares, or upgrades the WSL gateway again. The gateway is effectively frozen at whatever version was installed.
• The Tray app does have its own update mechanism (self-update of the Windows executable via GitHub Releases, checked at startup), but that path only updates the Windows EXE — it never touches the WSL gateway.

The problem this creates:

Because the Tray EXE updates itself automatically and quickly, while the gateway stays frozen, the two drift apart over time. A newly updated Tray app can end up talking to an older gateway. Nothing today notices or corrects this.

Why lock-step instead of broad compatibility:

Supporting "one Tray version compatible with many gateway versions" turns compatibility testing into an M×N matrix — every Tray release would have to be validated against every historical gateway version. That cost is prohibitive. Instead, we constrain each Tray version to require exactly one gateway version (the one it ships with), collapsing the matrix to M×1: each Tray build is only ever responsible for the single gateway version it targets.

Design philosophy alignment:

The repo already establishes a "Tray-driven, pinned version, human-gated" model — CI only warns (non-blocking) when the pinned version drifts from upstream latest, and an automation workflow opens a draft PR so a human reviews and merges every version bump. Version advancement is always a deliberate, gated decision — never an automatic chase of the newest upstream release. This proposal extends that same philosophy to the runtime: the Tray app drives the gateway to its own required version, not to whatever is newest on npm.

Goals

• The local WSL gateway version "travels with" the Tray EXE: Tray self-update ships a new required version → Tray detects the installed gateway no longer matches → prompts the user → user confirms → Tray upgrades the gateway in place to the required version.
• Detect and surface version mismatch clearly, without silently tolerating drift.
• Keep this entirely separate from the existing Tray EXE self-update — two independent mechanisms that happen to share a UI location.

Non-Goals

• Not chasing npm "latest" — the upgrade target is always the version the Tray app ships with, preserving the human-gated review model.
• Not reusing the gateway's own self-update path (the upstream update.available / update.run mechanism), which would chase latest and is unverified against our locked-down WSL appliance.
• Not re-running the full onboarding pipeline or touching the WSL distro lifecycle — no distro unregister/recreate. This is an in-place CLI upgrade + service restart only.
• Not managing remote gateways — this applies only to the local, Tray-provisioned WSL gateway.
• Not changing the Tray EXE self-update mechanism.

Design Decisions

1. Constraint strength — strict version lock with a strong prompt, but no hard block.
   When the gateway version does not match the Tray's required version, the Tray shows a prominent, persistent prompt guiding the user to a one-click upgrade — but it does not refuse the connection or disable features. This safety valve exists because the upgrade path (a network-dependent install script run inside WSL) can fail and currently has no rollback; a hard block would turn "upgrade failed" into "completely unusable / bricked gateway." This still captures the full M×1 testing benefit without betting availability on every upgrade succeeding.

2. Match criterion — exact equality.
   The gateway version must be strictly equal to the Tray's required version. Any difference means "needs alignment," regardless of whether the gateway is older or newer (e.g. a user who manually installed a newer gateway is also prompted to align back to the Tray's required version).

3. Upgrade trigger — user-confirmed.
   Mismatch is detected and surfaced, but the actual upgrade only runs after the user explicitly confirms. No silent background upgrade.

4. Detection point — after the WSL distro is ready (not after a WebSocket connection).
   The check runs once the local WSL distro is up and only for the local, Tray-provisioned WSL gateway. It reads the installed version directly from WSL by running openclaw --version — it does not wait for a successful gateway connection or handshake. The natural hook is the existing startup keepalive flow, which already ensures the distro is running and already gates on "is this the local WSL gateway." See "Why read the version from WSL" below for the rationale, including why gating on a WebSocket connection would be self-defeating.

Why read the version from WSL instead of the handshake

The gateway reports a version over its connection handshake, and the Tray already receives it. However, for a lock-step install check, reading the version directly from WSL (openclaw --version) is both more correct and more robust:

• It measures the right thing. The handshake version is what the running gateway process reports (what's currently executing in memory). The lock-step model cares about what's installed on disk — the openclaw CLI version that the install script put there. These can diverge: right after an upgrade replaces the on-disk CLI but before the gateway service restarts, the handshake still reports the old (still-running) version. openclaw --version reads the on-disk CLI — the same artifact install-cli.sh --version <X> produces — so we compare with the same yardstick we install with. The loop is closed end to end.
• It's decoupled from the protocol layer — so the check must not be gated on a connection. Obtaining the handshake version requires a successful protocol negotiation and connection. If a gateway is old enough that protocol negotiation fails, the handshake version is unavailable — precisely when we most need to prompt for alignment. Running openclaw --version only requires the WSL distro to be running (not the gateway service, not a WebSocket): as long as WSL can run a command, we get the version. Crucially, this means the trigger must not be a successful gateway connection either — gating the check on "connected" would re-introduce the exact coupling we are trying to remove, and would silently skip the check for a gateway too old to connect (leaving the user stuck with no upgrade prompt). Reading from WSL after the distro is ready keeps "what version is installed" fully independent of "can we connect."
• The prerequisite is already satisfied at startup. The Tray already runs a keepalive step at startup that ensures the local WSL distro is up and running (and already decides whether the active gateway is the local WSL one). The version check attaches naturally to that flow — no new precondition, no waiting on the gateway service or the connection.
• The primitives already exist. openclaw --version is already used during onboarding to verify the install; the Tray runtime already runs WSL commands (for keepalive and gateway start/stop) via the same command runner; and the required PATH prefix for invoking openclaw is already defined. Reuse is straightforward.

The handshake-reported version is still useful for display (it tells the user what's currently running) and remains shown in Settings, but it is no longer the basis for the lock-step decision.

How It Works (Mechanism)

The feature is a self-contained loop. It reuses the existing startup keepalive flow and the existing WSL command/control primitives — it does not invent a new install pathway, and it does not depend on the gateway connection/handshake.

1. Version basis.
   The Tray app already carries a compile-time "required gateway version" constant (the LKG). When the Tray EXE self-updates, a new build ships with a (possibly) new required version. That constant is the single source of truth for what the gateway should be.

2. Detect after the distro is ready, by reading WSL directly.
   Hooked into the existing startup keepalive flow: once the local WSL distro is confirmed running, and only when the active gateway is the local, Tray-provisioned WSL gateway, the Tray runs openclaw --version inside the distro (with the standard PATH prefix) and parses the installed CLI version from stdout. It compares that against its required version using an exact-equality check.

   • Equal → nothing to do.
   • Not equal (older or newer) → mark "needs alignment."
   • Unparseable / command fails → conservatively do nothing (log only), to avoid false alarms.

   This does not wait for a WebSocket connection or handshake — the version comes straight from disk, so the check works even when the gateway is too old to connect.

3. Surface the mismatch.
   A mismatch is exposed through app state so the UI can react. In the Settings "Gateway info" area (which already displays the gateway version), a strong, persistent prompt appears — "gateway version does not match the required version — upgrade to align" — with an upgrade action. A one-time toast notification can also alert the user and deep-link into Settings. (There is already an unused "Gateway update required" string resource that fits this exactly.)

4. Upgrade on confirmation.
   When the user confirms, a lightweight upgrade coordinator:

   • resolves the local WSL distro name,
   • ensures the WSL VM / distro is ready,
   • runs the existing install-script command (the same install-cli.sh --version <required> mechanism used at onboarding, with its built-in HTTPS/safety constraints) pinned to the Tray's required version,
   • restarts the gateway service via the existing WSL gateway control primitive,
   • re-reads openclaw --version from WSL to confirm the on-disk version is now aligned (more direct and faster than waiting for a fresh handshake, and unaffected by the protocol layer),
   • lets the existing reconnect-with-backoff logic bring the connection back,
   • reports success/failure via a toast.

   Crucially this is a lightweight path — it drives the install command and the service restart directly. It does not run the full multi-step setup pipeline and does not clean/recreate the distro, so an upgrade can never be destructive to existing gateway state.

5. Safety valve.
   If the upgrade fails (network, script error, WSL not ready), the old gateway remains usable and connected. The mismatch prompt persists until alignment succeeds, so the user can retry — but they are never left with a broken, unusable gateway.

6. User control.
   A settings toggle (default on) governs whether the Tray performs this mismatch check and prompt. The upgrade itself always requires an explicit user click regardless of the toggle.

Relationship to Tray EXE self-update

These are two independent mechanisms with adjacent UI:

	Tray EXE self-update (existing)	Gateway alignment (this issue)
Target	Windows EXE	WSL gateway/CLI
Version read from	GitHub Releases (latest tag)	openclaw --version inside WSL (on-disk CLI)
Upgrade source	GitHub Releases	install script, pinned to Tray's required version
Trigger	Startup, synchronous	Startup keepalive (after distro ready), async
Effect	Replace EXE, restart Windows app	In-place CLI upgrade + gateway restart, Tray auto-reconnects

The net effect: Tray self-update advances the required gateway version → next startup detects (by reading WSL) that the installed gateway no longer matches → user is prompted to align. The two stay coupled through the required-version constant, while remaining separate execution paths.

Open Questions / Follow-ups

• Upgrade atomicity & rollback. The current install path has no rollback. Hardening this (atomic upgrade, restore-previous-on-failure, offline handling) is a prerequisite if we ever want to tighten the constraint from "strong prompt" to "hard block."

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 1, 2026, 3:58 AM ET / 07:58 UTC.

Summary
Keep open: current main pins the gateway version for first-run install and has WSL keepalive/control primitives, but it does not compare the installed WSL CLI version with the Tray-required LKG or offer an in-place alignment upgrade.

Reproducibility: yes. source inspection gives a high-confidence reproduction path: install a local gateway with one pinned LKG, update to a Tray build with a different GatewayLkgVersion, and observe that startup keepalive starts the distro without comparing or upgrading the installed CLI version.

Next step
Needs maintainer approval for the strict local-gateway lock-step policy, default-on setting, and upgrade/downgrade UX before an automated repair lane should implement it.

Review details

Best possible solution:

Add a Tray-owned local WSL gateway alignment service that runs after the setup-managed distro is ready, reads the installed CLI version from WSL, compares it to GatewayLkgVersion.LkgVersion, surfaces mismatch state in Settings/toast, and runs the pinned install plus restart/recheck only after user confirmation.

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

Yes, source inspection gives a high-confidence reproduction path: install a local gateway with one pinned LKG, update to a Tray build with a different GatewayLkgVersion, and observe that startup keepalive starts the distro without comparing or upgrading the installed CLI version.

Is this the best way to solve the issue?

Unclear until maintainers approve the product direction. If lock-step is accepted, the requested path is the maintainable implementation shape because it reuses the existing LKG pin, WSL command runner, install command, and WslGatewayController restart instead of re-running onboarding.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The requested behavior changes startup WSL command execution, user prompting, in-place install, and gateway restart semantics; maintainers should approve the failure and retry policy before implementation.
• Exact equality plus a default-on check can prompt users who intentionally installed a different local gateway version, so downgrade/override UX needs explicit product handling.

Codex review notes: model internal, reasoning high; reviewed against 4166e0fd63f8.

Label changes

Label changes:

• add P2: This is a core local WSL gateway compatibility improvement with real user impact after Tray updates, but it is not an emergency or confirmed live regression.
• add impact:other: The issue concerns local gateway version drift and upgrade alignment, which is maintainer-visible but outside the specific owned impact categories.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a core local WSL gateway compatibility improvement with real user impact after Tray updates, but it is not an emergency or confirmed live regression.
• impact:other: The issue concerns local gateway version drift and upgrade alignment, which is maintainer-visible but outside the specific owned impact categories.

Evidence reviewed

What I checked:

• Pinned install basis: GatewayLkgVersion defines the embedded LKG and only applies it to setup config when the gateway version is unset and the default install URL is used. (src/OpenClaw.SetupEngine/GatewayLkgVersion.cs:5, 4166e0fd63f8)
• Initial install path only: InstallCliStep builds the install script command from ctx.Config.Gateway.Version and verifies openclaw --version during setup, but this is in the setup pipeline rather than a Tray runtime alignment loop. (src/OpenClaw.SetupEngine/SetupSteps.cs:1203, 4166e0fd63f8)
• Startup keepalive lacks version comparison: WslGatewayKeepAliveService resolves the active local distro and starts a detached wsl sleep process; the inspected startup path does not run openclaw --version or compare to GatewayLkgVersion.LkgVersion. (src/OpenClaw.Tray.WinUI/Services/WslGatewayKeepAliveService.cs:29, 4166e0fd63f8)
• Settings only displays connected gateway self version: SettingsPage.RefreshGatewayInfo copies GatewaySelf.VersionText from the connected handshake state and otherwise shows dashes; there is no persistent mismatch prompt or upgrade action in this path. (src/OpenClaw.Tray.WinUI/Pages/SettingsPage.xaml.cs:273, 4166e0fd63f8)
• Existing restart primitive can support a future fix: WslGatewayController already builds start/stop/restart commands with the OpenClaw WSL PATH prefix, which supports the issue's proposed restart step but does not perform version installation or recheck by itself. (src/OpenClaw.Connection/WslGatewayController.cs:32, 4166e0fd63f8)
• Narrow protocol incompatibility UI is not the requested alignment loop: Current chat tests cover a connected gateway missing mainSessionKey as an incompatible gateway signal, which is narrower than detecting installed WSL CLI drift before a successful gateway connection. (tests/OpenClaw.Tray.Tests/OpenClawChatDataProviderTests.cs:1246, 4166e0fd63f8)

Likely related people:

• ranjeshj: Introduced the LKG pinning and drift-update model that this issue extends from first-run install into runtime local WSL alignment. (role: introduced behavior; confidence: high; commits: 45df0763e1ca, dcc77f55e2c9, ca8c6772db81; files: src/OpenClaw.SetupEngine/GatewayLkgVersion.cs, src/OpenClaw.SetupEngine/SetupSteps.cs, .github/workflows/gateway-lkg-update.yml)
• indierawk2k2: Merged history shows prior ownership of the local WSL gateway lifecycle, including keeping the WSL gateway alive across tray restarts and Windows logon. (role: feature owner; confidence: medium; files: src/OpenClaw.Tray.WinUI/App.xaml.cs, src/OpenClaw.Tray.WinUI/Services/WslGatewayKeepAliveService.cs)
• AlexAlves87: Extracted WslGatewayKeepAliveService from App.xaml.cs, making the keepalive hook the natural place to attach a source-level version check. (role: recent area contributor; confidence: medium; commits: b175439fbfd4; files: src/OpenClaw.Tray.WinUI/Services/WslGatewayKeepAliveService.cs)
• bkudiess: Added WSL gateway dependency-recovery and shared WslGatewayController restart helpers that a future alignment coordinator would likely reuse. (role: adjacent owner; confidence: medium; commits: 1e6951331f1c; files: src/OpenClaw.Connection/WslGatewayController.cs, docs/ONBOARDING_WIZARD.md)

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.