Browser Troubleshooting (Linux)

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

OpenClaw’s browser control server fails to launch Chrome/Brave/Edge/Chromium with the error:

{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}

Root Cause

On Ubuntu (and many Linux distros), the default Chromium installation is a snap package. Snap’s AppArmor confinement interferes with how OpenClaw spawns and monitors the browser process. The apt install chromium command installs a stub package that redirects to snap:

Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).

This is NOT a real browser — it’s just a wrapper.

Solution 1: Install Google Chrome (Recommended)

Install the official Google Chrome .deb package, which is not sandboxed by snap:

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  # if there are dependency errors

Then update your OpenClaw config (~/.openclaw/openclaw.json):

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

Then restart the gateway and try again:

pkill -f openclaw-gateway
openclaw gateway run

Solution 2: Use snap Chromium with attach-only mode

If you must use snap Chromium, configure OpenClaw to only attach to a browser you launch manually:

Update config:

{
  "browser": {
    "attachOnly": true
  }
}

Launch Chromium manually:

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

(Advanced) Set up a systemd service or cron job to auto-start the above.

Solution 3: Use WSL2 (if on Windows)

If you are on Windows, using WSL2 (Windows Subsystem for Linux) can simplify browser setup:

# Inside WSL2
sudo apt-get install -y google-chrome-stable
# Then set executablePath: "/usr/bin/google-chrome-stable"

Verify the browser is working

Use curl to test the local API:

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

# Start and list tabs
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

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

This means you are using the chrome profile (extension relay mode) and the system is waiting for the extension to connect a tab.

Fix 1: Use the managed browser instead: openclaw browser start --browser-profile openclaw
Fix 2: Install the Chrome extension, open a tab, and click the extension icon to attach.

Browser Login（瀏覽器登入）WSL2 + Windows + remote Chrome CDP troubleshooting（WSL2 + Windows + 遠端 Chrome CDP 疑難排解）

總覽

外掛程式

技能

自動化

工具

Agent 協調

Browser Troubleshooting（瀏覽器疑難排解）

Browser Troubleshooting (Linux)

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

Root Cause

Solution 1: Install Google Chrome (Recommended)

Solution 2: Use snap Chromium with attach-only mode

Solution 3: Use WSL2 (if on Windows)

Verify the browser is working

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

​Browser Troubleshooting (Linux)

​Problem: “Failed to start Chrome CDP on port 18800”

​Root Cause

​Solution 1: Install Google Chrome (Recommended)

​Solution 2: Use snap Chromium with attach-only mode

​Solution 3: Use WSL2 (if on Windows)

​Verify the browser is working

​Common issue: “Chrome extension relay is running, but no tab is connected”

Browser Troubleshooting (Linux)

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

Root Cause

Solution 1: Install Google Chrome (Recommended)

Solution 2: Use snap Chromium with attach-only mode

Solution 3: Use WSL2 (if on Windows)

Verify the browser is working

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