feat: add clawctl open command

[paulcam206]

What Problem This Solves

The packaged clawctl surface has no safe command that opens the authenticated Control UI for its managed gateway.

User Impact

User impact: after setup and gateway startup, users can run clawctl open to open OpenClaw's verified one-time browser handoff without revealing the long-lived gateway token.

Why This Change Was Made

clawctl open requires completed setup and a positively observed running managed gateway, then delegates TLS, base-path, authentication, readiness, and one-time pairing resolution to packaged OpenClaw's dashboard --json flow. The launcher accepts only an absolute loopback HTTP(S) handoff whose port the managed gateway was actually observed listening on, opens it through the Windows default browser, and never writes the authenticated URL to human output, JSON, or logs.

Because the managed gateway can be pinned to a port that the agent's own OpenClaw configuration does not name, the dashboard child is resolved against the gateway's single verified observed port through upstream's supported OPENCLAW_GATEWAY_PORT contract. Without that, upstream resolved its default port and reported the gateway as not running.

Gateway status output now directs users to clawctl open instead of recommending token disclosure. Missing or incomplete setup and non-running gateways fail without starting lifecycle work or opening a browser.

Evidence

Validated at head 04b5124c241fea9d0b369921516655e575773edb:

• .\scripts\Test-DotNetQuality.ps1 — passed with 0 warnings and 0 errors.
• dotnet test .\OpenClaw.Gateway.MSIX.slnx --configuration Release --no-restore — 834 passed.
• .\scripts\Test-NativeAotCli.Tests.ps1 — 18 NativeAOT scenarios passed.
• .\scripts\Test-DocReferences.ps1 — 0 findings.
• .\scripts\Test-Deploy-LocalPackage.Tests.ps1 — passed, including repair of missing or modified staged redirect scripts.

Real end-to-end runs against an installed local package with completed setup and a running managed gateway:

• Default port (18789): clawctl open --json exited 0 and the default browser opened the Control UI. Standard output carried only {"ok":true,...,"gateway":{"state":"running"}} with no URL, token fragment, or port.
• Custom port: the gateway was restarted pinned to 51789 while the agent's own gateway.port remained unset, so upstream's own resolution still pointed at its default. clawctl open --json exited 0 with no host environment override set, targeting the gateway purely from its observed port.
• Counterfactual for the same condition: openclaw dashboard --json, which reaches upstream without the override exactly as the previous revision did, exited 1 with {"ok":false,"reason":"Gateway is not running."}. That is the defect this revision fixes.
• The gateway was returned to its default port afterward.

Destination and session authority, exercised through the production validator using genuine captured upstream handoff output rather than synthetic text:

• Genuine output on the observed port was accepted.
• The same genuine output was rejected when the observed-port set was substituted, before any browser activation.
• The same genuine output failed closed when no ports were observed.

Stale-session final effect, observed against the installed package with a genuine handoff in flight. The recorded session was replaced while a real clawctl open was resolving its handoff, then restored byte-for-byte:

ORIGINAL_GENERATION=ecff56f7...        (truncated)
REPLACED_AT_MS=8000
OPEN_EXIT=1
OPEN_OUTPUT={"ok":false,"command":"open","error":{"type":"cli_error",
  "message":"the recorded isolated-session generation changed before the
  operation completed. Retry the command"}}
RESTORED_EXACT=True

The browser was not activated, and no authenticated URL or token was emitted. Repeating the replacement across a range of timings produced the same rejection whenever it landed inside the run; the session-identity guard fires while the handoff is still being resolved, so activation is never reached. The final pre-activation re-check of the recorded sandbox and generation is the defense-in-depth behind that guard; its window is too narrow to drive from outside the process, so it is covered by deterministic final-effect tests instead, which also assert zero browser calls for a substituted port and for a replaced session.

Not run: signing and MSIX composition lanes, because this change does not modify package contents, manifest, signing inputs, or release policy. The captured authenticated handoff used for the authority checks was held outside the repository and deleted; no authenticated URL or token appears in this PR, the tests, or the repository.

[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 21, 2026, 3:55 PM ET / 19:55 UTC (Revision 4).

ClawSweeper review

What this changes

Adds clawctl open to launch the managed gateway’s authenticated Control UI, updates command guidance, and includes native redirect scripts in local deployment layouts.

Merge readiness

✅ Ready for maintainer review

This PR remains useful: current main lacks the command, the earlier code findings are addressed, and the updated installed-package evidence resolves the remaining stale-session proof concern. No blocking introduced defect was found.

Priority: P2
Reviewed head: 04b5124c241fea9d0b369921516655e575773edb

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with relevant installed-package authority proof, reported native validation, and no remaining blocking findings.
Proof confidence	🐚 platinum hermit (4/6)	Sufficient (terminal): Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (terminal): Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.
Evidence reviewed	10 items	Pinned change ownership: Reviewed the introduced delta from ee41ab7 to 04b5124 across all 16 files. Raw test-merge records also identify the pinned main followed by the exact PR head as parents. Still necessary on main and latest release: The main command tree has no open command. The latest release, v2026.9.4-msix.3, targets the same main SHA. The repository pull-request listing did not identify a replacement implementing this command. Release verification: GitHub reports v2026.9.4-msix.3 published on September 19, 2026, targeting ee41ab7; the proposed command is not in that release.
Findings	None	None.
Security	None	None.

How this fits together

The Windows launcher manages an isolated OpenClaw session and its gateway. The new command asks packaged OpenClaw for a browser handoff, validates its destination and session identity, then activates the Windows default browser.

flowchart LR
    A[clawctl open] --> B[Check setup and running gateway]
    B --> C[Packaged OpenClaw dashboard]
    C --> D[One-time browser handoff]
    D --> E{Observed port and current session}
    E -->|Valid| F[Windows default browser]
    E -->|Invalid| G[Safe error without credentials]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test line delta	Production +413/-29; tests +647/-9	Production growth supports the browser handoff, captured session execution and deployment repair, with broader regression coverage.

Technical review

Best possible solution:

Keep upstream responsible for authenticated handoff creation and the Windows launcher responsible for validating and activating it without exposing credentials.

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

Not applicable as a feature request; main’s command tree confirms the missing capability, and supplied installed-package runs demonstrate the proposed behavior.

Is this the best way to solve the issue?

Yes. Reusing upstream dashboard resolution while keeping destination validation and browser activation in the Windows host preserves the existing ownership boundaries.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove merge-risk: 🚨 security-boundary: Current PR review selected no merge-risk labels.

Label justifications:

• P2: This is a bounded usability improvement for opening the managed gateway’s authenticated Control UI.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.
• proof: sufficient: Contributor real behavior proof is sufficient. Installed-package clawctl open runs demonstrate allowed browser activation on default and custom ports; genuine-output destination checks and the new real session-replacement transcript demonstrate rejection before activation. Deterministic tests supplement the narrow final-check window, resolving the previous authority-proof request.

Evidence

What I checked:

• Pinned change ownership: Reviewed the introduced delta from ee41ab7 to 04b5124 across all 16 files. Raw test-merge records also identify the pinned main followed by the exact PR head as parents. (04b5124c241f)
• Still necessary on main and latest release: The main command tree has no open command. The latest release, v2026.9.4-msix.3, targets the same main SHA. The repository pull-request listing did not identify a replacement implementing this command. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs:190, ee41ab70e76c)
• Release verification: GitHub reports v2026.9.4-msix.3 published on September 19, 2026, targeting ee41ab7; the proposed command is not in that release. (ee41ab70e76c)
• Production authority and prior repairs: The handler requires setup and an observed running gateway, supplies the single observed port and native runtime fields to the captured dashboard launch, validates the handoff, and rechecks sandbox generation before browser activation. Shell activation now permits a null process handle. These address all three earlier code findings. (src/OpenClaw.Launcher/Program.cs:612, 04b5124c241f)
• Explicit upstream dependency: The new production handler executes packaged openclaw.mjs with dashboard --json. The workflow pins upstream to 3a9d69db306cd7f081e06254cb89c4bcc14a7107, making that upstream dashboard contract relevant to this review. (.github/workflows/gateway-msix.yml:34, 04b5124c241f)
• Pinned upstream handoff contract: The pinned dashboard JSON implementation disables recovery, verifies readiness and the applicable loopback alias, then returns a separately minted browserUrl. This supports delegating authentication, TLS and base-path resolution to upstream rather than implementing a competing resolver. (src/commands/dashboard.ts, 3a9d69db306c)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• 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-19T01:51:33.904Z sha 7f46faf :: needs real behavior proof before merge. :: [P2] Preserve native-runtime setup in the captured dashboard launch | [P2] Accept successful shell activation without a process handle
• reviewed 2026-09-21T19:01:16.324Z sha 747ea81 :: needs real behavior proof before merge. :: [P2] Pass the managed gateway’s effective port to the dashboard
• reviewed 2026-09-21T19:34:25.495Z sha 867f0b5 :: needs real behavior proof before merge. :: none

[paulcam206]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[paulcam206]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/35645878140
• Updated: 2026-09-21T19:36:59.708Z

[paulcam206]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.