Browser

text

Copy

openclaw browser

Manage OpenClaw's browser control surface and run browser actions (lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging).

Related:

• Browser tool + API: Browser tool

Common flags

• text

  Copy

  --url <gatewayWsUrl>
  : Gateway WebSocket URL (defaults to config).
• text

  Copy

  --token <token>
  : Gateway token (if required).
• text

  Copy

  --timeout <ms>
  : request timeout (ms).
• text

  Copy

  --expect-final
  : wait for a final Gateway response.
• text

  Copy

  --browser-profile <name>
  : choose a browser profile (default from config).
• text

  Copy

  --json
  : machine-readable output (where supported).

Quick start (local)

bash
Copy
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 run the same readiness check with

.

Quick troubleshooting

If

fails with , troubleshoot CDP readiness first. If and succeed but or fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.

Minimal sequence:

bash
Copy
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

Detailed guidance: Browser troubleshooting

Lifecycle

bash
Copy
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

Notes:

• text

  Copy

  doctor --deep
  adds a live snapshot probe. It is useful when basic CDP readiness is green but you want proof that the current tab can be inspected.
• For
  text

  Copy

  attachOnly
  and remote CDP profiles,
  text

  Copy

  openclaw browser stop
  closes the active control session and clears temporary emulation overrides even when OpenClaw did not launch the browser process itself.
• For local managed profiles,
  text

  Copy

  openclaw browser stop
  stops the spawned browser process.
• text

  Copy

  openclaw browser start --headless
  applies only to that start request and only when OpenClaw launches a local managed browser. It does not rewrite
  text

  Copy

  browser.headless
  or profile config, and it is a no-op for an already-running browser.
• On Linux hosts without
  text

  Copy

  DISPLAY
  or
  text

  Copy

  WAYLAND_DISPLAY
  , local managed profiles run headless automatically unless
  text

  Copy

  OPENCLAW_BROWSER_HEADLESS=0
  ,
  text

  Copy

  browser.headless=false
  , or
  text

  Copy

  browser.profiles.<name>.headless=false
  explicitly requests a visible browser.

If the command is missing

If

is an unknown command, check in .

When

is present, list the bundled browser plugin explicitly unless the config already has a root block:

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

An explicit root

block, for example or , also activates the bundled browser plugin under a restrictive plugin allowlist.

Related: Browser tool

Profiles

Profiles are named browser routing configs. In practice:

• text

  Copy

  openclaw
  : launches or attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
• text

  Copy

  user
  : controls your existing signed-in Chrome session via Chrome DevTools MCP.
• custom CDP profiles: point at a local or remote CDP endpoint.

bash
Copy
openclaw browser profiles
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

Use a specific profile:

bash
Copy
openclaw browser --browser-profile work tabs

Tabs

bash
Copy
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

returns first, then the stable such as , the optional label, and the raw . Agents should pass back into , , snapshots, and actions. You can assign a label with , , or ; labels, tab ids, raw target ids, and unique target-id prefixes are all accepted. When Chromium replaces the underlying raw target during a navigation or form submit, OpenClaw keeps the stable /label attached to the replacement tab when it can prove the match. Raw target ids remain volatile; prefer .

Snapshot / screenshot / actions

Snapshot:

bash
Copy
openclaw browser snapshot
openclaw browser snapshot --urls

Screenshot:

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

Notes:

• text

  Copy

  --full-page
  is for page captures only; it cannot be combined with
  text

  Copy

  --ref
  or
  text

  Copy

  --element
  .
• text

  Copy

  existing-session
  /
  text

  Copy

  user
  profiles support page screenshots and
  text

  Copy

  --ref
  screenshots from snapshot output, but not CSS
  text

  Copy

  --element
  screenshots.
• text

  Copy

  --labels
  overlays current snapshot refs on the screenshot.
• text

  Copy

  snapshot --urls
  appends discovered link destinations to AI snapshots so agents can choose direct navigation targets instead of guessing from link text alone.

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

bash
Copy
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>

Action responses return the current raw

after action-triggered page replacement when OpenClaw can prove the replacement tab. Scripts should still store and pass /labels for long-lived workflows.

File + dialog helpers:

bash
Copy
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept

Managed Chrome profiles save ordinary click-triggered downloads into the OpenClaw downloads directory (

by default, or the configured temp root). Use or when the agent needs to wait for a specific file and return its path; those explicit waiters own the next download.

State and storage

Viewport + emulation:

bash
Copy
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

Cookies + storage:

bash
Copy
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

bash
Copy
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

Use the built-in

profile, or create your own profile:

bash
Copy
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 --browser-profile chrome-live tabs

This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.

Current existing-session limits:

• snapshot-driven actions use refs, not CSS selectors
• text

  Copy

  browser.actionTimeoutMs
  defaults supported
  text

  Copy

  act
  requests to 60000 ms when callers omit
  text

  Copy

  timeoutMs
  ; per-call
  text

  Copy

  timeoutMs
  still wins.
• text

  Copy

  click
  is left-click only
• text

  Copy

  type
  does not support
  text

  Copy

  slowly=true
• text

  Copy

  press
  does not support
  text

  Copy

  delayMs
• text

  Copy

  hover
  ,
  text

  Copy

  scrollintoview
  ,
  text

  Copy

  drag
  ,
  text

  Copy

  select
  ,
  text

  Copy

  fill
  , and
  text

  Copy

  evaluate
  reject per-call timeout overrides
• text

  Copy

  select
  supports one value only
• text

  Copy

  wait --load networkidle
  is not supported
• file uploads require
  text

  Copy

  --ref
  /
  text

  Copy

  --input-ref
  , do not support CSS
  text

  Copy

  --element
  , and currently support one file at a time
• dialog hooks do not support
  text

  Copy

  --timeout
• screenshots support page captures and
  text

  Copy

  --ref
  , but not CSS
  text

  Copy

  --element
• text

  Copy

  responsebody
  , download interception, PDF export, and batch actions still require a managed browser or raw CDP profile

Remote browser control (node host proxy)

If the Gateway runs on a different machine than the browser, run a node host on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).

Use

to control auto-routing and to pin a specific node if multiple are connected.

Security + remote setup: Browser tool, Remote access, Tailscale, Security

Related

• CLI reference
• Browser