openclaw/docs/cli/browser.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw browser` (lifecycle, profiles, tabs, actions, state, and debugging)	You use `openclaw browser` and want examples for common tasks You want to control a browser running on another machine via a node host You want to attach to your local signed-in Chrome via Chrome MCP	browser

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

• --url <gatewayWsUrl>: Gateway WebSocket URL (defaults to config).
• --token <token>: Gateway token (if required).
• --timeout <ms>: request timeout (ms).
• --expect-final: wait for a final Gateway response.
• --browser-profile <name>: choose a browser profile (default from config).
• --json: machine-readable output (where supported).

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

Quick troubleshooting

If start fails with not reachable after start, troubleshoot CDP readiness first. If start and tabs succeed but open or navigate fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.

Minimal sequence:

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

openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile

Notes:

• For attachOnly and remote CDP profiles, 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, openclaw browser stop stops the spawned browser process.

If the command is missing

If openclaw browser is an unknown command, check plugins.allow in ~/.openclaw/openclaw.json.

When plugins.allow is present, the bundled browser plugin must be listed explicitly:

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

browser.enabled=true does not restore the CLI subcommand when the plugin allowlist excludes browser.

Related: Browser tool

Profiles

Profiles are named browser routing configs. In practice:

• openclaw: launches or attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
• user: controls your existing signed-in Chrome session via Chrome DevTools MCP.
• custom CDP profiles: point at a local or remote CDP endpoint.

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:

openclaw browser --browser-profile work tabs

Tabs

openclaw browser tabs
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>

Snapshot / screenshot / actions

Snapshot:

openclaw browser snapshot

Screenshot:

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

Notes:

• --full-page is for page captures only; it cannot be combined with --ref or --element.
• existing-session / user profiles support page screenshots and --ref screenshots from snapshot output, but not CSS --element screenshots.

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

openclaw browser navigate https://example.com
openclaw browser click <ref>
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>

File + dialog helpers:

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

State and storage

Viewport + emulation:

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:

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

Use the built-in user profile, or create your own existing-session profile:

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
• click is left-click only
• type does not support slowly=true
• press does not support delayMs
• hover, scrollintoview, drag, select, fill, and evaluate reject per-call timeout overrides
• select supports one value only
• wait --load networkidle is not supported
• file uploads require --ref / --input-ref, do not support CSS --element, and currently support one file at a time
• dialog hooks do not support --timeout
• screenshots support page captures and --ref, but not CSS --element
• 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 gateway.nodes.browser.mode to control auto-routing and gateway.nodes.browser.node to pin a specific node if multiple are connected.

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