# OpenClaw Browser Relay Guide: Chrome Extension Install and Fixes

> How to install and pair the OpenClaw Browser Relay Chrome extension, fix the red ! badge and 'not reachable after start', and why 2026.8.2 is the version to run.

- Source: https://www.aifreeapi.com/en/posts/openclaw-browser-relay-guide
- Language: en
- Published: 2026-02-04
- Updated: 2026-10-09
- Publisher: AI Free API (https://www.aifreeapi.com)

The OpenClaw Browser Relay is a Chrome extension plus a small native host that lets OpenClaw's browser tool automate eligible tabs in the Chrome profile you are already signed in to. It is not a headless browser and it has no chat box of its own; it is the connection between the OpenClaw Gateway and your tabs. As of October 9, 2026, the documented path is: update OpenClaw to 2026.8.2 or later, run `openclaw browser extension install`, fully quit and reopen Chrome, approve the Chrome Web Store request, then confirm with `openclaw browser --browser-profile chrome tabs`. If that command lists your tabs, the relay is paired and working.

If instead the extension icon shows a red "!", the popup says "Relay unavailable", or a command returns `Chrome CDP websocket for profile "openclaw" is not reachable after start`, go straight to the two troubleshooting sections below. The last error comes from the managed `openclaw` profile, not from the extension, and it has a different set of causes.

## What the OpenClaw Browser Relay (Chrome extension) is and what it needs

![How the OpenClaw Browser Relay connects: Gateway, native host, Chrome extension and the tab over the Chrome DevTools Protocol](https://www.aifreeapi.com/posts/en/openclaw-browser-relay-guide/img/cdp-architecture.png)

According to the [Chrome Extension page of the OpenClaw docs](https://docs.openclaw.ai/tools/chrome-extension), the relay lets the browser tool "automate eligible tabs in your signed-in Chrome profile". It attaches to tabs through Chrome's `chrome.debugger` API, which is why you never see Chrome's remote-debugging consent prompt. The extension popup shows the connection state, the access mode, and Pause/Allow controls for the current tab; everything else happens through OpenClaw.

CDP, the Chrome DevTools Protocol, is the command protocol Chrome exposes to its own DevTools: a WebSocket on which a client asks for navigation, DOM snapshots, screenshots and script evaluation. The relay forwards those commands to the attached tab. Two routes exist. When the Gateway is running, the extension connects to its `/browser/extension` route; standalone, it uses a loopback WebSocket at `ws://127.0.0.1:<port>/extension`, and the address must be exactly `127.0.0.1`. The port is not a fixed number: it comes from the browser profile configuration, including an explicit `cdpPort` if you set one. `openclaw browser extension cdp` prints the non-secret connection metadata if you need to see which route and port are in use. The standalone relay daemon exits after 10 minutes without traffic and wakes up at most once a minute, so a first command after a pause can take a moment.

Requirements, as the docs list them:

- Google Chrome, Chrome for Testing, or Chromium (other browsers are covered in the browser-support section).
- OpenClaw installed on the same machine, or an OpenClaw browser node running on that machine. If OpenClaw itself is not set up yet, start with [How to Install OpenClaw on Mac, Windows, Linux or a Server](/en/posts/openclaw-installation-guide).
- macOS or Linux, or Windows through the `OpenClaw.BrowserBootstrap.exe` native executable.

OpenClaw was formerly called Clawdbot. `clawdbot` commands, a fixed relay port number and a token you paste into the extension by hand belong to that earlier flow; the current one is below.

## How to install and pair the Browser Relay extension

![Install and pairing sequence for the OpenClaw Browser Relay, from the CLI command to the first successful tabs listing](https://www.aifreeapi.com/posts/en/openclaw-browser-relay-guide/img/workflow-diagram.png)

1. **Check your OpenClaw version.** Run `openclaw --version`. Anything below 2026.8.2 is affected by the September 2026 advisory (see the advisories section below), and versions before 2026.2.1 by the February one. Update first so you pair once, on a fixed relay.
2. **Run `openclaw browser extension install`** and leave it running. It registers the native host and asks Chrome to install the extension from the Chrome Web Store. Fully quit Chrome (not just the window), reopen it, and approve the Store request when Chrome shows it. If the request does not appear quickly, `--wait-ms 60000` gives it a full minute; `--json` returns machine-readable output. The docs note that Linux has no per-user Store request, so on Linux expect to need the development path in the next step if nothing appears.
3. **Development or Store-less install:** `openclaw browser extension install --no-store` prints a local path; open `chrome://extensions`, enable Developer mode and use Load unpacked on that path. The step-by-step variant is `openclaw browser extension setup --action inspect|install|verify --json`: `inspect` reports the current state, `install` performs the setup, `verify` confirms it.
4. **Pair.** Pairing normally completes automatically through the native bootstrap. If automatic setup is disabled or the extension says it is waiting for local OpenClaw, run `openclaw browser extension pair` and enter the pairing string in the extension; treat that string as a password. For a Gateway on another machine, use `openclaw browser extension pair --gateway-url wss://…`; a non-loopback Gateway must be reached over `wss://`, not `ws://`. The CLI's JSON output never includes the relay key. If you have seen instructions about a "verify token" step, this is it: the docs call it the relay key and pairing, and there is no token to copy by hand in the current flow.
5. **Point OpenClaw at the extension.** Either `openclaw config set browser.defaultProfile chrome`, or set `browser.profiles.chrome.driver: "extension"` and name the profile per command. Without this step, `openclaw browser …` commands default to the managed `openclaw` profile, which is a separate browser and a common source of confusion.
6. **Verify:** `openclaw browser --browser-profile chrome tabs`. A list of your open tabs means the extension, native host and Gateway are talking. `openclaw browser extension status` shows the relay's own view if the list is empty.

The extension asks for the `debugger`, `tabs`, `tabGroups`, `storage`, `alarms` and `nativeMessaging` permissions. The list matches what it does: `debugger` attaches to tabs, `nativeMessaging` reaches the native host, `tabGroups` supports the Selected tabs mode.

## All tabs vs Selected tabs: which access mode to use

The popup offers two access modes. **All tabs** is the default: the agent may drive any eligible tab in the profile. **Selected tabs** limits it to tabs inside an OpenClaw tab group, so you decide which pages the agent can touch by moving them into that group. Use Selected tabs when the profile also holds banking, mail or admin tabs you do not want in reach; use All tabs when the profile is dedicated to agent work. Pause and Allow in the popup toggle the current tab.

In both modes some tabs are never eligible: incognito windows, `chrome://` and `chrome-extension://` pages, tabs without a URL, and Chrome Web Store pages. Local files (`file://`) work only after you enable "Allow access to file URLs" for the extension in `chrome://extensions`.

## Automate posting to a website through the relay: tabs, open, snapshot

The CLI is how you prove the relay works and inspect what the agent sees; the agent itself drives the tabs through the browser tool when you ask it to draft, fill in and post. The [CLI reference](https://docs.openclaw.ai/cli/browser) gives the minimal sequence as `doctor → start → tabs → open`; with the extension profile it looks like this:

```bash
openclaw browser doctor --browser-profile chrome
openclaw browser --browser-profile chrome tabs
openclaw browser --browser-profile chrome open https://example.com/new-post
openclaw browser --browser-profile chrome snapshot --urls
openclaw browser --browser-profile chrome screenshot --full-page
```

`tabs` returns a `suggestedTargetId` for the tab the next command will use. `snapshot` gives the page structure the agent reasons over (`--urls` adds link targets); `screenshot` accepts `--full-page`, `--ref` for a single element and `--labels`. Each request times out after 30,000 ms plus about 10 s of transport allowance, and downloads land in `/tmp/openclaw/downloads`. If `tabs` works but `open` fails on a specific URL, the cause is usually the navigation policy that blocks private or internal addresses, not the relay; test with a public URL first.

## Browser Relay vs the managed openclaw profile vs the user profile

![Comparison of the OpenClaw browser profiles: Browser Relay extension, managed openclaw profile, user profile and remote CDP](https://www.aifreeapi.com/posts/en/openclaw-browser-relay-guide/img/browser-modes.png)

The relay is one of several ways OpenClaw can reach a browser, and the error you get depends on which one a command is actually using. The [Browser docs index](https://docs.openclaw.ai/tools/browser) and the CLI reference describe these profiles:

| Profile | What it drives | Choose it when |
|---|---|---|
| `chrome` with `driver: "extension"` (Browser Relay) | Eligible tabs in your signed-in Chrome, through the extension | You need your existing logins and want to watch the agent work |
| `openclaw` (managed, the default) | A separate agent-only browser with its own user data directory, isolated from your personal browsing | You want isolation; most "not reachable after start" reports come from this profile |
| `user` | Your signed-in Chrome through Chrome DevTools MCP | Documented alternative to the extension for the same signed-in session |
| Custom CDP profile | A local or remote CDP endpoint, for example `http://127.0.0.1:9222`, a hosted browser (Browserless, Browserbase, Notte) or a node browser proxy | The browser runs on another machine |

The browser control service listens on loopback only. On macOS, only selected cookies can be copied from your Chrome into a managed profile, so a managed browser will not inherit your logins; that is the main reason to pick the relay over it.

## Fix "Chrome CDP websocket for profile openclaw is not reachable after start"

The full message, as reported in the OpenClaw issue tracker, is `After 15 seconds, the gateway kills Chrome and returns: Error: Chrome CDP websocket for profile "openclaw" is not reachable after start`, often wrapped in a `GatewayClientRequestError`. It means the managed `openclaw` browser was launched but its DevTools WebSocket never answered within the readiness window. The CLI docs are explicit: when `start` fails this way, troubleshoot CDP readiness first, and only then look at the extension or navigation.

Start with `openclaw browser doctor` (add `--deep` for a live snapshot check), then work through the causes reported in the [GitHub issues on this error](https://github.com/openclaw/openclaw/issues?q=is%3Aissue+%22not+reachable+after+start%22) (April–May 2026, all since closed):

- **A regressed release.** Several reports clustered on 2026.4.11 and 2026.4.12. Check `openclaw --version` against the current release notes and update; this alone resolved many of the threads.
- **Chrome exits right after spawn.** Reports from macOS on Apple silicon describe the process dying 1–2 seconds after launch or `DevToolsActivePort` failures after a Chrome update. Launch the browser manually once to see whether it stays up.
- **Windows readiness timeout.** Windows users reported that the fixed wait was too short for a cold Chrome start; a configurable launch timeout was requested in the same cluster. Retry after Chrome has been opened once.
- **VPS, Docker, WSL2 and sandboxes.** Reports describe the agent's private-network (SSRF) policy being applied to the profile's own loopback CDP endpoint, and `127.0.0.1` hard-coded inside the sandbox. Manual CDP worked while the managed launch failed in these threads, which is the signature to look for.
- **A stale `SingletonLock`** left by a previous Chrome in the managed profile directory, with no retry backoff. Make sure no old Chrome from that profile is running before `start`.

If `doctor` shows the Gateway itself is not up, or ports are not listening, that is a Gateway problem rather than a browser one; [OpenClaw Port Not Listening: Complete Troubleshooting Guide [2026]](/en/posts/openclaw-port-not-listening) covers it. If `start` and `tabs` succeed and only `open` fails, see the navigation-policy note in the automation section above.

## "Relay unavailable", the red ! badge and version mismatch: extension-side errors

These symptoms belong to the extension path. The troubleshooting items in the docs, plus symptoms reported in community threads, map as follows:

| What you see | What it means | What to try |
|---|---|---|
| Red "!" on the extension icon | The extension cannot reach the relay server (wording from the extension's own options page) | Confirm the Gateway or standalone relay is running; run `openclaw browser extension status`; fully quit and reopen Chrome |
| "Relay unavailable" in the popup | Same fault from the relay side: Gateway not running, native host not reachable, daemon asleep, or wrong port | Is the Gateway running? Then check the native host, wait a moment for wake-up, and compare the port with `openclaw browser extension cdp` |
| "Native host not pre-registered" / "No extension ID" | The native host registration did not complete, or the extension was loaded before the bootstrap ran | Run `openclaw browser extension install` again, then fully quit Chrome. Chromium caches a missing native host for the life of the process, so a window close is not enough |
| "Version mismatch" | Extension and OpenClaw versions do not match | Reload the extension in `chrome://extensions`, update OpenClaw, run `openclaw browser doctor --browser-profile chrome` |
| "Waiting for local OpenClaw" | The extension is installed but no local OpenClaw has answered | `openclaw browser extension status`; start the Gateway if it is stopped |
| "Automatic setup disabled" | Pairing will not happen on its own | `openclaw browser extension pair` and enter the pairing string |
| WebSocket auth fails, "no valid credentials available" | The extension holds no valid relay key, typically after the move to Browser Relay Authentication v2 broke an older extension's pairing (a community report from around March 2026) | Update OpenClaw, reload the extension, pair again |

Two general rules save time here. First, a full Chrome quit is part of almost every fix because of the native-host caching. Second, the current extension expects an OpenClaw that speaks Authentication v2; pairing an old extension build against a new Gateway, or the reverse, shows up as auth failures rather than a clear version error. For Gateway-side errors that are not browser specific, the [OpenClaw Error Troubleshooting Center: Complete Fix Guide for Every Error Code (2026)](/en/posts/openclaw-error-troubleshooting-center) is the right place.

## Does the Browser Relay work in Brave, Edge, Firefox or Safari?

The extension docs name Google Chrome, Chrome for Testing and Chromium. Brave and Edge appear in the browser docs as supported browsers for the managed `openclaw` profile, which talks to them over CDP directly; the Chrome extension itself is documented only for the three Chrome builds. For Brave, that managed-profile path is the one that applies: Brave is Chromium-based and speaks CDP, so OpenClaw can launch and drive it as an isolated profile.

No Firefox, Safari or Android extension is documented, and nothing in the docs describes pairing those browsers; treat them as unsupported until the docs say otherwise. If you need a browser on another machine, the custom CDP profile against a remote or hosted browser is the documented route.

## Two 2026 security advisories: update to 2026.8.2 or later

The relay is a privileged component: whatever can speak to it can read and act in your signed-in tabs. Two advisories in 2026 changed how it authenticates, and both are closed by updating.

**CVE-2026-28458 (GHSA-mr32-vwc2-5j6h, February 14, 2026).** Per the advisory, the Browser Relay's `/cdp` WebSocket endpoint on the relay port of that era (18792) accepted connections without a token, so any website open in the browser could issue CDP commands: read cookies, run JavaScript in other tabs. Affected versions were 2026.1.20 through 2026.2.0; 2026.2.1 fixed it by checking a per-session secret on the WebSocket upgrade. CVSS 7.4 (High); NVD published it on March 5, 2026. Vulnerability databases such as [SentinelOne's entry](https://www.sentinelone.com/vulnerability-database/cve-2026-28458/) carry the same version range.

**GHSA-m78m-7h3q-q938 (September 11, 2026, Moderate, CVSS 5.3).** The [advisory](https://github.com/openclaw/openclaw/security/advisories/GHSA-m78m-7h3q-q938) describes the relay reserving entries in a single global pending-authentication pool before a client proved it held the relay key. An unauthenticated attacker with network access to the relay route could fill every slot and stop paired extensions from completing Browser Relay Authentication v2. No relay key or browser data was exposed. Fixed in 2026.8.2; the remediation also says to restrict network access to the relay route and to restart the relay if it is saturated.

Beyond updating, the documented protections are the ones already built into the flow: the control service and standalone relay bind to loopback, a Gateway on another host must be reached over `wss://`, the pairing string is a password, and the CLI never prints the relay key in JSON output. Use Selected tabs when the profile holds sensitive sessions, and keep the Gateway off the public internet.