Browser Automation — Setup, Extensions & Troubleshooting

## 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 status openclaw browser status --json # Start managed browser openclaw browser start --profile openclaw # Check available tabs openclaw 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 2. **Start the relay if not running:** bash openclaw browser serve --port 18792 3. **In the extension settings:** - Set port to 18792 (or your chosen port) - You should see: "Relay reachable at http://127.0.0.1:18792/" 4. **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 processes pkill -f Chrome # or on macOS killall "Google Chrome" # Restart gateway openclaw gateway restart # Restart browser relay openclaw 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 installed which chromium-browser which google-chrome-stable # If using snap chromium, install Google Chrome instead wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo dpkg -i google-chrome-stable_current_amd64.deb sudo apt --fix-broken install -y # Then set the executable path openclaw 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 port ssh -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 port openclaw browser serve --port 18791 **Verify the setup:** bash # On gateway side, check connected nodes openclaw nodes list --connected # On Mac, check node status openclaw node status --json # Trigger a browser request through the gateway openclaw 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 work openclaw browser --browser-profile openclaw start openclaw browser --browser-profile openclaw snapshot # If snapshot fails, check for Playwright errors in logs openclaw 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 latest npm install -g openclaw@latest openclaw gateway restart # Or build from git cd ~/openclaw && git pull && pnpm install && pnpm build openclaw daemon restart

## Step 6: Fix Brave Browser Specific Issues Brave requires explicit path configuration: Install Brave properly (not flatpak): ``bash # Remove flatpak version flatpak uninstall com.brave.Browser # Install via apt sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg \ https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg echo "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.list sudo 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 processes pkill -f Chrome || pkill -f chromium || pkill -f brave # Kill gateway openclaw gateway stop # Wait a moment sleep 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 start openclaw browser start --profile openclaw openclaw 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 } } }