Complete reference for all openclaw browser commands, profile management, tab control, page inspection, UI interaction, and environment emulation.
What is the Browser Command Surface?
openclaw browser is a CLI-driven browser automation layer that routes commands through the OpenClaw Gateway to a controlled Chrome instance. It supports two modes: the openclaw profile, which launches an isolated managed Chrome process, and the chrome profile, which connects to your existing browser via an extension relay.
This makes it suitable for both headless CI pipelines and interactive developer workflows where you want the agent to control a browser session you can actually see.
How to Navigate this Reference
If you just need to wire up or swap profiles, start with Profile Management. For driving a live page, clicking, typing, filling forms, go to Action Commands, but read the snapshot entry in Inspection first since most actions require a <ref> ID you can only get from a snapshot. For emulating specific devices, locales, or network conditions, State & Environment has everything. The Common Flags apply globally and are not repeated on individual commands.
Common Flags
These flags can be appended to most openclaw browser commands. They control gateway targeting, auth, and output format.
| Flag | Description |
|---|---|
--url <gatewayWsUrl> | Gateway WebSocket URL. Defaults to the value in your config file. |
--token <token> | Gateway authentication token, if required by your Gateway setup. |
--timeout <ms> | Request timeout in milliseconds. Useful for slow pages or high-latency remote Gateways. |
--browser-profile <name> | Choose a specific browser profile, e.g. openclaw or chrome. Overrides the default profile for that command only. |
| –json | Outputs the result in machine-readable JSON format. Pipe this into scripts or other CLI tools. |
Profile Management
Profiles are named browser routing configurations. Picking the right profile determines whether commands hit an isolated managed Chrome instance or your existing browser via the extension relay.
| openclaw Isolated managed Chrome instance. OpenClaw owns the browser lifecycle, starts, stops, and manages state. Best for automation, testing, and agent workflows where you want a clean, repeatable environment. | chrome Existing browser via extension relay. Controls the browser you already have open. Useful for interactive debugging, or when you want the agent to act on a session with existing login state. |
| profiles List all browser profiles with their current status. | create-profile –name <name> Create a new profile. –color | –cdp-url |
| delete-profile –name <name> Delete a named profile and its associated configuration. | reset-profile Reset the state of the current profile back to defaults. Does not delete the profile. |
Basic Management & Tabs
Service lifecycle and tab management. These are your first commands when setting up or debugging a browser session.
| status Check the current status of the browser service and its connection state. | start / stop Manually start or stop the browser server. Useful when the managed instance needs a hard restart. |
| tabs List all currently open tabs with their index and target ID. | tab new Open a new blank tab in the current browser session. |
| tab select <n> Bring a tab to the foreground by its index number from tabs output. | tab close <n> Close a tab by its index number. |
| open <url> Open a specific URL in the current tab. | focus <targetId> Focus a specific tab by its target ID (from tabs output). |
| close [targetId] Close a specific tab by target ID. Omitting the ID closes the active tab. |
Inspection Commands
Read the current state of the page, DOM structure, pixels, network traffic, console output. Run snapshot before any action command; it’s where <ref> IDs come from.
| snapshot Capture a stable UI tree for the agent. The output contains <ref> IDs required by all action commands. Run this first before clicking, typing, or interacting with anything. –format ai | –format aria | –interactive | –compact | –efficient | screenshot Capture the viewport as pixels. Use –full-page for the entire scrollable page. –full-page | –ref <ref> | –element <selector> |
| pdf Print the current page to a PDF file using the browser’s built-in renderer. | console View browser console logs. Filter by level to reduce noise. –level error | –level warn | –level info |
| errors –clear View current page errors. Pass –clear to flush the error buffer after viewing. | requests –filter api –clear View or clear captured network requests. Use –filter api to scope to XHR/fetch calls only. |
| responsebody “**/api” –max-chars 5000 Extract the response body of specific network requests by URL glob pattern. Limit output size with –max-chars. |
snapshot defaults to –format ai which is optimised for agent consumption. Use –format aria if you need an accessibility-tree representation instead. The –compact and –efficient presets reduce output size for large pages.
Action Commands
Commands that interact with the page. Most require a <ref> ID, run snapshot first to get current element references.
<ref> IDs are snapshot-scoped and become stale after navigation or DOM changes. Re-run snapshot any time the page state changes before issuing new action commands.
| navigate <url> Navigate the current tab to a URL and wait for page load. | click <ref> Click an element by its ref ID. –double | –button <left|right|middle> | –modifiers |
| type <ref> <text> Type text into a focused element. –submit | –slowly | press <key> Press a specific keyboard key, e.g. Enter, Escape, Tab. |
| hover <ref> Move the cursor over an element to trigger hover states without clicking. | drag <startRef> <endRef> Drag one element to another. Both arguments are ref IDs from snapshot. |
| select <ref> <values> Select one or more options in a <select> dropdown by value. | upload <paths> Upload a file. You must arm this command before triggering the file chooser dialog, not after. |
| fill –fields ‘[{“ref”:”1″,”type”:”text”,”value”:”Ada”}]’ Fill multiple form fields at once using a JSON array. More efficient than sequential type calls when populating multi-field forms. | dialog –accept|–dismiss Arm the browser to automatically accept or dismiss the next JS dialog (alert, confirm, prompt). Call before the action that triggers the dialog. |
| wait Wait for specific conditions before proceeding. –time <ms> | –text <value> | –url | –fn | evaluate –fn <code> Execute arbitrary JavaScript in the page context. Returns the expression result. Use carefully, there’s no sandbox. |
Both upload and dialog are arm-then-trigger commands, issue the command first to register the handler, then perform the browser action that fires the dialog or file chooser. Reversing the order will miss the event.
State & Environment Control
Manipulate the browser’s persistent state and emulate different environments, network conditions, device types, geolocation, locale, and more.
| Command | Description |
|---|---|
| cookies | List all cookies. Use cookies set to add one, or cookies clear to remove them. |
storage local get|set|clear | Read, write, or clear localStorage values for the current origin. |
| storage session clear | Clear sessionStorage for the current origin. |
set offline on|off | Toggle network disconnection emulation. Useful for testing offline-first behavior and service worker fallbacks. |
set headers --headers-json <json> | Inject custom HTTP headers into all subsequent requests from this session. |
set credentials <user> <pass> | Set HTTP basic authentication credentials. Use –clear to remove them. |
set geo <lat> <lon> | Emulate a specific geolocation. Overrides the real browser location for Geolocation API calls. |
set media <dark|light> | Emulate prefers-color-scheme. Triggers CSS media query changes immediately. |
set timezone <tz> | Emulate a specific IANA timezone (e.g. America/New_York). |
set locale <loc> | Emulate a specific locale (e.g. fr-FR). Affects Intl formatting and navigator.language. |
set device "<name>" | Emulate a specific mobile device viewport, user-agent, and DPR, e.g. set device "iPhone 14". Applies all device descriptors at once. |
State overrides like set offline, set headers, and set geo persist for the life of the session. They are not automatically cleared between page navigations. Call the corresponding clear/off variant explicitly when done, or use reset-profile to wipe all overrides at once.
