🦞OpenClaw Guide
Browser

Browser Automation — Setup, Extensions & Troubleshooting

Complete guide to setting up OpenClaw browser automation, including Chrome Extension Relay, headless browser mode, VPS configurations, remote gateway setups, and fixing common issues like tabs not found and relay not reachable errors.

⚠️ The Problem

Users encounter various browser automation issues including: Chrome Extension Relay showing a red '!' mark and not connecting, headless browser not working on Docker/VPS, the bot opening tabs but unable to see or interact with them, remote gateway setups failing to connect the relay, and browser automation completely failing after updates. Common error messages include:

  • net::ERR_INVALID_ARGUMENT when trying to access tabs
  • Error: HTTP 500 or exec failed: Error: 500
  • Relay not reachable at http://127.0.0.1:18792/
  • Bot says it "can't see" or "can't find" the tab it just opened
  • Playwright is not available in this gateway build
  • Extension shows "Relay reachable" but still has red '!' icon
  • Browser opens but snapshots/actions fail with 501 errors

🔍 Why This Happens

Browser automation issues arise from several sources:

1. Profile Confusion (chrome vs openclaw): OpenClaw has two browser profiles:

  • chrome profile: Requires the Browser Relay extension attached to a tab. If extension isn't installed or tab isn't attached, the agent can't see anything.
  • openclaw profile: Managed browser that works without extensions but requires Playwright.

2. Port Conflicts in SSH Tunnel Setups: When running OpenClaw on a VPS with a local browser, SSH tunnel ports can conflict with local browser serve commands.

3. Missing Dependencies on Linux: Headless Chrome/Chromium on Docker, Raspberry Pi, or Ubuntu may be missing shared libraries, or using the wrong Chromium build (snap vs deb).

4. Remote Gateway Relay Routing: In remote gateway setups with node hosts, the relay starts on-demand when the gateway routes a browser request to that node. The extension talks to 127.0.0.1:18792 on the same machine as Chrome—not the VPS.

5. Extension State Corruption: Browser extension relay can get into a stuck state, especially after updates, requiring a complete restart cycle.

6. Playwright Not Installed: The gateway build may not include Playwright, causing snapshot and action commands to fail even when the browser opens successfully.

✅ The Fix

Step 1: Understand the Two Browser Profiles

OpenClaw has two distinct browser modes:

Profile: chrome (Extension Relay)

  • Uses your existing Chrome with the OpenClaw Browser Relay extension
  • You must click the toolbar icon on a tab to attach it
  • Best for: Local setups, maintaining login sessions, interacting with your real browser

Profile: openclaw (Managed Browser)

  • OpenClaw launches and controls its own browser instance
  • No extension needed, works headlessly
  • Best for: VPS, Docker, automation without user interaction
bash
# Check current browser statusopenclaw browser status --json# Start managed browseropenclaw browser start --profile openclaw# Check available tabsopenclaw browser tabs

Step 2: Fix Chrome Extension Relay Issues

If the extension shows a red '!' icon:

  1. Verify the relay is running:
bash
curl http://127.0.0.1:18792/# Should return "OK" or similar
  1. Start the relay if not running:
bash
openclaw browser serve --port 18792
  1. In the extension settings:
  1. Attach a tab:
  • Navigate to a page in Chrome
  • Click the OpenClaw Browser Relay toolbar icon
  • The badge should turn ON (green/active)

If still not working, try a clean restart:

bash
# Kill any stuck Chrome processespkill -f Chrome# or on macOSkillall "Google Chrome"# Restart gatewayopenclaw gateway restart# Restart browser relayopenclaw browser serve --port 18792

Step 3: Configure Managed Browser (Headless/VPS)

For Docker, VPS, or Raspberry Pi where you want headless operation:

Basic Configuration:

json5
// ~/.openclaw/config.json{  "browser": {    "enabled": true,    "defaultProfile": "openclaw",  // Use managed browser    "headless": true,    "noSandbox": true  // Required for Docker/containers  }}

Docker/Raspberry Pi with Chromium:

json5
{  "browser": {    "enabled": true,    "executablePath": "/usr/bin/chromium",    "headless": true,    "noSandbox": true  }}

Ubuntu - Use Google Chrome, Not Snap Chromium:

bash
# Check which browser is installedwhich chromium-browserwhich google-chrome-stable# If using snap chromium, install Google Chrome insteadwget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudo dpkg -i google-chrome-stable_current_amd64.debsudo apt --fix-broken install -y# Then set the executable pathopenclaw config set browser.executablePath /usr/bin/google-chrome-stable

Step 4: Fix Remote Gateway + Local Browser Setup

When your gateway runs on a VPS but you want to use your local Mac/PC's Chrome:

Architecture:

  • Gateway on VPS (port 18789)
  • Node host on your local machine (Mac/PC)
  • Chrome with extension on your local machine
  • Relay starts on local machine when needed

On the VPS (Gateway side):

json5
// Gateway config{  "gateway": {    "nodes": {      "browser": {        "mode": "node",  // Route browser requests to nodes        "node": "<your-mac-node-id>"  // Pin to specific node      }    }  }}

On your Mac (Node host side):

json5
// Node config{  "nodeHost": {    "browserProxy": {      "enabled": true  // Must be true!    }  },  "browser": {    "enabled": true  // Must not be false  }}

SSH Tunnel Setup (if not using Tailscale):

bash
# Forward gateway port AND browser relay portssh -N \  -L 18789:127.0.0.1:18789 \  -R 18791:127.0.0.1:18791 \  clawdbot@<vps-ip># On local machine, start browser serve on the reverse-tunneled portopenclaw browser serve --port 18791

Verify the setup:

bash
# On gateway side, check connected nodesopenclaw nodes list --connected# On Mac, check node statusopenclaw node status --json# Trigger a browser request through the gatewayopenclaw browser tabs

Step 5: Fix "Can't See" / Tab Not Found Issues

If the bot opens tabs but says it can't see or find them:

Problem: Using chrome profile without extension attached

json5
// Switch to managed browser in config{  "browser": {    "defaultProfile": "openclaw"  // Not "chrome"  }}

Problem: Playwright not available

bash
# Test if snapshots workopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw snapshot# If snapshot fails, check for Playwright errors in logsopenclaw logs --limit 200 | grep -i "browser\|cdp\|playwright\|snapshot"

Problem: Known bug in extension relay (GitHub #1674) This was fixed in commit 6c3a9fc but may not be in your npm version:

bash
# Upgrade to latestnpm install -g openclaw@latestopenclaw gateway restart# Or build from gitcd ~/openclaw && git pull && pnpm install && pnpm buildopenclaw daemon restart

Step 6: Fix Brave Browser Specific Issues

Brave requires explicit path configuration:

Install Brave properly (not flatpak):

bash
# Remove flatpak versionflatpak uninstall com.brave.Browser# Install via aptsudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg \  https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpgecho "deb [signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] \  https://brave-browser-apt-release.s3.brave.com/ stable main" | \  sudo tee /etc/apt/sources.list.d/brave-browser-release.listsudo apt update && sudo apt install brave-browser

Configure OpenClaw for Brave:

json5
{  "browser": {    "enabled": true,    "executablePath": "/usr/bin/brave-browser",    "defaultProfile": "openclaw"  }}

Step 7: The "Force Fix" Approach

When nothing else works, try this nuclear option:

1. Kill everything:

bash
# Kill browser processespkill -f Chrome || pkill -f chromium || pkill -f brave# Kill gatewayopenclaw gateway stop# Wait a momentsleep 3

2. Clear browser state:

bash
# Remove OpenClaw browser profile (will be recreated)rm -rf ~/.openclaw/browser-data/

3. Uninstall and reinstall extension (if using relay):

  • Go to chrome://extensions/
  • Remove OpenClaw Browser Relay
  • Reinstall from the Chrome Web Store

4. Start fresh:

bash
openclaw gateway startopenclaw browser start --profile openclawopenclaw browser snapshot  # Test it works

Pro tip from users: Sometimes removing the relay extension temporarily "forces" the bot to fix the headless browser setup. Once headless works, reinstall the extension and both methods will work.

Recommended Browser Configuration

For local development (with extension):

json5
{  "browser": {    "enabled": true,    "defaultProfile": "chrome",    "controlUrl": "http://127.0.0.1:18792"  }}

For VPS/Docker (headless):

json5
{  "browser": {    "enabled": true,    "defaultProfile": "openclaw",    "executablePath": "/usr/bin/google-chrome-stable",    "headless": true,    "noSandbox": true,    "args": [      "--disable-dev-shm-usage",      "--disable-gpu"    ]  }}

For remote gateway + local browser:

json5
// Gateway config{  "gateway": {    "nodes": {      "browser": {        "mode": "node"      }    }  }}// Node config on local machine{  "nodeHost": {    "browserProxy": {      "enabled": true    }  }}

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
openclaw browser status --jsonCheck current browser configuration and connection status
openclaw browser start --profile openclawStart the managed browser (no extension needed)
openclaw browser start --profile chromeStart browser relay mode (requires extension)
openclaw browser serve --port 18792Start the browser relay server for the Chrome extension
openclaw browser tabsList all available browser tabs
openclaw browser snapshotTake a snapshot of the current page (test browser connectivity)
curl http://127.0.0.1:18792/Test if browser relay is running and reachable
openclaw nodes list --connectedList connected nodes (for remote gateway setups)
openclaw node status --jsonCheck local node status and browser proxy capability
openclaw config set browser.executablePath /path/to/browserSet custom browser executable path
pkill -f ChromeKill all Chrome processes (use when browser is stuck)
openclaw gateway restartRestart gateway after config changes

Related Issues

    📚 You Might Also Like

    Blog

    50 Things to Do With OpenClaw After Setup

    The difference between OpenClaw-as-chatbot and OpenClaw-as-actual-assistant is integrations and automation. Here are 50 real use cases across email, calendar, research, writing, dev, finance, and personal productivity.

    Guide

    How to Set Up OpenClaw on Mac Mini (Perfect Always-On Setup)

    The ideal dedicated AI assistant setup. Buy once, runs forever, no monthly fees for hosting.

    Integration

    Discord

    Add your AI assistant to Discord servers and DMs. Get help, manage tasks, and run automations directly from your Discord channels.

    Feature

    AI Automation — Let AI Take Action For You

    Go beyond chatbots. OpenClaw is AI that actually does things—sends emails, schedules meetings, manages files, controls your smart home. Real automation, not just conversation.

    🐙 Your AI should run your business.

    Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

    Join Vibe Combinator →