feat: set up on first launch and start eligible gateways

[paulcam206]

What Problem This Solves

Users must currently run separate setup and gateway-start commands before a clean OpenClaw installation becomes fully usable.

User Impact

User impact: openclaw now provisions an installation that has never been set up and automatically starts a startup-eligible stopped gateway after a successful interactive command.

The first openclaw invocation on a clean machine creates the MXC session, agent profile/runtime, and sign-in recovery state. CLAWCTL_AUTO_SETUP=0 restores the previous fail-with-setup-guidance behavior, and CLAWCTL_AUTO_GATEWAY_START=0 restores the previous gateway-start hint.

Why This Change Was Made

Automatic setup reuses the existing setup owner and runs only when the setup marker is absent. Preparing, tearing-down, unreadable, incomplete, foreign-identity, newer-schema, and stale-runtime states retain their explicit recovery paths.

Gateway auto-start reuses the existing gateway controller and runs only after a successful interactive command when configuration is startup-eligible and the gateway is NotStarted or positively observed Stopped. Start failures warn on stderr without changing the OpenClaw child exit code. Successful startup and its per-logon acknowledgement are recorded in one lifecycle critical section.

Automatic-start progress retains the process console capability established before postflight so interactive Windows Terminal sessions use Spectre live status. Cold starts wait up to 90 seconds for the listener before reporting that the gateway is still starting.

Evidence

Validated at head da5293a0e015fe0d18164f4202afa5ce98e5623f:

• .\scripts\Test-DotNetQuality.ps1 — passed with no warnings or errors
• dotnet test .\tests\OpenClaw.Launcher.Tests\OpenClaw.Launcher.Tests.csproj --configuration Release --no-build --no-restore --nologo — 1,036 passed
• .\scripts\Test-NativeAotCli.Tests.ps1 — 23 scenarios passed, including first launch, prepared launch, setup opt-out, gateway-start opt-out, stdout ownership, and native alias identity
• .\scripts\Test-DocReferences.ps1 — 0 findings
• git diff --check — passed
• ClawSweeper review on the prior head identified a late gateway-acknowledgement race; the acknowledgement is now rechecked under the automatic-start lifecycle lock, with a deterministic delayed-postflight/start/stop regression

Not run:

• Installed-MSIX deployment or real-session mutation was not run on the developer machine; lifecycle behavior is covered by fixture-owned functional tests and the published NativeAOT driver.
• ClawSweeper re-review of the updated head is pending.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 21, 2026, 8:58 PM ET / September 22, 2026, 00:58 UTC (Revision 3).

ClawSweeper review

What this changes

The Windows launcher automatically sets up a never-configured installation and starts eligible gateways after successful interactive commands, with environment-variable opt-outs.

Merge readiness

✅ Ready for maintainer review

The previous acknowledgement-race blocker is resolved, and no remaining blocking defect was found. The feature remains absent from current main and the latest release.

Priority: P2
Reviewed head: da5293a0e015fe0d18164f4202afa5ce98e5623f

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The implementation has coherent lifecycle ownership, focused regression coverage, and reported native validation, with the prior blocker resolved.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from the external proof gate. Reported NativeAOT runs exercise first-use and prepared-launch routing through Program.RunAsync with fixture-owned isolation boundaries; live MXC provisioning, installed upgrades, and real gateway startup are not claimed.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored PR is exempt from the external proof gate. Reported NativeAOT runs exercise first-use and prepared-launch routing through Program.RunAsync with fixture-owned isolation boundaries; live MXC provisioning, installed upgrades, and real gateway startup are not claimed.
Evidence reviewed	8 items	Previous blocker resolved: Automatic startup now acquires the lifecycle lock, rechecks the current logon's acknowledgement, and invokes the controller's no-reacquire startup path. The prior reviewed source was also inspected through GitHub and lacked this locked suppression check. Deterministic race regression: LateAcknowledgementAfterStopSuppressesPendingAutomaticStart pauses the status response, records acknowledgement under the lifecycle lock, resumes postflight, and asserts that no automatic start occurs. This addresses the previous review's concrete rank-up request. Setup and compatibility boundary: Automatic setup checks marker absence twice, including under the lifecycle lock, and shares the explicit setup implementation. Existing-marker, interrupted-setup, foreign-marker, opt-out, prepared-installation, and concurrent-first-launch coverage exercises preservation of the established state boundary; no persisted schema is changed.
Findings	None	None.
Security	None	None.

How this fits together

The Windows launcher forwards OpenClaw commands into an isolated agent session. Its setup and gateway lifecycle owners prepare that session, launch commands, and manage the background gateway.

flowchart TD
    A[OpenClaw invocation] --> B{Setup marker absent?}
    B -->|Yes and enabled| C[Shared setup owner]
    B -->|No| D[Validate recorded session]
    C --> D
    D --> E[Run command inside isolated session]
    E --> F{Successful interactive command and eligible gateway?}
    F -->|Yes and enabled| G[Start gateway under lifecycle lock]
    F -->|Otherwise| H[Return child exit code]
    G --> H

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +627 net lines; tests +1,691 net lines	Production growth supports the new automatic lifecycle paths while consolidating setup ownership; tests cover lifecycle decisions, concurrency, and native startup.

Technical review

Best possible solution:

Keep automatic first-use setup and eligible gateway startup within the existing lifecycle owners, preserving opt-outs and explicit recovery for degraded state.

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

Not applicable to the feature request; source inspection confirms the prior race is repaired and its deterministic regression covers the reported interleaving.

Is this the best way to solve the issue?

Yes. Sharing the existing setup implementation and gateway controller avoids competing lifecycle owners while retaining state validation and opt-outs.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 207d19d0fd28.

Labels

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored PR is exempt from the external proof gate. Reported NativeAOT runs exercise first-use and prepared-launch routing through Program.RunAsync with fixture-owned isolation boundaries; live MXC provisioning, installed upgrades, and real gateway startup are not claimed.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove merge-risk: 🚨 compatibility: Current PR review selected no merge-risk labels.

Label justifications:

• P2: This is a bounded Windows first-run and gateway-start improvement without an established urgent production regression.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored PR is exempt from the external proof gate. Reported NativeAOT runs exercise first-use and prepared-launch routing through Program.RunAsync with fixture-owned isolation boundaries; live MXC provisioning, installed upgrades, and real gateway startup are not claimed.

Evidence

What I checked:

• Previous blocker resolved: Automatic startup now acquires the lifecycle lock, rechecks the current logon's acknowledgement, and invokes the controller's no-reacquire startup path. The prior reviewed source was also inspected through GitHub and lacked this locked suppression check. (src/OpenClaw.Launcher/Gateway/AgentGatewayGuidance.cs:197, da5293a0e015)
• Deterministic race regression: LateAcknowledgementAfterStopSuppressesPendingAutomaticStart pauses the status response, records acknowledgement under the lifecycle lock, resumes postflight, and asserts that no automatic start occurs. This addresses the previous review's concrete rank-up request. (tests/OpenClaw.Launcher.Tests/Gateway/AgentGatewayGuidanceTests.cs:127, da5293a0e015)
• Setup and compatibility boundary: Automatic setup checks marker absence twice, including under the lifecycle lock, and shares the explicit setup implementation. Existing-marker, interrupted-setup, foreign-marker, opt-out, prepared-installation, and concurrent-first-launch coverage exercises preservation of the established state boundary; no persisted schema is changed. (src/OpenClaw.Launcher/Session/SetupOrchestrator.cs:68, da5293a0e015)
• Current main still needs this feature: Fetched main directly calls StartForExecutionAsync without automatic setup. Its gateway postflight still prints the start hint rather than starting the gateway. The open-PR listing did not identify another replacement implementing this work. (src/OpenClaw.Launcher/Gateway/AgentGatewayGuidance.cs:79, 207d19d0fd28)
• Latest release check: The latest release, v2026.9.4-msix.3, also calls StartForExecutionAsync directly and contains neither EnsureSetup nor SetupOrchestrator in its launcher entrypoint. The release tag resolves to the recorded release commit. (src/OpenClaw.Launcher/Program.cs:304, ee41ab70e76c)
• Validation and proof scope: The captured PR body reports the quality gate, 1,036 tests, 23 NativeAOT scenarios, documentation references, and whitespace checks passing at the exact head. The native driver exercises Program.RunAsync with fixture-owned session and recovery collaborators. Installed-MSIX deployment and real-session mutation were explicitly not run; these results are not represented as live MXC provisioning proof. The author is a COLLABORATOR, so the external-contributor proof gate does not apply. (tests/OpenClaw.Launcher.AotSmoke/SmokeProgram.cs:528, da5293a0e015)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• 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.

History

Review history (2 earlier review cycles)

• reviewed 2026-09-21T23:59:56.232Z sha 535c476 :: blocked before merge. :: [P2] [P2] Recheck acknowledgement under the gateway startup lock
• reviewed 2026-09-22T00:20:28.967Z sha 535c476 :: blocked before merge. :: [P2] [P2] Recheck acknowledgement under the gateway startup lock