Add README guidance for migrating to MXC Sessions

[samanthamsong]

Problem

Users with an existing WSL-based OpenClaw Gateway do not have clear README guidance for moving to the native Windows Gateway running inside an MXC Session. The supported migration path, prerequisites, preservation guarantees, and recovery steps need to be explicit before MXC Sessions become the primary local setup model.

Proposed documentation

Add a migration section to the repository README that explains:

• What an MXC Session is and why the local Gateway runs inside one.
• Which Windows and MXC capabilities are required.
• How to determine whether the current PC supports the migration.
• How to migrate an existing WSL-based Gateway to a local Windows Gateway in an MXC Session.
• Which Gateway configuration, credentials, identity, sessions, and user data are preserved or moved.
• How the Companion App detects an existing installation and offers migration.
• How to verify that the new Gateway and Windows Node are connected and healthy.
• How to recover, retry, or roll back safely if migration fails.
• How to continue connecting to an existing remote Gateway instead of migrating.
• Known limitations and where to find diagnostics or support.

Acceptance criteria

• The README contains a discoverable, step-by-step migration guide.
• The guide clearly distinguishes the Gateway Session from per-tool process containment.
• Prerequisites and unsupported configurations are documented before any destructive step.
• Data-preservation and rollback behavior are stated explicitly.
• Commands, UI labels, and paths match the shipping Companion App experience.
• The guide links to the detailed architecture, setup, testing, and troubleshooting documentation where appropriate.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 16, 2026, 2:52 PM ET / 18:52 UTC.

Summary
Keep open. The requested migration guide is absent, and current main still provisions WSL gateways. This collaborator-authored documentation request needs a confirmed migration contract before it can describe supported shipping behavior.

Reproducibility: not applicable. as a runtime bug reproduction. Source inspection confirms the documentation gap and the current WSL-based setup contract.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should this guide wait for an implemented MXC Gateway migration contract, or is there an approved implementation and target release that documentation should follow?	Gate the guide on the migration contract: Keep this documentation task open until the implementation defines supported hosts, data transfer, recovery, and exact UI labels.

Why: Current setup implements WSL installation and replacement, so an automated documentation change cannot safely invent migration commands or preservation guarantees.

Next step
Confirm the migration implementation and release scope before assigning a documentation PR; the preservation and recovery contract cannot safely be inferred.

Review details

Best possible solution:

Publish a versioned migration guide alongside a validated migration workflow, preserving remote-gateway choice and clearly separating Gateway Sessions from per-command containment.

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

Not applicable as a runtime bug reproduction. Source inspection confirms the documentation gap and the current WSL-based setup contract.

Is this the best way to solve the issue?

Yes, a discoverable README guide is appropriate, but its procedural steps must follow an implemented and validated migration contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The migration's supported platforms, data-preservation guarantees, UI entrypoint, and rollback behavior are not established by current source; publishing procedural instructions now could misrepresent destructive WSL replacement as migration.

Codex review notes: model internal, reasoning medium; reviewed against 3c43751b2bac.

Label changes

Label changes:

• add P3: This is prospective migration documentation, with no reported failure blocking the currently supported setup path.
• add issue-rating: 🌊 off-meta tidepool: 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:

• P3: This is prospective migration documentation, with no reported failure blocking the currently supported setup path.

Evidence reviewed

What I checked:

• Current README distinguishes setup from containment: The full README describes installing a local WSL gateway or connecting an existing gateway. Lines 123-125 limit MXC sandbox coverage to Windows-node commands; no WSL-to-Gateway-Session migration guide is present. (README.md:123, 3c43751b2bac)
• Production setup remains WSL-based: BuildDefaultSteps provisions a WSL distro, installs the gateway service, pairs operator and node, and verifies connectivity. It does not implement the requested migration. (src/OpenClaw.SetupEngine/SetupPipeline.cs:90, 3c43751b2bac)
• Existing-install detection is not migration: The classifier distinguishes app-owned local WSL gateways from external connections. ONBOARDING_WIZARD.md describes replacing the app-owned WSL installation with an explicit deletion warning, not moving its data into an MXC Session. (src/OpenClaw.Tray.WinUI/Services/SetupExistingGatewayClassifier.cs:28, 3c43751b2bac)
• Tests establish the current setup contract: The default-pipeline test asserts WSL preflight, platform setup, lockdown, gateway startup, pairing, and end-to-end verification. Tests were inspected, not executed, under the read-only review contract. (tests/OpenClaw.SetupEngine.Tests/SetupPipelineTests.cs:101, 3c43751b2bac)
• Latest release has the same baseline: The checkout is 3c43751 and carries tag v2026.9.4. GitHub identifies v2026.9.4 as the latest release, published September 15, 2026; the requested guide is absent from this baseline. (3c43751b2bac)
• Related session work is distinct: MXC session management (Entra Agent Sessions + WAM helper) #849 is a closed request for Entra/WAM session authentication. Its comments show an inactivity closure, not an implemented migration. Canonical searches found no replacement migration guide; the supplied merged chat PRs are unrelated.

Likely related people:

• samanthamsong: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Scott Hanselman: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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.