/browser-use

name: browser-use
description: "Control the user's existing signed-in Chrome: callable Codex Chrome plugin first, then OpenClaw extension-backed mcporter, with direct DevTools attachment only as a last fallback."

Browser Use

Control the user's existing real Chrome profile, especially for login-dependent work and live UI verification.

Route

1. Use the Codex `Chrome` or `Chrome [Internal]` plugin when it is callable in the active session. Installed on disk is not enough. 2. Otherwise prefer the OpenClaw extension-backed mcporter route. 3. Use legacy direct DevTools attachment only as the explicit last fallback.

For mcporter, the MCP call remains the agent-facing control interface. The OpenClaw extension is the transport underneath it, not a separate tool. Set `chromeDevtoolsRelay: "require"` on the canonical global Chrome server definition to enforce relay-only routing. Keep the caller policy explicit as well:

MCPORTER_CHROME_DEVTOOLS_RELAY_POLICY=require mcporter call chrome-devtools.<tool>

Seeing an agent request the `chrome-devtools` MCP tool is therefore expected. A Chrome **Allow remote debugging?** prompt or a relay-policy error indicates that the extension transport was not used. The shared daemon retains canonical policy; a shell environment prefix alone cannot change that policy.

Never use isolated Chrome, the Codex in-app browser, Playwright, Puppeteer, AppleScript, `osascript`, generic GUI scripting, or macOS `open` as a browser-control substitute unless the user explicitly asks for an isolated or new browser. Peekaboo is allowed only for Chrome or extension setup and visible prompts. Login-heavy sites often depend on the real profile's cookies, SSO, device trust, and extensions.

For a rendered-browser bug, prove behavior through this real profile. Treat `curl`, source inspection, API checks, and isolated test browsers as supporting evidence, not substitutes for live UI proof.

Extension Relay Model

OpenClaw creates a random per-host relay key in its mode-`0600` credentials directory. The extension and same-host clients use nonce-bound mutual HMAC proofs. The reusable key is never sent to an unverified loopback listener, placed in a URL, or passed to the child MCP process. Keep credentials out of configuration, command output, chat, logs, and screenshots.

On a same-host relay, mcporter authenticates `/json/version` and upgrades the same retained socket to `/cdp`, then gives `chrome-devtools-mcp` a protected one-use local handoff. Agents still call the standard MCP tools; successful relay routing is what removes direct DevTools attachment and Chrome's approval prompt.

New pairings default to **All tabs**: every ordinary eligible tab is exposed except tabs explicitly paused in the popup. Existing pairings keep their stored mode. In **Selected tabs** mode, membership in the Chrome tab group titled **OpenClaw** is the sharing boundary. Restricted/internal pages, incognito, other profiles, and tabs without an eligible URL remain excluded in both modes.

Topology Boundary

Direct remote Gateway pairing over `wss://` lets OpenClaw's Gateway-side browser tool control local Chrome. It does not create a local relay for a local mcporter process. Do not routinely copy remote secrets or build ad-hoc SSH tunnels around this boundary.

If local mcporter cannot authenticate to a local relay, the extension-backed mcporter route is unavailable. Report that clearly or use the labeled legacy fallback; never represent remote Gateway control or direct attachment as local relay success.

Setup and Repair

• Run `openclaw browser extension install` before **Load unpacked**. It copies

the extension to the stable OpenClaw-owned path, pre-registers that path's deterministic Chrome ID, and prints the path to load. The first native call then pairs automatically for local or browser-node topology.

• Use `openclaw browser extension status --json` to verify the installed copy,

exact origins, and native-host registrations. Status must report no issues and `manualSetupRequired: false`.

• Confirm Settings reports automatic setup ready and the popup reports

**Connected**. New installs should show **All tabs** unless the user changes the access mode; no copied pairing string or popup setup is part of the normal local flow.

• A previous native-host miss is cached for the Chrome process. If the extension

attempted native messaging before installation, restart Chrome once after installing; repeated retries in the same process cannot repair that cache.

• After pairing or changing the relay route, stop the mcporter daemon before

re-running relay-only proof. A Gateway restart can leave the Chrome DevTools child alive with a dead upstream socket; `mcporter daemon stop` retires it before the next call creates a fresh connection.

• Direct remote Gateway pairing remains an Advanced manual flow. It serves the

Gateway browser path and does not create a local relay for local mcporter.

Discovery Timeout and Daemon Configuration

MCPorter discovers the actual relay through `openclaw browser extension cdp --json`. Even packaged OpenClaw can take more than five seconds to cold-start. In mcporter 0.13.10, discovery failure falls back to port 18799; a timeout can therefore appear as `network-error` at the wrong endpoint, or as `browser_owner_conflict` when a later discovery returns the real endpoint. Do not interpret that sequence as proof that another Chrome owner or credential rotation caused the failure.

For the shared Chrome owner, use the OS account's canonical `~/.mcporter/mcporter.json` (or `mcporter.jsonc` only when the JSON file is absent). Merge these fields into its existing Chrome definition, preserving its command, arguments and other settings:

{
  "chromeDevtoolsRelay": "require",
  "env": {
    "MCPORTER_CHROME_DEVTOOLS_RELAY_TIMEOUT_MS": "20000"
  }
}

The relay timeout bounds each discovery or authentication step; it does