Browser proxy should be ready-to-use or visibly blocked with a guided repair path

[RomneyDa]

Problem

Browser control requires a separately running browser-control host on Gateway port + 2. Current diagnostics explain some failure modes, but a normal user can still request a browser action, see no visible result, and watch the agent unsuccessfully troubleshoot or restart the Gateway.

Desired outcome

Browser control is either ready to use or clearly unavailable with a concrete in-app repair path.

Definition of done

• Run a preflight when Browser Control is enabled and before the first browser request.
• Distinguish absent, unreachable, unauthenticated, and incorrectly SSH-forwarded hosts.
• Offer a concrete repair action: start/install/configure the host, or explicitly disable the capability with a clear explanation.
• Supply concise capability-state guidance to chat/agent context so it does not repeatedly restart the Gateway to diagnose the same prerequisite.
• Add local MCP and gateway-mediated proof for success and each blocked state.

Related

• Browser-host installer/launcher is still explicitly unfinished in docs/WINDOWS_NODE_ARCHITECTURE.md.
• Tool containment testing + triage (camera, browser) #850 is the broader camera/browser containment tracking epic.
• PCMag report (Aug. 6, 2026): https://www.pcmag.com/opinions/microsoft-thinks-openclaw-is-the-future-of-windows-my-testing-says-otherwise

[clawsweeper]

Codex review: this still needs some work. Reviewed September 28, 2026, 3:11 PM ET / 19:11 UTC.

Summary
Current main still sends browser actions without the requested readiness check or state-specific recovery. The earlier fix PR closed unmerged, and the maintainer's validated checkpoint has no published PR; current-release reports show the blocked experience remains relevant.

Reproducibility: yes. for the readiness gap: current source sends the requested browser action without a separate preflight, and current-release reports describe the owner-verification blocked state. This read-only review did not execute the full live state matrix.

Root-cause cluster
Relationship: canonical
Canonical: #1154
Summary: This issue owns browser-specific guided readiness; related reports cover an overlapping blocked state, broader capability diagnostics, and a separate host-installation lane.

Members:

• partial_overlap: Windows browser.proxy blocked: local listener owner could not be verified after clean WSL reinstall #1333 - The maintainer retained its listener-owner failure as a distinct current-release acceptance case.
• partial_overlap: Show why camera, browser proxy, and system.run are unavailable, with actionable status for users and agents #1155 - It requests shared status across browser, camera, and system.run; this issue owns browser-host repair guidance.
• superseded: fix: preflight browser proxy readiness #1157 - The earlier readiness implementation closed unmerged and does not own the current work.
• adjacent_distinct: feat(browser): install and pair Chrome with Windows Companion #1446 - That open draft concerns Chrome installation and pairing, outside the approved guided-readiness increment.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Next step
The security-sensitive, maintainer-owned increment has an unpublished checkpoint and a trusted live-proof blocker, so another automated fix PR is not a safe route.

Security
Needs attention: The proposed authenticated probe is security-sensitive because browser requests use a shared gateway token.

Review details

Best possible solution:

Land the approved authenticated status preflight with inline Doctor or Fix guidance and an explicit Disable option, while retaining listener-owner verification before every shared-token request.

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

Yes for the readiness gap: current source sends the requested browser action without a separate preflight, and current-release reports describe the owner-verification blocked state. This read-only review did not execute the full live state matrix.

Is this the best way to solve the issue?

Yes. The maintainer-approved, read-only check is a bounded way to explain failures without adding browser-host installation to this increment; it must retain the existing token-safety gate.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The reported checkpoint has no published PR or trusted browser listener environment for live ready-state and complete blocked-state proof through MCP and the Gateway.

Codex review notes: model internal, reasoning high; reviewed against dba81213371c.

Label changes

Label changes:

No label changes.

Label justifications:

• P0: A first-time user can enable Browser Control yet remain blocked, with recovery currently requiring technical host and forwarding steps.
• impact:security: Browser requests carry a shared token, so readiness checks must preserve listener-owner verification before delivery.
• impact:ux-release-blocker: The reported Browser Control path has no complete in-app way to identify and repair a missing or unverified host.

Evidence reviewed

Security concerns:

• [high] Preserve listener verification before token delivery — src/OpenClaw.Shared/Capabilities/BrowserProxyCapability.cs:80
  The existing proxy checks listener ownership before its shared-token request. The readiness probe must do the same for each request, including after a listener or forward changes.
  Confidence: 0.95

What I checked:

• Current request path: ExecuteAsync resolves the endpoint and optionally verifies its owner, then immediately sends the requested method and path; it has no separate browser-host readiness preflight. (src/OpenClaw.Shared/Capabilities/BrowserProxyCapability.cs:77, dba81213371c)
• Security boundary: The proxy checks listener ownership before sending a request with the shared token. App wiring verifies a managed local listener or an owned SSH forward. (src/OpenClaw.Tray.WinUI/App.xaml.cs:2337, dba81213371c)
• Partial existing diagnostics: Command Center warns when the browser host port is not listening and offers copied setup guidance, but the browser status projection contains settings, token, port, forward, and caveat fields rather than live host readiness. (src/OpenClaw.Tray.WinUI/Services/ConnectionDiagnosticsProjection.cs:435, dba81213371c)
• Current documented prerequisite: The testing guide says a separate browser-control host must listen on gateway port plus two and describes manual SSH, token, and host checks. (docs/WINDOWS_NODE_TESTING.md:208, dba81213371c)
• Current test scope: Existing capability tests cover direct forwarding, endpoint selection, unauthorized responses, and blocking token delivery to an unverified listener; they do not establish the requested status preflight. (tests/OpenClaw.Shared.Tests/CapabilityTests.cs:963, dba81213371c)
• Maintainer direction and checkpoint: The September 28 maintainer comments approve a guided, non-mutating readiness increment that preserves listener-owner verification. A later checkpoint reports local validation and blocked-state MCP/Gateway observations, but explicitly says ready-state live proof is unavailable and no PR was created. Browser proxy should be ready-to-use or visibly blocked with a guided repair path #1154 (comment) and Browser proxy should be ready-to-use or visibly blocked with a guided repair path #1154 (comment).

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)
• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; 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.