Browser (OpenClaw-managed)

OpenClaw can run a dedicated Chrome/Brave/Edge/Chromium profile that the agent controls. It is isolated from your personal browser and is managed through a small local control service inside the Gateway (loopback only).

Beginner view:

• Think of it as a separate, agent-only browser.
• The
  text

  Copy

  openclaw
  profile does not touch your personal browser profile.
• The agent can open tabs, read pages, click, and type in a safe lane.
• The built-in
  text

  Copy

  user
  profile attaches to your real signed-in Chrome session via Chrome MCP.

What you get

• A separate browser profile named openclaw (orange accent by default).
• Deterministic tab control (list/open/focus/close).
• Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.
• A bundled
  text

  Copy

  browser-automation
  skill that teaches agents the snapshot, stable-tab, stale-ref, and manual-blocker recovery loop when the browser plugin is enabled.
• Optional multi-profile support (
  text

  Copy

  openclaw
  ,
  text

  Copy

  work
  ,
  text

  Copy

  remote
  , ...).

This browser is not your daily driver. It is a safe, isolated surface for agent automation and verification.

Quick start

bash
Copy
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

If you get “Browser disabled”, enable it in config (see below) and restart the Gateway.

If

is missing entirely, or the agent says the browser tool is unavailable, jump to Missing browser command or tool.

Plugin control

The default

tool is a bundled plugin. Disable it to replace it with another plugin that registers the same tool name:

json5
Copy
{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

Defaults need both

and . Disabling only the plugin removes the CLI, gateway method, agent tool, and control service as one unit; your config stays intact for a replacement.

Browser config changes require a Gateway restart so the plugin can re-register its service.

Agent guidance

Tool-profile note:

includes and , but it does not include the full tool. If the agent or a spawned sub-agent should use browser automation, add browser at the profile stage:

json5
Copy
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

For a single agent, use

. alone is not enough because sub-agent policy is applied after profile filtering.

The browser plugin ships two levels of agent guidance:

• The
  text

  Copy

  browser
  tool description carries the compact always-on contract: pick the right profile, keep refs on the same tab, use
  text

  Copy

  tabId
  /labels for tab targeting, and load the browser skill for multi-step work.
• The bundled
  text

  Copy

  browser-automation
  skill carries the longer operating loop: check status/tabs first, label task tabs, snapshot before acting, resnapshot after UI changes, recover stale refs once, and report login/2FA/captcha or camera/microphone blockers as manual action instead of guessing.

Plugin-bundled skills are listed in the agent's available skills when the plugin is enabled. The full skill instructions are loaded on demand, so routine turns do not pay the full token cost.

Missing browser command or tool

If

is unknown after an upgrade, is missing, or the agent reports the browser tool as unavailable, the usual cause is a list that omits and no root config block exists. Add it:

json5
Copy
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

An explicit root

block, for example or , activates the bundled browser plugin even under a restrictive , matching channel config behavior. and do not substitute for allowlist membership by themselves. Removing entirely also restores the default.

Profiles:

text

Copy

openclaw

vs

text

Copy

user

• text

  Copy

  openclaw
  : managed, isolated browser (no extension required).
• text

  Copy

  user
  : built-in Chrome MCP attach profile for your real signed-in Chrome session.

For agent browser tool calls:

• Default: use the isolated
  text

  Copy

  openclaw
  browser.
• Prefer
  text

  Copy

  profile="user"
  when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
• text

  Copy

  profile
  is the explicit override when you want a specific browser mode.

Set

if you want managed mode by default.

Configuration

Browser settings live in

.

json5
Copy
{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Ports and reachability

SSRF policy

Profile behavior

Use Brave or another Chromium-based browser

If your system default browser is Chromium-based (Chrome/Brave/Edge/etc), OpenClaw uses it automatically. Set

to override auto-detection. Top-level and per-profile values accept for your OS home directory:

bash
Copy
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Or set it in config, per platform:

```json5} { browser: { executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", }, } ``` ```json5} { browser: { executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe", }, } ``` ```json5} { browser: { executablePath: "/usr/bin/brave-browser", }, } ```

Per-profile

only affects local managed profiles that OpenClaw launches. profiles attach to an already-running browser instead, and remote CDP profiles use the browser behind .

Local vs remote control

• Local control (default): the Gateway starts the loopback control service and can launch a local browser.
• Remote control (node host): run a node host on the machine that has the browser; the Gateway proxies browser actions to it.
• Remote CDP: set
  text

  Copy

  browser.profiles.<name>.cdpUrl
  (or
  text

  Copy

  browser.cdpUrl
  ) to attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.
• For externally managed CDP services on loopback (for example Browserless in Docker published to
  text

  Copy

  127.0.0.1
  ), also set
  text

  Copy

  attachOnly: true
  . Loopback CDP without
  text

  Copy

  attachOnly
  is treated as a local OpenClaw-managed browser profile.
• text

  Copy

  headless
  only affects local managed profiles that OpenClaw launches. It does not restart or change existing-session or remote CDP browsers.
• text

  Copy

  executablePath
  follows the same local managed profile rule. Changing it on a running local managed profile marks that profile for restart/reconcile so the next launch uses the new binary.

Stopping behavior differs by profile mode:

• local managed profiles:
  text

  Copy

  openclaw browser stop
  stops the browser process that OpenClaw launched
• attach-only and remote CDP profiles:
  text

  Copy

  openclaw browser stop
  closes the active control session and releases Playwright/CDP emulation overrides (viewport, color scheme, locale, timezone, offline mode, and similar state), even though no browser process was launched by OpenClaw

Remote CDP URLs can include auth:

• Query tokens (e.g.,
  text

  Copy

  https://provider.example?token=<token>
  )
• HTTP Basic auth (e.g.,
  text

  Copy

  https://user:pass@provider.example
  )

OpenClaw preserves the auth when calling

endpoints and when connecting to the CDP WebSocket. Prefer environment variables or secrets managers for tokens instead of committing them to config files.

Node browser proxy (zero-config default)

If you run a node host on the machine that has your browser, OpenClaw can auto-route browser tool calls to that node without any extra browser config. This is the default path for remote gateways.

Notes:

• The node host exposes its local browser control server via a proxy command.
• Profiles come from the node’s own
  text

  Copy

  browser.profiles
  config (same as local).
• text

  Copy

  nodeHost.browserProxy.allowProfiles
  is optional. Leave it empty for the legacy/default behavior: all configured profiles remain reachable through the proxy, including profile create/delete routes.
• If you set
  text

  Copy

  nodeHost.browserProxy.allowProfiles
  , OpenClaw treats it as a least-privilege boundary: only allowlisted profiles can be targeted, and persistent profile create/delete routes are blocked on the proxy surface.
• Disable if you don’t want it:
  • On the node:
    text

    Copy

    nodeHost.browserProxy.enabled=false
  • On the gateway:
    text

    Copy

    gateway.nodes.browser.mode="off"

Browserless (hosted remote CDP)

Browserless is a hosted Chromium service that exposes CDP connection URLs over HTTPS and WebSocket. OpenClaw can use either form, but for a remote browser profile the simplest option is the direct WebSocket URL from Browserless' connection docs.

Example:

json5
Copy
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Notes:

• Replace
  text

  Copy

  <BROWSERLESS_API_KEY>
  with your real Browserless token.
• Choose the region endpoint that matches your Browserless account (see their docs).
• If Browserless gives you an HTTPS base URL, you can either convert it to
  text

  Copy

  wss://
  for a direct CDP connection or keep the HTTPS URL and let OpenClaw discover
  text

  Copy

  /json/version
  .

Browserless Docker on the same host

When Browserless is self-hosted in Docker and OpenClaw runs on the host, treat Browserless as an externally managed CDP service:

json5
Copy
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

The address in

must be reachable from the OpenClaw process. Browserless must also advertise a matching reachable endpoint; set Browserless to that same public-to-OpenClaw WebSocket base, such as , , or a stable private Docker network address. If returns pointing at an address OpenClaw cannot reach, CDP HTTP can look healthy while the WebSocket attach still fails.

Do not leave

unset for a loopback Browserless profile. Without , OpenClaw treats the loopback port as a local managed browser profile and may report that the port is in use but not owned by OpenClaw.

Direct WebSocket CDP providers

Some hosted browser services expose a direct WebSocket endpoint rather than the standard HTTP-based CDP discovery (

). OpenClaw accepts three CDP URL shapes and picks the right connection strategy automatically:

• HTTP(S) discovery —
  text

  Copy

  http://host[:port]
  or
  text

  Copy

  https://host[:port]
  . OpenClaw calls
  text

  Copy

  /json/version
  to discover the WebSocket debugger URL, then connects. No WebSocket fallback.
• Direct WebSocket endpoints —
  text

  Copy

  ws://host[:port]/devtools/<kind>/<id>
  or
  text

  Copy

  wss://...
  with a
  text

  Copy

  /devtools/browser|page|worker|shared_worker|service_worker/<id>
  path. OpenClaw connects directly via a WebSocket handshake and skips
  text

  Copy

  /json/version
  entirely.
• Bare WebSocket roots —
  text

  Copy

  ws://host[:port]
  or
  text

  Copy

  wss://host[:port]
  with no
  text

  Copy

  /devtools/...
  path (e.g. Browserless, Browserbase). OpenClaw tries HTTP
  text

  Copy

  /json/version
  discovery first (normalising the scheme to
  text

  Copy

  http
  /
  text

  Copy

  https
  ); if discovery returns a
  text

  Copy

  webSocketDebuggerUrl
  it is used, otherwise OpenClaw falls back to a direct WebSocket handshake at the bare root. If the advertised WebSocket endpoint rejects the CDP handshake but the configured bare root accepts it, OpenClaw falls back to that root as well. This lets a bare
  text

  Copy

  ws://
  pointed at a local Chrome still connect, since Chrome only accepts WebSocket upgrades on the specific per-target path from
  text

  Copy

  /json/version
  , while hosted providers can still use their root WebSocket endpoint when their discovery endpoint advertises a short-lived URL that is not suitable for Playwright CDP.

Browserbase

Browserbase is a cloud platform for running headless browsers with built-in CAPTCHA solving, stealth mode, and residential proxies.

json5
Copy
{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

Notes:

• Sign up and copy your API Key from the Overview dashboard.
• Replace
  text

  Copy

  <BROWSERBASE_API_KEY>
  with your real Browserbase API key.
• Browserbase auto-creates a browser session on WebSocket connect, so no manual session creation step is needed.
• The free tier allows one concurrent session and one browser hour per month. See pricing for paid plan limits.
• See the Browserbase docs for full API reference, SDK guides, and integration examples.

Security

Key ideas:

• Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
• The standalone loopback browser HTTP API uses shared-secret auth only: gateway token bearer auth,
  text

  Copy

  x-openclaw-password
  , or HTTP Basic auth with the configured gateway password.
• Tailscale Serve identity headers and
  text

  Copy

  gateway.auth.mode: "trusted-proxy"
  do not authenticate this standalone loopback browser API.
• If browser control is enabled and no shared-secret auth is configured, OpenClaw auto-generates
  text

  Copy

  gateway.auth.token
  on startup and persists it to config.
• OpenClaw does not auto-generate that token when
  text

  Copy

  gateway.auth.mode
  is already
  text

  Copy

  password
  ,
  text

  Copy

  none
  , or
  text

  Copy

  trusted-proxy
  .
• Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.
• Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.

Remote CDP tips:

• Prefer encrypted endpoints (HTTPS or WSS) and short-lived tokens where possible.
• Avoid embedding long-lived tokens directly in config files.

Profiles (multi-browser)

OpenClaw supports multiple named profiles (routing configs). Profiles can be:

• openclaw-managed: a dedicated Chromium-based browser instance with its own user data directory + CDP port
• remote: an explicit CDP URL (Chromium-based browser running elsewhere)
• existing session: your existing Chrome profile via Chrome DevTools MCP auto-connect

Defaults:

• The
  text

  Copy

  openclaw
  profile is auto-created if missing.
• The
  text

  Copy

  user
  profile is built-in for Chrome MCP existing-session attach.
• Existing-session profiles are opt-in beyond
  text

  Copy

  user
  ; create them with
  text

  Copy

  --driver existing-session
  .
• Local CDP ports allocate from 18800–18899 by default.
• Deleting a profile moves its local data directory to Trash.

All control endpoints accept

; the CLI uses .

Existing session via Chrome DevTools MCP

OpenClaw can also attach to a running Chromium-based browser profile through the official Chrome DevTools MCP server. This reuses the tabs and login state already open in that browser profile.

Official background and setup references:

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

Built-in profile:

• text

  Copy

  user

Optional: create your own custom existing-session profile if you want a different name, color, or browser data directory.

Default behavior:

• The built-in
  text

  Copy

  user
  profile uses Chrome MCP auto-connect, which targets the default local Google Chrome profile.

Use

for Brave, Edge, Chromium, or a non-default Chrome profile. expands to your OS home directory:

json5
Copy
{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

Then in the matching browser:

1. Open that browser's inspect page for remote debugging.
2. Enable remote debugging.
3. Keep the browser running and approve the connection prompt when OpenClaw attaches.

Common inspect pages:

• Chrome:
  text

  Copy

  chrome://inspect/#remote-debugging
• Brave:
  text

  Copy

  brave://inspect/#remote-debugging
• Edge:
  text

  Copy

  edge://inspect/#remote-debugging

Live attach smoke test:

bash
Copy
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

What success looks like:

• text

  Copy

  status
  shows
  text

  Copy

  driver: existing-session
• text

  Copy

  status
  shows
  text

  Copy

  transport: chrome-mcp
• text

  Copy

  status
  shows
  text

  Copy

  running: true
• text

  Copy

  tabs
  lists your already-open browser tabs
• text

  Copy

  snapshot
  returns refs from the selected live tab

What to check if attach does not work:

• the target Chromium-based browser is version
  text

  Copy

  144+
• remote debugging is enabled in that browser's inspect page
• the browser showed and you accepted the attach consent prompt
• text

  Copy

  openclaw doctor
  migrates old extension-based browser config and checks that Chrome is installed locally for default auto-connect profiles, but it cannot enable browser-side remote debugging for you

Agent use:

• Use
  text

  Copy

  profile="user"
  when you need the user’s logged-in browser state.
• If you use a custom existing-session profile, pass that explicit profile name.
• Only choose this mode when the user is at the computer to approve the attach prompt.
• the Gateway or node host can spawn
  text

  Copy

  npx chrome-devtools-mcp@latest --autoConnect

Notes:

• This path is higher-risk than the isolated
  text

  Copy

  openclaw
  profile because it can act inside your signed-in browser session.
• OpenClaw does not launch the browser for this driver; it only attaches.
• OpenClaw uses the official Chrome DevTools MCP
  text

  Copy

  --autoConnect
  flow here. If
  text

  Copy

  userDataDir
  is set, it is passed through to target that user data directory.
• Existing-session can attach on the selected host or through a connected browser node. If Chrome lives elsewhere and no browser node is connected, use remote CDP or a node host instead.

Custom Chrome MCP launch

Override the spawned Chrome DevTools MCP server per profile when the default

flow is not what you want (offline hosts, pinned versions, vendored binaries):

When

is set on an existing-session profile, OpenClaw skips and forwards the endpoint to Chrome MCP automatically:

• text

  Copy

  http(s)://...
  →
  text

  Copy

  --browserUrl <url>
  (DevTools HTTP discovery endpoint).
• text

  Copy

  ws(s)://...
  →
  text

  Copy

  --wsEndpoint <url>
  (direct CDP WebSocket).

Endpoint flags and

cannot be combined: when is set, is ignored for Chrome MCP launch, since Chrome MCP attaches to the running browser behind the endpoint rather than opening a profile directory.