OpenClaw Browser CLI Reference

`openclaw browser`

The browser control surface in OpenClaw handles lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging. Use it to manage and execute browser actions.

Common flags

--url <gatewayWsUrl>: Gateway WebSocket URL, falls back to config.
--token <token>: Gateway token, only when required.
--timeout <ms>: request timeout in milliseconds, defaults to 30000.
--expect-final: wait for the final Gateway response.
--browser-profile <name>: pick a browser profile, defaults to openclaw or browser.defaultProfile.
--json: machine-readable output where supported. Since this is a browser-level option, place it before the subcommand for clarity, for instance openclaw browser --json status. Placing it after, like openclaw browser status --json, also works if the child command does not define its own --json.

Quick start (local)

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

Agents can verify readiness the same way with browser({ action: "doctor" }).

Quick troubleshooting

When start returns not reachable after start, start by checking CDP readiness. If start and tabs pass but open or navigate fails, the browser control plane is operational and the issue is typically a navigation SSRF policy block.

A minimal sequence:

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

For details: Browser troubleshooting

Lifecycle

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile

doctor --deep adds a live snapshot probe, useful when basic CDP readiness passes but you want confirmation that the current tab is inspectable.
On a running local managed profile, status and doctor pull cached graphics diagnostics from Chrome: hardware or software classification, renderer, backend, device and driver, feature and disabled-status details, plus accelerated video capabilities. openclaw browser --json status gives the complete structured payload. Passive status never starts Chrome just to gather this data.
stop ends the active control session and clears temporary emulation overrides, including for attachOnly and remote CDP profiles where OpenClaw did not start the browser process. For local managed profiles, stop also terminates the spawned browser process.
start --headless affects only that start request, and only when OpenClaw starts a local managed browser. It does not modify browser.headless or profile config, and does nothing for an already-running browser.
On Linux hosts lacking DISPLAY or WAYLAND_DISPLAY, local managed profiles run headless by default unless OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false, or browser.profiles.<name>.headless=false explicitly asks for a visible browser.

If the command is missing

If openclaw browser is unrecognized, look at plugins.allow in ~/.openclaw/openclaw.json. When plugins.allow exists, list the bundled browser plugin explicitly unless the config already has a root browser block:

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

An explicit root browser block, such as browser.enabled=true or browser.profiles.<name>, also enables the bundled browser plugin under a restrictive plugin allowlist.

Profiles

Profiles are named browser routing configurations:

openclaw (default): starts or connects to a dedicated OpenClaw-managed Chrome instance with an isolated user data directory.
user: drives your existing signed-in Chrome session through Chrome DevTools MCP.
custom CDP profiles: target a local or remote CDP endpoint.

openclaw browser profiles
openclaw browser system-profiles
openclaw browser system-profiles --browser brave
openclaw browser import-profile --browser chrome --system Default --into imported
openclaw browser import-profile --system "Profile 1" --into work --domains google.com,youtube.com
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work

Apply a specific profile with --browser-profile <name> on any subcommand, for example openclaw browser --browser-profile work tabs.

On macOS, system-profiles enumerates the real Chrome, Brave, Edge, or Chromium profiles present on the machine. After a single macOS Keychain/Touch ID approval prompt, import-profile decrypts their cookies and loads them into a new OpenClaw-managed profile. Only cookies get imported; local storage and IndexedDB remain untouched. Certain Google sessions rely on device-bound session credentials (DBSC), so re-authentication may still be needed following the import.

When the macOS app runs against a local Gateway, it can present this import option once and set the isolated imported profile as the default for agent browsing. Every import needs an explicit click; a successful import or a dismissal silences later automatic prompts, and Settings → General → Browser login stays available for importing again.

System-profile import is on by default. To turn off both CLI and agent-triggered imports, set browser.allowSystemProfileImport=false. The import only works on the local host and cannot go through the browser node proxy.

import-profile addresses a managed profile on the same machine. If your OpenClaw Gateway and agent browser live on a different computer, use cookie-sync to decrypt cookies on this Mac and send them into a managed profile on that remote Gateway via the operator connection:

openclaw browser cookie-sync --domains github.com,news.ycombinator.com --into work
openclaw browser --url wss://gateway.example.com cookie-sync --domains github.com --into work --watch

--domains is mandatory. Cookie sync transfers live session cookies, so an unrestricted cookie jar is never sent; a missing or empty allowlist triggers a hard error.
--into chooses the target managed profile on the Gateway (default imported); --gateway/--url picks a remote Gateway (default is the configured/local one).
--watch keeps the process alive and re-pushes whenever the source Cookies database changes. The macOS Keychain secret is read once per watch session, so you approve a single consent prompt instead of one per change.
Decryption happens only on the local host (macOS only) and shares the allowlist and Keychain path with import-profile. Cookies are decrypted on this Mac and transmitted over the existing TLS-pinned Gateway connection; no cookie values are ever displayed.
Some Google sessions use device-bound session credentials (DBSC) that remain attached to this Mac and can still demand re-authentication after sync. For those sites, prefer driving the browser on the Mac itself through the browser node proxy.

The macOS app offers the same feature under Settings → General → Cookie sync: a toggle that defaults to off, an editable domain allowlist, and a target-profile field. In remote mode, when enabled, it supervises cookie-sync --watch for you against the connected Gateway and shows a live status row.

Chrome extension relay

openclaw browser extension path
openclaw browser extension install
openclaw browser extension install --json --wait-ms 60000
openclaw browser extension status
openclaw browser extension status --json
openclaw browser extension uninstall-host
openclaw browser extension pair
openclaw browser extension pair --gateway-url wss://gateway.example.com
openclaw browser extension cdp
openclaw browser extension cdp --json

extension install pre-registers the origin-locked native bootstrap host in existing Chrome-family user-data roots. Run it first, then add OpenClaw from the Chrome Web Store. The stable Load unpacked path stays available as a development fallback.
extension status reports Store discovery separately from approved unpacked IDs and paths, plus owned-registration health and whether manual setup is required. JSON output never includes a pairing string or relay key.
extension uninstall-host removes only verified OpenClaw-owned native-host manifests and launchers. The Chrome extension itself is left in place.
extension path is read-only. It prints the stable installed copy when present and the bundled source directory otherwise.
extension pair remains the advanced manual flow. --gateway-url creates a direct remote-Gateway pairing URL; non-loopback URLs must use wss://.
extension cdp prints non-secret Browser Relay Authentication v2 metadata: the loopback browser/CDP endpoints, protocol version, key ID, and fixed challenge/complete binding. It never prints the relay key or an authorization header by default.

Automatic local bootstrap connects through the local Gateway's exact /browser/extension route so the first authenticated extension connection starts the lazy browser-control service. Keep openclaw gateway run or the managed Gateway service running; no separate browser request or prewarm is needed. Local OpenClaw and mcporter calls still use the profile relay port reported by extension pair or extension cdp after that wakeup. Browser-node pairings continue to use the relay on the browser-node host, while explicit --gateway-url pairings remain direct-remote and manual-only.

The advanced manual extension pair command without --gateway-url retains the host-local /extension relay URL. With the native host installed, Automatic local setup enabled, and an extension build that supports relay wake-up, reconnecting can start a standalone relay on the saved pairing's configured port. This does not start Gateway browser control: authenticated CDP clients can use the standalone relay without a Gateway, but openclaw browser actions still require one. For source-checkout testing, load the managed unpacked copy from the same OpenClaw installation.

extension cdp --legacy-bearer is a temporary migration escape hatch. It prints the old Bearer header with a warning only while browser.extensionRelay.allowLegacyAuth=true; otherwise it exits with an error without printing a credential. Use --json for machine output; warnings remain on stderr so stdout stays valid JSON.

Setup, security model, and recovery steps: Chrome extension.

If the extension already attempted automatic setup before the native host existed, Chromium retains that miss for the running browser process. Restart Chrome once, run extension install, then reopen the Store extension; popup retries alone cannot recover that existing process.

Tabs

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw browser close t1

tabs returns suggestedTargetId first, then the stable tabId (such as t1), the optional label, and the raw targetId. Pass suggestedTargetId back into focus, close, snapshots, and actions. Assign a label with open --label, tab new --label, or tab label; labels, tab ids, raw target ids, and unique target-id prefixes are all accepted. The request field is still named targetId for compatibility, but it accepts any of these tab references.

Raw target ids are volatile diagnostic handles, not durable agent memory: when Chromium replaces the underlying raw target during a navigation or form submit, OpenClaw keeps the stable tabId/label attached to the replacement tab when it can prove the match. Prefer suggestedTargetId.

Snapshot / screenshot / actions

Snapshot:

openclaw browser snapshot
openclaw browser snapshot --urls

Screenshot:

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels

--full-page handles page captures exclusively, so combining it with --ref or --element is not possible.
Page screenshots and --ref captures from snapshot output are supported by existing-session / user profiles, but CSS --element screenshots are not available there.
Current snapshot refs are overlaid on the screenshot by --labels. For Playwright-backed profiles, this works with --full-page (full-page overlay), --ref (element-clip overlay by ARIA ref), and --element (element-clip overlay by CSS selector); in element-clip modes, labels are projected relative to the element. The response also carries an annotations array (omitted when empty) containing each ref's bounding box: ref, number, role, optional name, and box: {x, y, width, height} in the captured image's coordinate space (viewport / fullpage / element-relative). A chrome-mcp overlay is rendered on page screenshots by existing-session profiles, but the Playwright projection helper is not used and annotations is not included; CSS --element screenshots are unsupported there. Labeled screenshots are unavailable without Playwright or chrome-mcp.
Discovered link destinations are appended to AI snapshots by snapshot --urls, letting agents pick direct navigation targets rather than inferring from link text alone.

Navigate/click/type (ref-based UI automation):

openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
openclaw browser evaluate --fn 'const title = document.title; return title;'
openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

Named keys and shortcuts like Escape, Control+Shift+T, and Control++ are accepted by press; common aliases for Esc, Return, Del, Ctrl, and Cmd are normalized.

For managed browser profiles, option values are preserved exactly by select. Quote empty or whitespace-sensitive values, such as openclaw browser select <ref> "" or openclaw browser select <ref> " padded ".

A function source, an expression, or a statement body is accepted by evaluate --fn. Statement bodies are wrapped as async functions, so use return for the value you want back. Use --timeout-ms when the page-side function may need longer than the default evaluate timeout. Both evaluate and wait --fn are disabled by browser.evaluateEnabled=false (default: true).

After action-triggered page replacement, action responses return the current raw targetId when OpenClaw can prove the replacement tab. For long-lived workflows, scripts should still store and pass suggestedTargetId/labels.

File + dialog helpers:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser upload media://inbound/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw browser dialog --dismiss --dialog-id d1

Ordinary click-triggered downloads from managed Chrome profiles are saved into the OpenClaw downloads directory (/tmp/openclaw/downloads by default, or the configured temp root). Use waitfordownload or download when the agent needs to wait for a specific file and return its path; those explicit waiters own the next download. Uploads accept files from the OpenClaw temp uploads root and OpenClaw-managed inbound media, including media://inbound/<id> and sandbox-relative media/inbound/<id> references. Nested media refs, traversal, and arbitrary local paths are rejected.

If saving a download fails, OpenClaw requests cancellation of the transfer and reports the original save error. Correct the output path or filesystem problem before starting a new download.

When an action opens a modal dialog, the action response returns blockedByDialog with browserState.dialogs.pending; pass --dialog-id to answer it directly. Dialogs handled outside OpenClaw appear under browserState.dialogs.recent.

Batch actions:

openclaw browser batch --actions '[{"kind":"wait","timeMs":500},{"kind":"click","ref":"12"},{"kind":"type","ref":"23","text":"hello"}]'
openclaw browser batch --actions-file plan.json
openclaw browser batch --actions-file - --continue

openclaw browser batch issues a kind="batch" /act request containing nested BrowserActRequest actions (wait, click, type, evaluate, ...), unlike open/navigate/snapshot/screenshot, which are CLI subcommands rather than /act types. With --continue, the stopOnError=false option is set (default behavior halts at the first error); --target-id limits the entire batch to a single tab. If a nested action fails, the command exits with a nonzero status; to keep the ordered results response, apply --json. For the complete contract covering ref lifecycle, target id conflicts, and error summaries, refer to Browser batch CLI. On profile="user" or existing-session profiles, batch is unavailable.

For stdin input via --actions-file and --actions-file -, the cap is 1,000,000 bytes. When plans exceed this, break them into multiple openclaw browser batch commands.

State and storage

Viewport and emulation settings:

openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass

Cookie and storage handling:

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 token abc123
openclaw browser storage session clear

Debugging

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

Existing Chrome via MCP

Either rely on the bundled user profile or define a custom existing-session one:

openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222
openclaw browser --browser-profile chrome-live tabs

By default, the existing-session path uses host-only Chrome MCP auto-connect. If a browser is already active with a DevTools endpoint, supply --cdp-url so Chrome MCP connects to that endpoint. For Docker, Browserless, or other remote scenarios where Chrome MCP semantics are unnecessary, opt for a CDP profile.

Current limitations for existing sessions:

Actions driven by snapshots rely on refs, not CSS selectors.
Supported act requests default to 60000 ms when timeoutMs is not provided; a per-call timeoutMs takes precedence.
Only left-click is available for click.
type lacks support for slowly=true.
press cannot handle delayMs.
Per-call timeout overrides are rejected by hover, scrollintoview, drag, select, and fill; evaluate does accept --timeout-ms.
select accepts a single value.
wait --load networkidle is unsupported (it functions on managed and raw/remote CDP profiles).
File uploads depend on --ref / --input-ref, exclude CSS --element, and handle one file per operation.
Dialog hooks do not accommodate --timeout.
Screenshots cover page captures and --ref, but not CSS --element.
Managed browsers or raw CDP profiles are still necessary for responsebody, download interception, PDF export, and batch actions.

Remote browser control (node host proxy)

When the Gateway and browser reside on separate machines, deploy a node host on the machine holding Chrome/Brave/Edge/Chromium. Browser actions are proxied by the Gateway to that node, eliminating the need for a dedicated browser control server.

To manage automatic routing, apply gateway.nodes.browser.mode, and if several nodes are linked, gateway.nodes.browser.node lets you lock onto one.

For security and remote configuration: Browser tool, Remote access, Tailscale, Security