Fix OpenClaw Browser Issues on Linux

I’ve spent plenty of time debugging setup issues that looked like code bugs but were actually just OS quirks. On Linux, package managers sometimes do things behind the scenes that break how tools interact with the system. If you are seeing errors when launching a browser through OpenClaw, you are likely hitting a permissions wall caused by how your distribution handles browser packages.

The most common issue happens because Ubuntu and other distros use Snap for Chromium. This creates a sandbox that prevents OpenClaw from talking to the browser correctly. Here is how I fix it.

What You’ll Need

• A Linux distribution (like Ubuntu)
• OpenClaw installed and initialized
• Sudo access for package installation

Quick Start: The Recommended Fix

The fastest way to get running is to move away from the Snap version of Chromium and use the official Google Chrome .deb package. It isn’t sandboxed by Snap, so OpenClaw can manage it without issues.

1. Install Google Chrome:

   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

2. Update your config: Open ~/.openclaw/openclaw.json and set the executablePath to point to the new binary:

   {
     "browser": {
       "enabled": true,
       "executablePath": "/usr/bin/google-chrome-stable",
       "headless": true,
       "noSandbox": true
     }
   }

Troubleshooting

Error: “Failed to start Chrome CDP on port 18800”

If you see this error, it means the browser control server couldn’t launch the process. This usually happens because apt install chromium actually installs a Snap wrapper, not a real binary.

Alternative Solution: Use Snap Chromium with Attach-Only Mode

If you cannot install the .deb package, you can manually start the browser and tell OpenClaw to just “attach” to it.

1. Update your config:

   {
     "browser": {
       "enabled": true,
       "attachOnly": true,
       "headless": true,
       "noSandbox": true
     }
   }

2. Start Chromium manually:

   chromium-browser --headless --no-sandbox --disable-gpu \
     --remote-debugging-port=18800 \
     --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
     about:blank &

Error: “Chrome extension relay is running, but no tab is connected”

This happens when you use the chrome profile. It expects the OpenClaw browser extension to be active in a tab.

I recommend these two fixes:

1. Use the managed browser: Run openclaw browser start --browser-profile openclaw or set browser.defaultProfile: "openclaw" in your JSON.
2. Use the extension relay: Install the extension, open a tab, and click the OpenClaw icon to attach it manually.

Verifying the Browser Works

Once you have applied a fix, I suggest running these commands to make sure everything is communicating:

1. Check status:

   curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

2. Test browsing:

   curl -s -X POST http://127.0.0.1:18791/start
   curl -s http://127.0.0.1:18791/tabs

Config Reference

Option	Description	Default
browser.enabled	Enable browser control	true
browser.executablePath	Path to a Chromium-based browser binary	auto-detected
browser.headless	Run without GUI	false
browser.noSandbox	Add --no-sandbox flag	false
browser.attachOnly	Don’t launch browser, only attach to existing	false
browser.cdpPort	Chrome DevTools Protocol port	18800

If you hit any other snags with your Linux setup, check the AI Setup Assistant.

What’s Next

• Browser Configuration Guide
• CLI Command Reference