browser-use

Files (3)

• SKILL.md
• auto-allow.py
• mcporter-config.md

SKILL.md (first lines)

# 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:

```bash
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:

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

The relay timeout bounds each discovery or authentication step; it does not
extend the client's total operation deadline. Initial Chrome startup can run
several discovery checks before MCP initialization and the requested tool call.
On older installed clients, pair the canonical `20000` per-step setting with

From steipete/agent-scripts, MIT.

More from steipete/agent-scripts