OpenClaw Browser Relay: How the Chrome Extension Works Now, and Why It Stops Connecting

TL;DR: The OpenClaw browser relay connects the OpenClaw Chrome extension to your agent so it can work in your signed-in Chrome tabs. Current releases set it up differently from the guides most people find: you run openclaw browser extension install, add the official Store extension, let a native host pair the two on macOS and Linux, and there is no fixed port or token to copy. When it stops connecting, the usual causes are the Gateway being down, the native host missing, automatic setup switched off, or a paired port that no longer matches a profile.

Contents

• What the OpenClaw Browser Relay Is
• What Changed From the Older Guides
• How to Install the OpenClaw Browser Relay Now
• Which Tabs the Agent Can Reach
• Why the OpenClaw Browser Relay Stops Connecting
• Tokens, Pairing Strings, and Relay Authentication v2
• The Risk You Are Taking On
• Key Takeaways
• FAQ

What the OpenClaw Browser Relay Is

The OpenClaw browser relay is the link between a Chrome extension and the OpenClaw browser tool. The extension attaches Chrome’s debugger to tabs you allow. A small relay on 127.0.0.1 passes Chrome DevTools Protocol (CDP) commands between those tabs and your agent, so the agent can click, type and read pages in the browser you are already signed in to.

That last part is the reason to use it. OpenClaw can also run its own managed browser profile, which is cleaner and safer, but it starts logged out of everything. The relay is for work that needs your real sessions: an internal dashboard, a vendor portal, a mailbox.

In config, the relay is a browser profile whose driver is extension. OpenClaw ships a built-in profile named chrome set up this way, and you can make it the default:

openclaw config set browser.defaultProfile chrome

What Changed From the Older Guides

Most setup guides for the OpenClaw browser relay describe an earlier version. Search results still tell you to load the extension unpacked, point it at ws://127.0.0.1:18792, and copy a token into the extension. Current releases work differently on every one of those points.

The port change trips people up most. OpenClaw assigns a distinct relay port to every extension-driver profile that does not pin its own cdpPort, so two profiles never share one.

Do not hard-code a number from a guide. openclaw browser extension cdp prints the endpoint your install is really using.

Check which Store listing you installed, too. The listing many older guides point to, “OpenClaw Browser Relay”, which still mentions MoltBot and ClawdBot, has a different Store ID from the one the current docs link to, and the native host only accepts the exact official ID. If yours came from an old guide, automatic pairing will not recognise it.

How to Install the OpenClaw Browser Relay Now

Setup is one command on the machine that runs Chrome, followed by approving the extension in Chrome. Chrome needs to have been launched at least once first, because the installer looks for Chrome’s profile directory.

openclaw browser extension install

Leave it running while you finish in Chrome. What happens next depends on the platform:

• macOS. The command registers a native host, then asks Chrome to install the official Store extension. Chrome only notices the request at startup, so fully quit and reopen Chrome, then approve OpenClaw. The macOS app’s Browser settings run the same setup.
• Linux. The command registers the native host. You then add OpenClaw from the Chrome Web Store yourself.
• Windows. There is no automatic setup. Add the Store extension, then use manual pairing from the extension’s Settings page.

Order matters. If the extension tried automatic setup before the native host existed, Chrome caches that miss for the life of the browser process. Restart Chrome once, rerun the install, and it clears.

Once the extension shows as connected, confirm it end to end rather than trusting the install output:

openclaw browser --browser-profile chrome tabs

The install result only reports what it saw on disk. The docs are explicit that a registered host or an enabled extension does not prove a live relay connection, and that last command is what does. If you pulled OpenClaw into a fresh setup recently, our OpenClaw setup and hardening guide covers the Gateway side this depends on.

Which Tabs the Agent Can Reach

The extension offers two access modes, and the choice decides how much of your browser the agent can touch. New automatic pairings start on All tabs. An existing pairing keeps its stored mode, and an older pairing with no stored mode starts on Selected tabs.

• All tabs. Every ordinary tab in that Chrome profile is available, except tabs you pause from the extension popup.
• Selected tabs. Only tabs inside the OpenClaw tab group are available. Dragging a tab into the group grants access, and dragging it out revokes it.

Switching to Selected tabs detaches every ungrouped tab straight away, including attaches already in progress. Tabs the agent opens itself stay in the OpenClaw group in either mode.

Some tabs are never available. Incognito tabs, internal pages such as chrome:// and chrome-extension://, and tabs without a usable URL are excluded, and file:// pages also need Chrome’s “Allow access to file URLs” setting. If the agent says a tab does not exist, check these before anything else.

Why the OpenClaw Browser Relay Stops Connecting

Nearly every relay failure is one of a short list, and the extension’s own status names most of them. Start with these three commands, which print status without exposing credentials:

openclaw browser extension status --json
openclaw browser doctor --browser-profile chrome
openclaw doctor

Then match what you see:

Two details catch people who pair for standalone use. Automatic wake-up only fires for the exact host 127.0.0.1; localhost and IPv6 addresses do not trigger it. And after an upgrade, a pairing that points at a removed profile or an old port fails closed instead of guessing, so re-pair to match the current profile.

If openclaw doctor reports config it wants to migrate, let it. Older configs carried a browser.relayBindHost setting and stale relay URLs on extension profiles, and doctor removes both. Our openclaw doctor --fix guide covers what it changes and what it leaves alone.

Tokens, Pairing Strings, and Relay Authentication v2

There is no relay token to find in current releases, which is why searches for one come up empty. Browser Relay Authentication v2 keeps the persistent relay key on the host. The extension and any external CDP client answer a signed challenge with a one-time proof tied to that single connection, so a captured proof cannot be replayed.

openclaw browser extension cdp prints what an external client needs: the loopback endpoint, protocol version, key ID and the challenge resources. It does not print the key or an authorization header unless you ask for the legacy form with --legacy-bearer, which only works while legacy authentication is allowed. External clients such as mcporter can stay connected alongside OpenClaw, sharing the same tabs.

The one secret you might handle is a manual pairing string from openclaw browser extension pair, used on Windows, for recovery, or to pair a laptop directly to a remote Gateway. The docs say to treat the whole string as a password. Remote pairings must use wss://, and the Gateway has to expose the exact /browser/extension path without a proxy prefix in front of it.

Older clients that still send a Bearer token only work while legacy relay authentication is allowed. The Gateway relay allows it by default for one migration window, the security audit warns about it, and the standalone relay stays v2-only unless you turn it on explicitly.

Update your clients, then switch it off:

{
  "browser": {
    "extensionRelay": {
      "allowLegacyAuth": false
    }
  }
}

The Risk You Are Taking On

The relay gives the model your browser, with your logins. The OpenClaw docs say this plainly: if a profile has signed-in sessions, the model can use those accounts, and for a remote Gateway, browser control amounts to operator access to everything that profile can reach.

That makes the access mode a security setting, not a convenience one. Selected tabs is the narrower choice for a personal profile, and a dedicated Chrome profile for the agent is narrower still. Keep the Gateway and any browser node on a private network, and never expose relay or browser-control ports to your LAN or the internet.

If the agent keeps telling you a tool is missing when it tries to use the browser, the relay may be fine and a tool policy may be filtering it. Our guide to the OpenClaw “tool does not exists” error walks through that side.

Key Takeaways

• The OpenClaw browser relay lets an agent drive your signed-in Chrome through the OpenClaw extension and a loopback CDP relay.
• Setup is openclaw browser extension install plus the official Store extension. Load unpacked is only a development fallback.
• There is no fixed port 18792 any more. Each extension profile gets its own port, and openclaw browser extension cdp tells you which.
• There is no token to copy. Authentication v2 never sends the key, and a manual pairing string is the only secret you handle.
• Most connection failures come down to the Gateway being down, the native host missing, automatic setup being off, or a stale port.
• Pick Selected tabs or a dedicated profile if the browser holds anything you would not hand to an operator.

For the full catalogue of OpenClaw error messages, see our OpenClaw errors guide. The upstream reference is the OpenClaw Chrome extension documentation.

Need help running OpenClaw in production?

Giving an agent a real browser is where a self-hosted setup stops being a toy and starts carrying real risk. Kaxo runs OpenClaw agents in production and checks behaviour like this against the running code, not just the docs.

Kaxo can scope the browser access, tool policy and network exposure with you.

Two ways to get help:

• AI Tools Audit: a structured review of your stack, including OpenClaw configuration, browser access and tool policy. Independent, no vendor referral fees.
• AI agent development: for teams building on OpenClaw who want the setup done right the first time.

Or book a discovery call to scope a one-time audit.

Soli Deo Gloria