{
  "title": "Browser (openclaw-managed)",
  "content": "OpenClaw can run a **dedicated Chrome/Brave/Edge/Chromium profile** that the agent controls.\nIt is isolated from your personal browser and is managed through a small local\ncontrol service inside the Gateway (loopback only).\n\n* Think of it as a **separate, agent-only browser**.\n* The `openclaw` profile does **not** touch your personal browser profile.\n* The agent can **open tabs, read pages, click, and type** in a safe lane.\n* The default `chrome` profile uses the **system default Chromium browser** via the\n  extension relay; switch to `openclaw` for the isolated managed browser.\n\n* A separate browser profile named **openclaw** (orange accent by default).\n* Deterministic tab control (list/open/focus/close).\n* Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.\n* Optional multi-profile support (`openclaw`, `work`, `remote`, ...).\n\nThis browser is **not** your daily driver. It is a safe, isolated surface for\nagent automation and verification.\n\nIf you get “Browser disabled”, enable it in config (see below) and restart the\nGateway.\n\n## Profiles: `openclaw` vs `chrome`\n\n* `openclaw`: managed, isolated browser (no extension required).\n* `chrome`: extension relay to your **system browser** (requires the OpenClaw\n  extension to be attached to a tab).\n\nSet `browser.defaultProfile: \"openclaw\"` if you want managed mode by default.\n\nBrowser settings live in `~/.openclaw/openclaw.json`.\n\n* The browser control service binds to loopback on a port derived from `gateway.port`\n  (default: `18791`, which is gateway + 2). The relay uses the next port (`18792`).\n* If you override the Gateway port (`gateway.port` or `OPENCLAW_GATEWAY_PORT`),\n  the derived browser ports shift to stay in the same “family”.\n* `cdpUrl` defaults to the relay port when unset.\n* `remoteCdpTimeoutMs` applies to remote (non-loopback) CDP reachability checks.\n* `remoteCdpHandshakeTimeoutMs` applies to remote CDP WebSocket reachability checks.\n* `attachOnly: true` means “never launch a local browser; only attach if it is already running.”\n* `color` + per-profile `color` tint the browser UI so you can see which profile is active.\n* Default profile is `chrome` (extension relay). Use `defaultProfile: \"openclaw\"` for the managed browser.\n* Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.\n* Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.\n\n## Use Brave (or another Chromium-based browser)\n\nIf your **system default** browser is Chromium-based (Chrome/Brave/Edge/etc),\nOpenClaw uses it automatically. Set `browser.executablePath` to override\nauto-detection:\n\n## Local vs remote control\n\n* **Local control (default):** the Gateway starts the loopback control service and can launch a local browser.\n* **Remote control (node host):** run a node host on the machine that has the browser; the Gateway proxies browser actions to it.\n* **Remote CDP:** set `browser.profiles.<name>.cdpUrl` (or `browser.cdpUrl`) to\n  attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.\n\nRemote CDP URLs can include auth:\n\n* Query tokens (e.g., `https://provider.example?token=<token>`)\n* HTTP Basic auth (e.g., `https://user:pass@provider.example`)\n\nOpenClaw preserves the auth when calling `/json/*` endpoints and when connecting\nto the CDP WebSocket. Prefer environment variables or secrets managers for\ntokens instead of committing them to config files.\n\n## Node browser proxy (zero-config default)\n\nIf you run a **node host** on the machine that has your browser, OpenClaw can\nauto-route browser tool calls to that node without any extra browser config.\nThis is the default path for remote gateways.\n\n* The node host exposes its local browser control server via a **proxy command**.\n* Profiles come from the node’s own `browser.profiles` config (same as local).\n* Disable if you don’t want it:\n  * On the node: `nodeHost.browserProxy.enabled=false`\n  * On the gateway: `gateway.nodes.browser.mode=\"off\"`\n\n## Browserless (hosted remote CDP)\n\n[Browserless](https://browserless.io) is a hosted Chromium service that exposes\nCDP endpoints over HTTPS. You can point a OpenClaw browser profile at a\nBrowserless region endpoint and authenticate with your API key.\n\n* Replace `<BROWSERLESS_API_KEY>` with your real Browserless token.\n* Choose the region endpoint that matches your Browserless account (see their docs).\n\n* Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.\n* Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.\n* Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.\n\n* Prefer HTTPS endpoints and short-lived tokens where possible.\n* Avoid embedding long-lived tokens directly in config files.\n\n## Profiles (multi-browser)\n\nOpenClaw supports multiple named profiles (routing configs). Profiles can be:\n\n* **openclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port\n* **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)\n* **extension relay**: your existing Chrome tab(s) via the local relay + Chrome extension\n\n* The `openclaw` profile is auto-created if missing.\n* The `chrome` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).\n* Local CDP ports allocate from **18800–18899** by default.\n* Deleting a profile moves its local data directory to Trash.\n\nAll control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.\n\n## Chrome extension relay (use your existing Chrome)\n\nOpenClaw can also drive **your existing Chrome tabs** (no separate “openclaw” Chrome instance) via a local CDP relay + a Chrome extension.\n\nFull guide: [Chrome extension](/tools/chrome-extension)\n\n* The Gateway runs locally (same machine) or a node host runs on the browser machine.\n* A local **relay server** listens at a loopback `cdpUrl` (default: `http://127.0.0.1:18792`).\n* You click the **OpenClaw Browser Relay** extension icon on a tab to attach (it does not auto-attach).\n* The agent controls that tab via the normal `browser` tool, by selecting the right profile.\n\nIf the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.\n\n### Sandboxed sessions\n\nIf the agent session is sandboxed, the `browser` tool may default to `target=\"sandbox\"` (sandbox browser).\nChrome extension relay takeover requires host browser control, so either:\n\n* run the session unsandboxed, or\n* set `agents.defaults.sandbox.browser.allowHostControl: true` and use `target=\"host\"` when calling the tool.\n\n1. Load the extension (dev/unpacked):\n\n* Chrome → `chrome://extensions` → enable “Developer mode”\n* “Load unpacked” → select the directory printed by `openclaw browser extension path`\n* Pin the extension, then click it on the tab you want to control (badge shows `ON`).\n\n* CLI: `openclaw browser --browser-profile chrome tabs`\n* Agent tool: `browser` with `profile=\"chrome\"`\n\nOptional: if you want a different name or relay port, create your own profile:\n\n* This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).\n* Detach by clicking the extension icon again.\n\n## Isolation guarantees\n\n* **Dedicated user data dir**: never touches your personal browser profile.\n* **Dedicated ports**: avoids `9222` to prevent collisions with dev workflows.\n* **Deterministic tab control**: target tabs by `targetId`, not “last tab”.\n\nWhen launching locally, OpenClaw picks the first available:\n\n1. Chrome\n2. Brave\n3. Edge\n4. Chromium\n5. Chrome Canary\n\nYou can override with `browser.executablePath`.\n\n* macOS: checks `/Applications` and `~/Applications`.\n* Linux: looks for `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.\n* Windows: checks common install locations.\n\n## Control API (optional)\n\nFor local integrations only, the Gateway exposes a small loopback HTTP API:\n\n* Status/start/stop: `GET /`, `POST /start`, `POST /stop`\n* Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`\n* Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`\n* Actions: `POST /navigate`, `POST /act`\n* Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`\n* Downloads: `POST /download`, `POST /wait/download`\n* Debugging: `GET /console`, `POST /pdf`\n* Debugging: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`\n* Network: `POST /response/body`\n* State: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`\n* State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`\n* 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`\n\nAll endpoints accept `?profile=<name>`.\n\n### Playwright requirement\n\nSome features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require\nPlaywright. If Playwright isn’t installed, those endpoints return a clear 501\nerror. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome.\nFor the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright.\n\nIf you see `Playwright is not available in this gateway build`, install the full\nPlaywright package (not `playwright-core`) and restart the gateway, or reinstall\nOpenClaw with browser support.\n\n#### Docker Playwright install\n\nIf your Gateway runs in Docker, avoid `npx playwright` (npm override conflicts).\nUse the bundled CLI instead:\n\nTo persist browser downloads, set `PLAYWRIGHT_BROWSERS_PATH` (for example,\n`/home/node/.cache/ms-playwright`) and make sure `/home/node` is persisted via\n`OPENCLAW_HOME_VOLUME` or a bind mount. See [Docker](/install/docker).\n\n## How it works (internal)\n\n* A small **control server** accepts HTTP requests.\n* It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via **CDP**.\n* For advanced actions (click/type/snapshot/PDF), it uses **Playwright** on top\n  of CDP.\n* When Playwright is missing, only non-Playwright operations are available.\n\nThis design keeps the agent on a stable, deterministic interface while letting\nyou swap local/remote browsers and profiles.\n\n## CLI quick reference\n\nAll commands accept `--browser-profile <name>` to target a specific profile.\nAll commands also accept `--json` for machine-readable output (stable payloads).\n\n* `openclaw browser status`\n* `openclaw browser start`\n* `openclaw browser stop`\n* `openclaw browser tabs`\n* `openclaw browser tab`\n* `openclaw browser tab new`\n* `openclaw browser tab select 2`\n* `openclaw browser tab close 2`\n* `openclaw browser open https://example.com`\n* `openclaw browser focus abcd1234`\n* `openclaw browser close abcd1234`\n\n* `openclaw browser screenshot`\n* `openclaw browser screenshot --full-page`\n* `openclaw browser screenshot --ref 12`\n* `openclaw browser screenshot --ref e12`\n* `openclaw browser snapshot`\n* `openclaw browser snapshot --format aria --limit 200`\n* `openclaw browser snapshot --interactive --compact --depth 6`\n* `openclaw browser snapshot --efficient`\n* `openclaw browser snapshot --labels`\n* `openclaw browser snapshot --selector \"#main\" --interactive`\n* `openclaw browser snapshot --frame \"iframe#main\" --interactive`\n* `openclaw browser console --level error`\n* `openclaw browser errors --clear`\n* `openclaw browser requests --filter api --clear`\n* `openclaw browser pdf`\n* `openclaw browser responsebody \"**/api\" --max-chars 5000`\n\n* `openclaw browser navigate https://example.com`\n* `openclaw browser resize 1280 720`\n* `openclaw browser click 12 --double`\n* `openclaw browser click e12 --double`\n* `openclaw browser type 23 \"hello\" --submit`\n* `openclaw browser press Enter`\n* `openclaw browser hover 44`\n* `openclaw browser scrollintoview e12`\n* `openclaw browser drag 10 11`\n* `openclaw browser select 9 OptionA OptionB`\n* `openclaw browser download e12 /tmp/report.pdf`\n* `openclaw browser waitfordownload /tmp/report.pdf`\n* `openclaw browser upload /tmp/file.pdf`\n* `openclaw browser fill --fields '[{\"ref\":\"1\",\"type\":\"text\",\"value\":\"Ada\"}]'`\n* `openclaw browser dialog --accept`\n* `openclaw browser wait --text \"Done\"`\n* `openclaw browser wait \"#main\" --url \"**/dash\" --load networkidle --fn \"window.ready===true\"`\n* `openclaw browser evaluate --fn '(el) => el.textContent' --ref 7`\n* `openclaw browser highlight e12`\n* `openclaw browser trace start`\n* `openclaw browser trace stop`\n\n* `openclaw browser cookies`\n* `openclaw browser cookies set session abc123 --url \"https://example.com\"`\n* `openclaw browser cookies clear`\n* `openclaw browser storage local get`\n* `openclaw browser storage local set theme dark`\n* `openclaw browser storage session clear`\n* `openclaw browser set offline on`\n* `openclaw browser set headers --json '{\"X-Debug\":\"1\"}'`\n* `openclaw browser set credentials user pass`\n* `openclaw browser set credentials --clear`\n* `openclaw browser set geo 37.7749 -122.4194 --origin \"https://example.com\"`\n* `openclaw browser set geo --clear`\n* `openclaw browser set media dark`\n* `openclaw browser set timezone America/New_York`\n* `openclaw browser set locale en-US`\n* `openclaw browser set device \"iPhone 14\"`\n\n* `upload` and `dialog` are **arming** calls; run them before the click/press\n  that triggers the chooser/dialog.\n* `upload` can also set file inputs directly via `--input-ref` or `--element`.\n* `snapshot`:\n  * `--format ai` (default when Playwright is installed): returns an AI snapshot with numeric refs (`aria-ref=\"<n>\"`).\n  * `--format aria`: returns the accessibility tree (no refs; inspection only).\n  * `--efficient` (or `--mode efficient`): compact role snapshot preset (interactive + compact + depth + lower maxChars).\n  * 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](/gateway/configuration#browser-openclaw-managed-browser)).\n  * Role snapshot options (`--interactive`, `--compact`, `--depth`, `--selector`) force a role-based snapshot with refs like `ref=e12`.\n  * `--frame \"<iframe selector>\"` scopes role snapshots to an iframe (pairs with role refs like `e12`).\n  * `--interactive` outputs a flat, easy-to-pick list of interactive elements (best for driving actions).\n  * `--labels` adds a viewport-only screenshot with overlayed ref labels (prints `MEDIA:<path>`).\n* `click`/`type`/etc require a `ref` from `snapshot` (either numeric `12` or role ref `e12`).\n  CSS selectors are intentionally not supported for actions.\n\n## Snapshots and refs\n\nOpenClaw supports two “snapshot” styles:\n\n* **AI snapshot (numeric refs)**: `openclaw browser snapshot` (default; `--format ai`)\n  * Output: a text snapshot that includes numeric refs.\n  * Actions: `openclaw browser click 12`, `openclaw browser type 23 \"hello\"`.\n  * Internally, the ref is resolved via Playwright’s `aria-ref`.\n\n* **Role snapshot (role refs like `e12`)**: `openclaw browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`)\n  * Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).\n  * Actions: `openclaw browser click e12`, `openclaw browser highlight e12`.\n  * Internally, the ref is resolved via `getByRole(...)` (plus `nth()` for duplicates).\n  * Add `--labels` to include a viewport screenshot with overlayed `e12` labels.\n\n* Refs are **not stable across navigations**; if something fails, re-run `snapshot` and use a fresh ref.\n* If the role snapshot was taken with `--frame`, role refs are scoped to that iframe until the next role snapshot.\n\nYou can wait on more than just time/text:\n\n* Wait for URL (globs supported by Playwright):\n  * `openclaw browser wait --url \"**/dash\"`\n* Wait for load state:\n  * `openclaw browser wait --load networkidle`\n* Wait for a JS predicate:\n  * `openclaw browser wait --fn \"window.ready===true\"`\n* Wait for a selector to become visible:\n  * `openclaw browser wait \"#main\"`\n\nThese can be combined:\n\nWhen an action fails (e.g. “not visible”, “strict mode violation”, “covered”):\n\n1. `openclaw browser snapshot --interactive`\n2. Use `click <ref>` / `type <ref>` (prefer role refs in interactive mode)\n3. If it still fails: `openclaw browser highlight <ref>` to see what Playwright is targeting\n4. If the page behaves oddly:\n   * `openclaw browser errors --clear`\n   * `openclaw browser requests --filter api --clear`\n5. For deep debugging: record a trace:\n   * `openclaw browser trace start`\n   * reproduce the issue\n   * `openclaw browser trace stop` (prints `TRACE:<path>`)\n\n`--json` is for scripting and structured tooling.\n\nRole snapshots in JSON include `refs` plus a small `stats` block (lines/chars/refs/interactive) so tools can reason about payload size and density.\n\n## State and environment knobs\n\nThese are useful for “make the site behave like X” workflows:\n\n* Cookies: `cookies`, `cookies set`, `cookies clear`\n* Storage: `storage local|session get|set|clear`\n* Offline: `set offline on|off`\n* Headers: `set headers --json '{\"X-Debug\":\"1\"}'` (or `--clear`)\n* HTTP basic auth: `set credentials user pass` (or `--clear`)\n* Geolocation: `set geo <lat> <lon> --origin \"https://example.com\"` (or `--clear`)\n* Media: `set media dark|light|no-preference|none`\n* Timezone / locale: `set timezone ...`, `set locale ...`\n* Device / viewport:\n  * `set device \"iPhone 14\"` (Playwright device presets)\n  * `set viewport 1280 720`\n\n## Security & privacy\n\n* The openclaw browser profile may contain logged-in sessions; treat it as sensitive.\n* `browser act kind=evaluate` / `openclaw browser evaluate` and `wait --fn`\n  execute arbitrary JavaScript in the page context. Prompt injection can steer\n  this. Disable it with `browser.evaluateEnabled=false` if you do not need it.\n* For logins and anti-bot notes (X/Twitter, etc.), see [Browser login + X/Twitter posting](/tools/browser-login).\n* Keep the Gateway/node host private (loopback or tailnet-only).\n* Remote CDP endpoints are powerful; tunnel and protect them.\n\nFor Linux-specific issues (especially snap Chromium), see\n[Browser troubleshooting](/tools/browser-linux-troubleshooting).\n\n## Agent tools + how control works\n\nThe agent gets **one tool** for browser automation:\n\n* `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act\n\n* `browser snapshot` returns a stable UI tree (AI or ARIA).\n* `browser act` uses the snapshot `ref` IDs to click/type/drag/select.\n* `browser screenshot` captures pixels (full page or element).\n* `browser` accepts:\n  * `profile` to choose a named browser profile (openclaw, chrome, or remote CDP).\n  * `target` (`sandbox` | `host` | `node`) to select where the browser lives.\n  * In sandboxed sessions, `target: \"host\"` requires `agents.defaults.sandbox.browser.allowHostControl=true`.\n  * If `target` is omitted: sandboxed sessions default to `sandbox`, non-sandbox sessions default to `host`.\n  * If a browser-capable node is connected, the tool may auto-route to it unless you pin `target=\"host\"` or `target=\"node\"`.\n\nThis keeps the agent deterministic and avoids brittle selectors.",
  "code_samples": [
    {
      "code": "If you get “Browser disabled”, enable it in config (see below) and restart the\nGateway.\n\n## Profiles: `openclaw` vs `chrome`\n\n* `openclaw`: managed, isolated browser (no extension required).\n* `chrome`: extension relay to your **system browser** (requires the OpenClaw\n  extension to be attached to a tab).\n\nSet `browser.defaultProfile: \"openclaw\"` if you want managed mode by default.\n\n## Configuration\n\nBrowser settings live in `~/.openclaw/openclaw.json`.",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* The browser control service binds to loopback on a port derived from `gateway.port`\n  (default: `18791`, which is gateway + 2). The relay uses the next port (`18792`).\n* If you override the Gateway port (`gateway.port` or `OPENCLAW_GATEWAY_PORT`),\n  the derived browser ports shift to stay in the same “family”.\n* `cdpUrl` defaults to the relay port when unset.\n* `remoteCdpTimeoutMs` applies to remote (non-loopback) CDP reachability checks.\n* `remoteCdpHandshakeTimeoutMs` applies to remote CDP WebSocket reachability checks.\n* `attachOnly: true` means “never launch a local browser; only attach if it is already running.”\n* `color` + per-profile `color` tint the browser UI so you can see which profile is active.\n* Default profile is `chrome` (extension relay). Use `defaultProfile: \"openclaw\"` for the managed browser.\n* Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.\n* Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.\n\n## Use Brave (or another Chromium-based browser)\n\nIf your **system default** browser is Chromium-based (Chrome/Brave/Edge/etc),\nOpenClaw uses it automatically. Set `browser.executablePath` to override\nauto-detection:\n\nCLI example:",
      "language": "unknown"
    },
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "## Local vs remote control\n\n* **Local control (default):** the Gateway starts the loopback control service and can launch a local browser.\n* **Remote control (node host):** run a node host on the machine that has the browser; the Gateway proxies browser actions to it.\n* **Remote CDP:** set `browser.profiles.<name>.cdpUrl` (or `browser.cdpUrl`) to\n  attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.\n\nRemote CDP URLs can include auth:\n\n* Query tokens (e.g., `https://provider.example?token=<token>`)\n* HTTP Basic auth (e.g., `https://user:pass@provider.example`)\n\nOpenClaw preserves the auth when calling `/json/*` endpoints and when connecting\nto the CDP WebSocket. Prefer environment variables or secrets managers for\ntokens instead of committing them to config files.\n\n## Node browser proxy (zero-config default)\n\nIf you run a **node host** on the machine that has your browser, OpenClaw can\nauto-route browser tool calls to that node without any extra browser config.\nThis is the default path for remote gateways.\n\nNotes:\n\n* The node host exposes its local browser control server via a **proxy command**.\n* Profiles come from the node’s own `browser.profiles` config (same as local).\n* Disable if you don’t want it:\n  * On the node: `nodeHost.browserProxy.enabled=false`\n  * On the gateway: `gateway.nodes.browser.mode=\"off\"`\n\n## Browserless (hosted remote CDP)\n\n[Browserless](https://browserless.io) is a hosted Chromium service that exposes\nCDP endpoints over HTTPS. You can point a OpenClaw browser profile at a\nBrowserless region endpoint and authenticate with your API key.\n\nExample:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* Replace `<BROWSERLESS_API_KEY>` with your real Browserless token.\n* Choose the region endpoint that matches your Browserless account (see their docs).\n\n## Security\n\nKey ideas:\n\n* Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.\n* Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.\n* Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.\n\nRemote CDP tips:\n\n* Prefer HTTPS endpoints and short-lived tokens where possible.\n* Avoid embedding long-lived tokens directly in config files.\n\n## Profiles (multi-browser)\n\nOpenClaw supports multiple named profiles (routing configs). Profiles can be:\n\n* **openclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port\n* **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)\n* **extension relay**: your existing Chrome tab(s) via the local relay + Chrome extension\n\nDefaults:\n\n* The `openclaw` profile is auto-created if missing.\n* The `chrome` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).\n* Local CDP ports allocate from **18800–18899** by default.\n* Deleting a profile moves its local data directory to Trash.\n\nAll control endpoints accept `?profile=<name>`; the CLI uses `--browser-profile`.\n\n## Chrome extension relay (use your existing Chrome)\n\nOpenClaw can also drive **your existing Chrome tabs** (no separate “openclaw” Chrome instance) via a local CDP relay + a Chrome extension.\n\nFull guide: [Chrome extension](/tools/chrome-extension)\n\nFlow:\n\n* The Gateway runs locally (same machine) or a node host runs on the browser machine.\n* A local **relay server** listens at a loopback `cdpUrl` (default: `http://127.0.0.1:18792`).\n* You click the **OpenClaw Browser Relay** extension icon on a tab to attach (it does not auto-attach).\n* The agent controls that tab via the normal `browser` tool, by selecting the right profile.\n\nIf the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.\n\n### Sandboxed sessions\n\nIf the agent session is sandboxed, the `browser` tool may default to `target=\"sandbox\"` (sandbox browser).\nChrome extension relay takeover requires host browser control, so either:\n\n* run the session unsandboxed, or\n* set `agents.defaults.sandbox.browser.allowHostControl: true` and use `target=\"host\"` when calling the tool.\n\n### Setup\n\n1. Load the extension (dev/unpacked):",
      "language": "unknown"
    },
    {
      "code": "* Chrome → `chrome://extensions` → enable “Developer mode”\n* “Load unpacked” → select the directory printed by `openclaw browser extension path`\n* Pin the extension, then click it on the tab you want to control (badge shows `ON`).\n\n2. Use it:\n\n* CLI: `openclaw browser --browser-profile chrome tabs`\n* Agent tool: `browser` with `profile=\"chrome\"`\n\nOptional: if you want a different name or relay port, create your own profile:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).\n* Detach by clicking the extension icon again.\n\n## Isolation guarantees\n\n* **Dedicated user data dir**: never touches your personal browser profile.\n* **Dedicated ports**: avoids `9222` to prevent collisions with dev workflows.\n* **Deterministic tab control**: target tabs by `targetId`, not “last tab”.\n\n## Browser selection\n\nWhen launching locally, OpenClaw picks the first available:\n\n1. Chrome\n2. Brave\n3. Edge\n4. Chromium\n5. Chrome Canary\n\nYou can override with `browser.executablePath`.\n\nPlatforms:\n\n* macOS: checks `/Applications` and `~/Applications`.\n* Linux: looks for `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.\n* Windows: checks common install locations.\n\n## Control API (optional)\n\nFor local integrations only, the Gateway exposes a small loopback HTTP API:\n\n* Status/start/stop: `GET /`, `POST /start`, `POST /stop`\n* Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`\n* Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`\n* Actions: `POST /navigate`, `POST /act`\n* Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`\n* Downloads: `POST /download`, `POST /wait/download`\n* Debugging: `GET /console`, `POST /pdf`\n* Debugging: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight`\n* Network: `POST /response/body`\n* State: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear`\n* State: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`\n* 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`\n\nAll endpoints accept `?profile=<name>`.\n\n### Playwright requirement\n\nSome features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require\nPlaywright. If Playwright isn’t installed, those endpoints return a clear 501\nerror. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome.\nFor the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright.\n\nIf you see `Playwright is not available in this gateway build`, install the full\nPlaywright package (not `playwright-core`) and restart the gateway, or reinstall\nOpenClaw with browser support.\n\n#### Docker Playwright install\n\nIf your Gateway runs in Docker, avoid `npx playwright` (npm override conflicts).\nUse the bundled CLI instead:",
      "language": "unknown"
    },
    {
      "code": "To persist browser downloads, set `PLAYWRIGHT_BROWSERS_PATH` (for example,\n`/home/node/.cache/ms-playwright`) and make sure `/home/node` is persisted via\n`OPENCLAW_HOME_VOLUME` or a bind mount. See [Docker](/install/docker).\n\n## How it works (internal)\n\nHigh-level flow:\n\n* A small **control server** accepts HTTP requests.\n* It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via **CDP**.\n* For advanced actions (click/type/snapshot/PDF), it uses **Playwright** on top\n  of CDP.\n* When Playwright is missing, only non-Playwright operations are available.\n\nThis design keeps the agent on a stable, deterministic interface while letting\nyou swap local/remote browsers and profiles.\n\n## CLI quick reference\n\nAll commands accept `--browser-profile <name>` to target a specific profile.\nAll commands also accept `--json` for machine-readable output (stable payloads).\n\nBasics:\n\n* `openclaw browser status`\n* `openclaw browser start`\n* `openclaw browser stop`\n* `openclaw browser tabs`\n* `openclaw browser tab`\n* `openclaw browser tab new`\n* `openclaw browser tab select 2`\n* `openclaw browser tab close 2`\n* `openclaw browser open https://example.com`\n* `openclaw browser focus abcd1234`\n* `openclaw browser close abcd1234`\n\nInspection:\n\n* `openclaw browser screenshot`\n* `openclaw browser screenshot --full-page`\n* `openclaw browser screenshot --ref 12`\n* `openclaw browser screenshot --ref e12`\n* `openclaw browser snapshot`\n* `openclaw browser snapshot --format aria --limit 200`\n* `openclaw browser snapshot --interactive --compact --depth 6`\n* `openclaw browser snapshot --efficient`\n* `openclaw browser snapshot --labels`\n* `openclaw browser snapshot --selector \"#main\" --interactive`\n* `openclaw browser snapshot --frame \"iframe#main\" --interactive`\n* `openclaw browser console --level error`\n* `openclaw browser errors --clear`\n* `openclaw browser requests --filter api --clear`\n* `openclaw browser pdf`\n* `openclaw browser responsebody \"**/api\" --max-chars 5000`\n\nActions:\n\n* `openclaw browser navigate https://example.com`\n* `openclaw browser resize 1280 720`\n* `openclaw browser click 12 --double`\n* `openclaw browser click e12 --double`\n* `openclaw browser type 23 \"hello\" --submit`\n* `openclaw browser press Enter`\n* `openclaw browser hover 44`\n* `openclaw browser scrollintoview e12`\n* `openclaw browser drag 10 11`\n* `openclaw browser select 9 OptionA OptionB`\n* `openclaw browser download e12 /tmp/report.pdf`\n* `openclaw browser waitfordownload /tmp/report.pdf`\n* `openclaw browser upload /tmp/file.pdf`\n* `openclaw browser fill --fields '[{\"ref\":\"1\",\"type\":\"text\",\"value\":\"Ada\"}]'`\n* `openclaw browser dialog --accept`\n* `openclaw browser wait --text \"Done\"`\n* `openclaw browser wait \"#main\" --url \"**/dash\" --load networkidle --fn \"window.ready===true\"`\n* `openclaw browser evaluate --fn '(el) => el.textContent' --ref 7`\n* `openclaw browser highlight e12`\n* `openclaw browser trace start`\n* `openclaw browser trace stop`\n\nState:\n\n* `openclaw browser cookies`\n* `openclaw browser cookies set session abc123 --url \"https://example.com\"`\n* `openclaw browser cookies clear`\n* `openclaw browser storage local get`\n* `openclaw browser storage local set theme dark`\n* `openclaw browser storage session clear`\n* `openclaw browser set offline on`\n* `openclaw browser set headers --json '{\"X-Debug\":\"1\"}'`\n* `openclaw browser set credentials user pass`\n* `openclaw browser set credentials --clear`\n* `openclaw browser set geo 37.7749 -122.4194 --origin \"https://example.com\"`\n* `openclaw browser set geo --clear`\n* `openclaw browser set media dark`\n* `openclaw browser set timezone America/New_York`\n* `openclaw browser set locale en-US`\n* `openclaw browser set device \"iPhone 14\"`\n\nNotes:\n\n* `upload` and `dialog` are **arming** calls; run them before the click/press\n  that triggers the chooser/dialog.\n* `upload` can also set file inputs directly via `--input-ref` or `--element`.\n* `snapshot`:\n  * `--format ai` (default when Playwright is installed): returns an AI snapshot with numeric refs (`aria-ref=\"<n>\"`).\n  * `--format aria`: returns the accessibility tree (no refs; inspection only).\n  * `--efficient` (or `--mode efficient`): compact role snapshot preset (interactive + compact + depth + lower maxChars).\n  * 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](/gateway/configuration#browser-openclaw-managed-browser)).\n  * Role snapshot options (`--interactive`, `--compact`, `--depth`, `--selector`) force a role-based snapshot with refs like `ref=e12`.\n  * `--frame \"<iframe selector>\"` scopes role snapshots to an iframe (pairs with role refs like `e12`).\n  * `--interactive` outputs a flat, easy-to-pick list of interactive elements (best for driving actions).\n  * `--labels` adds a viewport-only screenshot with overlayed ref labels (prints `MEDIA:<path>`).\n* `click`/`type`/etc require a `ref` from `snapshot` (either numeric `12` or role ref `e12`).\n  CSS selectors are intentionally not supported for actions.\n\n## Snapshots and refs\n\nOpenClaw supports two “snapshot” styles:\n\n* **AI snapshot (numeric refs)**: `openclaw browser snapshot` (default; `--format ai`)\n  * Output: a text snapshot that includes numeric refs.\n  * Actions: `openclaw browser click 12`, `openclaw browser type 23 \"hello\"`.\n  * Internally, the ref is resolved via Playwright’s `aria-ref`.\n\n* **Role snapshot (role refs like `e12`)**: `openclaw browser snapshot --interactive` (or `--compact`, `--depth`, `--selector`, `--frame`)\n  * Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).\n  * Actions: `openclaw browser click e12`, `openclaw browser highlight e12`.\n  * Internally, the ref is resolved via `getByRole(...)` (plus `nth()` for duplicates).\n  * Add `--labels` to include a viewport screenshot with overlayed `e12` labels.\n\nRef behavior:\n\n* Refs are **not stable across navigations**; if something fails, re-run `snapshot` and use a fresh ref.\n* If the role snapshot was taken with `--frame`, role refs are scoped to that iframe until the next role snapshot.\n\n## Wait power-ups\n\nYou can wait on more than just time/text:\n\n* Wait for URL (globs supported by Playwright):\n  * `openclaw browser wait --url \"**/dash\"`\n* Wait for load state:\n  * `openclaw browser wait --load networkidle`\n* Wait for a JS predicate:\n  * `openclaw browser wait --fn \"window.ready===true\"`\n* Wait for a selector to become visible:\n  * `openclaw browser wait \"#main\"`\n\nThese can be combined:",
      "language": "unknown"
    },
    {
      "code": "## Debug workflows\n\nWhen an action fails (e.g. “not visible”, “strict mode violation”, “covered”):\n\n1. `openclaw browser snapshot --interactive`\n2. Use `click <ref>` / `type <ref>` (prefer role refs in interactive mode)\n3. If it still fails: `openclaw browser highlight <ref>` to see what Playwright is targeting\n4. If the page behaves oddly:\n   * `openclaw browser errors --clear`\n   * `openclaw browser requests --filter api --clear`\n5. For deep debugging: record a trace:\n   * `openclaw browser trace start`\n   * reproduce the issue\n   * `openclaw browser trace stop` (prints `TRACE:<path>`)\n\n## JSON output\n\n`--json` is for scripting and structured tooling.\n\nExamples:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "What you get",
      "id": "what-you-get"
    },
    {
      "level": "h2",
      "text": "Quick start",
      "id": "quick-start"
    },
    {
      "level": "h2",
      "text": "Profiles: `openclaw` vs `chrome`",
      "id": "profiles:-`openclaw`-vs-`chrome`"
    },
    {
      "level": "h2",
      "text": "Configuration",
      "id": "configuration"
    },
    {
      "level": "h2",
      "text": "Use Brave (or another Chromium-based browser)",
      "id": "use-brave-(or-another-chromium-based-browser)"
    },
    {
      "level": "h2",
      "text": "Local vs remote control",
      "id": "local-vs-remote-control"
    },
    {
      "level": "h2",
      "text": "Node browser proxy (zero-config default)",
      "id": "node-browser-proxy-(zero-config-default)"
    },
    {
      "level": "h2",
      "text": "Browserless (hosted remote CDP)",
      "id": "browserless-(hosted-remote-cdp)"
    },
    {
      "level": "h2",
      "text": "Security",
      "id": "security"
    },
    {
      "level": "h2",
      "text": "Profiles (multi-browser)",
      "id": "profiles-(multi-browser)"
    },
    {
      "level": "h2",
      "text": "Chrome extension relay (use your existing Chrome)",
      "id": "chrome-extension-relay-(use-your-existing-chrome)"
    },
    {
      "level": "h3",
      "text": "Sandboxed sessions",
      "id": "sandboxed-sessions"
    },
    {
      "level": "h3",
      "text": "Setup",
      "id": "setup"
    },
    {
      "level": "h2",
      "text": "Isolation guarantees",
      "id": "isolation-guarantees"
    },
    {
      "level": "h2",
      "text": "Browser selection",
      "id": "browser-selection"
    },
    {
      "level": "h2",
      "text": "Control API (optional)",
      "id": "control-api-(optional)"
    },
    {
      "level": "h3",
      "text": "Playwright requirement",
      "id": "playwright-requirement"
    },
    {
      "level": "h2",
      "text": "How it works (internal)",
      "id": "how-it-works-(internal)"
    },
    {
      "level": "h2",
      "text": "CLI quick reference",
      "id": "cli-quick-reference"
    },
    {
      "level": "h2",
      "text": "Snapshots and refs",
      "id": "snapshots-and-refs"
    },
    {
      "level": "h2",
      "text": "Wait power-ups",
      "id": "wait-power-ups"
    },
    {
      "level": "h2",
      "text": "Debug workflows",
      "id": "debug-workflows"
    },
    {
      "level": "h2",
      "text": "JSON output",
      "id": "json-output"
    },
    {
      "level": "h2",
      "text": "State and environment knobs",
      "id": "state-and-environment-knobs"
    },
    {
      "level": "h2",
      "text": "Security & privacy",
      "id": "security-&-privacy"
    },
    {
      "level": "h2",
      "text": "Troubleshooting",
      "id": "troubleshooting"
    },
    {
      "level": "h2",
      "text": "Agent tools + how control works",
      "id": "agent-tools-+-how-control-works"
    }
  ],
  "url": "llms-txt#browser-(openclaw-managed)",
  "links": []
}