Mastering OpenClaw's Browser Tool

OpenClaw's browser tool is a powerful component designed to run dedicated browser profiles for agent automation without interfering with your personal browser. It operates through a controlled, local service that interfaces with Chromium-based browsers via CDP (Chrome DevTools Protocol).

Key Features

Isolated Browser Profiles

The tool provides isolated browser instances named by profile, with openclaw being the default managed profile. This profile runs in a separate user data directory, ensuring your personal browsing sessions remain untouched. The chrome profile connects to your existing Chrome tabs via an extension relay, allowing the agent to control specific tabs you've manually attached.

Key aspects:

• Orange-tinted UI for visual identification
• Runs on CDP port 18800 by default
• Can run in headless or headful mode
• Supports multiple named profiles for different purposes

Automation Capabilities

Agents can perform a range of browser actions including:

• Navigation: Open, focus, and close tabs
• Interaction: Click elements, type text, drag and select
• Snapshotting: Capture AI snapshots with numeric references or role-based snapshots with named references
• Screenshotting: Take full-page or element-specific screenshots
• State Management: Control cookies, storage, and device settings

Profile Management

OpenClaw supports multiple browser profiles, allowing for workflow separation:

• openclaw: Default isolated, managed browser
• chrome: Extension relay to your system browser
• Custom profiles: Can be created for specific use cases

You can set browser.defaultProfile: "openclaw" in your config to make the isolated browser the default.

Configuration

Browser settings are configured in ~/.openclaw/openclaw.json:

{
  browser: {
    enabled: true,
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
    },
  },
}

Browser Selection

By default, OpenClaw auto-detects the first available Chromium-based browser (Chrome → Brave → Edge → Chromium → Chrome Canary). You can override this by setting browser.executablePath.

On macOS, you can specify Brave Browser with:

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

Automation Workflow

A typical browser automation workflow involves:

1. Snapshot: Capture the current page state with browser snapshot, which returns elements with references
2. Action: Use element references (e.g., 12 for AI snapshots or e12 for role snapshots) to perform actions like browser click 12 or browser type 23 "text"
3. Verification: Take screenshots or check page state to verify results

Reference Types

The browser tool supports two snapshot formats with different reference systems:

• AI snapshots (numeric refs): Default format that assigns numeric IDs to elements

  • Usage: openclaw browser click 12
  • Best for: Simple automation workflows

• Role snapshots (role refs like e12): Returns role-based references with [ref=e12] format

  • Usage: openclaw browser click e12
  • Best for: Complex UIs requiring precise element targeting

Important: References are not stable across page navigations. Always re-run snapshot after navigation to get fresh references.

Security Considerations

• Browser control is limited to loopback connections, accessible only through Gateway auth or node pairing
• Remote CDP URLs and API tokens should be treated as sensitive information
• The isolated openclaw profile prevents access to your personal browsing data
• For production use, keep the Gateway on a private network (Tailscale recommended)

Troubleshooting Tips

When facing automation issues:

1. Check visibility: Run browser snapshot --interactive to see available elements
2. Verify targeting: Use browser highlight <ref> to see which element will be targeted
3. Monitor errors: Check browser errors --clear and browser requests --filter api --clear for failed requests
4. Record traces: Use browser trace start followed by browser trace stop to capture and analyze interactions

The browser tool is essential for web automation tasks, providing a reliable interface between your agents and web applications. By understanding its capabilities and configuration options, you can build robust, repeatable automation workflows that integrate seamlessly with your existing tools and systems.