​

Browser (openclaw-managed)

• 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 built-in 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.
• Optional multi-profile support (openclaw, work, remote, …).

​

Quick start

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

​

Plugin control

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

• plugins.entries.browser.enabled not disabled
• browser.enabled=true

​

Missing browser command or tool

{
  plugins: {
    allow: ["telegram"],
  },
}

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

• browser.enabled=true is not enough by itself when plugins.allow is set.
• plugins.entries.browser.enabled=true is also not enough by itself when plugins.allow is set.
• tools.alsoAllow: ["browser"] does not load the bundled browser plugin. It only adjusts tool policy after the plugin is already loaded.
• If you do not need a restrictive plugin allowlist, removing plugins.allow also restores the default bundled browser behavior.

• openclaw browser is an unknown command.
• browser.request is missing.
• The agent reports the browser tool as unavailable or missing.

​

Profiles: openclaw vs user

• openclaw: managed, isolated browser (no extension required).
• user: built-in Chrome MCP attach profile for your real signed-in Chrome session.

• Default: use the isolated openclaw browser.
• Prefer profile="user" when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
• profile is the explicit override when you want a specific browser mode.

​

Configuration

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // 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)
    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" },
      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" },
    },
  },
}

• The browser control service binds to loopback on a port derived from gateway.port (default: 18791, which is gateway + 2).
• 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 managed local CDP port when unset.
• remoteCdpTimeoutMs applies to remote (non-loopback) CDP reachability checks.
• remoteCdpHandshakeTimeoutMs applies to remote CDP WebSocket reachability checks.
• Browser navigation/open-tab is SSRF-guarded before navigation and best-effort re-checked on final http(s) URL after navigation.
• In strict SSRF mode, remote CDP endpoint discovery/probes (cdpUrl, including /json/version lookups) are checked too.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork defaults to true (trusted-network model). Set it to false for strict public-only browsing.
• browser.ssrfPolicy.allowPrivateNetwork remains supported as a legacy alias for compatibility.
• 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 openclaw (OpenClaw-managed standalone browser). Use defaultProfile: "user" to opt into the signed-in user 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.
• driver: "existing-session" uses Chrome DevTools MCP instead of raw CDP. Do not set cdpUrl for that driver.
• Set browser.profiles.<name>.userDataDir when an existing-session profile should attach to a non-default Chromium user profile such as Brave or Edge.

​

Use Brave (or another Chromium-based browser)

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

• Query tokens (e.g., https://provider.example?token=<token>)
• HTTP Basic auth (e.g., https://user:pass@provider.example)

​

Node browser proxy (zero-config default)

• 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).
• 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 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: nodeHost.browserProxy.enabled=false
  • On the gateway: gateway.nodes.browser.mode="off"

​

Browserless (hosted remote CDP)

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

• Replace <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 wss:// for a direct CDP connection or keep the HTTPS URL and let OpenClaw discover /json/version.

​

Direct WebSocket CDP providers

• HTTP(S) endpoints — OpenClaw calls /json/version to discover the WebSocket debugger URL, then connects.
• WebSocket endpoints (ws:// / wss://) — OpenClaw connects directly, skipping /json/version. Use this for services like Browserless, Browserbase, or any provider that hands you a WebSocket URL.

​

Browserbase

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

• Sign up and copy your API Key from the Overview dashboard.
• Replace <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

• Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
• If browser control is enabled and no auth is configured, OpenClaw auto-generates gateway.auth.token on startup and persists it to config.
• 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.

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

• The openclaw profile is auto-created if missing.
• The user profile is built-in for Chrome MCP existing-session attach.
• Existing-session profiles are opt-in beyond user; create them with --driver existing-session.
• Local CDP ports allocate from 18800–18899 by default.
• Deleting a profile moves its local data directory to Trash.

​

Existing-session via Chrome DevTools MCP

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

• user

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

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

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.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

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

• status shows driver: existing-session
• status shows transport: chrome-mcp
• status shows running: true
• tabs lists your already-open browser tabs
• snapshot returns refs from the selected live tab

• the target Chromium-based browser is version 144+
• remote debugging is enabled in that browser’s inspect page
• the browser showed and you accepted the attach consent prompt
• 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

• Use 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 npx chrome-devtools-mcp@latest --autoConnect

• This path is higher-risk than the isolated openclaw profile because it can act inside your signed-in browser session.
• OpenClaw does not launch the browser for this driver; it attaches to an existing session only.
• OpenClaw uses the official Chrome DevTools MCP --autoConnect flow here. If userDataDir is set, OpenClaw passes it through to target that explicit Chromium user data directory.
• Existing-session screenshots support page captures and --ref element captures from snapshots, but not CSS --element selectors.
• Existing-session wait --url supports exact, substring, and glob patterns like other browser drivers. wait --load networkidle is not supported yet.
• Some features still require the managed browser path, such as PDF export and download interception.
• Existing-session is host-local. If Chrome lives on a different machine or a different network namespace, use remote CDP or a node host instead.

​

Isolation guarantees

• Dedicated user data dir: never touches your personal browser profile.
• Dedicated ports: avoids 9222 to prevent collisions with dev workflows.
• Deterministic tab control: target tabs by targetId, not “last tab”.

​

Browser selection

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: checks /Applications and ~/Applications.
• Linux: looks for google-chrome, brave, microsoft-edge, chromium, etc.
• Windows: checks common install locations.

​

Control API (optional)

• Status/start/stop: GET /, POST /start, POST /stop
• Tabs: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• Actions: POST /navigate, POST /act
• Hooks: POST /hooks/file-chooser, POST /hooks/dialog
• Downloads: POST /download, POST /wait/download
• Debugging: GET /console, POST /pdf
• Debugging: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Network: POST /response/body
• State: GET /cookies, POST /cookies/set, POST /cookies/clear
• State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Settings: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> or HTTP Basic auth with that password

​

Playwright requirement

​

Docker Playwright install

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

How it works (internal)

• A small control server accepts HTTP requests.
• It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via CDP.
• For advanced actions (click/type/snapshot/PDF), it uses Playwright on top of CDP.
• When Playwright is missing, only non-Playwright operations are available.

​

CLI quick reference

• openclaw browser status
• openclaw browser start
• openclaw browser stop
• openclaw browser tabs
• openclaw browser tab
• openclaw browser tab new
• openclaw browser tab select 2
• openclaw browser tab close 2
• openclaw browser open https://example.com
• openclaw browser focus abcd1234
• openclaw browser close abcd1234

• openclaw browser screenshot
• openclaw browser screenshot --full-page
• openclaw browser screenshot --ref 12
• openclaw browser screenshot --ref e12
• openclaw browser snapshot
• openclaw browser snapshot --format aria --limit 200
• openclaw browser snapshot --interactive --compact --depth 6
• openclaw browser snapshot --efficient
• openclaw browser snapshot --labels
• openclaw browser snapshot --selector "#main" --interactive
• openclaw browser snapshot --frame "iframe#main" --interactive
• openclaw browser console --level error
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• openclaw browser navigate https://example.com
• openclaw browser resize 1280 720
• openclaw browser click 12 --double
• openclaw browser click e12 --double
• openclaw browser type 23 "hello" --submit
• openclaw browser press Enter
• openclaw browser hover 44
• openclaw browser scrollintoview e12
• openclaw browser drag 10 11
• openclaw browser select 9 OptionA OptionB
• openclaw browser download e12 report.pdf
• openclaw browser waitfordownload report.pdf
• openclaw browser upload /tmp/openclaw/uploads/file.pdf
• openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
• openclaw browser dialog --accept
• openclaw browser wait --text "Done"
• openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
• openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
• openclaw browser highlight e12
• openclaw browser trace start
• openclaw browser trace stop

• openclaw browser cookies
• openclaw browser cookies set session abc123 --url "https://example.com"
• openclaw browser cookies clear
• openclaw browser storage local get
• openclaw browser storage local set theme dark
• openclaw browser storage session clear
• openclaw browser set offline on
• openclaw browser set headers --headers-json '{"X-Debug":"1"}'
• openclaw browser set credentials user pass
• openclaw browser set credentials --clear
• openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
• openclaw browser set geo --clear
• openclaw browser set media dark
• openclaw browser set timezone America/New_York
• openclaw browser set locale en-US
• openclaw browser set device "iPhone 14"

• upload and dialog are arming calls; run them before the click/press that triggers the chooser/dialog.
• Download and trace output paths are constrained to OpenClaw temp roots:
  • traces: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
  • downloads: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
• Upload paths are constrained to an OpenClaw temp uploads root:
  • uploads: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
• upload can also set file inputs directly via --input-ref or --element.
• snapshot:
  • --format ai (default when Playwright is installed): returns an AI snapshot with numeric refs (aria-ref="<n>").
  • --format aria: returns the accessibility tree (no refs; inspection only).
  • --efficient (or --mode efficient): compact role snapshot preset (interactive + compact + depth + lower maxChars).
  • Config default (tool/CLI only): set browser.snapshotDefaults.mode: "efficient" to use efficient snapshots when the caller does not pass a mode (see Gateway configuration).
  • Role snapshot options (--interactive, --compact, --depth, --selector) force a role-based snapshot with refs like ref=e12.
  • --frame "<iframe selector>" scopes role snapshots to an iframe (pairs with role refs like e12).
  • --interactive outputs a flat, easy-to-pick list of interactive elements (best for driving actions).
  • --labels adds a viewport-only screenshot with overlayed ref labels (prints MEDIA:<path>).
• click/type/etc require a ref from snapshot (either numeric 12 or role ref e12). CSS selectors are intentionally not supported for actions.

​

Snapshots and refs

• AI snapshot (numeric refs): openclaw browser snapshot (default; --format ai)
  • Output: a text snapshot that includes numeric refs.
  • Actions: openclaw browser click 12, openclaw browser type 23 "hello".
  • Internally, the ref is resolved via Playwright’s aria-ref.
• Role snapshot (role refs like e12): openclaw browser snapshot --interactive (or --compact, --depth, --selector, --frame)
  • Output: a role-based list/tree with [ref=e12] (and optional [nth=1]).
  • Actions: openclaw browser click e12, openclaw browser highlight e12.
  • Internally, the ref is resolved via getByRole(...) (plus nth() for duplicates).
  • Add --labels to include a viewport screenshot with overlayed e12 labels.

• Refs are not stable across navigations; if something fails, re-run snapshot and use a fresh ref.
• If the role snapshot was taken with --frame, role refs are scoped to that iframe until the next role snapshot.

​

Wait power-ups

• Wait for URL (globs supported by Playwright):
  • openclaw browser wait --url "**/dash"
• Wait for load state:
  • openclaw browser wait --load networkidle
• Wait for a JS predicate:
  • openclaw browser wait --fn "window.ready===true"
• Wait for a selector to become visible:
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Debug workflows

1. openclaw browser snapshot --interactive
2. Use click <ref> / type <ref> (prefer role refs in interactive mode)
3. If it still fails: openclaw browser highlight <ref> to see what Playwright is targeting
4. If the page behaves oddly:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. For deep debugging: record a trace:
   • openclaw browser trace start
   • reproduce the issue
   • openclaw browser trace stop (prints TRACE:<path>)

​

JSON output

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

​

State and environment knobs

• Cookies: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Headers: set headers --headers-json '{"X-Debug":"1"}' (legacy set headers --json '{"X-Debug":"1"}' remains supported)
• HTTP basic auth: set credentials user pass (or --clear)
• Geolocation: set geo <lat> <lon> --origin "https://example.com" (or --clear)
• Media: set media dark|light|no-preference|none
• Timezone / locale: set timezone ..., set locale ...
• Device / viewport:
  • set device "iPhone 14" (Playwright device presets)
  • set viewport 1280 720

​

Security & privacy

• The openclaw browser profile may contain logged-in sessions; treat it as sensitive.
• browser act kind=evaluate / openclaw browser evaluate and wait --fn execute arbitrary JavaScript in the page context. Prompt injection can steer this. Disable it with browser.evaluateEnabled=false if you do not need it.
• For logins and anti-bot notes (X/Twitter, etc.), see Browser login + X/Twitter posting.
• Keep the Gateway/node host private (loopback or tailnet-only).
• Remote CDP endpoints are powerful; tunnel and protect them.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​

Troubleshooting

​

Agent tools + how control works

• browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

• browser snapshot returns a stable UI tree (AI or ARIA).
• browser act uses the snapshot ref IDs to click/type/drag/select.
• browser screenshot captures pixels (full page or element).
• browser accepts:
  • profile to choose a named browser profile (openclaw, chrome, or remote CDP).
  • target (sandbox | host | node) to select where the browser lives.
  • In sandboxed sessions, target: "host" requires agents.defaults.sandbox.browser.allowHostControl=true.
  • If target is omitted: sandboxed sessions default to sandbox, non-sandbox sessions default to host.
  • If a browser-capable node is connected, the tool may auto-route to it unless you pin target="host" or target="node".

​

Related

• Tools Overview — all available agent tools
• Sandboxing — browser control in sandboxed environments
• Security — browser control risks and hardening