Mastering Browser Automation in OpenClaw

OpenClaw provides powerful browser automation capabilities through its browser tool, allowing agents to interact with websites programmatically. This guide covers the core concepts and practical usage patterns.

The Two Browser Profiles

OpenClaw supports two distinct browser control modes:

1. openclaw Profile (Managed)

• A dedicated, isolated Chromium-based browser instance
• Automatically managed by OpenClaw with its own user data directory
• Orange accent border for visual identification
• Ideal for secure, deterministic automation tasks
• Controlled via loopback CDP (Chrome DevTools Protocol)

2. chrome Profile (Extension Relay)

• Connects to your existing Chrome/Brave/Edge tabs via extension
• Requires the OpenClaw Browser Relay extension to be installed
• Click the extension icon to attach control to a specific tab
• Best for interacting with existing logged-in sessions

Recommendation: Use the openclaw profile for most automation tasks to maintain isolation and security.

Quick Start Commands

# Check browser status
openclaw browser status

# Start the managed browser
openclaw browser start

# Open a new tab
openclaw browser open https://example.com

# Take a snapshot of the current page
openclaw browser snapshot

Core Automation Workflow

The standard pattern for browser automation follows four steps:

1. Navigate to the target URL
2. Snapshot the page to get actionable references
3. Act on elements using their references
4. Verify the outcome

Step 1: Navigation

browser navigate https://example.com/login

Step 2: Snapshot

Take an interactive snapshot to identify clickable elements:

browser snapshot --interactive

This returns output like:

[ref=e12] Login with Google
[ref=e15] Email address
[ref=e18] Password
[ref=e22] Sign In

Step 3: Action

Use the references to interact with the page:

# Fill email field
browser type e15 "user@example.com"

# Fill password field
browser type e18 "password123"

# Click sign-in button
browser click e22

Step 4: Verification

Wait for the next page to load:

browser wait --url "**/dashboard"
browser wait --load networkidle

Advanced Features

State Management

Preserve session state across interactions:

# Save cookies
browser cookies > cookies.json

# Restore cookies
browser cookies set session abc123 --url "https://example.com"

# Set custom headers
browser set headers --headers-json '{"X-API-Key": "secret"}'

Environment Configuration

Simulate different devices and conditions:

# Set mobile viewport
browser set device "iPhone 14"

# Enable offline mode
browser set offline on

# Change timezone
browser set timezone America/New_York

Debugging

When automation fails, use these diagnostic tools:

# View console errors
browser console --level error

# Highlight an element
browser highlight e12

# Record a trace
browser trace start
# ... reproduce issue ...
browser trace stop

Security Considerations

• The openclaw profile is isolated from your personal browsing data
• Treat remote CDP URLs and authentication tokens as sensitive secrets
• Avoid executing arbitrary JavaScript via evaluate unless absolutely necessary
• Keep the Gateway and browser instances on private networks

Best Practices

1. Always re-take snapshots after navigation - references are not stable across page loads
2. Use --interactive snapshots for action planning as they provide clean reference lists
3. Combine multiple wait conditions for robust verification
4. Clean up browser state between test runs with browser cookies clear
5. Use the managed openclaw profile for production automation

Browser automation unlocks powerful workflows in OpenClaw, from automated testing to web scraping and form filling. Start with simple navigation tasks and gradually incorporate more advanced features as needed.