Skill: pe4atnik/win11-visible-browser (version 1.0.3)

--- name: win11-visible-browser description: 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. metadata: {"openclaw":{"requires":{"bins":["openclaw","curl","ip"]}}} --- # Win11 Visible Browser Automation 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. ClawScan risk mitigations to preserve: - Prefer a dedicated browser profile by default; use a personal/logged-in profile only after explicit user approval. - Do not proceed with browser, account, payment, form, firewall, portproxy, config, or Scheduled Task changes unless the action and rollback are clear. - Verify Windows firewall rules are scoped to WSL/Hyper-V CIDR; never expose the CDP port to the LAN or Internet. - Create persistent Scheduled Tasks only after explicit approval, and keep rollback documented with `Unregister-ScheduledTask`. ## 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. ## Browser Resource Budget / Tab Hygiene Visible browser control is expensive: it consumes tokens, Edge/Chrome memory, and CDP stability budget. Before using the visible browser, prefer cheaper tools when they satisfy the task. ### Cost ladder Use the cheapest sufficient tool, in this order: 1. Local files, project notes, memory, or CLI output. 2. First-class APIs/CLIs (`clawhub`, `openclaw`, `curl`, source-specific tools). 3. `web_fetch` for readable public pages. 4. Browser `evaluate` for structured extraction from an already-open page. 5. Browser snapshot/screenshot for UI understanding or evidence. 6. Visible Edge/Chrome CDP only when logins, cookies, human-in-the-loop, visual verification, or sites that reject cheaper access are actually needed. If the user explicitly asks to open a site/tab in the visible browser, do not debate whether the browser is necessary. Still check basic safety/resource risk first and report if opening another tab may overload the browser. ### Existing tabs are not agent-owned Treat all tabs that existed before the current task as user state. - Do not close, reload, navigate, or repurpose existing user tabs without explicit permission. - Existing tabs already count against free system memory; do not double-subtract them in memory estimates. - They still count against CDP complexity: many existing pages/iframes/workers can make automation unstable. - If existing tabs leave too little resource budget, stop and ask for cleanup permission instead of taking over those tabs. Classify tabs mentally: - **User tabs**: existed before the task; do not touch. - **User-requested tabs**: opened because the user explicitly asked; do not close unless asked. - **Agent task tabs**: opened by the agent for the current task; save useful URLs and close/clean them when done. - **Archived tabs**: URLs saved into a project file such as `browser-tabs-YYYY-MM-DD.md`; safe to close only after user approval. - **Critical/manual tabs**: login, captcha, payment, forms, account settings; human-in-the-loop only. ### Preflight budget check Before non-trivial visible-browser work, estimate both memory budget and CDP complexity budget. Prefer the helper: ```bash {baseDir}/scripts/browser-budget-check.sh win-edge ``` If the helper is unavailable, inspect CDP directly: ```bash WIN_IP=$(ip route | awk '/default/ {print $3; exit}') curl -sS --max-time 8 "http://$WIN_IP:9223/json/list" ``` Decision inputs: - current `page`, `iframe`, and `worker` target counts; - whether reCAPTCHA/service workers are present; - current browser memory when measurable; - free system memory after existing user tabs; - minimum number of new tabs required by the task; - whether the task can use one reusable tab instead. Approximate planning costs: - simple/static tab: 50-150 MB; - normal web app tab: 100-250 MB; - heavy SPA/account dashboard: 250+ MB; - iframe/worker-heavy or reCAPTCHA site: treat as high risk; do not open cards in parallel. Memory rule of thumb: - keep at least 1 GB safety headroom; - if free memory after headroom is < estimated task cost, do not start; - if unsure, use one tab and write progress to project files rather than opening more tabs. CDP complexity stop rules: - `targets > 30`: stop and propose inventory/cleanup; - `pages > 10`: caution; avoid opening more tabs unless explicitly needed; - `iframe + worker > max(6, pages * 2)`: stop; the site is spawning too much browser state; - any reCAPTCHA burst: stop automation and switch to human-in-the-loop or project-file workflow; - repeated `targetId`, `Execution context destroyed`, or timeout errors: refresh target inventory instead of retrying blindly. ### Minimal-tab workflow Do not use the browser as task memory. - Default to one list/search tab and, if needed, one reusable detail tab. - Do not open a fan-out of many result cards/resumes/products. - Extract links from a list into a project file first. - Visit/detail one item at a time, record the result, then reuse or close the tab. - Prefer `evaluate` to extract structured data; use snapshots only when the UI structure is unknown. - Keep final chat replies compact: summary + path to saved project file, not full DOM dumps. ### Cleanup and archiving At the end of a browser task: 1. Save useful URLs/data into the relevant project (`browser-tabs-YYYY-MM-DD.md`, `candidates.md`, `sources.md`, `progress.md`, etc.). 2. Report which agent-created tabs can be closed. 3. Close only agent-owned or user-approved archived tabs. 4. Leave user tabs and user-requested tabs alone. For cleanup of a polluted browser session, first create a read-only inventory grouped by domain/type, deduplicate URLs, and write it to the project. Only after that, ask permission to close the relevant domain/targets. ## 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. ```text 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: [REDACTED_SECRET] For implementation details, read `{baseDir}/references/setup.md`. ## Diagnose first Run read-only checks before repair: ```bash 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: ```bash {baseDir}/scripts/check-win11-visible-browser.sh win-edge ``` If CDP works, smoke-test real browser control: ```bash 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. ## Data extraction For structured data extraction (prices, search results, product specs, availability): 1. Snapshot the page once to understand the layout. 2. Use `act kind=evaluate` with a JavaScript function to extract clean data as JSON/strings in a single call. 3. Repeat `evaluate` for pagination or updated data; no new snapshot needed unless the DOM structure changes. This uses orders of magnitude fewer tokens than snapshot-per-action loops. Tips: - If content loads lazily on scroll, scroll the container into view via evaluate before extraction. - Extract all visible results in one pass: name, price, seller, delivery date, link. - Some sites (Ozon, Wildberries, М.Видео) trigger antibot challenges on `web_fetch` but work through the visible CDP-attached browser. - Яндекс Маркет generally works with both `web_fetch` and the visible browser. ## Visual result presentation Beyond text, the visible browser lets you show results directly to the user: - **Open result tabs** — after finding a product/article/video, open it in a labeled browser tab so the user can see and interact with it in real time. - **Screenshot capture** — take a `screenshot` of the relevant page section and attach it to your response for instant visual confirmation. - **Multi-tab orchestration** — open several search results at once with distinct labels (`label="product-1"`, `label="product-2"`), letting the user visually compare while you summarise. - **Article/video handoff** — for tutorials or reviews, open the content in a tab and snapshot the key section so the user can continue watching/reading. - **Evidence delivery** — when a specific piece of information is critical (price, address, phone, delivery date), snapshot exactly that block and deliver it for verification.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)