mirror of https://github.com/openclaw/openclaw.git synced 2026-07-09 10:53:58 +00:00

Files

Peter Steinberger d6801f23d4 feat(browser): restore driver "extension" via a loopback Chrome extension relay (no remote-debugging prompt) (#100619 )

* feat(browser): restore driver "extension" via loopback Chrome extension relay

Reintroduces browser profile driver "extension" (removed in 2026.3.22) as a
loopback relay that drives the user's signed-in Chrome through an MV3 extension
instead of the remote-debugging port. This avoids Chrome's blocking "Allow
remote debugging?" prompt, which cannot be clicked when the operator drives
OpenClaw from a phone. Automated tabs live in an "OpenClaw" tab group (the
consent boundary), mirroring the Codex/Claude-in-Chrome model.

- relay bridge synthesizes the CDP browser target surface for Playwright
  connectOverCDP and forwards session-scoped commands to chrome.debugger
- relay server binds loopback only; both sides authenticate with a token
  derived (HMAC-SHA256) from gateway auth, so the raw credential never reaches
  Chrome; extension origin + loopback Host checks guard the upgrade
- built-in "chrome" profile; distinct relay ports per extension profile;
  relay reconciles on auth rotation / cdpPort change and prunes removed profiles
- doctor + status surface the extension transport; doctor keeps repairing the
  retired relay endpoint URL on legacy "extension" profiles

Refs #53599

* feat(browser): bundle the OpenClaw MV3 Chrome extension

Thin MV3 extension (chrome-extension/): a WebSocket client to the loopback
relay plus chrome.debugger forwarding and OpenClaw tab-group management. All
CDP target synthesis lives server-side in the relay bridge, so the extension
stays a dumb transport (the removed 2026.3 extension put that logic in a
1000-line untestable service worker). Popup handles pairing and per-tab share
toggle; `openclaw browser extension path|pair` load and pair it. A build copy
hook stages it into dist so the load path is stable.

Refs #53599

* docs(browser): document the Chrome extension profile

Adds docs/tools/chrome-extension for the restored extension driver (install,
pair, tab-group consent model, security posture) and wires it into the browser
docs profile section and nav.

Refs #53599

* feat(browser): make the extension relay work on remote browser nodes

Derives the relay auth token from a host-local secret in the credentials dir
(created on first use) instead of gateway auth. Each machine that runs a
browser — the gateway host and every browser node host — owns its own token, so
the extension pairs with whichever machine hosts its Chrome and no gateway
credential travels to a node. The node host already runs the shared browser
control bootstrap, so this is all that was missing for cross-machine control.

Also removes the "relay needs gateway auth before it can start" failure mode:
startup and `openclaw browser extension pair` ensure the secret exists.

Refs #53599

* fix(browser): harden relay secret creation and satisfy CI lint/typecheck

- Make the host-local relay secret creation atomic (O_CREAT|O_EXCL + adopt the
  winner on EEXIST) so the gateway service and `extension pair` CLI cannot mint
  divergent tokens on a fresh host (would 401 until restart); credentials dir
  created mode 0700. (adversarial review finding)
- Resolve type-aware oxlint findings across the relay + extension: unknown catch
  vars, addEventListener over ws.on* in the MV3 worker, void async listeners,
  drop useless returns/spreads, Object.assign over map-spread, safe ws frame
  decode (Buffer[]/ArrayBuffer), toSorted.
- Add extensionRelayDefaultPort/extensionRelayPorts to remaining test config
  literals; type the extension relay-core module (.d.ts, excluded from dist);
  regenerate docs_map.

* fix(browser): satisfy OpenGrep security policy on the relay

- Hash both operands before timingSafeEqual so token comparison has no
  length short-circuit (GHSA-JJ6Q-RRRF-H66H).
- Bound the relay WebSocketServer with maxPayload (64 MiB, headroom for CDP
  screenshots/bodies) against oversized frames (GHSA-VW3H-Q6XQ-JJM5).
- Rewrite the config test env helper to avoid the skill-env-host-injection
  shape (GHSA-82G8-464F-2MV7); it is a test-only env swap.

2026-07-06 10:08:27 +01:00

4.8 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Chrome extension: let OpenClaw drive your signed-in Chrome with no remote-debugging prompt

You want an agent to drive your real signed-in Chrome from your phone

You keep hitting the Chrome "Allow remote debugging?" prompt with nobody at the desk

You want to understand the security model of browser takeover via the extension

Chrome Extension

Chrome extension

The OpenClaw Chrome extension lets an agent control your signed-in Chrome tabs without launching a separate managed browser, and without Chrome's blocking "Allow remote debugging?" prompt.

This matters when you drive OpenClaw from a phone (Telegram, WhatsApp, etc.): the user profile attaches over Chrome's remote-debugging port, which pops a desktop consent dialog nobody can click when you are away. The extension uses the chrome.debugger API instead, so the only in-page hint is Chrome's dismissible "OpenClaw started debugging this browser" banner.

This is the same shape used by Anthropic's Claude in Chrome and OpenAI's Codex Chrome extensions.

How it works

Three parts:

Browser control service (Gateway or node host): the API the browser tool calls.
Extension relay (loopback WebSocket): a small server the control service starts on 127.0.0.1. It presents a Chrome DevTools Protocol endpoint to OpenClaw and speaks to the extension. Both sides authenticate with a host-local token (see below).
OpenClaw Chrome extension (MV3): attaches to tabs with chrome.debugger, forwards CDP traffic, and manages the OpenClaw tab group.

OpenClaw only sees and controls tabs that are in the OpenClaw tab group. The group is the consent boundary: drag a tab in to share it, drag it out (or click the toolbar button) to revoke access instantly.

Install and pair

Print the unpacked extension path:
```
openclaw browser extension path
```
Open chrome://extensions, enable Developer mode, click Load unpacked, and select the printed directory.
Print the pairing string:
```
openclaw browser extension pair
```
Click the OpenClaw toolbar icon and paste the pairing string into the popup. The badge turns ON when the extension connects to the relay.

The pairing token is a host-local secret created on first use and stored under credentials/ in the state directory (mode 0600). Each machine that runs a browser — the Gateway host and every browser node host — owns its own token, so no credential has to travel between machines. To rotate it, delete the browser-extension-relay.secret file and pair again.

Use it

Select the built-in chrome profile in a browser tool call, or make it the default:

openclaw config set browser.defaultProfile chrome

{
  browser: {
    profiles: {
      chrome: { driver: "extension", color: "#FF4500" },
    },
  },
}

Share a tab: click the OpenClaw toolbar button on that tab (it joins the OpenClaw tab group), or drag any tab into the group.
The agent can also open new tabs; those land in the group automatically.
Revoke: click the button again, drag the tab out of the group, or dismiss Chrome's debugging banner. The agent loses access to that tab immediately.

Remote browser nodes

The extension works whether Chrome runs on the Gateway host or on a separate browser node host. The relay is always loopback-only and runs on the machine with the browser:

Same host (Gateway + Chrome on one machine): pair on that machine.
Remote node (Chrome on a node, Gateway elsewhere): run openclaw browser extension path / pair on the node, load and pair the extension there. The Gateway proxies browser actions to the node over its existing authenticated node link; the node's local relay drives the extension. No new inbound port is opened on the node.

The pairing token is per host, so each node prints its own string.

Diagnostics

openclaw browser status --browser-profile chrome
openclaw browser doctor --browser-profile chrome

doctor reports the Chrome extension relay check as failing until the extension popup shows Connected.

Security model

The relay binds loopback only; both WebSocket sides are authenticated with the derived token, and the extension side is origin-checked to chrome-extension://.
The agent can only see and drive tabs in the OpenClaw tab group. Your other tabs stay private.
Compared with the user (Chrome MCP) profile, which exposes your whole signed-in browser once you approve the remote-debugging prompt, the extension keeps the shared surface scoped to a tab group you control at a glance.

See also: Browser for the full profile model and the managed openclaw and Chrome MCP user profiles.

4.8 KiB Raw Blame History