OpenClaw Chrome Extension

Chrome extension

The OpenClaw Chrome extension gives an agent command over your signed-in Chrome tabs without spinning up a separate managed browser, and it avoids Chrome's intrusive "Allow remote debugging?" consent dialog.

This becomes critical when you operate OpenClaw from a mobile device via Telegram, WhatsApp, or similar channels: the user profile hooks into Chrome's remote-debugging port, which triggers a desktop confirmation popup that remains unclickable when you're not at the machine. The extension instead relies on the chrome.debugger API, leaving only Chrome's dismissible "OpenClaw started debugging this browser" notification as the sole in-page indicator.

Anthropic's Claude in Chrome and OpenAI's Codex Chrome extensions follow the same architectural pattern.

How it works

The setup comprises three components:

Browser control service (Gateway or node host): the backend that the browser tool invokes.
Extension relay: a lightweight server that the control service binds to loopback for same-host and browser-node configurations, or routes through the Gateway's relay-authenticated WebSocket path for direct remote access. It exposes a Chrome DevTools Protocol endpoint to OpenClaw and communicates with the extension.
OpenClaw Chrome extension (MV3): binds to tabs via chrome.debugger, relays CDP traffic, and maintains the OpenClaw tab group.

OpenClaw's visibility and control extend only to tabs residing in the OpenClaw tab group. This group acts as the consent mechanism: the relay advertises exclusively grouped tabs, and the extension verifies current group membership before executing any authority-bearing command on an existing tab. Dragging a tab into the group shares it; dragging it out or hitting the toolbar button cuts off access instantly, even if a relay client holds outdated tab information.

Install and pair

Output the path to the unpacked extension:
```
openclaw browser extension path
```
Navigate to chrome://extensions, switch on Developer mode, select Load unpacked, and choose the directory you printed.
Generate the pairing string:
```
openclaw browser extension pair
```
Click the OpenClaw toolbar icon and insert the pairing string into the popup. The badge flips to ON once the extension establishes a relay connection.

The pairing token functions as a per-host secret generated on initial use and persisted under credentials/ within the state directory (permissions set to 0600). Every machine hosting a browser, including the Gateway host and each browser node host, maintains its own token, eliminating any need to transfer credentials across machines. To rotate it, remove the browser-extension-relay.secret file and repeat the pairing process.

This secret resides in the pairing string fragment rather than the WebSocket URL transmitted to the server. During connection establishment, the extension supplies it as a WebSocket subprotocol credential. This approach keeps it out of standard proxy request URLs and access logs; nonetheless, treat the full pairing string with the same care as a password.

Use it

Choose the built-in chrome profile in a browser tool call, or set it as the default:

openclaw config set browser.defaultProfile chrome

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

To share a tab: press the OpenClaw toolbar button on that tab, which adds it to the OpenClaw tab group, or drag any tab into the group.
The agent can spawn new tabs as well; these are placed into the group automatically.
To revoke: press the button again, drag the tab out of the group, or close Chrome's debugging banner. The agent immediately loses access to that tab.

Authenticated external CDP clients

The relay accommodates authenticated external CDP clients, including mcporter, chrome-devtools-mcp, and Puppeteer. These leverage the same paired Chrome instance and the identical tab-group consent boundary, bypassing Chrome's "Allow remote debugging?" prompt. Retrieve the endpoint and bearer-auth header:

openclaw browser extension cdp

As an illustration, Google's chrome-devtools-mcp establishes a connection with:

npx chrome-devtools-mcp --wsEndpoint ws://127.0.0.1:18799/cdp \
  --wsHeaders '{"Authorization":"Bearer <token>"}'

openclaw browser extension cdp --json produces { browserUrl, wsEndpoint, headers } for scripting purposes. External CDP clients authenticate against the local CDP endpoint using this header, while the extension authenticates its separate relay WebSocket through the subprotocol credential mentioned earlier. Both originate from the same per-host relay secret. Guard it as private information, and rotate it by deleting credentials/browser-extension-relay.secret and re-pairing.

mcporter stands as a supported external CDP client that requires no extension-side configuration: when a paired relay responds on this host, it automatically translates chrome-devtools-mcp --autoConnect server commands to the relay endpoint, so agents invoking Chrome DevTools through mcporter avoid the remote-debugging prompt entirely (set MCPORTER_DISABLE_CHROME_DEVTOOLS_RELAY=1 there to decline).

Tab copilot side panel

Once the extension is paired, select Open tab copilot from its toolbar popup. OpenClaw sets up sidepanel.html for that specific Chrome tab; the manifest contains no global side-panel path. Consequently, each tab receives its own panel document, Gateway session, message subscription, and typed browser-tool binding.

The panel never includes the page URL, title, DOM, or visible text in your message. It transmits only the text you enter. Browser actions carry a distinct Gateway-authenticated binding that references the Chrome tab and CDP target, and the browser tool refuses attempts to swap that target or execute browser-wide actions. Replies remain within the panel (deliver: false); they do not adopt a Telegram, Discord, or other channel route.

The copilot operates as a dedicated paired Gateway device with operator.read and operator.write scopes. On its first use, review and approve its request:

openclaw devices list
openclaw devices approve <requestId>

The extension preserves that device identity and the Gateway-issued device token, scoped to the canonical Gateway endpoint that issued them. Pairing a different Gateway results in separate identity, token, and session custody; credentials and sessions are never shared across endpoints. The extension does not store the Gateway shared secret. A panel can subscribe exclusively to its own tab sessions, and the Gateway filters those events prior to delivery.

Should the Gateway connection drop mid-run, the extension retains durable custody of that run ID. Upon reconnection, it aborts the unresolved run before re-enabling any panel, then reloads transcript history. This fail-closed measure prevents browser actions from proceeding unnoticed across a delivery gap.

Closing a tab immediately terminates its live subscription, aborts any visible run, and flags that tab's session as archived. If the Gateway is temporarily offline, the extension holds the pending archive and retries only when that same Gateway endpoint reconnects; it never dispatches an archive request to a different Gateway. After a browser crash, the next launch archives sessions left by the prior browser instance. Archived sessions reject new work, while their transcripts remain accessible in session history. Browser-copilot keys are thread sessions, so standard age and entry-count maintenance keeps them intact. The per-agent session disk budget still applies (default 10gb) and may evict the oldest sessions under pressure; refer to session maintenance.

The side panel currently demands either a Gateway-hosted extension relay or a direct remote Gateway relay. A loopback relay on a browser node cannot yet supply the node route required by the typed tab binding, so the panel rejects that topology rather than falling back to browser-wide routing.

Send a page to OpenClaw

Employ Send page to OpenClaw in the toolbar popup to transmit readable page text to your primary OpenClaw session. You may append an optional note, utilize the page or selection right-click menu, or press Alt+Shift+S. OpenClaw prioritizes your current selection when one exists, queues the share as a system event, and rouses the main session immediately.

The tab need not belong to the OpenClaw tab group. This constitutes a one-shot, explicit share: nothing else on the page is revealed, and it grants no ongoing access. Google Docs are exported as plain text using your signed-in browser session, without requiring Google API setup. X and Twitter threads are extracted without the surrounding interface chrome.

Page text is enclosed in OpenClaw's external-content safety boundary. Your optional note remains outside that boundary as your own instruction. Page text and selections are limited to roughly 120,000 characters and include a truncation marker when shortened.

Page sharing functions when the extension relay is hosted by the Gateway, via same-host pairing or direct wss:// Gateway pairing. Node-hosted relays return a clear error for now. To remap the keyboard shortcut, open chrome://extensions/shortcuts.

Remote / cross-machine

The Gateway host does not need Chrome installed. Three configurations are supported:

Same host (Gateway and Chrome share one machine): run pairing on that machine with openclaw browser extension pair. The relay only listens on loopback. If the local Gateway has TLS enabled, explicitly provide its certificate hostname using --gateway-url wss://gateway-host.example; pairing will never fall back to a loopback IP.
Direct to a remote Gateway (Chrome on your laptop, Gateway on a VPS, and nothing else on the laptop): on the Gateway, execute openclaw browser extension pair --gateway-url wss://your-gateway.example.com. This outputs a wss://…/browser/extension#<secret> string; load and pair the extension on the laptop. The extension links straight to the Gateway over wss://, no OpenClaw installation, Node, CLI, or open inbound port is needed on the laptop. This is the managed-hosting option.
Via a browser node host (Chrome on a machine that already runs an OpenClaw node): run pair on the node and pair locally; the Gateway forwards browser actions to the node using its existing authenticated node link.

The pairing secret is tied to each host (the Gateway's, in the direct case) and is verified by the Gateway's /browser/extension route. For the direct path, enable TLS on the Gateway (wss://) so both the pairing secret and CDP traffic stay encrypted. The secret lives in the URL fragment of the pairing string and is sent during the WebSocket handshake as a subprotocol credential, so standard proxy access logs never see it in the request URL. Make sure any reverse proxy forwards the standard Sec-WebSocket-Protocol header.

Diagnostics

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

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

Security model

Same-host and browser-node relays bind to loopback; direct remote pairing uses the Gateway's wss:// route. Both WebSocket endpoints authenticate with the per-host secret, and the extension side is origin-checked against chrome-extension://.
Direct Gateway pairing does not accept the relay token in the request URL; the bundled extension sends it in the WebSocket subprotocol list instead.
The relay only exposes tabs in the OpenClaw tab group, and the extension rechecks group membership on its own before every authority-bearing existing-tab command. Your other tabs remain private.
Side-panel runs get double scoping: Gateway delivery applies a per-session allowlist, and browser tools enforce the Chrome tab/target binding carried outside the prompt.
Compared with the user (Chrome MCP) profile, which exposes your entire signed-in browser once you approve the remote-debugging prompt, the extension keeps the shared surface limited to a tab group you can see and control.

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