Tools & Automation15 min readIntermediate

Browser Control

OpenClaw can run a dedicated Chrome/Brave/Edge/Chromium profile that the AI agent controls for safe web automation

What You'll Learn

  • Core concepts of OpenClaw browser control and isolation mechanisms
  • How to configure openclaw and chrome browser profiles
  • Using CLI commands for browser automation
  • How local vs remote control works
  • Chrome extension relay mode setup and usage
  • Snapshot and Refs system for element identification
  • Security best practices and privacy protection

Table of Contents

What is Browser Control

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's a safe, isolated surface for agent automation and verification

Quick Start

Get started with browser control using these commands:

Check browser status

openclaw browser --browser-profile openclaw status

Start browser

openclaw browser --browser-profile openclaw start

Open webpage

openclaw browser --browser-profile openclaw open https://example.com

Get page snapshot

openclaw browser --browser-profile openclaw snapshot

If you get "Browser disabled", enable it in config (see below) and restart the Gateway

Browser Profiles

OpenClaw supports two main browser profile modes:

openclaw - Managed Isolated Browser

A dedicated Chromium-based browser instance with its own user data directory + CDP port, no extension required. This is the safest and most isolated approach.

chrome - Extension Relay

Drive your existing Chrome tabs via a local CDP relay + Chrome extension. Requires the OpenClaw extension to be attached to a tab.

Tip: Set browser.defaultProfile: "openclaw" if you want managed mode by default

Configuration Details

Browser settings live in ~/.openclaw/openclaw.json config file:

~/.openclaw/openclaw.json

{
  browser: {
    enabled: true,
    remoteCdpTimeoutMs: 1500,
    remoteCdpHandshakeTimeoutMs: 3000,
    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" }
    }
  }
}

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, the derived browser ports shift to stay in the same "family"

cdpUrl defaults to the relay port when unset

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

Browser Selection

When launching locally, OpenClaw picks the first available browser in order. You can also override with browser.executablePath.

Auto-Detection Order

If your system default browser is Chromium-based (Chrome/Brave/Edge/etc), OpenClaw uses it automatically. Detection order:

  • •System default browser if Chromium-based
  • •Chrome
  • •Brave
  • •Edge
  • •Chromium
  • •Chrome Canary

macOS

/Applications/Brave Browser.app/Contents/MacOS/Brave Browser

Windows

C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe

Linux

/usr/bin/brave-browser

Local vs Remote Control

OpenClaw supports two control modes:

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

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.

  • •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"

Chrome Extension Relay

OpenClaw can also drive your existing Chrome tabs (no separate "openclaw" Chrome instance) via a local CDP relay + a Chrome extension.

How It Works

  • 1.The Gateway runs locally (same machine) or a node host runs on the browser machine
  • 2.A local relay server listens at a loopback cdpUrl (default: http://127.0.0.1:18792)
  • 3.You click the OpenClaw Browser Relay extension icon on a tab to attach (it does not auto-attach)
  • 4.The agent controls that tab via the normal browser tool, by selecting the right profile
  • 5.If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions
openclaw browser extension install

Install the extension (dev/unpacked)

Chrome → chrome://extensions → enable "Developer mode"

Enable Chrome Developer Mode

"Load unpacked" → select the directory printed by openclaw browser extension path

Load the extension

Pin the extension, then click it on the tab you want to control (badge shows ON)

Attach extension to tab

CLI Command Reference

All commands accept --browser-profile with a profile name to target a specific profile. All commands also accept --json for machine-readable output (stable payloads).

Basic Commands

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

Action Commands

openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser snapshot
openclaw browser navigate https://example.com
openclaw browser click 12 --double

Snapshot Commands

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

Note: AI snapshot returns a text snapshot with numeric refs; role snapshot returns a role-based list/tree with [ref=e12]

State Management

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 set offline on
openclaw browser set geo 37.7749 -122.4194
openclaw browser set timezone America/New_York

Snapshots and Refs

OpenClaw supports two "snapshot" styles for page element identification and interaction:

AI Snapshot (Numeric Refs)

Use openclaw browser snapshot (default; --format ai) to get a snapshot with numeric refs

openclaw browser click 12

Role Snapshot (Role Refs like e12)

Use openclaw browser snapshot --interactive (or --compact, --depth, --selector, --frame) to get a role-based list with [ref=e12]

openclaw browser click e12

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
  • •click/type etc require a ref from snapshot (either numeric 12 or role ref e12); CSS selectors are intentionally not supported for actions

Security & Privacy

Key Security Principles

  • •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
  • •Prefer HTTPS endpoints and short-lived tokens where possible
  • •Avoid embedding long-lived tokens directly in config files

Privacy Warnings

  • !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 JavaScript execution; disable it with browser.evaluateEnabled=false if you don't need it
  • !Keep the Gateway/node host private (loopback or tailnet-only)
  • !Remote CDP endpoints are powerful; tunnel and protect them

Agent Tools

The agent gets one tool for browser automation, supporting status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act.

browser Tool

All control endpoints accept ?profile= with a profile name to select a specific browser profile

browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
profile

Choose a named browser profile (openclaw, chrome, or remote CDP)

target

Select where the browser lives (sandbox | host | node). In sandboxed sessions, target: "host" requires agents.defaults.sandbox.browser.allowHostControl=true

Continue Learning

Browser control is just one of OpenClaw's powerful features. Explore more tutorials and documentation:

View All TutorialsVisit Official Docs