Win11 Visible Browser Automation

Control, diagnose, or repair a visible Windows 11 Edge/Chrome browser from OpenClaw running in WSL2 via CDP. Use when browser automation should share the user's real visible browser session, existing tabs, cookies, logins, and state; when login, captcha, 2FA, approvals, or manual takeover require a human-in-the-loop; or when WSL2/OpenClaw browser control needs CDP, firewall, portproxy, attachOnly profile, or Windows browser troubleshooting.

Use this skill when OpenClaw runs in WSL2/Linux but should work in a visible Windows 11 Edge/Chrome browser that the human can watch, use, and take over.

This is for legitimate assisted browsing in a normal visible browser session. Do not use it to bypass site protections, automate prohibited activity, or hide automation from the user.

Safety gate

Before state-changing actions, state what/where/risk/rollback and wait for explicit confirmation. State-changing actions include editing OpenClaw config, creating Scheduled Tasks, changing Windows firewall/portproxy, starting/stopping browser processes, writing scripts outside the workspace, sending forms/messages, purchases, or account actions.

Positioning

Prefer visible browser automation when the task benefits from:

• existing tabs already open in the user's browser;
• cookies, logins, extensions, and normal browser state;
• visible step-by-step human oversight;
• manual human help for login, captcha, 2FA, consent screens, account pickers, file dialogs, or sensitive approvals;
• sites that do not work well through web_fetch or a fresh/headless browser.

Use safe wording: this skill gives the agent access to a normal visible browser while keeping the human in the loop. It does not try to bypass anti-bot systems.

Recommended architecture

Use a dedicated Windows browser profile by default. Use the user's personal browser profile only when the user explicitly wants existing personal cookies/logins/tabs.

OpenClaw Gateway in WSL2
  → OpenClaw browser profile (example: win-edge)
  → http://WINDOWS_WSL_GATEWAY_IP:9223
  → Windows portproxy/firewall relay
  → 127.0.0.1:9222
  → visible Windows 11 Edge/Chrome profile

Recommended defaults:

• OpenClaw browser profile: win-edge or win-chrome
• Windows CDP local port: 9222
• WSL-visible relay port: 9223
• Dedicated browser profile: C:\ProgramData\OpenClaw\browser-profile
• Startup/repair task: OpenClaw-Start-Windows-Browser-CDP

For implementation details, read {baseDir}/references/setup.md.

Diagnose first

Run read-only checks before repair:

openclaw browser profiles
openclaw browser --browser-profile win-edge doctor
WIN_IP=$(ip route | awk '/default/ {print $3; exit}')
curl -sS --max-time 5 "http://$WIN_IP:9223/json/version"

Or use the bundled helper:

{baseDir}/scripts/check-win11-visible-browser.sh win-edge

If CDP works, smoke-test real browser control:

openclaw browser --browser-profile win-edge open https://example.com
openclaw browser --browser-profile win-edge snapshot --format aria

Repair order

Repair in layers and stop when the layer works:

1. Confirm Windows Edge/Chrome is installed and can run visibly.
2. Start the browser with CDP on Windows localhost, usually 127.0.0.1:9222.
3. Expose it to WSL with a Windows relay/portproxy, usually 0.0.0.0:9223 → 127.0.0.1:9222.
4. Restrict Windows firewall to the current WSL/Hyper-V CIDR, not the whole LAN or Internet.
5. Configure an OpenClaw browser profile with cdpUrl pointing to the WSL-visible Windows endpoint and attachOnly: true.
6. Reload/restart Gateway if the profile is not visible.
7. Run doctor and a page/snapshot smoke test.

The bundled Windows repair script is {baseDir}/scripts/start-win11-browser-cdp-for-openclaw.ps1. Treat it as a template: review paths, profile name, browser path, ports, and firewall rule names before installing or running it.

Common blockers

• No supported browser found: WSL cannot launch Windows Edge/Chrome as a local Linux browser; use remote CDP.
• Windows CDP works but WSL curl times out: fix portproxy/firewall/WSL subnet.
• Browser profile not found: OpenClaw config not loaded; reload/restart Gateway.
• WSL gateway IP changed: update browser.profiles.<name>.cdpUrl or rerun the documented repair flow.
• Existing tabs/logins are missing: you are probably using a dedicated profile, not the user's real profile. Ask before switching profiles.

Evidence to report

When done, report:

• browser profile name and CDP URL tested;
• openclaw browser --browser-profile <profile> doctor result;
• /json/version result from WSL;
• Windows task/log status if relevant;
• smoke-test URL opened and snapshot result;
• any remaining manual human step needed.