Add agent config readiness and gateway start guidance

[paulcam206]

What Problem This Solves

The packaged openclaw.exe launcher cannot currently distinguish an unconfigured agent from one whose default config is eligible to start the managed gateway, so status output and successful commands cannot give timely, accurate startup guidance.

User Impact

User impact: users can see whether a stopped gateway is unconfigured, not ready, or startup eligible, and successful interactive OpenClaw commands gently suggest clawctl gateway-service start only when that action is appropriate.

The readiness result is intentionally a file-only heuristic for the isolated agent's default openclaw.json; it does not claim that the gateway will remain healthy. Guidance is suppressed for the current Windows logon after a manual start or after the launcher observes the gateway running.

Why This Change Was Made

The isolated agent owns the relevant OpenClaw config, while invoking the supported OpenClaw CLI just to inspect it starts the launcher, session, Node.js, and OpenClaw stack. This change adds a NativeAOT-safe session-host helper that reads only the default config and classifies it as absent, not ready, or startup eligible.

Both clawctl status surfaces use that result only when the gateway is not confirmed running. Successful interactive OpenClaw calls combine startup eligibility with a managed-gateway liveness probe before showing the crab-branded hint. The acknowledgment state is scoped to the current Windows logon, and the final hint decision is serialized with acknowledgment so concurrent invocations cannot emit stale guidance.

Evidence

Validated locally on Windows at head 41041dbd3621e8113edb38197c8b8dd6a34d6243:

• .\scripts\Test-DotNetQuality.ps1 — passed with zero warnings or errors and clean whitespace/code-style checks.
• dotnet test .\OpenClaw.Gateway.MSIX.slnx --configuration Release --no-restore — 778 passed.
• .\scripts\Test-NativeAotCli.Tests.ps1 — passed, including NativeAOT readiness JSON and capability-aware colored crab-hint scenarios.
• A final committed-range review found two acknowledgment concurrency defects. Both were fixed before the original PR head, with regression coverage for busy lock acquisition and a racing acknowledgment.
• ClawSweeper reviewed 6d11e42 and found three compatibility defects. This head contains regression coverage proving that MXC advisory failures preserve successful and nonzero child exit codes, MXC and malformed-protocol readiness failures retain both structured status documents as unknown, exact retained recovery scripts upgrade to --recovery, and modified scripts remain untouched.

Gateway MSIX workflow run 35397086105 and CodeQL run 35397080151 validate this exact head. Change classification passed; the analyzers, CodeQL, OpenClaw npm package build, Gateway MSIX host tests, and x64/ARM64 unsigned package composition were pending when this evidence was recorded.

Live Developer Mode evidence was collected on ancestor f9f27ec:

• a fresh isolated agent repeatedly returned Absent / ConfigFileMissing; successful and failed openclaw calls preserved their exit codes, skipped gateway liveness, emitted no hint, and cleaned their request files;
• after onboarding, both human and JSON status surfaces reported readiness, and a startup-eligible stopped gateway produced the unquoted clawctl gateway-service start hint;
• after manual gateway start, both status surfaces reported running on recorded port 18789, omitted readiness, and the dashboard returned HTTP 200;
• a subsequent openclaw --version returned 0 without adding a readiness probe after the current-logon acknowledgment.

The final console-writer provenance and acknowledgment-serialization commits were not redeployed because loose-package deployment would replace that newly configured running agent session. Those commits are covered by the full xUnit, static-analysis, and NativeAOT lanes above. Official signing was not run because PR builds intentionally produce unsigned packages and the workflow rejects official signing outside main.

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

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 18, 2026, 5:34 PM ET / 21:34 UTC (Revision 3).

ClawSweeper review

What this changes

Adds file-only configuration readiness to Windows gateway status, conditional startup hints after OpenClaw commands, and per-logon hint suppression.

Merge readiness

✅ Ready for maintainer review

The three prior findings are resolved, and no remaining blocking defect was found. This collaborator-authored PR adds useful behavior absent from current main and the latest release.

Likely related people: paulcam206 — high-confidence routing candidate based on prior merged gateway and session work.

Priority: P2
Reviewed head: 41041dbd3621e8113edb38197c8b8dd6a34d6243

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A useful, coherent implementation with all prior blockers repaired and focused compatibility coverage.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-author exemption applies. The body reports real Windows readiness, hint, and suppression observations on f9f27ec; later exception-handling, rendering, and recovery fixes have supplemental test evidence but were not redeployed. No material authorization change creates an additional proof gate.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-author exemption applies. The body reports real Windows readiness, hint, and suppression observations on f9f27ec; later exception-handling, rendering, and recovery fixes have supplemental test evidence but were not redeployed. No material authorization change creates an additional proof gate.
Evidence reviewed	8 items	Prior findings resolved: The exact-head GitHub commit patch adds MxcException containment to the advisory, converts backend and protocol failures into unknown readiness, and handles retained recovery scripts before recording manual acknowledgment. This recovered the relevant comparison after local historical-object retrieval failed. Failure-path regression coverage: BackendAdvisoryFailurePreservesAgentExitCode covers child exit codes 0 and 17. StatusJsonRetainsGatewayWhenReadinessProbeFails covers both status commands with backend failures and mismatched protocol responses, retaining gateway state and unknown readiness. Fresh and retained recovery compatibility: Fresh recovery scripts include --recovery. Retained scripts are upgraded only when their contents exactly match the previous generated script; modified scripts remain untouched. Tests cover retained recovery without false acknowledgment and preservation of modified content.
Findings	None	None.
Security	None	None.

How this fits together

The Windows launcher runs OpenClaw inside an isolated agent session. A session helper reads the agent’s default configuration, and the launcher combines that classification with managed gateway status to display guidance.

flowchart TD
  A[OpenClaw command or status request] --> B[Windows launcher]
  B --> C[Isolated session helper]
  D[Default agent configuration] --> C
  C --> E[Readiness classification]
  F[Gateway state and logon acknowledgment] --> G[Guidance decision]
  E --> G
  G --> H[Status output or startup hint]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +1,259/-65; tests +1,560/-12	Production growth implements the helper protocol, readiness presentation, logon acknowledgment, and recovery compatibility described in the PR.
Previous blockers	3 resolved, 0 remaining	The current implementation and focused regression coverage address every retained finding from the previous review.

Technical review

Best possible solution:

Keep readiness advisory and narrowly scoped to the default configuration, preserving child results, structured diagnostics, and existing recovery behavior.

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

Not applicable to the feature request; the previous defects now have focused regression coverage, inspected but not executed during this read-only review.

Is this the best way to solve the issue?

Yes. The file-only helper supplies narrowly defined guidance without starting OpenClaw to inspect configuration, and the current head contains the necessary failure isolation and retained-script compatibility handling.

AGENTS.md: not found in the target repository.

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

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-author exemption applies. The body reports real Windows readiness, hint, and suppression observations on f9f27ec; later exception-handling, rendering, and recovery fixes have supplemental test evidence but were not redeployed. No material authorization change creates an additional proof gate.
• 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 readiness and startup-guidance improvement without evidence of an urgent user-facing 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-author exemption applies. The body reports real Windows readiness, hint, and suppression observations on f9f27ec; later exception-handling, rendering, and recovery fixes have supplemental test evidence but were not redeployed. No material authorization change creates an additional proof gate.

Evidence

What I checked:

• Prior findings resolved: The exact-head GitHub commit patch adds MxcException containment to the advisory, converts backend and protocol failures into unknown readiness, and handles retained recovery scripts before recording manual acknowledgment. This recovered the relevant comparison after local historical-object retrieval failed. (src/OpenClaw.Launcher/Gateway/AgentGatewayGuidance.cs:85, 41041dbd3621)
• Failure-path regression coverage: BackendAdvisoryFailurePreservesAgentExitCode covers child exit codes 0 and 17. StatusJsonRetainsGatewayWhenReadinessProbeFails covers both status commands with backend failures and mismatched protocol responses, retaining gateway state and unknown readiness. (tests/OpenClaw.Launcher.Tests/ProgramTests.cs:933, 41041dbd3621)
• Fresh and retained recovery compatibility: Fresh recovery scripts include --recovery. Retained scripts are upgraded only when their contents exactly match the previous generated script; modified scripts remain untouched. Tests cover retained recovery without false acknowledgment and preservation of modified content. (src/OpenClaw.Launcher/Gateway/GatewayLauncherScript.cs:78, 41041dbd3621)
• Bounded readiness contract: The helper reads only the agent profile’s default configuration and classifies exact local gateway mode. Documentation explicitly excludes alternate profiles, includes, substitutions, secrets, plugins, and runtime health guarantees. The probe uses the existing session dispatch boundary. (src/OpenClaw.SessionHost/SessionConfigReadinessChecker.cs:31, 41041dbd3621)
• Still necessary on main and latest release: Current main’s status handlers report gateway state without configuration readiness. The latest release tag points to that same main commit. The merged gateway-start work at feat: wait for the gateway and report where it is listening #72 concerns listener readiness and port reporting, not this configuration classification. (src/OpenClaw.Launcher/Program.cs:420, a99bb66d2162)
• Release identity: The inspected main revision carries v2026.9.4-msix.2; this PR’s readiness additions are not in that release. (a99bb66d2162)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; 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-18T21:17:09.234Z sha 6d11e42 :: blocked before merge. :: [P2] Contain backend failures in the post-command advisory | [P2] Convert backend and protocol probe errors into unknown readiness | [P2] Handle retained recovery scripts when adding the provenance flag
• reviewed 2026-09-18T21:27:02.405Z sha 6d11e42 :: blocked before merge. :: [P2] Contain backend failures in the post-command advisory | [P2] Convert backend and protocol probe errors into unknown readiness | [P2] Handle retained recovery scripts before acknowledging manual starts