[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 661906f3f6d586504512a7f1dc3625663047a052 after rebasing onto 0afdfad. The managed and NativeAOT lanes ran at parent f3b9873af065b6ff42416b78cd2856e6bcd8577e; the head adds only a local-development documentation correction:

• .\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,062 passed
• .\scripts\Test-NativeAotCli.Tests.ps1 — 24 scenarios passed, including PowerShell completion, 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
• Documentation audit — changed user, architecture, troubleshooting, output-style, evidence, and instruction surfaces agree with source; unchanged contributor, release, local-development, script, and test guidance was skimmed, and the stale -SkipSetup instruction was corrected
• ClawSweeper reviewed pre-rebase head da5293a0e015fe0d18164f4202afa5ce98e5623f with no actionable or security findings; the rebase integration is additionally covered by the validation above

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 has not yet reviewed the rebased head.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 22, 2026, 1:15 PM ET / 17:15 UTC (Revision 4).

ClawSweeper review

What this changes

The Windows launcher provisions first-use installations and starts eligible gateways after successful interactive commands, with environment-variable opt-outs, progress output, and lifecycle regression coverage.

Merge readiness

✅ Ready for maintainer review

This remains useful work absent from current main and the latest release. The earlier acknowledgement race is fixed, and the rebased patch has no actionable correctness or security findings.

Priority: P2
Reviewed head: f3b9873af065b6ff42416b78cd2856e6bcd8577e

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A coherent implementation with focused lifecycle coverage, reported native validation, and no remaining actionable findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: The external-contributor gate does not apply to this collaborator-authored PR. Reported NativeAOT execution covers the production startup route with fixture-owned MXC and recovery collaborators; installed-package and real-session behavior were not exercised. No stored-data contract changes require migration proof.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The external-contributor gate does not apply to this collaborator-authored PR. Reported NativeAOT execution covers the production startup route with fixture-owned MXC and recovery collaborators; installed-package and real-session behavior were not exercised. No stored-data contract changes require migration proof.
Evidence reviewed	8 items	Reviewed change identity: Reviewed all 27 introduced paths between pinned main 0afdfad and original PR head f3b9873. The supplied verified test merge has those exact main and head parents; there is no base-only drift. Single provisioning owner and preserved recovery: EnsureAsync admits only a missing setup marker, repeats that check under the lifecycle lock, and calls the setup sequence extracted from Program. Existing, unreadable, foreign, preparing, and tearing-down markers are not implicitly repaired. Focused tests cover prepared installations, opt-outs, failed recovery registration, and concurrent first launches. Previous blocking race resolved: Automatic startup rechecks the per-logon acknowledgement after acquiring the lifecycle lock, then calls the controller without reacquiring it. Successful-start acknowledgement occurs before lock release. LateAcknowledgementAfterStopSuppressesPendingAutomaticStart covers the previous blocker. The earlier reviewed SHA was unavailable locally, so no unchanged-code claim is inferred from it.
Findings	None	None.
Security	None	None.

How this fits together

The Windows launcher forwards OpenClaw commands into an isolated agent session. Setup prepares that session, while gateway postflight uses configuration readiness and observed process state to decide whether to start the background gateway.

flowchart TD
    A[OpenClaw invocation] --> B{Setup marker absent?}
    B -->|Yes and enabled| C[Shared setup owner]
    B -->|No or opted out| D[Validate recorded session]
    C --> D
    D --> E[Run OpenClaw in isolation]
    E --> F{Successful and eligible?}
    F -->|Yes and enabled| G[Start gateway under lifecycle lock]
    F -->|Otherwise| H[Preserve exit code and recovery guidance]
    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 automatic lifecycle coordination and shared ownership; most added lines provide fixture and regression coverage.

Technical review

Best possible solution:

Keep provisioning and gateway startup in their existing owners, with automatic behavior limited by explicit state checks and documented opt-outs.

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

Not applicable as a defect reproduction: this PR adds automatic behavior. Source confirms main still requires explicit setup and provides a gateway-start hint.

Is this the best way to solve the issue?

Yes. Extracting the existing setup sequence and reusing the gateway controller avoids competing lifecycle owners while preserving argument forwarding and explicit degraded-state recovery.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 0afdfad29910.

Labels

Label changes:

No label changes.

Label justifications:

• P2: This is a bounded first-launch and gateway usability improvement without an established urgent 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 external-contributor gate does not apply to this collaborator-authored PR. Reported NativeAOT execution covers the production startup route with fixture-owned MXC and recovery collaborators; installed-package and real-session behavior were not exercised. No stored-data contract changes require migration proof.

Evidence

What I checked:

• Reviewed change identity: Reviewed all 27 introduced paths between pinned main 0afdfad and original PR head f3b9873. The supplied verified test merge has those exact main and head parents; there is no base-only drift. (f3b9873af065)
• Single provisioning owner and preserved recovery: EnsureAsync admits only a missing setup marker, repeats that check under the lifecycle lock, and calls the setup sequence extracted from Program. Existing, unreadable, foreign, preparing, and tearing-down markers are not implicitly repaired. Focused tests cover prepared installations, opt-outs, failed recovery registration, and concurrent first launches. (src/OpenClaw.Launcher/Session/SetupOrchestrator.cs:52, f3b9873af065)
• Previous blocking race resolved: Automatic startup rechecks the per-logon acknowledgement after acquiring the lifecycle lock, then calls the controller without reacquiring it. Successful-start acknowledgement occurs before lock release. LateAcknowledgementAfterStopSuppressesPendingAutomaticStart covers the previous blocker. The earlier reviewed SHA was unavailable locally, so no unchanged-code claim is inferred from it. (src/OpenClaw.Launcher/Gateway/AgentGatewayGuidance.cs:197, f3b9873af065)
• Existing isolation and persistence contracts retained: Gateway startup still validates setup and session identity, rejects uncertain or pending ownership, and dispatches through SessionGatewayClient and its generation-checked workspace operations. The patch changes when existing operations run without changing persisted record schemas, protocol versions, dependency pins, signing inputs, or execution principals. (src/OpenClaw.Launcher/Gateway/GatewayController.cs:220, f3b9873af065)
• Still necessary on main and in the latest release: The guidance implementation on pinned main and release commit ee41ab7 only prints a start hint. GitHub release metadata identifies that commit as v2026.9.4-msix.3, published September 19. The merged predecessor Add agent config readiness and gateway start guidance #79 explicitly supplies readiness and guidance, not this automatic lifecycle behavior. (src/OpenClaw.Launcher/Gateway/AgentGatewayGuidance.cs:79, ee41ab70e76c)
• Reported validation and its scope: The complete supplied PR body reports the quality gate, 1,062 launcher tests, 24 NativeAOT scenarios, documentation references, and whitespace checks passing at the reviewed head. The native fixture invokes Program.RunAsync for first launch, prepared launch, forwarding, and setup opt-out, while replacing MXC and recovery registration with fixture collaborators. Installed-MSIX deployment and real-session mutation are explicitly unrun. Collaborator authorship exempts this PR from the external-contributor live-proof gate. (tests/OpenClaw.Launcher.AotSmoke/SmokeProgram.cs:543, f3b9873af065)

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 (3 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
• reviewed 2026-09-22T00:58:47.904Z sha da5293a :: needs maintainer review before merge. :: none

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.