Mastering Browser Automation in OpenClaw

Browser automation is a cornerstone of OpenClaw’s power, enabling agents to interact with websites programmatically—opening tabs, reading content, clicking elements, and filling forms—within a secure, isolated environment.

Unlike traditional automation tools that interfere with your personal browsing, OpenClaw uses a dedicated, managed browser profile (openclaw) that runs separately from your daily browser. This ensures complete isolation: your cookies, history, and sessions remain untouched, while the agent operates in a clean, predictable lane.

Key Components

1. The openclaw Profile

The openclaw browser profile is automatically created and managed by the Gateway. It runs on a dedicated CDP (Chrome DevTools Protocol) port (default: 18800) and is visually distinguished by an orange browser window border. This profile is never your default browser—it exists solely for agent automation.

2. Profiles: openclaw vs chrome

• openclaw: A fully managed, isolated Chromium-based browser instance.
• chrome: A relay to your existing Chrome tabs via a browser extension (requires manual tab attachment).

By default, OpenClaw uses the chrome profile. To switch to managed mode, set browser.defaultProfile: "openclaw" in your config.

3. Control via the browser Tool

Agents use the browser tool to perform actions:

• Navigation: open, navigate, focus
• Interaction: click, type, select, drag
• Capture: screenshot, snapshot, pdf
• Inspection: console, cookies, storage

All actions require a ref (reference ID) obtained from a prior snapshot, ensuring precise targeting without brittle CSS selectors.

Getting Started

1. Enable the browser in ~/.openclaw/openclaw.json:

{
  "browser": {
    "enabled": true,
    "defaultProfile": "openclaw",
    "headless": false
  }
}

2. Start the browser:

openclaw browser start

3. Open a page:

openclaw browser open https://example.com

4. Take a snapshot to get actionable refs:

openclaw browser snapshot --interactive

5. Click an element using its ref (e.g., e12):

openclaw browser click e12

Best Practices

• Always re-run snapshot after navigation—refs are not stable across page loads.
• Use --interactive mode for clearer lists of clickable elements.
• For debugging, use highlight e12 to visually confirm the target.
• Keep the managed browser profile secure—treat it as a privileged interface.

Security Notes

• The managed browser runs locally and is loopback-only.
• Remote control via node hosts or Browserless.io is supported but should be secured with tokens and private networks.
• Arbitrary JavaScript execution (evaluate) is disabled by default and should be used with caution.

With OpenClaw’s browser automation, you gain reliable, deterministic control over web interfaces—ideal for scraping, testing, and integrating with web apps—all while maintaining strict security boundaries.