OpenClaw Browser Automation Skill

IMPORTANT: Before You Start

READ THE PROJECT README.md FIRST!

Before executing any browser automation tasks:

1. Read the project's README.md to understand the context and requirements
2. Identify target URLs, credentials (if any), and expected outcomes
3. Plan your automation workflow before running commands
4. Check if authentication/session state exists that can be reused

Installation

Quick Install (Recommended)

npm install -g agent-browser
agent-browser install --with-deps

Verify Installation

agent-browser --version

If installation fails, try:

npx agent-browser install --with-deps

Core Workflow Pattern

Every browser automation task follows this pattern:

1. OPEN    -> Navigate to target URL
2. SNAPSHOT -> Analyze page structure, get element refs
3. INTERACT -> Click, fill, select using refs
4. VERIFY   -> Re-snapshot to confirm changes
5. REPEAT   -> Continue until task complete
6. CLOSE    -> Clean up browser session

Quick Reference

Navigation

Command	Description
agent-browser open <url>	Navigate to URL
agent-browser back	Go back in history
agent-browser forward	Go forward
agent-browser reload	Reload current page
agent-browser close	Close browser session

Page Analysis

Command	Description
agent-browser snapshot -i	Most used: Interactive elements with refs
agent-browser snapshot -i -c	Compact interactive snapshot
agent-browser snapshot -s "#main"	Scope to specific container
agent-browser snapshot -d 3	Limit tree depth

Element Interaction (use @refs from snapshot)

Command	Description
agent-browser click @e1	Click element
agent-browser fill @e1 "text"	Clear field and type (preferred for inputs)
agent-browser type @e1 "text"	Type without clearing
agent-browser press Enter	Press keyboard key
agent-browser press Control+a	Key combination
agent-browser select @e1 "value"	Select dropdown option
agent-browser check @e1	Check checkbox
agent-browser uncheck @e1	Uncheck checkbox
agent-browser hover @e1	Hover over element
agent-browser upload @e1 file.pdf	Upload file

Data Extraction

Command	Description
agent-browser get text @e1	Get element text content
agent-browser get html @e1	Get inner HTML
agent-browser get value @e1	Get input field value
agent-browser get attr @e1 href	Get specific attribute
agent-browser get title	Get page title
agent-browser get url	Get current URL
agent-browser get count ".selector"	Count matching elements

Waiting (Critical for Reliability)

Command	Description
agent-browser wait @e1	Wait for element to appear
agent-browser wait 2000	Wait milliseconds
agent-browser wait --text "Success"	Wait for text to appear
agent-browser wait --url "/dashboard"	Wait for URL change
agent-browser wait --load networkidle	Wait for network idle

Screenshots & PDF

Command	Description
agent-browser screenshot out.png	Save screenshot
agent-browser screenshot --full out.png	Full page screenshot
agent-browser pdf output.pdf	Save page as PDF

Common Task Recipes

Recipe 1: Login Flow

# 1. Open login page
agent-browser open https://example.com/login

# 2. Get interactive elements
agent-browser snapshot -i
# Output: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign in" [ref=e3]

# 3. Fill credentials
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "secure_password"

# 4. Submit
agent-browser click @e3

# 5. Wait for redirect
agent-browser wait --url "/dashboard"
agent-browser wait --load networkidle

# 6. Save session for reuse
agent-browser state save session.json

# 7. Verify success
agent-browser snapshot -i

Recipe 2: Data Extraction Loop

# Navigate to listing page
agent-browser open https://example.com/products

# Get initial snapshot
agent-browser snapshot -i

# Extract data from each item
agent-browser get text @e1
agent-browser get attr @e2 href

# Check for pagination
agent-browser snapshot -s ".pagination"

# Click next if exists
agent-browser click @e5
agent-browser wait --load networkidle

# Re-snapshot for new content
agent-browser snapshot -i

Recipe 3: Form Submission with Validation

# Open form
agent-browser open https://example.com/contact

# Analyze form structure
agent-browser snapshot -i

# Fill all required fields
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "john@example.com"
agent-browser fill @e3 "Hello, this is my message."

# Select dropdown if present
agent-browser select @e4 "support"

# Check required checkbox
agent-browser check @e5

# Submit form
agent-browser click @e6

# Wait and verify submission
agent-browser wait --text "Thank you"
agent-browser snapshot -i

Recipe 4: Session Persistence

# First time: Login and save state
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "/home"
agent-browser state save auth-session.json

# Later: Restore session and continue
agent-browser state load auth-session.json
agent-browser open https://app.example.com/dashboard
# Already logged in!

Recipe 5: Multi-Tab Workflow

# Open first site
agent-browser open https://site-a.com

# Open second tab
agent-browser tab new https://site-b.com

# List tabs
agent-browser tab
# Output: Tab 1: site-a.com, Tab 2: site-b.com (active)

# Switch between tabs
agent-browser tab 1
agent-browser snapshot -i
# Work on tab 1...

agent-browser tab 2
agent-browser snapshot -i
# Work on tab 2...

Recipe 6: Debugging Failed Automation

# Enable headed mode to see what's happening
agent-browser open https://example.com --headed

# Check for JavaScript errors
agent-browser errors

# View console output
agent-browser console

# Highlight element to verify selection
agent-browser highlight @e1

# Take screenshot for debugging
agent-browser screenshot debug.png

# Start trace for detailed analysis
agent-browser trace start
# ... perform actions ...
agent-browser trace stop trace.zip

Semantic Locators (Alternative to Refs)

When refs are unstable or you need more readable selectors:

# Find by role
agent-browser find role button click --name "Submit"

# Find by text content
agent-browser find text "Sign In" click

# Find by label
agent-browser find label "Email" fill "user@test.com"

# Find first matching selector
agent-browser find first ".item" click

# Find nth element
agent-browser find nth 2 "a" text

Network Control

# Mock API response
agent-browser network route "*/api/user" --body '{"name":"Test User"}'

# Block analytics/ads
agent-browser network route "*google-analytics*" --abort
agent-browser network route "*facebook.com*" --abort

# View captured requests
agent-browser network requests --filter api

# Remove routes
agent-browser network unroute

Browser Configuration

# Set viewport for responsive testing
agent-browser set viewport 1920 1080
agent-browser set viewport 375 667  # Mobile

# Emulate device
agent-browser set device "iPhone 14"
agent-browser set device "Pixel 5"

# Set geolocation
agent-browser set geo 40.7128 -74.0060  # New York

# Dark mode testing
agent-browser set media dark

Best Practices

1. Always Snapshot After Navigation

agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot -i  # ALWAYS do this after navigation

2. Use fill Instead of type for Inputs

# GOOD: Clears existing text first
agent-browser fill @e1 "new text"

# BAD: Appends to existing text
agent-browser type @e1 "new text"

3. Add Explicit Waits for Reliability

# After clicking that triggers navigation
agent-browser click @e1
agent-browser wait --load networkidle

# After AJAX updates
agent-browser click @e1
agent-browser wait --text "Updated"

4. Handle Iframes Explicitly

# Switch to iframe before interacting
agent-browser frame "#iframe-id"
agent-browser snapshot -i
agent-browser click @e1

# Return to main frame
agent-browser frame main

5. Save Session State Early

# Save immediately after successful login
agent-browser state save session.json
# Can reload if something breaks later

Error Recovery

Element Not Found

# Re-snapshot to get updated refs
agent-browser snapshot -i

# Try semantic locator
agent-browser find text "Button Text" click

# Check if element is in iframe
agent-browser frame "#iframe"
agent-browser snapshot -i

Page Not Loading

# Increase timeout
agent-browser open https://slow-site.com --timeout 60000

# Wait explicitly
agent-browser wait --load networkidle
agent-browser wait 5000

Session Lost

# Reload saved state
agent-browser state load session.json
agent-browser reload

Debug Mode

# Visual debugging
agent-browser open https://example.com --headed
agent-browser screenshot debug.png
agent-browser errors
agent-browser console

Parallel Sessions

For working with multiple isolated browsers:

# Session 1
agent-browser --session user1 open https://app.com
agent-browser --session user1 snapshot -i

# Session 2 (completely isolated)
agent-browser --session user2 open https://app.com
agent-browser --session user2 snapshot -i

# List all sessions
agent-browser session list

# Each session has separate cookies, storage, and state

JSON Output for Parsing

Add --json flag to get machine-readable output:

agent-browser snapshot -i --json | jq '.elements[]'
agent-browser get text @e1 --json
agent-browser get url --json

Video Recording

# Start recording from current page
agent-browser record start ./demo.webm

# Perform your automation
agent-browser click @e1
agent-browser fill @e2 "text"

# Stop and save
agent-browser record stop

Troubleshooting Checklist

1. Command not found: Run agent-browser install --with-deps
2. Element not found: Run agent-browser snapshot -i to refresh refs
3. Page timeout: Add --timeout 60000 for slow pages
4. Can't see what's happening: Add --headed flag
5. Login not persisting: Use agent-browser state save/load
6. Refs changed: Always re-snapshot after navigation
7. Iframe content: Use agent-browser frame to switch context