docs: propose a single MSIX lifecycle for OpenClaw on Windows - #1073
Draft
llongley wants to merge 1 commit into
Draft
docs: propose a single MSIX lifecycle for OpenClaw on Windows#1073llongley wants to merge 1 commit into
llongley wants to merge 1 commit into
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
clawsweeper
Bot
added
rating: 🦪 silver shellfish
|
Codex review: needs real behavior proof before merge. Reviewed August 9, 2026, 10:51 AM ET / 14:51 UTC. ClawSweeper reviewWhat this changesThis PR adds an MSIX packaging-lifecycle proposal and updates release, uninstall, and storage-validator guidance for the Windows Companion. Merge readiness⛔ Blocked until real behavior proof from a real setup is added - 10 items remain Keep open. The draft contains four previously reported factual gaps and lacks real current-head package proof; it also needs a maintainer decision before becoming official lifecycle guidance. Likely related people: Caleb Eden (high confidence) and Barbara Kudiess (medium confidence). Priority: P2 Review scores
Verification
How this fits togetherThe Windows Companion is the packaged tray and Windows-node application, while SetupEngine manages the separately installed WSL gateway. These docs and the validator define how package installation, updates, retained state, and removal would be assessed before an MSIX release path is enabled. flowchart LR
A[Current Inno installer and ZIP updater] --> B[Windows Companion]
B --> C[Proposed App Installer servicing]
D[SetupEngine and WSL gateway] --> E[Maintenance and removal path]
C --> E
E --> F[Storage validation evidence]
F --> G[Release guidance]
Decision needed
Why: Current main explicitly pauses MSIX releases, and the proposed coordinator, servicing authority, and channel contracts establish new long-lived product behavior that source review cannot approve. Before merge
Findings
Agent review detailsSecurityNone. Review metrics
Merge-risk optionsMaintainer options:
Technical reviewBest possible solution: Keep MSIX paused until maintainers approve the lifecycle direction, then correct the proposal and validator and attach redacted proof from a real current-head Companion package run. Do we have a high-confidence way to reproduce the issue? Yes, source inspection reproduces one defect: the validator queries OpenClaw.Tray while current main's MSIX identity is OpenClaw.Companion. No real current-head Companion package execution was supplied for the changed validator guidance. Is this the best way to solve the issue? No. The plan needs the four factual corrections and explicit product approval before it can be the repository's recommended servicing model. Full review comments:
Overall correctness: patch is incorrect AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against 582a44713860. LabelsLabel justifications:
EvidenceWhat I checked:
Likely related people:
Rank-up movesOptional improvements that raise the rating; they are not merge blockers.
Rating scale
Overall follows the weaker of proof and patch quality. Workflow
HistoryReview history (36 earlier review cycles; latest 8 shown)
|
clawsweeper
Bot
added
merge-risk: 🚨 other
DrusTheAxe
reviewed
Aug 2, 2026
| @@ -0,0 +1,799 @@ | |||
| # One supported install, update, repair, and removal path for OpenClaw on Windows | |||
|
|
|||
| The way OpenClaw is installed, updated, repaired, and removed on Windows should be changed because those responsibilities are currently split across mechanisms that do not know about each other. This document presents the recommended design, the evidence behind it, the remaining validation gates, and the decisions that need team agreement. | |||
There was a problem hiding this comment.
General rule of thumb: Use max line length = 100 in .md files
Makes it easier to review, diff, etc
VS code is very good at reflowing Markdown, especially with the Reflow Markdown extension (alt-q to reflow paragraph, doesn't break URLs, etc)
|
|
||
| 1. Package the **Windows companion** as MSIX. The companion package contains the WinUI tray application, the Windows node hosted in that process, setup and connection libraries, and all required Windows runtime files for one architecture. | ||
| 2. Keep the **gateway separate from the companion package**, both now and if a Windows-hosted gateway becomes available. The current gateway remains a separately installed WSL component. A Windows-hosted gateway appears likely to arrive through separate OpenClaw and Windows platform work, but it has no published schedule or contract at the time of writing. This proposal allows the companion to ship without it and adopt it later; construction of that gateway is not proposed here. | ||
| 3. Install each supported companion channel through App Installer. A `.appinstaller` document associates the installed package with that channel's HTTPS update source so Windows can check, stage, verify, and apply later companion versions. |
There was a problem hiding this comment.
The App Installer app is merely one of many possible ways to install MSIX packages. Alternatives include PowerShell cmdlets, WinGet, the Microsoft Store, Intune, and many more.
All produce equivalent results.
|
|
||
| 1. Package the **Windows companion** as MSIX. The companion package contains the WinUI tray application, the Windows node hosted in that process, setup and connection libraries, and all required Windows runtime files for one architecture. | ||
| 2. Keep the **gateway separate from the companion package**, both now and if a Windows-hosted gateway becomes available. The current gateway remains a separately installed WSL component. A Windows-hosted gateway appears likely to arrive through separate OpenClaw and Windows platform work, but it has no published schedule or contract at the time of writing. This proposal allows the companion to ship without it and adopt it later; construction of that gateway is not proposed here. | ||
| 3. Install each supported companion channel through App Installer. A `.appinstaller` document associates the installed package with that channel's HTTPS update source so Windows can check, stage, verify, and apply later companion versions. |
There was a problem hiding this comment.
Developers are encouraged to embed a .appinstaller file in their .msix packge. This way there's no need for separate files.
(Admins after the fact can't embed a .appinstaller file into a signed package w/o breaking the signing integrity, thus admins adding .appinstaller to a package MUST put it outside the package. But for developers authoring the package, embedding ensures even if someone directly installs a .msix the .appinstaller's information will be used for updates, repair, etc)
| 1. Package the **Windows companion** as MSIX. The companion package contains the WinUI tray application, the Windows node hosted in that process, setup and connection libraries, and all required Windows runtime files for one architecture. | ||
| 2. Keep the **gateway separate from the companion package**, both now and if a Windows-hosted gateway becomes available. The current gateway remains a separately installed WSL component. A Windows-hosted gateway appears likely to arrive through separate OpenClaw and Windows platform work, but it has no published schedule or contract at the time of writing. This proposal allows the companion to ship without it and adopt it later; construction of that gateway is not proposed here. | ||
| 3. Install each supported companion channel through App Installer. A `.appinstaller` document associates the installed package with that channel's HTTPS update source so Windows can check, stage, verify, and apply later companion versions. | ||
| 4. Use the same small signed **per-user Inno coordinator** for WSL-backed Stable, Preview, and installed Dev channels. This creates an additional Windows Installed Apps maintenance entry alongside each channel's companion MSIX; it is not another package containing the companion. It installs a signed `OpenClawMaintenance.exe` program that inventories, migrates, repairs, and removes OpenClaw components even after the companion has been removed. The coordinator also installs the companion through its approved `.appinstaller` source so that the update association is recorded. |
There was a problem hiding this comment.
'same small signed' - odd phrasing. Typo?
| 4. Use the same small signed **per-user Inno coordinator** for WSL-backed Stable, Preview, and installed Dev channels. This creates an additional Windows Installed Apps maintenance entry alongside each channel's companion MSIX; it is not another package containing the companion. It installs a signed `OpenClawMaintenance.exe` program that inventories, migrates, repairs, and removes OpenClaw components even after the companion has been removed. The coordinator also installs the companion through its approved `.appinstaller` source so that the update association is recorded. | ||
| 5. Keep SetupEngine responsible for the current WSL gateway. Its acquisition path should be strengthened so reviewed gateway releases are described by signed, immutable metadata and exact payload hashes rather than relying on a mutable HTTPS installation script. | ||
| 6. Support Stable, Preview, and installed Dev side by side using separate package identities, URI protocol handlers, state roots, startup registrations, maintenance registrations, `.appinstaller` feeds, local Model Context Protocol (MCP) endpoints and tokens, and app execution aliases when approved. Versions within one channel update in place. Installing one channel must not force removal of another. | ||
| 7. Treat the `windows.customInstall` MSIX extension, which declares install, repair, and uninstall actions, as a promising alternative to the coordinator. It should not be used until the [five clearance requirements](#windowscustominstall) covering platform guidance, production lifecycle proof, managed deployment, Store review when applicable, and OpenClaw approval are met. The disposable prototype established only action ordering and interactive-user file-system scope. |
There was a problem hiding this comment.
Treat the
windows.customInstallMSIX extension...as a promising alternative to the coordinator.
It's not.
The windows.customInstall extension is only usable by MSIXVC and as noticed on the docs
This element is currently intended to be used only by certain types of desktop PC games that are published by Microsoft and our partners.
There is no intention to change this restriction at this time.
What are you trying to accomplish? There may be other (supported) ways to do so.
Are you familiar with the windows.preInstalledConfigTask and windows.updateTask extensions? See https://learn.microsoft.com/en-us/windows/uwp/launch-resume/run-a-background-task-during-updatetask for more details.
Are you familiar with Uninstall/Reset/Repair Tasks #2779? If this interests you please share your feedback at that link.
To name a few. Devil's in the details so it's hard to say more without a better understanding of what you're trying to accomplish (sorry, I'm not familiar with the coordinator's details).
| 9. Keep the current full Inno companion installer and ZIP updater until the MSIX path has passed installation, update, migration, repair, recovery, and complete-removal gates. The full Inno companion payload should be retired only after every responsibility has a validated replacement. The small Inno coordinator in item 4 remains part of the WSL-period design. | ||
| 10. Advance the design through explicit validation gates. The package boundary, custom-install action mechanics, and coordinator removal ordering have been established by prototypes. Production-trusted signing, App Installer update association and package replacement, package repair, managed deployment, ARM64 runtime behavior, and migration of real OpenClaw state remain required before the design is supported. | ||
|
|
||
| MSIX is recommended for the companion for the reasons listed under [Why MSIX is recommended for the companion](#why-msix-is-recommended-for-the-companion). Those benefits apply only to the companion MSIX. Comparable gateway assurances should be provided separately through SetupEngine's signed release metadata, exact payload verification, inventory, transactional update, and recovery contract. Neither mechanism reduces the permissions of the full-trust tray and in-process Windows node. |
There was a problem hiding this comment.
Those benefits apply only to the companion MSIX.
Is OpenClaw for Windows == companion + gateway?
I'm curious what the gateway would need that MSIX currently doesn't provide.
| | `windows.customInstall` | It can declare package install, repair, and uninstall actions and request user-context execution. | Technically promising but not a baseline. The [five clearance requirements](#windowscustominstall) apply: platform eligibility and semantics; production-signed App Installer lifecycle proof, including repair, removal, failure recovery, and target-user execution; managed-deployment proof; Store approval when applicable; and OpenClaw release and security approval. | | ||
| | Direct MSIX | It provides an immutable signed companion artifact and works for offline or controlled installation. | Supported as an artifact, but not the primary self-service path because a direct MSIX does not establish an update association. | | ||
| | Portable ZIP | It is useful for development, diagnostics, and recovery. | Retain as a support artifact. It is not an installed product lifecycle. | | ||
| | Put the gateway in the companion MSIX | It appears to simplify first acquisition. | Rejected. The gateway is optional, writable, long-running, independently versioned, and owned by a different update and repair lifecycle. | |
There was a problem hiding this comment.
You're missing another alternative: Put the gateway in its own MSIX
That would address most issues if packing companion + gateway in one MSIX package. I'm curious if it addresses all, or why not.
| | Small per-user Inno coordinator plus companion MSIX | It keeps a maintenance executable available after package removal and naturally runs against the current user's WSL and CurrentUser state. | Recommended for each installed WSL-backed Stable, Preview, and Dev channel. It is a temporary coordinator, not a second copy of the companion. | | ||
| | Machine-context MSI coordinator | It offers standardized Windows Installer product, repair, logging, and enterprise policy concepts. | Rejected as the baseline for the current per-user WSL lifecycle. WSL registration and CurrentUser credentials require target-user execution. A machine-context design would need a supported way to identify and act as that user, and the prototype demonstrated the risk of a success result scoped only to `SYSTEM`. | | ||
| | Per-user MSI coordinator | It could run in the correct user context while retaining Windows Installer semantics. | Not selected. It adds MSI component, upgrade, and custom-action complexity without a demonstrated lifecycle advantage over the existing Inno expertise. | | ||
| | `windows.customInstall` | It can declare package install, repair, and uninstall actions and request user-context execution. | Technically promising but not a baseline. The [five clearance requirements](#windowscustominstall) apply: platform eligibility and semantics; production-signed App Installer lifecycle proof, including repair, removal, failure recovery, and target-user execution; managed-deployment proof; Store approval when applicable; and OpenClaw release and security approval. | |
There was a problem hiding this comment.
It can declare an MSIXVC package...
Not a general purpose solution. Not viable for your scenarios today, and unlikely ever to be. See https://github.com/openclaw/openclaw-windows-node/pull/1073/changes#r3699825644 for more information
|
|
||
| Store publication during the WSL period remains difficult because an ordinary Store listing does not deliver the separate Inno coordinator. A Store release should wait for one of these: | ||
|
|
||
| - OpenClaw is approved to use `windows.customInstall` and the production lifecycle passes; |
There was a problem hiding this comment.
I wouldn't expect to see this. See previous comments
| | Microsoft Store | Deferred until representative policy and submission evidence covers full-trust execution, requested capabilities, external gateway lifecycle, state, identity, and complete removal. | | ||
| | WinGet | Added only after it points to an approved installer and the resulting update authority is unambiguous. | | ||
|
|
||
| Store publication during the WSL period remains difficult because an ordinary Store listing does not deliver the separate Inno coordinator. A Store release should wait for one of these: |
There was a problem hiding this comment.
What would be required for coordinator to be an MSIX package?
What of these (if anything) is a problem achieving with MSIX?
(Sorry, I'm not familiar with coordinator or the InnoSetup details)
clawsweeper
Bot
added
merge-risk: 🚨 compatibility
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Problem This Solves
Installing, updating, repairing, and removing OpenClaw on Windows is spread across Inno Setup, a ZIP updater, in-progress MSIX packaging, SetupEngine, and a separately installed WSL gateway. Nothing in the repository says how those pieces are meant to fit together, which of them MSIX should own, or what we'd need to prove before retiring the current installer.
Why This Change Was Made
This adds a proposal (
docs/MSIX_LIFECYCLE_PLAN.md) for what MSIX would own: the app package only, with the WSL gateway installed and updated on its own path, app updates delivered through App Installer, and the same small per-user maintenance program installed alongside each of Stable, Preview, and installed Dev. It separates what the prototypes proved from what they didn't, so the unproven parts don't read as settled. It covers current behavior, the alternatives it rules out and why, what the prototypes actually showed, the implementation steps, and what each step has to prove before the next one starts. The current Inno installer and ZIP updater stay in place until the MSIX path clears those gates.It also links the release and uninstall docs to the proposal, and corrects the uninstall recovery guidance and the guidance in the MSIX storage validation script so they match the per-channel package identities, the startup task, the current state paths, and the restricted
windows.customInstallextension.User Impact
No runtime behavior changes. Maintainers and reviewers now have one place in the repository to decide how OpenClaw on Windows should be packaged and serviced, along with the evidence and validation still needed before anyone implements it.
Evidence
windows.customInstallactions, signed deployment trust, per-user coordination, removing the app package and the maintenance entry in either order, and cleanup run as the system account instead of the signed-in user. Package composition was checked for both x64 and ARM64 builds, but ARM64 runtime behavior is one of the gates still open.Change Type
Scope
winnodeValidation
git diff --checkscripts/validate-msix-storage-paths.ps1.\build.ps1dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj --no-restore- 3,399 passed, 32 skippeddotnet test .\tests\OpenClaw.Tray.Tests\OpenClaw.Tray.Tests.csproj --no-restore- 2,022 passedThe first Tray test run hit one timing-related failure in
QueuedSend_LifecycleStartBeforeAck_PromotesByIdempotencyKey. That test passed when rerun on its own, and the full required build and test set passed on the final rerun.Real Behavior Proof
a9cfa04a.\build.ps1; the required Shared and Tray test projects;git diff --check; PowerShell parser validation; repository-relative link, anchor, and source line-range validationYes/No/N/A): N/ASecurity Impact
Yes/No): NoYes/No): NoYes/No): NoYes/No): NoYes/No): NoYes, explain the risk and mitigation: N/AThe proposal writes down future requirements for package trust, gateway payload verification, credential storage, cleanup, and fail-closed command execution, but this PR doesn't implement any of them.
Compatibility and Migration
Yes/No): YesYes/No): NoYes/No): NoReview Conversations