From f7b880f9b266a2e27cd4390d5d55ce21c9b25a1e Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Thu, 16 Jul 2026 15:04:13 -0700 Subject: [PATCH 01/11] RFC: OpenClaw MSIX packaging for Windows Add proposal for a dedicated openclaw-msix-packaging repository that builds a package-specific host app and pinned OpenClaw payload into a signed MSIX, with the host app provisioning a dedicated agent user and session-isolated Agent Session to run the Gateway. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 93b33c00-2350-43f2-b727-43d5bdb7d057 --- rfcs/0010-openclaw-msix-packaging.md | 292 +++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 rfcs/0010-openclaw-msix-packaging.md diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md new file mode 100644 index 00000000..08c6dac0 --- /dev/null +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -0,0 +1,292 @@ +--- +title: OpenClaw MSIX Packaging for Windows +authors: + - Linus Huang +created: 2026-07-14 +last_updated: 2026-07-16 +status: draft +issue: +rfc_pr: +--- + +# Proposal: OpenClaw MSIX Packaging for Windows + +## Summary + +Define a reproducible packaging and release pipeline for deploying OpenClaw on +Windows as an MSIX package. A dedicated `openclaw/openclaw-msix-packaging` +repository will build a package-specific host app and an OpenClaw payload +tarball from a commit pinned for each MSIX release, validate +architecture-specific artifacts with GitHub Actions, and publish them through +GitHub Releases. The installed host app will provision and manage an Agent +Session under a dedicated agent user, then run the OpenClaw Gateway inside +that session. This provides stable app identity, enterprise-friendly +deployment, and a contained runtime boundary for OpenClaw on Windows. + +## Motivation + +Enterprise administrators need a way to identify, inventory, approve, deploy, +and remove OpenClaw consistently from managed Windows devices. A dedicated +OpenClaw MSIX artifact gives the Windows installation a stable, reviewable +package identity, declared capabilities, and a standard Windows +application-management surface, inspectable and governed like any other +managed application. + +Package identity alone is not a runtime security boundary for an autonomous +agent: the OpenClaw Gateway can execute tools, connect to services, and act on +a user's behalf. The managed deployment should therefore run the Gateway in a +separate, session-isolated Agent Session under a dedicated agent user rather +than the interactive user's own session. The host app included in the MSIX +package is responsible for provisioning that session, staging the OpenClaw +payload, and controlling the Gateway lifecycle. + +Keeping the packaging definition in a dedicated repository also supports trust +and maintainability: contributors and enterprise reviewers can determine +exactly which source revision, capabilities, build tools, signing steps, and +release checks produced a given OpenClaw MSIX artifact. + +## Goals + +- Create an `openclaw/openclaw-msix-packaging` repository containing the + Windows host app, package definitions, release workflows, validation, and + contributor documentation. +- Produce reviewable and reproducible MSIX builds from an explicitly pinned + OpenClaw source revision as the only external product source input. +- Include a package-specific host app that provisions the dedicated agent user, + creates the Agent Session, and manages the packaged Gateway lifecycle. +- Publish signed MSIX artifacts under a stable OpenClaw-controlled identity, + with checksums and source-version metadata, through GitHub Releases. +- Make the [Windows companion app](https://github.com/openclaw/openclaw-windows-node) present **Install OpenClaw MSIX** as the + default or preferred option for creating a local OpenClaw Gateway. + +## Non-Goals + +- Publishing through or depending on the Microsoft Store, including + Store-managed updates. +- Enabling unattended package auto-update by default. IT administrators remain + responsible for managing package updates. +- Defining every enterprise runtime policy, data-loss-prevention rule, or tool + authorization rule that may be applied to OpenClaw. + +## Proposal + +### Repository and ownership + +Create a dedicated `openclaw/openclaw-msix-packaging` repository. It owns the +Windows-specific host app and the packaging of OpenClaw source into +release-ready MSIX artifacts. The repository should contain: + +- Source for the package-specific host app. +- MSIX manifests and package assets. +- Scripts that acquire and verify a pinned OpenClaw source revision. +- Build orchestration for x64 and ARM64. +- GitHub Actions workflows for pull requests, release candidates, and releases. +- Documentation for local builds, release operations, signing, installation, + upgrade, rollback, and uninstall behavior. + +The only product source input is the OpenClaw repository. The packaging +repository must not carry a long-lived copy of OpenClaw source; each MSIX +release instead pins the exact OpenClaw source revision it packages. Build +toolchains and packaging dependencies are locked in the packaging repository. + +The host app is packaging infrastructure specific to the Windows MSIX +deployment. It is not a fork of the OpenClaw Gateway and must keep its +responsibilities narrow: package activation, Agent Session provisioning, +Gateway lifecycle, health, repair, and cleanup. + +### Build and release pipeline + +GitHub Actions should provide three levels of validation: + +1. Pull requests build non-production packages and run manifest, payload, and + installation tests without access to production signing credentials. +2. Release-candidate workflows build from a clean checkout using the pinned + OpenClaw source revision and produce artifacts for manual validation. +3. A protected release workflow signs the approved artifacts, verifies the + resulting signatures and payloads, and publishes a GitHub Release. + +The release workflow should: + +- Restore dependencies from locked manifests, then build the host app, + OpenClaw payload, and required runtime components for x64 and ARM64. +- Produce architecture-specific `.msix` files (and a combined `.msixbundle`, + if adopted), validating package identity, capabilities, entry points, and + payload inventory. +- Sign production artifacts with an OpenClaw-controlled code-signing identity + and verify the resulting signature. +- Generate SHA-256 checksums, an SBOM, and build provenance. +- Publish release notes identifying the OpenClaw source revision and any + security-relevant packaging changes. + +Production signing credentials must be supplied through a protected signing +service or GitHub environment. They must never be committed to the repository +or exposed to pull-request workflows. + +### Package and runtime architecture + +The MSIX package provides OpenClaw's Windows package identity, a Gateway +payload built from a pinned source revision, declared capabilities, packaged +entry points, and a host app that manages the contained runtime. + +On first-run setup, the host app should: + +1. Verify that the package identity, publisher, architecture, OpenClaw version, + and payload inventory match the signed package metadata. +2. Provision a dedicated agent user through the supported Windows APIs. +3. Create a session-isolated Agent Session for that agent user. +4. Extract the OpenClaw payload from its packaged tarball and stage it inside + the Agent Session. +5. Start a terminal session within the Agent Session that runs OpenClaw's + onboarding, matching the onboarding experience of a standard OpenClaw + install. +6. Start and stop the Gateway through a narrow lifecycle interface. +7. Clean up or explicitly preserve Gateway state and Agent Session resources + during repair, reset, rollback, and uninstall. + +The host app should expose a stable way for OpenClaw clients and nodes to obtain +the Gateway endpoint and complete normal pairing. Those clients are consumers +of a running Gateway; they do not own the Agent Session or Gateway lifecycle. + +The Gateway must not silently fall back to running under the interactive user +when Agent Session provisioning fails. Enterprise policy must be able to require the session-isolated mode and disable +fallbacks. + +Package data and long-lived Gateway state must have an explicit lifecycle. +Updating or uninstalling the MSIX package must not leave an unknown running +Gateway, orphaned agent account, or inaccessible state. If Windows cannot +remove Agent Session state transactionally with package removal, the host app +must expose a supported cleanup flow and clearly warn administrators before +uninstall. + +```mermaid +flowchart LR + Pin[Pinned OpenClaw source revision] --> Tarball[OpenClaw payload tarball] + Tarball --> CI[MSIX build and validation] + Host["C# MSIX host app source"] --> CI + CI --> Sign[Protected signing step] + Sign --> GH[OpenClaw MSIX GitHub Release] + GH --> Install[User or enterprise installation] + Install --> App[MSIX host app] + App --> User[Dedicated agent user] + App --> Session[Session-isolated Agent Session] + User --> Session + App --> Stage["Extract tarball and stage payload"] + Stage --> Session + Session --> Terminal["Terminal session: OpenClaw onboarding"] + Terminal --> Gateway[OpenClaw Gateway] +``` + +**Figure 1.** The packaging repository builds an OpenClaw payload tarball from +a pinned source revision and packages it with a C# host app, preferably +published with NativeAOT, into the MSIX. After installation, that host app +provisions the dedicated agent user and Agent Session, extracts and stages the +payload into that session, and starts a terminal session that runs OpenClaw's +onboarding — the same onboarding experience as a standard OpenClaw install — +before the Gateway runs. MSIX identity and runtime isolation are complementary +controls. + +### Distribution and updates + +GitHub Releases are the canonical distribution point for the first version of +this proposal. A release should provide direct artifact links, checksums, +signatures, provenance, release notes, and an SBOM. + +For enterprise deployments, the initial update flow is administrator +controlled: + +1. An administrator selects an exact OpenClaw MSIX release. +2. The administrator reviews the release notes, declared package + capabilities, included component versions, signature, checksums, SBOM, + and provenance. +3. The organization validates the package and Gateway payload in its own test + environment. +4. The administrator approves and imports the exact artifact into the + organization's Windows application-management system. +5. The management system stages or deploys the approved version according to + organization rollout and rollback policy. + +The installed package and host app must not bypass that process by fetching and +installing a newer OpenClaw payload on their own. Unattended auto-update is +disabled by default in v1. + +For consumer installations, v1 may provide a manual update check or link to an +explicit GitHub Release, but installation still requires a clear user action. +The final consumer update experience remains to be determined. + +### Windows companion app setup integration + +After the MSIX release reaches the readiness bar below, the Windows companion +app setup UI should replace its current WSL recommendation with **Install +OpenClaw MSIX** as the default or preferred option for creating a local Gateway. +Selecting it should download/launch the approved MSIX installation flow or direct the +user to the appropriate artifact. + +### Release readiness + +MSIX should become the preferred Windows installation mechanism once: + +- x64 and ARM64 packages are built and signed through the packaging pipeline. +- Install, upgrade, rollback, repair, reset, and uninstall paths have automated + and manual coverage. +- Package capability changes are reviewable and release-blocking. +- Agent user and Agent Session provisioning, recovery, and cleanup have a + documented support boundary. +- The host app can provision and operate a packaged local Gateway without + silently reducing its isolation. +- Existing local Gateway users, including WSL users, have a documented migration + path to the packaged deployment. + +Developer, source-based, and remote-Gateway paths can remain available during +the transition, but Windows installation documentation should prefer the +OpenClaw MSIX artifact after the release criteria are satisfied. + +## Rationale + +- MSIX is preferred over making a source checkout, bootstrap script, or loose +archive the enterprise deployment contract because it provides a stable package +identity, declarative manifest, signed artifact, predictable lifecycle, and +integration with Windows application-management systems. These properties make +the installed application and its requested capabilities easier to inventory +and review. + +- MSIX is not a substitute for Gateway containment — a packaged desktop +application can still execute with broad user access. As covered in +Motivation, the dedicated agent user and session-isolated Agent Session +provide the runtime boundary; the MSIX only identifies and deploys the +workload that the host app then contains. + +- A separate packaging repository creates a focused review and ownership boundary +for the host app, manifests, OpenClaw source pinning, signing, and release +policy. It avoids adding Windows-specific packaging and signing machinery to the +core OpenClaw repository while still consuming OpenClaw directly from an exact +source revision rather than maintaining a fork. + +- GitHub Releases are preferred over Microsoft Store publication for the initial +rollout because they keep the artifact and build evidence reviewable while +allowing enterprises to validate and redistribute an exact approved package +through their existing management systems. Store publication can be considered +separately if consumer distribution requirements justify its policy, identity, +and update implications. + +- Disabling unattended auto-update by default prioritizes administrator control, +reproducibility, and rollback over consumer convenience. This is the safer +starting point for a package whose payload can execute agent actions. A +consumer-friendly update channel can be added after its consent, verification, +and rollback behavior are defined. + +## Unresolved questions + +- Which Windows execution-container or Agent Session APIs are required, what + is their minimum supported Windows version, and what support state is required + before MSIX becomes the default? +- Which capabilities must be declared in the package manifest, and which + changes require explicit security review? +- What is the exact migration path for an existing WSL-based or source-based + local Gateway? +- How are Gateway data, agent accounts, and Agent Session resources cleaned + up during uninstall, failed setup, rollback, or package identity changes? +- Can an administrator roll back the package without rolling back or corrupting + Gateway state? +- How should enterprise deployment systems receive revocation or urgent + security-update guidance without allowing clients to install unapproved + payloads? From e279e18524e294d85431f55fb3049e7b04cfae1a Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Mon, 20 Jul 2026 11:26:00 -0700 Subject: [PATCH 02/11] docs: clarify MSIX release policy Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3cd24431-d6fe-4603-b495-c289228b4ccb --- rfcs/0010-openclaw-msix-packaging.md | 60 +++++++++++++++++----------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index 08c6dac0..fe37d809 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-07-16 +last_updated: 2026-07-20 status: draft issue: rfc_pr: @@ -50,8 +50,9 @@ release checks produced a given OpenClaw MSIX artifact. - Create an `openclaw/openclaw-msix-packaging` repository containing the Windows host app, package definitions, release workflows, validation, and contributor documentation. -- Produce reviewable and reproducible MSIX builds from an explicitly pinned - OpenClaw source revision as the only external product source input. +- Produce reviewable and reproducible MSIX builds whose OpenClaw payload is + built from an explicitly pinned revision of the official + [`openclaw/openclaw`](https://github.com/openclaw/openclaw) repository. - Include a package-specific host app that provisions the dedicated agent user, creates the Agent Session, and manages the packaged Gateway lifecycle. - Publish signed MSIX artifacts under a stable OpenClaw-controlled identity, @@ -84,10 +85,14 @@ release-ready MSIX artifacts. The repository should contain: - Documentation for local builds, release operations, signing, installation, upgrade, rollback, and uninstall behavior. -The only product source input is the OpenClaw repository. The packaging -repository must not carry a long-lived copy of OpenClaw source; each MSIX -release instead pins the exact OpenClaw source revision it packages. Build -toolchains and packaging dependencies are locked in the packaging repository. +The official +[`openclaw/openclaw`](https://github.com/openclaw/openclaw) repository is the +source of truth for the OpenClaw payload. The packaging repository must not +carry a long-lived copy or fork of OpenClaw source; each MSIX release instead +pins the exact upstream revision it packages. This does not make OpenClaw the +build's only input: host app source, bootstrapper and session-runtime +components, toolchains, and packaging dependencies are separate inputs that +must be pinned, verified, and recorded in the release SBOM and provenance. The host app is packaging infrastructure specific to the Windows MSIX deployment. It is not a fork of the OpenClaw Gateway and must keep its @@ -105,6 +110,21 @@ GitHub Actions should provide three levels of validation: 3. A protected release workflow signs the approved artifacts, verifies the resulting signatures and payloads, and publishes a GitHub Release. +After the MSIX distribution path meets the release-readiness criteria in this +RFC, the production release cadence should follow OpenClaw's release channels: + +- Every OpenClaw release promoted to the `stable` channel, including subsequent + security or reliability updates to the active stable line, should have a + corresponding production-signed MSIX release. +- Beta or other prerelease OpenClaw releases may produce clearly labeled + prerelease MSIX artifacts for validation. +- Moving `dev` or `main` builds may produce CI artifacts, but must not be + published as production MSIX releases. + +Packaging-only fixes may publish a new MSIX package revision while retaining +the same embedded OpenClaw version. Release metadata must identify both the +MSIX package version and the exact OpenClaw version it contains. + The release workflow should: - Restore dependencies from locked manifests, then build the host app, @@ -191,23 +211,15 @@ GitHub Releases are the canonical distribution point for the first version of this proposal. A release should provide direct artifact links, checksums, signatures, provenance, release notes, and an SBOM. -For enterprise deployments, the initial update flow is administrator -controlled: - -1. An administrator selects an exact OpenClaw MSIX release. -2. The administrator reviews the release notes, declared package - capabilities, included component versions, signature, checksums, SBOM, - and provenance. -3. The organization validates the package and Gateway payload in its own test - environment. -4. The administrator approves and imports the exact artifact into the - organization's Windows application-management system. -5. The management system stages or deploys the approved version according to - organization rollout and rollback policy. - -The installed package and host app must not bypass that process by fetching and -installing a newer OpenClaw payload on their own. Unattended auto-update is -disabled by default in v1. +Enterprise administrators should handle OpenClaw MSIX like any other Windows +app distributed outside the Microsoft Store. They should use their existing +tools and policies to review, test, approve, deploy, update, and roll back a +specific signed release. OpenClaw does not require a separate IT deployment +process. + +The installed package and host app must not bypass administrator approval by +fetching and installing a newer OpenClaw payload on their own. Unattended +auto-update is disabled by default in v1. For consumer installations, v1 may provide a manual update check or link to an explicit GitHub Release, but installation still requires a clear user action. From 689cca37a1d5019fc72fc148339ac98bb2dda2ee Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Tue, 21 Jul 2026 11:05:49 -0700 Subject: [PATCH 03/11] Refocus MSIX RFC on packaging lifecycle Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6aa7eb66-af4f-44cd-a5a8-fe80ae9d0057 --- rfcs/0010-openclaw-msix-packaging.md | 128 +++++++++++++-------------- 1 file changed, 61 insertions(+), 67 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index fe37d809..b8b60e44 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-07-20 +last_updated: 2026-07-21 status: draft issue: rfc_pr: @@ -18,10 +18,10 @@ Windows as an MSIX package. A dedicated `openclaw/openclaw-msix-packaging` repository will build a package-specific host app and an OpenClaw payload tarball from a commit pinned for each MSIX release, validate architecture-specific artifacts with GitHub Actions, and publish them through -GitHub Releases. The installed host app will provision and manage an Agent -Session under a dedicated agent user, then run the OpenClaw Gateway inside -that session. This provides stable app identity, enterprise-friendly -deployment, and a contained runtime boundary for OpenClaw on Windows. +GitHub Releases. After installation, the host app will verify and stage the +payload, run OpenClaw onboarding, and manage the Gateway lifecycle. This +provides stable app identity, enterprise-friendly deployment, and predictable +installation and update behavior on Windows. ## Motivation @@ -32,13 +32,11 @@ package identity, declared capabilities, and a standard Windows application-management surface, inspectable and governed like any other managed application. -Package identity alone is not a runtime security boundary for an autonomous -agent: the OpenClaw Gateway can execute tools, connect to services, and act on -a user's behalf. The managed deployment should therefore run the Gateway in a -separate, session-isolated Agent Session under a dedicated agent user rather -than the interactive user's own session. The host app included in the MSIX -package is responsible for provisioning that session, staging the OpenClaw -payload, and controlling the Gateway lifecycle. +MSIX package identity and signing do not by themselves define how the Gateway +payload is prepared or how long-lived state survives package updates. The host +app included in the MSIX package is responsible for verifying and staging the +payload, running onboarding, and controlling the Gateway lifecycle. This keeps +Windows packaging behavior out of the OpenClaw core. Keeping the packaging definition in a dedicated repository also supports trust and maintainability: contributors and enterprise reviewers can determine @@ -53,8 +51,8 @@ release checks produced a given OpenClaw MSIX artifact. - Produce reviewable and reproducible MSIX builds whose OpenClaw payload is built from an explicitly pinned revision of the official [`openclaw/openclaw`](https://github.com/openclaw/openclaw) repository. -- Include a package-specific host app that provisions the dedicated agent user, - creates the Agent Session, and manages the packaged Gateway lifecycle. +- Include a package-specific host app that verifies and stages the packaged + payload and manages the Gateway lifecycle. - Publish signed MSIX artifacts under a stable OpenClaw-controlled identity, with checksums and source-version metadata, through GitHub Releases. - Make the [Windows companion app](https://github.com/openclaw/openclaw-windows-node) present **Install OpenClaw MSIX** as the @@ -68,6 +66,8 @@ release checks produced a given OpenClaw MSIX artifact. responsible for managing package updates. - Defining every enterprise runtime policy, data-loss-prevention rule, or tool authorization rule that may be applied to OpenClaw. +- Defining runtime isolation. A separate RFC may define a session-based runtime + model. ## Proposal @@ -90,13 +90,13 @@ The official source of truth for the OpenClaw payload. The packaging repository must not carry a long-lived copy or fork of OpenClaw source; each MSIX release instead pins the exact upstream revision it packages. This does not make OpenClaw the -build's only input: host app source, bootstrapper and session-runtime -components, toolchains, and packaging dependencies are separate inputs that -must be pinned, verified, and recorded in the release SBOM and provenance. +build's only input: host app source, bootstrapper, runtime components, +toolchains, and packaging dependencies are separate inputs that must be pinned, +verified, and recorded in the release SBOM and provenance. The host app is packaging infrastructure specific to the Windows MSIX deployment. It is not a fork of the OpenClaw Gateway and must keep its -responsibilities narrow: package activation, Agent Session provisioning, +responsibilities narrow: package activation, payload verification and staging, Gateway lifecycle, health, repair, and cleanup. ### Build and release pipeline @@ -146,37 +146,34 @@ or exposed to pull-request workflows. The MSIX package provides OpenClaw's Windows package identity, a Gateway payload built from a pinned source revision, declared capabilities, packaged -entry points, and a host app that manages the contained runtime. +entry points, and a host app that manages payload setup and the Gateway +lifecycle. On first-run setup, the host app should: 1. Verify that the package identity, publisher, architecture, OpenClaw version, - and payload inventory match the signed package metadata. -2. Provision a dedicated agent user through the supported Windows APIs. -3. Create a session-isolated Agent Session for that agent user. -4. Extract the OpenClaw payload from its packaged tarball and stage it inside - the Agent Session. -5. Start a terminal session within the Agent Session that runs OpenClaw's - onboarding, matching the onboarding experience of a standard OpenClaw - install. -6. Start and stop the Gateway through a narrow lifecycle interface. -7. Clean up or explicitly preserve Gateway state and Agent Session resources - during repair, reset, rollback, and uninstall. + payload digest, and payload inventory match the signed package metadata. +2. Extract the OpenClaw payload from its packaged tarball into a clean, + versioned staging directory. +3. Verify the staged files against the payload inventory before activation. +4. Run OpenClaw's onboarding, matching the onboarding experience of a standard + OpenClaw install. +5. Start and stop the Gateway through a narrow lifecycle interface. +6. Clean up or explicitly preserve Gateway state during repair, reset, + rollback, and uninstall. The host app should expose a stable way for OpenClaw clients and nodes to obtain the Gateway endpoint and complete normal pairing. Those clients are consumers -of a running Gateway; they do not own the Agent Session or Gateway lifecycle. +of a running Gateway; they do not own its lifecycle. -The Gateway must not silently fall back to running under the interactive user -when Agent Session provisioning fails. Enterprise policy must be able to require the session-isolated mode and disable -fallbacks. +Behavior for multiple Windows users must be explicit, including ownership of +the staged payload, Gateway state, credentials, and endpoints. -Package data and long-lived Gateway state must have an explicit lifecycle. -Updating or uninstalling the MSIX package must not leave an unknown running -Gateway, orphaned agent account, or inaccessible state. If Windows cannot -remove Agent Session state transactionally with package removal, the host app -must expose a supported cleanup flow and clearly warn administrators before -uninstall. +Staged payload files and long-lived Gateway state must have an explicit +lifecycle. Updating or uninstalling the MSIX package must not leave an unknown +running Gateway or inaccessible state. If Windows cannot remove external state +transactionally with package removal, the host app must expose a supported +cleanup flow and clearly warn administrators before uninstall. ```mermaid flowchart LR @@ -187,23 +184,20 @@ flowchart LR Sign --> GH[OpenClaw MSIX GitHub Release] GH --> Install[User or enterprise installation] Install --> App[MSIX host app] - App --> User[Dedicated agent user] - App --> Session[Session-isolated Agent Session] - User --> Session - App --> Stage["Extract tarball and stage payload"] - Stage --> Session - Session --> Terminal["Terminal session: OpenClaw onboarding"] - Terminal --> Gateway[OpenClaw Gateway] + App --> Verify["Verify payload tarball and inventory"] + Verify --> Stage["Extract to clean versioned staging"] + Stage --> Onboarding["Run OpenClaw onboarding"] + Onboarding --> Gateway[OpenClaw Gateway] + App -->|Manage lifecycle| Gateway ``` **Figure 1.** The packaging repository builds an OpenClaw payload tarball from a pinned source revision and packages it with a C# host app, preferably published with NativeAOT, into the MSIX. After installation, that host app -provisions the dedicated agent user and Agent Session, extracts and stages the -payload into that session, and starts a terminal session that runs OpenClaw's -onboarding — the same onboarding experience as a standard OpenClaw install — -before the Gateway runs. MSIX identity and runtime isolation are complementary -controls. +verifies the tarball and file inventory, extracts the payload into clean +versioned staging, runs OpenClaw's onboarding, and manages the Gateway +lifecycle. The tarball provides a single payload unit to hash, inventory, and +audit. ### Distribution and updates @@ -238,13 +232,12 @@ user to the appropriate artifact. MSIX should become the preferred Windows installation mechanism once: - x64 and ARM64 packages are built and signed through the packaging pipeline. -- Install, upgrade, rollback, repair, reset, and uninstall paths have automated +- The payload tarball and staged files are verified before activation. +- Install, update, rollback, repair, reset, and uninstall paths have automated and manual coverage. +- Gateway state ownership and cleanup are documented, including behavior for + multiple Windows users. - Package capability changes are reviewable and release-blocking. -- Agent user and Agent Session provisioning, recovery, and cleanup have a - documented support boundary. -- The host app can provision and operate a packaged local Gateway without - silently reducing its isolation. - Existing local Gateway users, including WSL users, have a documented migration path to the packaged deployment. @@ -261,11 +254,13 @@ integration with Windows application-management systems. These properties make the installed application and its requested capabilities easier to inventory and review. -- MSIX is not a substitute for Gateway containment — a packaged desktop -application can still execute with broad user access. As covered in -Motivation, the dedicated agent user and session-isolated Agent Session -provide the runtime boundary; the MSIX only identifies and deploys the -workload that the host app then contains. +- A separate host app keeps Windows packaging and lifecycle code out of +OpenClaw core. It owns payload verification and staging, onboarding, Gateway +lifecycle, health, repair, and cleanup. + +- A payload tarball gives each release one unit to hash, inventory, and audit. +Clean versioned staging keeps updates and rollback predictable, while keeping +the package format independent of later runtime changes. - A separate packaging repository creates a focused review and ownership boundary for the host app, manifests, OpenClaw source pinning, signing, and release @@ -288,15 +283,14 @@ and rollback behavior are defined. ## Unresolved questions -- Which Windows execution-container or Agent Session APIs are required, what - is their minimum supported Windows version, and what support state is required - before MSIX becomes the default? - Which capabilities must be declared in the package manifest, and which changes require explicit security review? - What is the exact migration path for an existing WSL-based or source-based local Gateway? -- How are Gateway data, agent accounts, and Agent Session resources cleaned - up during uninstall, failed setup, rollback, or package identity changes? +- What are the ownership rules for Gateway state, credentials, and endpoints + when multiple Windows users install or run the package? +- How are payload files and Gateway state cleaned up during uninstall, failed + setup, rollback, or package identity changes? - Can an administrator roll back the package without rolling back or corrupting Gateway state? - How should enterprise deployment systems receive revocation or urgent From 3cd7250bf8445fe76984a0c003a0ee699e90f31f Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Tue, 21 Jul 2026 17:12:05 -0700 Subject: [PATCH 04/11] Highlight PFN package identity in MSIX RFC Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6aa7eb66-af4f-44cd-a5a8-fe80ae9d0057 --- rfcs/0010-openclaw-msix-packaging.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index b8b60e44..92ccd4d2 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -20,8 +20,8 @@ tarball from a commit pinned for each MSIX release, validate architecture-specific artifacts with GitHub Actions, and publish them through GitHub Releases. After installation, the host app will verify and stage the payload, run OpenClaw onboarding, and manage the Gateway lifecycle. This -provides stable app identity, enterprise-friendly deployment, and predictable -installation and update behavior on Windows. +provides a stable Package Family Name (PFN), enterprise-friendly deployment, +and predictable installation and update behavior on Windows. ## Motivation @@ -32,6 +32,9 @@ package identity, declared capabilities, and a standard Windows application-management surface, inspectable and governed like any other managed application. +Windows uses the PFN to associate the package with package-scoped app data and +clean that data up on uninstall. + MSIX package identity and signing do not by themselves define how the Gateway payload is prepared or how long-lived state survives package updates. The host app included in the MSIX package is responsible for verifying and staging the From 85c8a4c0d3fec9ed537f82c07ec927e656eed224 Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Tue, 28 Jul 2026 20:53:35 -0700 Subject: [PATCH 05/11] Refine OpenClaw MSIX lifecycle RFC Clarify installation, preferred update behavior, package identity, and future PFN management while removing rollback from scope. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7b5e8cf9-246d-4f16-83d0-3abd731a0813 --- rfcs/0010-openclaw-msix-packaging.md | 184 ++++++++++++++++----------- 1 file changed, 107 insertions(+), 77 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index 92ccd4d2..c872cc3f 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-07-21 +last_updated: 2026-07-28 status: draft issue: rfc_pr: @@ -18,10 +18,11 @@ Windows as an MSIX package. A dedicated `openclaw/openclaw-msix-packaging` repository will build a package-specific host app and an OpenClaw payload tarball from a commit pinned for each MSIX release, validate architecture-specific artifacts with GitHub Actions, and publish them through -GitHub Releases. After installation, the host app will verify and stage the -payload, run OpenClaw onboarding, and manage the Gateway lifecycle. This -provides a stable Package Family Name (PFN), enterprise-friendly deployment, -and predictable installation and update behavior on Windows. +GitHub Releases. The MSIX installs the packaged app and its Windows identity; +on first launch, the host app prepares the payload and runs onboarding before +the Gateway is ready to use. This provides a stable Package Family Name (PFN), +enterprise-friendly deployment, and predictable installation and update +behavior on Windows. ## Motivation @@ -32,14 +33,10 @@ package identity, declared capabilities, and a standard Windows application-management surface, inspectable and governed like any other managed application. -Windows uses the PFN to associate the package with package-scoped app data and -clean that data up on uninstall. - -MSIX package identity and signing do not by themselves define how the Gateway -payload is prepared or how long-lived state survives package updates. The host -app included in the MSIX package is responsible for verifying and staging the -payload, running onboarding, and controlling the Gateway lifecycle. This keeps -Windows packaging behavior out of the OpenClaw core. +Windows uses the PFN to associate system-managed resources with the packaged +app and clean up those resources when the package is removed. +A separate RFC will define how the platform uses this package identity when +managing OpenClaw Gateway instances. Keeping the packaging definition in a dedicated repository also supports trust and maintainability: contributors and enterprise reviewers can determine @@ -63,10 +60,9 @@ release checks produced a given OpenClaw MSIX artifact. ## Non-Goals -- Publishing through or depending on the Microsoft Store, including - Store-managed updates. -- Enabling unattended package auto-update by default. IT administrators remain - responsible for managing package updates. +- Publishing v1 through or depending on the Microsoft Store, including + Store-managed updates. GitHub Releases are the canonical initial release + channel. - Defining every enterprise runtime policy, data-loss-prevention rule, or tool authorization rule that may be applied to OpenClaw. - Defining runtime isolation. A separate RFC may define a session-based runtime @@ -86,7 +82,7 @@ release-ready MSIX artifacts. The repository should contain: - Build orchestration for x64 and ARM64. - GitHub Actions workflows for pull requests, release candidates, and releases. - Documentation for local builds, release operations, signing, installation, - upgrade, rollback, and uninstall behavior. + update, repair, reset, and uninstall behavior. The official [`openclaw/openclaw`](https://github.com/openclaw/openclaw) repository is the @@ -100,7 +96,7 @@ verified, and recorded in the release SBOM and provenance. The host app is packaging infrastructure specific to the Windows MSIX deployment. It is not a fork of the OpenClaw Gateway and must keep its responsibilities narrow: package activation, payload verification and staging, -Gateway lifecycle, health, repair, and cleanup. +Gateway lifecycle, health, repair, and supported reset flows. ### Build and release pipeline @@ -149,34 +145,11 @@ or exposed to pull-request workflows. The MSIX package provides OpenClaw's Windows package identity, a Gateway payload built from a pinned source revision, declared capabilities, packaged -entry points, and a host app that manages payload setup and the Gateway -lifecycle. - -On first-run setup, the host app should: - -1. Verify that the package identity, publisher, architecture, OpenClaw version, - payload digest, and payload inventory match the signed package metadata. -2. Extract the OpenClaw payload from its packaged tarball into a clean, - versioned staging directory. -3. Verify the staged files against the payload inventory before activation. -4. Run OpenClaw's onboarding, matching the onboarding experience of a standard - OpenClaw install. -5. Start and stop the Gateway through a narrow lifecycle interface. -6. Clean up or explicitly preserve Gateway state during repair, reset, - rollback, and uninstall. - -The host app should expose a stable way for OpenClaw clients and nodes to obtain -the Gateway endpoint and complete normal pairing. Those clients are consumers -of a running Gateway; they do not own its lifecycle. - -Behavior for multiple Windows users must be explicit, including ownership of -the staged payload, Gateway state, credentials, and endpoints. - -Staged payload files and long-lived Gateway state must have an explicit -lifecycle. Updating or uninstalling the MSIX package must not leave an unknown -running Gateway or inaccessible state. If Windows cannot remove external state -transactionally with package removal, the host app must expose a supported -cleanup flow and clearly warn administrators before uninstall. +entry points, and the host app. The lifecycle section below defines how the +host prepares and manages the Gateway. + +The host app is the packaged entry point and exposes a stable way for OpenClaw +clients and nodes to obtain the Gateway endpoint and complete normal pairing. ```mermaid flowchart LR @@ -194,13 +167,75 @@ flowchart LR App -->|Manage lifecycle| Gateway ``` -**Figure 1.** The packaging repository builds an OpenClaw payload tarball from -a pinned source revision and packages it with a C# host app, preferably -published with NativeAOT, into the MSIX. After installation, that host app -verifies the tarball and file inventory, extracts the payload into clean -versioned staging, runs OpenClaw's onboarding, and manages the Gateway -lifecycle. The tarball provides a single payload unit to hash, inventory, and -audit. +**Figure 1.** The packaging repository creates a signed MSIX containing the C# +host app and a payload built from a pinned OpenClaw revision. + +### End-to-end lifecycle + +The MSIX provides the Windows package identity and the files needed to +bootstrap OpenClaw. The Gateway runs from the payload prepared by the host app. + +#### Installing the OpenClaw MSIX + +An administrator or user installs the signed MSIX. Windows verifies it, +registers its package identity, and presents OpenClaw as an installed packaged +app in Start. At this point, the packaged app is installed, but OpenClaw has not +yet been onboarded and the Gateway is not ready. + +Launching OpenClaw starts the host app. On first run, the host verifies the +packaged tarball, extracts the Gateway, and runs OpenClaw onboarding. After +onboarding completes, the Gateway is ready and the packaged app provides its +entry point. + +#### Uninstalling the OpenClaw MSIX + +Uninstalling OpenClaw removes the registered MSIX and its installed entry +points, and the Gateway is stopped. + +> **Note:** Resources created on behalf of the packaged app are associated with +> its package identity. When the MSIX is uninstalled, the system cleans up those +> package-associated resources. OpenClaw is not invoked and does not run custom +> cleanup code during uninstall. The cleanup mechanism is outside the scope of +> this RFC. + +#### Updating OpenClaw through MSIX (preferred) + +In an enterprise deployment, an IT administrator reviews and deploys a newer +signed MSIX with the same package identity and a higher package version. +Windows replaces the installed package files, including the host app and +bundled payload, while keeping the package identity stable. It does not directly +replace the extracted Gateway or its data. + +Installing the newer MSIX does not immediately replace an extracted Gateway +that is already running. The host detects the new packaged payload the next +time it starts or restarts the Gateway. It verifies and stages the payload +separately rather than overwriting the active files. If the Gateway is running, +the host stops it, activates the staged version, and starts it again. Enterprise +deployments that require immediate activation must include that restart in +their rollout. + +Until activation finishes, the installed MSIX version and the active Gateway +version may differ. A partially staged payload must not be activated. If an +update changes stored data or configuration, the release must include and test +the required migration. + +#### Updating through OpenClaw itself + +OpenClaw may also update its extracted installation through its native +`openclaw update` command. A user may invoke the same behavior indirectly by +asking OpenClaw to update itself. + +The packaging layer cannot reliably prevent this update path. A native update +changes the running OpenClaw files without changing the installed MSIX version +or its signed payload. The PFN continues to identify the packaged application, +but the MSIX version no longer identifies the exact OpenClaw revision currently +running. + +Native updating is therefore not encouraged for managed enterprise +installations. It can bypass administrator approval, make inventory less +precise, and complicate support. The packaging host does not initiate a native +update on its own. A later MSIX update returns the Gateway to the version +carried by the administrator-approved package. ### Distribution and updates @@ -210,13 +245,12 @@ signatures, provenance, release notes, and an SBOM. Enterprise administrators should handle OpenClaw MSIX like any other Windows app distributed outside the Microsoft Store. They should use their existing -tools and policies to review, test, approve, deploy, update, and roll back a +tools and policies to review, test, approve, deploy, update, and remove a specific signed release. OpenClaw does not require a separate IT deployment process. -The installed package and host app must not bypass administrator approval by -fetching and installing a newer OpenClaw payload on their own. Unattended -auto-update is disabled by default in v1. +The update behavior and limitations are described in the lifecycle section +above. Unattended MSIX package updates are disabled by default in v1. For consumer installations, v1 may provide a manual update check or link to an explicit GitHub Release, but installation still requires a clear user action. @@ -232,12 +266,12 @@ user to the appropriate artifact. ### Release readiness -MSIX should become the preferred Windows installation mechanism once: +MSIX should become the preferred Windows installation mechanism for enterprise once: - x64 and ARM64 packages are built and signed through the packaging pipeline. - The payload tarball and staged files are verified before activation. -- Install, update, rollback, repair, reset, and uninstall paths have automated - and manual coverage. +- Install, onboarding, update, repair, reset, and uninstall paths have + automated and manual coverage. - Gateway state ownership and cleanup are documented, including behavior for multiple Windows users. - Package capability changes are reviewable and release-blocking. @@ -258,12 +292,13 @@ the installed application and its requested capabilities easier to inventory and review. - A separate host app keeps Windows packaging and lifecycle code out of -OpenClaw core. It owns payload verification and staging, onboarding, Gateway -lifecycle, health, repair, and cleanup. +OpenClaw core while providing the packaged entry point needed to prepare and +manage the Gateway. - A payload tarball gives each release one unit to hash, inventory, and audit. -Clean versioned staging keeps updates and rollback predictable, while keeping -the package format independent of later runtime changes. +Clean versioned staging prevents a partially prepared update from replacing the +active Gateway, while keeping the package format independent of later runtime +changes. - A separate packaging repository creates a focused review and ownership boundary for the host app, manifests, OpenClaw source pinning, signing, and release @@ -278,24 +313,19 @@ through their existing management systems. Store publication can be considered separately if consumer distribution requirements justify its policy, identity, and update implications. -- Disabling unattended auto-update by default prioritizes administrator control, -reproducibility, and rollback over consumer convenience. This is the safer +- Disabling unattended MSIX package updates by default prioritizes administrator +control and reproducibility over consumer convenience. This is the safer starting point for a package whose payload can execute agent actions. A -consumer-friendly update channel can be added after its consent, verification, -and rollback behavior are defined. +consumer-friendly package update channel can be added after its consent and +verification behavior are defined. ## Unresolved questions - Which capabilities must be declared in the package manifest, and which changes require explicit security review? -- What is the exact migration path for an existing WSL-based or source-based - local Gateway? -- What are the ownership rules for Gateway state, credentials, and endpoints - when multiple Windows users install or run the package? -- How are payload files and Gateway state cleaned up during uninstall, failed - setup, rollback, or package identity changes? -- Can an administrator roll back the package without rolling back or corrupting - Gateway state? +- If Microsoft Store distribution is introduced later, packages that are released + from GitHub and those from the Store will have different PFNs. How will side-by-side + installation be handled? - How should enterprise deployment systems receive revocation or urgent security-update guidance without allowing clients to install unapproved payloads? From 0a4276b3d5d3c1d7e550fb3713b041e940cfa1b4 Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Wed, 29 Jul 2026 10:14:02 -0700 Subject: [PATCH 06/11] Add packaged self-update open question Track whether packaged OpenClaw should prevent command- and prompt-driven native updates and what enterprise enforcement is possible. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7b5e8cf9-246d-4f16-83d0-3abd731a0813 --- rfcs/0010-openclaw-msix-packaging.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index c872cc3f..850c706b 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-07-28 +last_updated: 2026-07-29 status: draft issue: rfc_pr: @@ -323,6 +323,10 @@ verification behavior are defined. - Which capabilities must be declared in the package manifest, and which changes require explicit security review? +- Should packaged OpenClaw disable native self-updates, including updates + initiated through `openclaw update` or by prompting the Gateway? If so, what + enforcement mechanism can enterprise administrators rely on, given that + OpenClaw does not provide one today? - If Microsoft Store distribution is introduced later, packages that are released from GitHub and those from the Store will have different PFNs. How will side-by-side installation be handled? From 39b8b12028bf1c4faf83f676d68f65e2857007b3 Mon Sep 17 00:00:00 2001 From: Xiaochang Huang Date: Mon, 3 Aug 2026 23:02:45 -0700 Subject: [PATCH 07/11] docs: link MSIX RFC pull request Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: c4e24ce6-c557-4073-909c-b2e7615bd870 --- rfcs/0010-openclaw-msix-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index 850c706b..b0c3555a 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -6,7 +6,7 @@ created: 2026-07-14 last_updated: 2026-07-29 status: draft issue: -rfc_pr: +rfc_pr: https://github.com/openclaw/rfcs/pull/58 --- # Proposal: OpenClaw MSIX Packaging for Windows From 287a7ff9619a43427caa691f49c80a49195b7274 Mon Sep 17 00:00:00 2001 From: Xiaochang Huang Date: Mon, 3 Aug 2026 23:31:50 -0700 Subject: [PATCH 08/11] docs: update MSIX RFC revision date Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: c4e24ce6-c557-4073-909c-b2e7615bd870 --- rfcs/0010-openclaw-msix-packaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index b0c3555a..fb109a28 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-07-29 +last_updated: 2026-08-03 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/58 From 9dc31c8b6faa4d6f38c046eb941798503412da50 Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Thu, 6 Aug 2026 10:17:31 -0700 Subject: [PATCH 09/11] Clarify MSIX distribution dependencies Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: d5132745-7693-44d9-a132-e5f7d9568cfc --- rfcs/0010-openclaw-msix-packaging.md | 33 ++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index fb109a28..3dafb953 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -55,6 +55,10 @@ release checks produced a given OpenClaw MSIX artifact. payload and manages the Gateway lifecycle. - Publish signed MSIX artifacts under a stable OpenClaw-controlled identity, with checksums and source-version metadata, through GitHub Releases. +- Make a supported way to disable OpenClaw Gateway self-updates a hard + dependency for the MSIX release. The mechanism belongs in OpenClaw rather + than this packaging RFC, but it is required so an administrator-approved + MSIX remains authoritative for the deployed Gateway version. - Make the [Windows companion app](https://github.com/openclaw/openclaw-windows-node) present **Install OpenClaw MSIX** as the default or preferred option for creating a local OpenClaw Gateway. @@ -231,17 +235,24 @@ or its signed payload. The PFN continues to identify the packaged application, but the MSIX version no longer identifies the exact OpenClaw revision currently running. -Native updating is therefore not encouraged for managed enterprise -installations. It can bypass administrator approval, make inventory less -precise, and complicate support. The packaging host does not initiate a native -update on its own. A later MSIX update returns the Gateway to the version -carried by the administrator-approved package. +Native updating the Gateway must therefore be disabled for managed enterprise +installations. Otherwise it can bypass administrator approval, break the +version and inventory contract, and leave the running Gateway outside the +tested and signed MSIX release. The packaging host does not initiate a native +update on its own, but that is insufficient because users and the Gateway can +still invoke the OpenClaw update path. A supported OpenClaw mechanism for +disabling Gateway self-updates is therefore a hard dependency for the MSIX +release, even though defining and implementing that mechanism is outside this +RFC. ### Distribution and updates GitHub Releases are the canonical distribution point for the first version of this proposal. A release should provide direct artifact links, checksums, signatures, provenance, release notes, and an SBOM. +Future versions may expand distribution to additional channels such as WinGet +or the Microsoft Store once their identity, signing, update, and publication +requirements are defined. Enterprise administrators should handle OpenClaw MSIX like any other Windows app distributed outside the Microsoft Store. They should use their existing @@ -269,6 +280,8 @@ user to the appropriate artifact. MSIX should become the preferred Windows installation mechanism for enterprise once: - x64 and ARM64 packages are built and signed through the packaging pipeline. +- OpenClaw provides a supported mechanism that disables Gateway self-updates + for managed MSIX installations. - The payload tarball and staged files are verified before activation. - Install, onboarding, update, repair, reset, and uninstall paths have automated and manual coverage. @@ -321,12 +334,14 @@ verification behavior are defined. ## Unresolved questions +- Is a standalone `openclaw/openclaw-msix-packaging` repository preferable, or + should the host app, package definitions, and release workflows be maintained + directly in `openclaw/openclaw`? - Which capabilities must be declared in the package manifest, and which changes require explicit security review? -- Should packaged OpenClaw disable native self-updates, including updates - initiated through `openclaw update` or by prompting the Gateway? If so, what - enforcement mechanism can enterprise administrators rely on, given that - OpenClaw does not provide one today? +- What supported OpenClaw enforcement mechanism will disable native + self-updates, including updates initiated through `openclaw update` or by + prompting the Gateway, for managed MSIX installations? - If Microsoft Store distribution is introduced later, packages that are released from GitHub and those from the Store will have different PFNs. How will side-by-side installation be handled? From dc41b57b531a9b195c7bb8e268ea69b1715b7cb4 Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Thu, 6 Aug 2026 18:05:44 -0700 Subject: [PATCH 10/11] Clarify WinGet and Store identity guidance Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: a34648ae-920d-4b39-9726-00a1a63cfe9d --- rfcs/0010-openclaw-msix-packaging.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index 3dafb953..ddb4c484 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -253,6 +253,10 @@ signatures, provenance, release notes, and an SBOM. Future versions may expand distribution to additional channels such as WinGet or the Microsoft Store once their identity, signing, update, and publication requirements are defined. +Publishing through WinGet requires submitting a package manifest to the WinGet +repository that references the signed MSIX hosted on GitHub Releases; WinGet +does not need to host a separate copy of the package. This allows GitHub +Releases to remain the canonical artifact source when WinGet support is added. Enterprise administrators should handle OpenClaw MSIX like any other Windows app distributed outside the Microsoft Store. They should use their existing @@ -342,9 +346,14 @@ verification behavior are defined. - What supported OpenClaw enforcement mechanism will disable native self-updates, including updates initiated through `openclaw update` or by prompting the Gateway, for managed MSIX installations? -- If Microsoft Store distribution is introduced later, packages that are released - from GitHub and those from the Store will have different PFNs. How will side-by-side - installation be handled? +- If Microsoft Store distribution is introduced later, can packages released + through GitHub and the Store preserve the same PFN? If not, how will + side-by-side installation be handled? + - [@DrusTheAxe](https://github.com/DrusTheAxe) noted that preserving the PFN + may be possible by defining the Store product identity in advance and using + an Azure Artifact Services certificate whose subject matches the package + manifest's `Publisher`. This is not a v1 priority; GitHub Releases will + remain the MSIX release channel for the time being. - How should enterprise deployment systems receive revocation or urgent security-update guidance without allowing clients to install unapproved payloads? From d6abbc1d2b45f289d14c1bf7e45a90f1768b5510 Mon Sep 17 00:00:00 2001 From: Linus Huang Date: Mon, 10 Aug 2026 12:43:06 -0700 Subject: [PATCH 11/11] Clarify MSIX Gateway lifecycle boundaries Define the unchanged Gateway protocol and pairing boundary, document app execution alias installation, and separate package removal from administrator-managed decommissioning and reset. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f06e6164-8cba-4365-8596-3cc422dbd189 --- rfcs/0010-openclaw-msix-packaging.md | 85 +++++++++++++++++++++++----- 1 file changed, 72 insertions(+), 13 deletions(-) diff --git a/rfcs/0010-openclaw-msix-packaging.md b/rfcs/0010-openclaw-msix-packaging.md index ddb4c484..8f16ed2a 100644 --- a/rfcs/0010-openclaw-msix-packaging.md +++ b/rfcs/0010-openclaw-msix-packaging.md @@ -3,7 +3,7 @@ title: OpenClaw MSIX Packaging for Windows authors: - Linus Huang created: 2026-07-14 -last_updated: 2026-08-03 +last_updated: 2026-08-10 status: draft issue: rfc_pr: https://github.com/openclaw/rfcs/pull/58 @@ -34,7 +34,9 @@ application-management surface, inspectable and governed like any other managed application. Windows uses the PFN to associate system-managed resources with the packaged -app and clean up those resources when the package is removed. +app and clean up those resources when the package is removed. Gateway state +and other resources created outside the package registration require separate, +explicit lifecycle handling as described below. A separate RFC will define how the platform uses this package identity when managing OpenClaw Gateway instances. @@ -71,6 +73,8 @@ release checks produced a given OpenClaw MSIX artifact. authorization rule that may be applied to OpenClaw. - Defining runtime isolation. A separate RFC may define a session-based runtime model. +- Defining a new Gateway endpoint, discovery mechanism, authentication scheme, + pairing flow, or Windows companion app connection role. ## Proposal @@ -152,8 +156,10 @@ payload built from a pinned source revision, declared capabilities, packaged entry points, and the host app. The lifecycle section below defines how the host prepares and manages the Gateway. -The host app is the packaged entry point and exposes a stable way for OpenClaw -clients and nodes to obtain the Gateway endpoint and complete normal pairing. +The host app is the packaged entry point. Its v1 responsibilities are package +activation, payload verification and staging, and launching or stopping the +packaged Gateway. It does not proxy Gateway traffic, distribute Gateway +credentials, or approve clients, nodes, or channel users. ```mermaid flowchart LR @@ -174,17 +180,44 @@ flowchart LR **Figure 1.** The packaging repository creates a signed MSIX containing the C# host app and a payload built from a pinned OpenClaw revision. +### Gateway compatibility boundary + +The MSIX deployment does not introduce a new Gateway endpoint, discovery +mechanism, connection protocol, authentication scheme, or pairing flow. The +packaged payload runs the standard OpenClaw Gateway and preserves its native +endpoint configuration, discovery, device authorization, node-capability +approval, channel behavior, and protocol handling. Clients and nodes connect +directly to the Gateway through existing OpenClaw mechanisms. + +Gateway configuration, credentials, pairing records, and user data remain +owned by OpenClaw rather than the packaging host. The host does not inspect, +copy, authorize, or revoke those credentials. Their exact storage and +retention behavior must be documented and tested for install, update, +uninstall, reset, and multi-user scenarios. + +This RFC does not define whether the Windows companion app connects to a +Gateway as an operator client, a node, or both. It changes the recommended +installation path for creating a local Gateway, not the companion app's +connection contract. Existing source-based, WSL, remote-Gateway, and companion +node-worker flows remain available unless a separate proposal changes them. + ### End-to-end lifecycle The MSIX provides the Windows package identity and the files needed to bootstrap OpenClaw. The Gateway runs from the payload prepared by the host app. +The host owns package activation and packaged-payload lifecycle mechanics; +OpenClaw continues to own Gateway runtime behavior and protocol state. +Enterprise administrators own deployment policy and the selection of the MSIX +version approved for each managed device. #### Installing the OpenClaw MSIX -An administrator or user installs the signed MSIX. Windows verifies it, -registers its package identity, and presents OpenClaw as an installed packaged -app in Start. At this point, the packaged app is installed, but OpenClaw has not -yet been onboarded and the Gateway is not ready. +An administrator or user installs the signed MSIX, either interactively by +opening it or through an enterprise deployment system. Windows verifies it, +registers its package identity and `openclaw.exe` app execution alias, and +presents OpenClaw as an installed packaged app in Start. No separate PATH +modification is required. At this point, the packaged app is installed, but +OpenClaw has not yet been onboarded and the Gateway is not ready. Launching OpenClaw starts the host app. On first run, the host verifies the packaged tarball, extracts the Gateway, and runs OpenClaw onboarding. After @@ -193,14 +226,33 @@ entry point. #### Uninstalling the OpenClaw MSIX -Uninstalling OpenClaw removes the registered MSIX and its installed entry -points, and the Gateway is stopped. +Removing the MSIX unregisters the packaged application, its package identity, +and its installed entry points, including the `openclaw.exe` execution alias. +Package removal must not be treated as an implicit destructive reset of Gateway +data. > **Note:** Resources created on behalf of the packaged app are associated with > its package identity. When the MSIX is uninstalled, the system cleans up those > package-associated resources. OpenClaw is not invoked and does not run custom -> cleanup code during uninstall. The cleanup mechanism is outside the scope of -> this RFC. +> cleanup code during uninstall. Gateway processes, state, or separately +> provisioned execution resources may exist outside the package registration +> and may require explicit decommissioning. The exact automated cleanup +> mechanism is outside the scope of this RFC and may be refined alongside a +> future session-isolation design. + +Enterprise administrators are responsible for ensuring that OpenClaw is +cleanly installed and decommissioned on managed devices. When resources outside +the package registration must also be removed, administrators may invoke +supported reset tooling or perform equivalent documented operations through +their device-management system, including stopping running Gateway instances +and applying the organization's state-retention policy. + +Package removal and destructive reset are separate operations. Ordinary +uninstall may preserve Gateway state for reinstall or recovery; reset may +permanently remove selected state and therefore requires explicit +administrative intent. The detailed decommissioning sequence and its +interaction with future session isolation can be defined by the corresponding +implementation or isolation design. #### Updating OpenClaw through MSIX (preferred) @@ -277,7 +329,9 @@ After the MSIX release reaches the readiness bar below, the Windows companion app setup UI should replace its current WSL recommendation with **Install OpenClaw MSIX** as the default or preferred option for creating a local Gateway. Selecting it should download/launch the approved MSIX installation flow or direct the -user to the appropriate artifact. +user to the appropriate artifact. This setup integration does not change how +the companion app discovers, authenticates to, or selects its role with a +Gateway. ### Release readiness @@ -291,6 +345,11 @@ MSIX should become the preferred Windows installation mechanism for enterprise o automated and manual coverage. - Gateway state ownership and cleanup are documented, including behavior for multiple Windows users. +- Package removal and destructive reset have distinct, documented behavior, + including administrator responsibility for managed-device decommissioning. +- Host lifecycle operations and native `openclaw gateway` commands cannot + create conflicting managed Gateway instances or bypass staged-payload + activation. - Package capability changes are reviewable and release-blocking. - Existing local Gateway users, including WSL users, have a documented migration path to the packaged deployment.