How to Use OpenClaw's Browser Tool for Web Automation

OpenClaw surpassed 350,000 GitHub stars by April 2026. Its browser tool is one of the platform's most capable built-in features, but most automation tutorials default to computer-use instead, a screenshot-and-click approach that trades structured page data for simplicity.

The browser tool connects directly to Chrome DevTools Protocol (CDP), returning structured accessibility snapshots with stable element references. Instead of analyzing screenshots pixel by pixel, the agent reads a page's accessibility tree, identifies interactive elements by numbered refs, and acts on them.

Three commands show the difference:

openclaw browser start
openclaw browser open https://example.com
openclaw browser snapshot

start launches an isolated Chromium instance. open navigates to a URL. snapshot returns an accessibility tree where each interactive element gets a numbered ref you can target with click or type. No coordinate guessing, no screenshot parsing.

The tool supports three profile types for different session needs, five auto-detected Chromium browsers, and fail-closed SSRF protection that blocks private network access by default. It sits between raw CDP scripting (powerful but verbose) and computer-use (simple but imprecise). You get structured page representations, direct element targeting, and profile-based session management with security defaults that work without configuration.

The trade-off: you need a Chromium-based browser available, either locally or through a cloud service. OpenClaw auto-detects Chrome, Brave, Edge, Chromium, and Chrome Canary across macOS, Linux, and Windows.

OpenClaw organizes browser sessions into three profile types. Each determines how the browser launches, what data the agent can access, and what security boundaries apply.

OpenClaw-Managed Profiles

The default. OpenClaw launches a dedicated Chromium instance with its own user data directory and CDP port (18800-18899 range). The agent gets a clean, isolated browser with no access to your personal browsing data.

{
  browser: {
    profiles: {
      openclaw: {
        cdpPort: 18800,
        color: "#FF4500"
      }
    }
  }
}

Managed profiles are the safest option for general automation. The agent cannot see your bookmarks, saved passwords, or logged-in sessions. Use this when you want full isolation between automation work and personal browsing.

Existing-Session Profiles

These attach to a running Chrome, Brave, or Edge browser through Chrome DevTools. The agent inherits your existing tabs, cookies, and login sessions.

{
  browser: {
    profiles: {
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00"
      }
    }
  }
}

This is the highest-risk profile type. The agent operates inside your signed-in browser and can access anything you are logged into. OpenClaw prompts for explicit approval before attaching. Use this only when the agent needs to interact with authenticated services where re-logging in is not practical.

For Brave, Edge, or a non-default Chrome profile, specify the userDataDir:

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        attachOnly: true
      }
    }
  }
}

Remote CDP Profiles

These connect to external Chromium instances via CDP URLs. They are built for cloud browser services and distributed setups where the browser runs on a different machine.

{
  browser: {
    profiles: {
      remote: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=YOUR_KEY",
        color: "#F97316"
      }
    }
  }
}

OpenClaw handles connection strategy automatically: HTTP discovery first, then WebSocket fallback, then direct WebSocket for bare root URLs. Use remote profiles when you need cloud infrastructure like residential proxies, CAPTCHA solving, or multi-region access.

All profiles are configured in ~/.openclaw/openclaw.json. You can run multiple profiles simultaneously on different CDP ports and switch between them per task using --browser-profile <name>.

Headless mode runs the browser without a visible window. On Linux servers without a display, OpenClaw enables headless automatically. On macOS and Windows, you set it explicitly.

Per-session headless:

openclaw browser start --headless

This flag applies only to that start request. For persistent headless behavior, set it in your configuration:

{
  browser: {
    headless: true,
    profiles: {
      work: {
        headless: true,
        cdpPort: 18801
      }
    }
  }
}

Per-profile values override the global browser.headless setting. You can run one profile headless for automation while keeping another visible for debugging. The environment variable OPENCLAW_BROWSER_HEADLESS (set to 1 or 0) forces behavior for the current process, though explicit start requests take priority.

Cloud browser services

Four hosted services integrate through remote CDP profiles:

Browserbase provides CAPTCHA solving, stealth browsing, and residential proxies. Its free tier includes one concurrent session and one browser hour per month. Sessions auto-create on WebSocket connect.

Notte offers a CDP gateway with auto-cleanup on disconnect. Free tier: five concurrent sessions and 100 lifetime browser hours.

Browserless runs as a hosted Chromium service or a self-hosted Docker container. For Docker on the same host, add attachOnly: true and point to ws://127.0.0.1:3000.

Browser Use provides anti-detection profiles and residential proxies across 195+ countries. Configure it with optional query parameters for session timeout, profile persistence, and proxy region:

{
  browser: {
    profiles: {
      "browser-use": {
        cdpUrl: "wss://connect.browser-use.com?apiKey=YOUR_KEY&proxyCountryCode=us",
        color: "#ff750e"
      }
    }
  }
}

When choosing between local and cloud, consider latency and cost. Local managed profiles respond in milliseconds with no per-session fees. Cloud profiles add network latency but provide IP diversity, CAPTCHA handling, and session persistence across agent restarts. Most workflows start local and move specific tasks to cloud when they hit anti-bot protections or need geographic diversity.

Store browser automation output where your team can find it

50GB free workspace storage with MCP-native access for OpenClaw agents. Intelligence Mode indexes scraped data for search by meaning. No credit card required.

Sign Up Free

OpenClaw's browser CLI covers lifecycle management, tab control, page interaction, and state management.

Lifecycle and diagnostics

openclaw browser start           # launch managed browser
openclaw browser stop            # shut down
openclaw browser status          # connection check
openclaw browser doctor          # diagnose issues across 5 layers
openclaw browser doctor --deep   # add live snapshot validation

The doctor command checks readiness across Gateway, plugin, profile, browser, and active tab layers. Run it first when something is not working.

Tab management

openclaw browser tabs                     # list open tabs
openclaw browser tab new --label docs     # open labeled tab
openclaw browser open https://example.com # navigate
openclaw browser focus docs               # switch to tab by label
openclaw browser close <tabId>            # close a tab

Labels give tabs stable names that persist across commands. Use them instead of raw tab IDs when running multi-tab workflows.

Page interaction with refs

Interaction works through the snapshot ref system. Take a snapshot to get element references, then use those refs in subsequent commands:

openclaw browser snapshot              # get accessibility tree with refs
openclaw browser click 12              # click element ref 12
openclaw browser click 12 --double     # double-click
openclaw browser type 23 "search text" # type into element ref 23
openclaw browser type 23 "text" --submit
openclaw browser press Enter
openclaw browser drag 10 11            # drag between refs
openclaw browser select 9 "Option A"  # select from dropdown

Refs are numbered identifiers assigned to interactive elements in the accessibility tree. They break after page navigations, so re-run snapshot after any action that changes the page.

OpenClaw supports three snapshot formats. The default AI snapshot uses aria-ref="12" identifiers, best for automated workflows. The interactive role snapshot (--interactive) uses [ref=e12] notation with depth and compactness controls, useful for debugging. The ARIA snapshot (--format aria) returns the raw accessibility tree.

Wait conditions

Combine conditions to pause until the page reaches a specific state:

openclaw browser wait --text "Done" \
  --url "**/dashboard" \
  --load networkidle \
  --timeout-ms 15000

Available conditions include text patterns, URL globs, network idle states, JavaScript predicates, and selector visibility. Combining them with a timeout prevents workflows from hanging on unexpected page states.

State management

openclaw browser set offline on              # simulate offline
openclaw browser set device "iPhone 14"      # device emulation
openclaw browser set geo 37.7749 -122.4194   # geolocation
openclaw browser set timezone America/New_York

State commands apply to the current session and persist until changed or the browser stops.

OpenClaw's browser tool operates under a fail-closed security model. Navigation targets are validated against an SSRF policy both before and after each request. Private network addresses are blocked by default.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com"],
      allowedHostnames: ["localhost"]
    }
  }
}

The hostnameAllowlist permits navigation to specific domains. dangerouslyAllowPrivateNetwork defaults to false and should stay that way unless you have a specific internal-network use case. The name includes "dangerously" for a reason.

Loopback-only access

The browser control API listens exclusively on loopback. External network traffic cannot reach it. Authentication uses one of three methods: gateway token bearer auth, an x-openclaw-password header, or HTTP Basic auth with the gateway password. When no shared secret is configured, OpenClaw generates a runtime-only token that expires when the process stops.

Multi-layer isolation

Beyond SSRF filtering and loopback binding, OpenClaw enforces several isolation boundaries:

• Dedicated user data directories prevent managed browser profiles from touching your personal browsing data
• Dedicated CDP ports (18800-18899 range) avoid collisions with developer tools
• Tab cleanup auto-closes idle tabs after 120 minutes by default
• Maximum 8 tabs per session prevents runaway tab accumulation
• JavaScript evaluation can be disabled entirely with browser.evaluateEnabled: false

For managed browser launches, OpenClaw bypasses provider proxies to preserve SSRF checks. If you add explicit proxy flags like --proxy-server or --proxy-pac-url, strict mode requires you to explicitly enable private-network access first.

These defaults mean a fresh OpenClaw install with browser enabled is locked down without any security configuration. Most users only need to add domains to hostnameAllowlist for their specific automation targets.

Browser automation generates artifacts: screenshots, downloaded PDFs, scraped datasets, exported reports. Where those files end up after the session matters, especially when agents or team members need access from different machines.

Local storage is the simplest option. Save downloads and screenshots to a project directory and process them on the same machine. This works for single-developer setups but breaks down when you need to share results or run agents across multiple hosts.

Cloud object storage like S3 or GCS handles distributed setups. You manage bucket configuration, access policies, and folder naming conventions yourself. Flexible, but requires infrastructure work upfront.

For teams running multiple OpenClaw agents, Fast.io adds a workspace layer on top of storage. Agents access workspaces through the Fast.io MCP server or REST API, uploading browser automation results directly from their workflows. Intelligence Mode auto-indexes uploaded files for semantic search, so you can query collected data by meaning rather than filename. The MCP skill documentation covers the full tool surface for agent integration.

The free tier includes 50GB storage, 5,000 credits per month, and 5 workspaces with no credit card required. For OpenClaw specifically, the Fast.io storage for OpenClaw page covers the setup path.

The ownership transfer pattern makes recurring automation practical. An agent scrapes data through the browser tool, uploads results to a workspace, and transfers ownership to a human reviewer. The agent keeps admin access for future runs while the human gets full control of the output. This works well for monitoring tasks where browser automation runs on a schedule and humans review the collected data periodically.