| --- |
| summary: "Integrated browser control service + action commands" |
| read_when: |
| - Adding agent-controlled browser automation |
| - Debugging why openclaw is interfering with your own Chrome |
| - Implementing browser settings + lifecycle in the macOS app |
| --- |
| |
| # 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. |
|
|
| ## 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`, ...). |
|
|
| This browser is **not** your daily driver. It is a safe, isolated surface for |
| agent automation and verification. |
|
|
| ## Quick start |
|
|
| ```bash |
| 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. |
|
|
| ## Profiles: `openclaw` vs `chrome` |
|
|
| - `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. |
|
|
| ## Configuration |
|
|
| Browser settings live in `~/.openclaw/openclaw.json`. |
|
|
| ```json5 |
| { |
| 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. |
|
|
| ## Use Brave (or another Chromium-based browser) |
|
|
| 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: |
|
|
| ```bash |
| openclaw config set browser.executablePath "/usr/bin/google-chrome" |
| ``` |
|
|
| ```json5 |
| // 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. |
|
|
| Remote CDP URLs can include auth: |
|
|
| - Query tokens (e.g., `https://provider.example?token=<token>`) |
| - HTTP Basic auth (e.g., `https://user:pass@provider.example`) |
|
|
| 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. |
|
|
| ## 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 `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 (hosted remote CDP) |
|
|
| [Browserless](https://browserless.io) 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: |
|
|
| ```json5 |
| { |
| 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). |
|
|
| ## Security |
|
|
| 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. |
|
|
| ## 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) |
| - **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`. |
|
|
| ## Chrome extension relay (use your existing Chrome) |
|
|
| 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](/tools/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. |
|
|
| ### Sandboxed sessions |
|
|
| 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. |
|
|
| ### Setup |
|
|
| 1. Load the extension (dev/unpacked): |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| 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. |
|
|
| ## 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 |
|
|
| When launching locally, OpenClaw picks the first available: |
|
|
| 1. Chrome |
| 2. Brave |
| 3. Edge |
| 4. Chromium |
| 5. Chrome Canary |
|
|
| You can override with `browser.executablePath`. |
|
|
| Platforms: |
|
|
| - macOS: checks `/Applications` and `~/Applications`. |
| - Linux: looks for `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc. |
| - Windows: checks common install locations. |
|
|
| ## Control API (optional) |
|
|
| For local integrations only, the Gateway exposes a small loopback HTTP API: |
|
|
| - 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` |
|
|
| All endpoints accept `?profile=<name>`. |
|
|
| ### Playwright requirement |
|
|
| Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require |
| Playwright. If Playwright isn’t installed, those endpoints return a clear 501 |
| error. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome. |
| For the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright. |
|
|
| If you see `Playwright is not available in this gateway build`, install the full |
| Playwright package (not `playwright-core`) and restart the gateway, or reinstall |
| OpenClaw with browser support. |
|
|
| ## How it works (internal) |
|
|
| High-level flow: |
|
|
| - 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. |
|
|
| This design keeps the agent on a stable, deterministic interface while letting |
| you swap local/remote browsers and profiles. |
|
|
| ## CLI quick reference |
|
|
| All commands accept `--browser-profile <name>` to target a specific profile. |
| All commands also accept `--json` for machine-readable output (stable payloads). |
|
|
| Basics: |
|
|
| - `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` |
|
|
| Inspection: |
|
|
| - `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` |
|
|
| Actions: |
|
|
| - `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 /tmp/report.pdf` |
| - `openclaw browser waitfordownload /tmp/report.pdf` |
| - `openclaw browser upload /tmp/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` |
|
|
| State: |
|
|
| - `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 --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"` |
|
|
| Notes: |
|
|
| - `upload` and `dialog` are **arming** calls; run them before the click/press |
| that triggers the chooser/dialog. |
| - `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](/gateway/configuration#browser-openclaw-managed-browser)). |
| - 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 |
|
|
| OpenClaw supports two “snapshot” styles: |
|
|
| - **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. |
|
|
| Ref behavior: |
|
|
| - 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 |
|
|
| You can wait on more than just time/text: |
|
|
| - 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"` |
|
|
| These can be combined: |
|
|
| ```bash |
| openclaw browser wait "#main" \ |
| --url "**/dash" \ |
| --load networkidle \ |
| --fn "window.ready===true" \ |
| --timeout-ms 15000 |
| ``` |
|
|
| ## Debug workflows |
|
|
| When an action fails (e.g. “not visible”, “strict mode violation”, “covered”): |
|
|
| 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 |
|
|
| `--json` is for scripting and structured tooling. |
|
|
| Examples: |
|
|
| ```bash |
| openclaw browser status --json |
| openclaw browser snapshot --interactive --json |
| openclaw browser requests --filter api --json |
| openclaw browser cookies --json |
| ``` |
|
|
| Role snapshots in JSON include `refs` plus a small `stats` block (lines/chars/refs/interactive) so tools can reason about payload size and density. |
|
|
| ## State and environment knobs |
|
|
| These are useful for “make the site behave like X” workflows: |
|
|
| - Cookies: `cookies`, `cookies set`, `cookies clear` |
| - Storage: `storage local|session get|set|clear` |
| - Offline: `set offline on|off` |
| - Headers: `set headers --json '{"X-Debug":"1"}'` (or `--clear`) |
| - 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](/tools/browser-login). |
| - Keep the Gateway/node host private (loopback or tailnet-only). |
| - Remote CDP endpoints are powerful; tunnel and protect them. |
|
|
| ## Troubleshooting |
|
|
| For Linux-specific issues (especially snap Chromium), see |
| [Browser troubleshooting](/tools/browser-linux-troubleshooting). |
|
|
| ## Agent tools + how control works |
|
|
| The agent gets **one tool** for browser automation: |
|
|
| - `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act |
|
|
| How it maps: |
|
|
| - `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"`. |
|
|
| This keeps the agent deterministic and avoids brittle selectors. |
|
|
