Community Guide

OpenClaw Browser Relay

What the OpenClaw browser relay is, how it differs from the managed browser profile, and when to use each mode.

Mar 19, 2026

Browser relay is a different mode, not a small setting

OpenClaw supports two browser stories:

a managed OpenClaw browser profile
a Chrome or Chromium extension relay that attaches to your system browser

If you mix those up, the browser feature feels random. If you keep them separate, the design is straightforward.

What the browser relay actually is

Browser relay means OpenClaw uses an extension-attached tab in your normal Chromium-based browser instead of launching a fully isolated OpenClaw-managed browser profile.

That makes relay mode useful when you want:

quick access to your normal browser environment
the system default Chromium browser
less friction for simple browsing tasks

But it also means you are not getting the same isolation as the dedicated managed profile.

Relay mode vs managed mode

Managed browser

Use the OpenClaw-managed browser profile when you want:

isolation from your personal browsing profile
a dedicated automation surface
fewer surprises about which tabs and sessions the agent can see

Browser relay

Use relay mode when you want:

to drive your existing Chromium browser
faster setup around the system browser
extension-based control instead of a separate agent-only browser

The decision is not “which one is more advanced?” It is “do I want convenience or isolation?”

The beginner-safe rule

If you are unsure, start with the managed browser.

Choose browser relay only when you specifically want the system browser and understand that the extension must be attached to the right tab and profile.

The config that matters

OpenClaw’s browser settings live in ~/.openclaw/openclaw.json.

The relay-related ideas are:

browser.enabled
browser.defaultProfile
browser.executablePath
browser.profiles.<name>

If you want extension relay as the default, the key choice is usually:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome"
  }
}

From there, OpenClaw expects a Chromium-based browser and an attached extension relay.

How to think about profiles

The docs describe two common mental models:

openclaw: an isolated, OpenClaw-managed profile
chrome: an extension relay to the system browser

That means a “browser problem” is often really a “wrong profile problem.”

If you are debugging, confirm which profile you are actually using before you debug anything deeper.

When browser relay is the right choice

Browser relay is a good fit when:

you want to keep using your preferred Chromium browser
you are doing light browsing rather than heavily isolated automation
you already understand how the extension relay attaches to the live tab

It is a weaker fit when:

you want a clean automation lane
you do not want personal browsing state near agent operations
you are trying to reduce ambiguity during debugging

Common browser relay failures

The extension is not attached where you think it is

Relay mode depends on the right browser tab and extension state. If the extension is attached elsewhere, OpenClaw may appear blind or inconsistent.

You are using the wrong profile

People often think they are testing relay mode while the config is still pointing at the managed browser, or the other way around.

You expected relay mode to be isolated

It is not the same security or session boundary as a dedicated OpenClaw browser profile.

You are debugging browser relay before the Gateway is healthy

Browser tooling still depends on the Gateway, auth, and local control service. If the base install is unstable, browser relay will not be stable either.

Security boundaries still matter

The official browser docs are conservative about security:

browser control is loopback-oriented
access flows through Gateway auth or paired nodes
remote CDP endpoints and tokens should be treated as secrets
public exposure is a bad default

Even in relay mode, the right mental model is still “private control surface,” not “public browser automation service.”

Practical setup order

The cleanest order is:

make sure your base OpenClaw install is healthy
decide whether you want isolation or convenience
start with one browser profile only
verify the profile you are actually using
only then add remote browser, Browserless, or other CDP variations

That order removes most false debugging paths.