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 ''openclaw'' profile does ''not'' touch your personal browser profile.

- The agent can open tabs, read pages, click, and type in a safe lane.

- The default ''chrome'' profile uses the ''system default Chromium browser'' via the

extension relay; switch to ''openclaw'' for the isolated managed browser.

- 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.

- Optional multi-profile support (''openclaw'', ''work'', ''remote'', ...).

This browser is not your daily driver. It is a safe, isolated surface for

agent automation and verification.

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.

- ''openclaw'': managed, isolated browser (no extension required).

- ''chrome'': extension relay to your ''system browser'' (requires the OpenClaw

extension to be attached to a tab).

Set ''browser.defaultProfile: "openclaw"'' if you want managed mode by default.

Browser settings live in ''~/.openclaw/openclaw.json''.

{
  browser: {
    enabled: true, // default: true
    // 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)
    defaultProfile: "chrome",
    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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Notes:

- The browser control service binds to loopback on a port derived from ''gateway.port''

(default: ''18791'', which is gateway + 2). The relay uses the next port (''18792'').

- If you override the Gateway port (''gateway.port'' or ''OPENCLAW_GATEWAY_PORT''),

the derived browser ports shift to stay in the same "family".

- ''cdpUrl'' defaults to the relay port when unset.

- ''remoteCdpTimeoutMs'' applies to remote (non-loopback) CDP reachability checks.

- ''remoteCdpHandshakeTimeoutMs'' applies to remote CDP WebSocket reachability checks.

- ''attachOnly: true'' means "never launch a local browser; only attach if it is already running."

- ''color'' + per-profile ''color'' tint the browser UI so you can see which profile is active.

- Default profile is ''chrome'' (extension relay). Use ''defaultProfile: "openclaw"'' for the managed browser.

- Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.

- Local ''openclaw'' profiles auto-assign ''cdpPort''/''cdpUrl'' — set those only for remote CDP.

If your system default browser is Chromium-based (Chrome/Brave/Edge/etc),

OpenClaw uses it automatically. Set ''browser.executablePath'' to override

auto-detection:

CLI example:

openclaw config set browser.executablePath "/usr/bin/google-chrome"

// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

- 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 ''browser.profiles.<name>.cdpUrl'' (or ''browser.cdpUrl'') to

attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.

Remote CDP URLs can include auth:

- Query tokens (e.g., ''https://provider.example?token=<token>'')

- HTTP Basic auth (e.g., ''https://user:[email protected]'')

OpenClaw preserves the auth when calling ''/json/*'' endpoints and when connecting

to the CDP WebSocket. Prefer environment variables or secrets managers for

tokens instead of committing them to config files.

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 ''browser.profiles'' config (same as local).

- Disable if you don't want it:

- On the node: ''nodeHost.browserProxy.enabled=false''

- On the gateway: ''gateway.nodes.browser.mode="off"''

''Browserless'' is a hosted Chromium service that exposes

CDP endpoints over HTTPS. You can point a OpenClaw browser profile at a

Browserless region endpoint and authenticate with your API key.

Example:

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

Notes:

- Replace ''<BROWSERLESS_API_KEY>'' with your real Browserless token.

- Choose the region endpoint that matches your Browserless account (see their docs).

Key ideas:

- Browser control is loopback-only; access flows through the Gateway's auth or node pairing.

- 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 HTTPS endpoints and short-lived tokens where possible.

- Avoid embedding long-lived tokens directly in config files.

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)

- extension relay: your existing Chrome tab(s) via the local relay + Chrome extension

Defaults:

- The ''openclaw'' profile is auto-created if missing.

- The ''chrome'' profile is built-in for the Chrome extension relay (points at ''http://127.0.0.1:18792'' by default).

- Local CDP ports allocate from 18800–18899 by default.

- Deleting a profile moves its local data directory to Trash.

All control endpoints accept ''?profile=<name>''; the CLI uses ''--browser-profile''.

OpenClaw can also drive your existing Chrome tabs (no separate "openclaw" Chrome instance) via a local CDP relay + a Chrome extension.

Full guide: ''Chrome extension''

Flow:

- The Gateway runs locally (same machine) or a node host runs on the browser machine.

- A local ''relay server'' listens at a loopback ''cdpUrl'' (default: ''http://127.0.0.1:18792'').

- You click the OpenClaw Browser Relay extension icon on a tab to attach (it does not auto-attach).

- The agent controls that tab via the normal ''browser'' tool, by selecting the right profile.

If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.

If the agent session is sandboxed, the ''browser'' tool may default to ''target="sandbox"'' (sandbox browser).

Chrome extension relay takeover requires host browser control, so either:

- run the session unsandboxed, or

- set ''agents.defaults.sandbox.browser.allowHostControl: true'' and use ''target="host"'' when calling the tool.

1. Load the extension (dev/unpacked):

openclaw browser extension install

- Chrome → ''chrome://extensions'' → enable "Developer mode"

- "Load unpacked" → select the directory printed by ''openclaw browser extension path''

- Pin the extension, then click it on the tab you want to control (badge shows ''ON'').

2. Use it:

- CLI: ''openclaw browser --browser-profile chrome tabs''

- Agent tool: ''browser'' with ''profile="chrome"''

Optional: if you want a different name or relay port, create your own profile:

openclaw browser create-profile   --name my-chrome   --driver extension   --cdp-url http://127.0.0.1:18792   --color "#00AA00"

Notes:

- This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).

- Detach by clicking the extension icon again.

- Dedicated user data dir: never touches your personal browser profile.

- ''Dedicated ports'': avoids ''9222'' to prevent collisions with dev workflows.