OpenClaw Browser Extension 2026 – Step-by-Step Setup, CLI Reference & Automation Examples

Master browser automation with OpenClaw. Learn the extension, browser relay, CLI commands, and real-world automation workflows.

OpenClaw AI alternatives

Understanding OpenClaw Browser Automation

Let's be clear about what's happening here. When you run OpenClaw, you're actually running three interconnected pieces of software. Understanding this architecture is the difference between using the tool effectively and spending hours debugging why nothing works.

The Three Parts of OpenClaw Browser Control

1. The Gateway (Your Command Center)

The Gateway is OpenClaw's central engine—it can sit on your computer or run on a server somewhere else on your network. Think of it as the brain of your automation. OpenClaw actually lives inside the Gateway, thinking through problems and deciding what needs to happen next. When OpenClaw decides "I should click the login button," the Gateway is responsible for translating that into the actual instruction that makes it real.

2. The Browser Control Service (The Middleman)

This is a small HTTP server that runs on your machine, separate from the Gateway. Its job is incredibly specific: translate commands from the Gateway into actual browser actions. Want to take a screenshot? The service does that. Want to click a button? It clicks. Want to read what's on the page? It reads. It uses something called the Chrome Debug Protocol (CDP) to communicate with Chrome.

3. The Chrome Extension (Your Hands)

This is what most people focus on, and rightfully so. The extension is the actual component that runs in your browser. When you click the toolbar button to attach it to a tab, the extension becomes the direct link between the control service and the page you're viewing. Without the extension, the control service can still manage a separate openclaw-specific browser profile. With the extension, it can hijack your existing Chrome tabs.

What You Can Actually Do with This Setup

Once these three parts are connected, the possibilities open up. You can automate:

• Navigate to any URL automatically
• Read the content of a page and understand what's there (visual snapshots, page structure)
• Click buttons, links, and interactive elements using smart references
• Type into form fields, including complex multi-step forms
• Drag and drop, select from dropdowns, fill multi-field forms
• Take screenshots (both element-level and full-page)
• Set cookies, headers, geolocation, timezone, device type
• Wait for specific conditions (URL changes, elements appearing, code conditions)
• Scrape data from pages automatically
• Download files, upload files, handle dialogs
• Generate PDFs of pages
• Execute JavaScript in the page context

None of this requires you to write any CSS selectors or write complicated automation scripts. The agent figures it out by looking at the page structure and understanding what's interactive.

Want more context? Check out our deep dive on what OpenClaw AI actually is and how it compares to other automation tools in our OpenClaw alternatives guide.

Chrome Extension vs Managed Browser (Which Approach?)

This is the fundamental choice you'll face. Both work. Both are legitimate. They're just different trade-offs.

Which Should You Actually Use?

Use the Chrome extension if: You're testing locally, running trusted automation, and want zero friction. For a personal productivity setup where you're automating your own workflows, the extension is the path of least resistance.

Use the managed browser if: You're sharing OpenClaw across a team, the Gateway runs remotely, you're handling sensitive data, or you want to keep your personal browsing completely separate from your automation. This is the production choice.

Use both if: You're like most power users—extension relay for quick local tests, managed profile for anything that matters or runs remotely.

Step-by-Step: Install the OpenClaw Chrome Extension

This is where most people get stuck. The documentation says "load unpacked" but doesn't explain what that actually means or why you need to do it twice (once to install, once to load in Chrome).

Prerequisites

Before you start, make sure you have:

• OpenClaw CLI installed: You should be able to run openclaw --version in your terminal
• The OpenClaw Gateway running: Usually started with openclaw gateway
• Chrome installed: Any Chromium-based browser works (Chrome, Brave, Edge, etc.)
• Developer mode access in Chrome: You need to enable this

Installation Steps (What Actually Happens)

openclaw browser extension install

Extension installed to: /Users/yourname/.openclaw/extensions/chrome

openclaw browser extension path

chrome://extensions/

Verify It's Working

Open a new tab with any website. Click the extension icon in your toolbar. You should see:

• A badge that says "ON" — the relay is responsive and the extension can talk to the control service
• A badge that says "..." — the extension is actively trying to establish the connection (this is normal for a few seconds)
• A badge that says "!" — something has blocked communication, most commonly because the relay server isn't actually running on this machine

If you see "ON", you're connected. The extension is now attached to that tab and OpenClaw can control it.

If You See the "!" Error

This is the most common issue. It means the extension can't find the browser relay server. Here's how to fix it:

Updating After OpenClaw Upgrades

When you upgrade OpenClaw (via npm update), the extension files in the package are new. You need to update your installed copy:

openclaw browser extension install

Then in Chrome → Extensions page, find the OpenClaw extension and click "Reload". That's it.

How Browser Relay Actually Works (The Hidden Magic)

The term "browser relay" confuses a lot of people because it sounds like just a server that relays traffic. It's more specific than that. Let's break it down.

What Browser Relay Actually Is

Browser relay is a small HTTP server that translates between the Extension and the Browser Control Service. When the extension sends a command, the relay server:

1. Receives the request from the Chrome extension running in your browser
2. Checks if the relay authentication token is valid (prevents anyone on your network from hijacking)
3. Converts the request to Chrome Debug Protocol (CDP) messages
4. Sends those messages to the actual browser control service
5. Gets the response back and converts it to a format the extension understands
6. Sends the response back to the extension

Why is this architecture useful? Because the extension runs in the browser (on your machine), the relay server runs on your machine, and they both communicate on your computer. There's no external network traffic. Everything stays local. Meanwhile, the Gateway talks to the relay server through a direct connection, which CAN run over a network if you want.

The Default Configuration

The relay server runs on a specific port. By default:

• Gateway port: 18791
• Browser control service: 18791 + 2 = 18793 (or the configured port)
• Browser relay: 18791 + 1 = 18792

If you change the Gateway port in your config, these related ports shift automatically. The relay always stays one port higher than the control service.

How CLI Commands Use the Relay

When you run openclaw browser snapshot, here's what's actually happening:

User Terminal
    |
    |-- runs: openclaw browser snapshot
    |
    --> connects to Gateway (port 18791)
    --> asks: "what does the attached tab see?"
    --> Gateway tells Browser Control Service
    --> Browser Control Service asks Relay: "what's on screen?"
    --> Relay asks Extension: "what's on screen?"
    --> Extension talks to Chrome
    --> Chrome returns page content
    --> works backwards through chain
    |
    <-- returns snapshot to terminal

The entire chain happens in milliseconds. But understanding the flow helps when debugging. If the snapshot command fails:

• Is the Gateway running?
• Is the relay server running (check: lsof -i :18792)?
• Is Chrome actually attached via the extension?
• Are all three pieces trying to talk on localhost?

Configuration: Where to Customize

You can customize relay behavior in your OpenClaw config file (usually ~/.openclaw/openclaw.json):

{
  "browser": {
    "enabled": true,
    "defaultProfile": "chrome",
    "color": "#FF4500",
    "profiles": {
      "chrome": {
        "driver": "extension",
        "cdpUrl": "http://127.0.0.1:18792"
      }
    }
  }
}

enabled: Turn browser control on/off globally

defaultProfile: Which profile to use by default (chrome uses extension relay, openclaw uses managed browser)

cdpUrl: Where the relay server listens. Change this if 18792 conflicts with something else on your machine

Essential Browser CLI Commands Reference

Once the extension is working, you interact with it mostly through CLI commands or through the agent's browser tool. Let's go through the commands you'll actually use.

Checking Status

First, check if everything is connected:

openclaw browser --browser-profile chrome status

This tells you whether the relay is reachable and whether a tab is currently attached.

Tab Management

List all open tabs:

openclaw browser --browser-profile chrome tabs

Output looks like:

ID: a1b2c3d4
Title: Example Domain
URL: https://example.com/
Type: page

ID: e5f6g7h8
Title: Google
URL: https://google.com/
Type: page

Open a new tab:

openclaw browser --browser-profile chrome open https://docs.openclaw.ai

Focus (bring to front) a specific tab:

openclaw browser --browser-profile chrome focus a1b2c3d4

Close a tab:

openclaw browser --browser-profile chrome close a1b2c3d4

Snapshots: Understanding What The Agent Sees

This is the most important command. When an agent needs to understand a page, it takes a snapshot. There are two types:

AI Snapshot (Default): Uses numeric references

openclaw browser --browser-profile chrome snapshot

Returns something like:

[1] Heading: OpenClaw Browser Extension Guide
[2] Paragraph: Master browser automation with OpenClaw...
[3] Link: "Get Started" [ref=3]
[4] Button: "Install Now" [ref=4]
[5] Text Input: "Search..." [ref=5]

Interactive/Role Snapshot: Uses more intelligent references

openclaw browser --browser-profile chrome snapshot --interactive

Returns:

[button] "Install Now" [ref=e12]
[link] "Get Started" [ref=e13]
[textbox] "Search..." [ref=e14]

The interactive format is actually what the agent prefers because it's more robust. If a button moves around on the page, the numeric reference breaks, but the role-based reference usually survives.

Navigation and Actions

Navigate to a URL:

openclaw browser --browser-profile chrome navigate https://example.com

Take a screenshot (pixels, not HTML structure):

openclaw browser --browser-profile chrome screenshot

Take a full-page screenshot:

openclaw browser --browser-profile chrome screenshot --full-page

Click an element (using the ref from snapshot):

openclaw browser --browser-profile chrome click e12

Type into a field:

openclaw browser --browser-profile chrome type e14 "my search query"

Type and submit (adds Enter):

openclaw browser --browser-profile chrome type e14 "query" --submit

Select from a dropdown:

openclaw browser --browser-profile chrome select e9 "Option A" "Option B"

Fill a multi-field form:

openclaw browser --browser-profile chrome fill --fields '[{"ref":"e1","value":"John"},{"ref":"e2","value":"john@example.com"}]'

Waiting and Conditions

Wait for a specific URL:

openclaw browser --browser-profile chrome wait --url "**/dashboard"

Wait for text to appear:

openclaw browser --browser-profile chrome wait --text "Success"

Wait for a selector to be visible:

openclaw browser --browser-profile chrome wait "#main"

Wait for a JavaScript condition:

openclaw browser --browser-profile chrome wait --fn "document.readyState === 'complete'"

You can stack multiple conditions—the agent won't move forward until every single one is satisfied:

openclaw browser --browser-profile chrome wait "#main" --url "**/dash" --load networkidle

Inspect and Debug

View console errors:

openclaw browser --browser-profile chrome console --level error

View network requests:

openclaw browser --browser-profile chrome requests --filter api

Get response body from an API call:

openclaw browser --browser-profile chrome responsebody "**/api/users" --max-chars 5000

Take a PDF of the page:

openclaw browser --browser-profile chrome pdf

State and Environment

Get all cookies:

openclaw browser --browser-profile chrome cookies

Set a cookie:

openclaw browser --browser-profile chrome cookies set session abc123 --url "https://example.com"

Set geolocation (for location-aware sites):

openclaw browser --browser-profile chrome set geo 37.7749 -122.4194

Set timezone:

openclaw browser --browser-profile chrome set timezone America/New_York

Emulate a device:

openclaw browser --browser-profile chrome set device "iPhone 14"

Go offline (for testing offline functionality):

openclaw browser --browser-profile chrome set offline on

Real-World Automation Examples (What You Actually Build)

Commands are useful, but they don't show you how to actually use this. Let's build three real workflows that people actually want to do. For advanced use cases—like building a full AI assistant or creating complex applications—see our guides on building an OpenClaw AI assistant and replacing SaaS tools with personal AI assistants.

Example 1: Automated Web Scraping with Snapshot

Goal: Visit a website, extract specific data, and save it.

Workflow:

#!/bin/bash

# Navigate to the page
openclaw browser --browser-profile chrome navigate "https://example.com/products"

# Wait for page to load
openclaw browser --browser-profile chrome wait --load networkidle

# Get an interactive snapshot so you can see how the agent will reference each element
openclaw browser --browser-profile chrome snapshot --interactive

# The output shows you all clickable items with their ref numbers (e1, e2, etc)
# Use those refs to target specific products and pull their information

In practice, you'd do this through the agent's browser tool, not manually. The agent would:

1. Take a snapshot to see the page structure
2. Extract information about each product from the snapshot
3. Click each product to see details
4. Collect all the data
5. Return it as JSON

Example 2: Filling and Submitting Forms

Goal: Automate a signup flow that requires multiple pages. Looking for an ambitious project? See how we built a Reddit-like social network with OpenClaw AI agents.

# First page: basic info
openclaw browser --browser-profile chrome navigate "https://example.com/signup"
openclaw browser --browser-profile chrome wait --text "First Name"
openclaw browser --browser-profile chrome snapshot --interactive

# Fill the form (refs come from snapshot)
openclaw browser --browser-profile chrome type e1 "John Doe"
openclaw browser --browser-profile chrome type e2 "john@example.com"
openclaw browser --browser-profile chrome type e3 "SecurePassword123"

# Click next button
openclaw browser --browser-profile chrome click e4

# Wait for next page to load
openclaw browser --browser-profile chrome wait --url "**/signup/confirm"

# Take snapshot of page 2
openclaw browser --browser-profile chrome snapshot --interactive

# Fill page 2
openclaw browser --browser-profile chrome type e5 "Organization Name"
openclaw browser --browser-profile chrome click e6  # checkbox

# Submit
openclaw browser --browser-profile chrome click e7
openclaw browser --browser-profile chrome wait --text "Signup successful"

Example 3: Handling Authentication and Cookies

Goal: Log into a site and maintain session for multiple operations.

# Navigate to login
openclaw browser --browser-profile chrome navigate "https://example.com/login"

# Fill login form
openclaw browser --browser-profile chrome snapshot --interactive
openclaw browser --browser-profile chrome type e1 "username"
openclaw browser --browser-profile chrome type e2 "password"
openclaw browser --browser-profile chrome click e3  # login button

# Wait for redirect to dashboard
openclaw browser --browser-profile chrome wait --url "**/dashboard"

# Capture the session cookie
openclaw browser --browser-profile chrome cookies --json > session.json

# Now you can do authenticated operations
openclaw browser --browser-profile chrome navigate "https://example.com/api/profile"
openclaw browser --browser-profile chrome screenshot

# Later, restore the session by importing the cookies
openclaw browser --browser-profile chrome cookies set auth_token "value" --url "https://example.com"

Security Best Practices (Treat Your Browser Like Your Keys)

This is important enough that we're saying it clearly: when you attach the OpenClaw extension to a Chrome tab, you're giving an AI agent the same access your browser has. If you're logged into your email, the agent can read your email. If you're logged into your bank, the agent can see your account details. This isn't a paranoia thing—it's just how browser access works.

Risk Assessment

If you use Chrome extension relay on your daily-driver browser:

• Risk: Very High
• What could go wrong: OpenClaw could accidentally read sensitive emails, visit malicious sites you're logged into, steal your data
• Recommendation: Don't do this

If you use Chrome extension relay on a dedicated profile just for OpenClaw:

• Risk: Medium
• What could go wrong: Agent can still access any sites logged into on that profile
• Recommendation: Best practice for extension relay

If you use managed browser profile:

• Risk: Low-Medium
• What could go wrong: Isolated from personal profile, but agent still controls a browser instance
• Recommendation: Use this for production and team setups

Actual Security Practices

1. Use a Dedicated Browser Profile

Create a separate Chrome profile just for OpenClaw automation. This way, even if something goes wrong, your personal browsing is completely separate.

In Chrome: Settings → Profiles → Add Profile → "Automation" → attach the extension to this profile only.

2. Limit What You Attach

Don't attach to sensitive tabs (banking, email, password managers). Only attach to tabs where you're comfortable with OpenClaw having full access.

3. Keep the Relay Local

The relay server should ONLY listen on localhost (127.0.0.1). Never expose it to your network or the internet. Your browser and the relay should be on the same machine.

In your config, make sure you never have:

// DON'T DO THIS
"cdpUrl": "http://192.168.1.100:18792"  // Network accessible
"cdpUrl": "http://0.0.0.0:18792"        // Internet accessible

4. Secure Remote Access (If Needed)

If your Gateway runs remotely and needs to control a browser on your machine, use a node host on the browser machine. The node host and relay stay local, and only the gateway connection goes over the network (which you should tunnel through Tailscale or SSH).

5. Monitor What The Agent Does

Before running automation against sensitive sites, check the logs:

openclaw browser --browser-profile chrome requests --filter api
openclaw browser --browser-profile chrome console --level error

Understand what requests are being made and what errors occur. Sanity-check that the agent is only doing what you asked.

6. Use the Managed Browser for Production

If this is anything you're deploying or sharing with a team, use the managed browser profile, not the extension relay. It's safer and more maintainable. For building secure, production-grade AI assistants, check out our complete guide on building OpenClaw AI assistants.

Troubleshooting: When Things Break (And They Will)

Extension Badge Shows "!" (Not Connected)

What it means: The extension can't reach the relay server.

Checklist:

1. Is the OpenClaw Gateway running? ps aux | grep openclaw or check your terminal
2. Is port 18792 open? lsof -i :18792 (on Mac/Linux)
3. Is anything else using port 18792? netstat -an | grep 18792
4. Is the Gateway started with browser enabled? Check config: cat ~/.openclaw/openclaw.json | grep -A5 browser
5. Try restarting: Close Chrome completely (including background processes), kill the Gateway, then restart both

If none of that works, check the extension Options page (right-click extension → Options) to see what relay URL it's trying to connect to and whether it can reach it.

"Snapshot" Command Returns Empty

What it means: Either the page hasn't loaded yet, or Playwright isn't installed.

Checklist:

1. Wait for the page to load first: openclaw browser wait --load networkidle
2. Verify Playwright is installed: npm list playwright in your OpenClaw directory
3. Check the page actually has content: openclaw browser screenshot to see if anything rendered
4. Try the role snapshot: openclaw browser snapshot --interactive

Click or Type Commands Fail

What it means: The ref number is wrong, the element isn't visible, or the element is covered by something else.

How to debug:

1. Take a fresh snapshot to get updated refs: openclaw browser snapshot --interactive
2. Use the new refs from that snapshot
3. If it still fails, use highlight to see what it's actually trying to click: openclaw browser highlight e12
4. Take a screenshot to visually confirm: openclaw browser screenshot
5. Check browser console for JS errors: openclaw browser console --level error

Extension Won't Load in Chrome

What it means: The path is wrong, or Chrome can't find the files.

Checklist:

1. Get the correct path: openclaw browser extension path
2. Verify the folder exists and has files: ls -la /path/from/above/
3. In Chrome, try "Load unpacked" again, selecting the exact folder
4. If it still fails, check browser console for errors: Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows)
5. Sometimes Chrome needs a restart and extension reload: Close Chrome, reopen, and reload the extension

Tab Commands Timeout

What it means: Usually the page is stuck loading, or there's a network issue.

How to fix:

1. Manually navigate in the browser to see if the page loads
2. Check if you're behind a corporate proxy that blocks the site
3. Try a simpler wait: openclaw browser wait --timeout-ms 5000
4. Check network requests: openclaw browser requests
5. If the wait hangs, Ctrl+C and try without waiting

Key Takeaways (What Actually Matters)

Browser automation with OpenClaw is powerful but requires understanding the architecture. Here's what to remember:

• Three parts work together: The Gateway (makes decisions), the browser control service (translates commands), and the extension (gives hands to your browser)
• Extension relay is convenience, not production: Great for testing, use a dedicated profile, not risky for sensitive work
• Managed browser is the right choice for scaling: Isolated, safer, better for teams
• Snapshots are your debugging tool: When something fails, take a snapshot and you'll usually see the problem
• Security matters more than convenience: Don't attach to sensitive tabs, keep the relay on localhost, use separate profiles
• The agent figures out the details: You don't need to write automation scripts; you describe what you need, and the agent determines the sequence of browser actions

If you're just starting, install the extension, test locally, and get familiar with the snapshot command. That's 90% of what you need. Once that works, you can explore managed profiles, remote setup, and advanced automation.

Start small. Test on pages you control. Then expand to real workflows. The rest is just repetition.

Questions or issues? Check the official OpenClaw documentation at docs.openclaw.ai. For browser-specific issues, see the browser troubleshooting guide and Chrome extension documentation.

Want to see OpenClaw in action? Check out our interactive web story showing how we built a Reddit-like social network using OpenClaw browser automation.

Last updated: February 2, 2026