Browser troubleshooting

Problem: "Failed to start Chrome CDP on port 18800"

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

text
Copy
{"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

command installs a stub package that redirects to snap:

text
Copy
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.

Other common Linux launch failures:

• text

  Copy

  The profile appears to be in use by another Chromium process
  means Chrome found stale
  text

  Copy

  Singleton*
  lock files in the managed profile directory. OpenClaw removes those locks and retries once when the lock points at a dead or different-host process.
• text

  Copy

  Missing X server or $DISPLAY
  means a visible browser was explicitly requested on a host without a desktop session. By default, local managed profiles now fall back to headless mode on Linux when
  text

  Copy

  DISPLAY
  and
  text

  Copy

  WAYLAND_DISPLAY
  are both unset. If you set
  text

  Copy

  OPENCLAW_BROWSER_HEADLESS=0
  ,
  text

  Copy

  browser.headless: false
  , or
  text

  Copy

  browser.profiles.<name>.headless: false
  , remove that headed override, set
  text

  Copy

  OPENCLAW_BROWSER_HEADLESS=1
  , start
  text

  Copy

  Xvfb
  , run
  text

  Copy

  openclaw browser start --headless
  for a one-shot managed launch, or run OpenClaw in a real desktop session.

Solution 1: Install Google Chrome (Recommended)

Install the official Google Chrome

package, which is not sandboxed by snap:

bash
Copy
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 (

):

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

Solution 2: Use Snap Chromium with Attach-Only Mode

If you must use snap Chromium, configure OpenClaw to attach to a manually-started browser:

1. Update config:

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

2. Start Chromium manually:

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

3. Optionally create a systemd user service to auto-start Chrome:

ini
Copy
# ~/.config/systemd/user/openclaw-browser.service
[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Enable with:

Verifying the Browser Works

Check status:

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

Test browsing:

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

Config reference

On Raspberry Pi, older VPS hosts, or slow storage, raise

when Chrome needs more time to expose its CDP HTTP endpoint. Raise when launch succeeds but still reports . Values must be positive integers up to ms; invalid config values are rejected.

Problem: "No Chrome tabs found for profile="user""

You're using an

/ Chrome MCP profile. OpenClaw can see local Chrome, but there are no open tabs available to attach to.

Fix options:

1. Use the managed browser:
   text

   Copy

   openclaw browser start --browser-profile openclaw
   (or set
   text

   Copy

   browser.defaultProfile: "openclaw"
   ).
2. Use Chrome MCP: make sure local Chrome is running with at least one open tab, then retry with
   text

   Copy

   --browser-profile user
   .

Notes:

• text

  Copy

  user
  is host-only. For Linux servers, containers, or remote hosts, prefer CDP profiles.
• text

  Copy

  user
  / other
  text

  Copy

  existing-session
  profiles keep the current Chrome MCP limits: ref-driven actions, one-file upload hooks, no dialog timeout overrides, no
  text

  Copy

  wait --load networkidle
  , and no
  text

  Copy

  responsebody
  , PDF export, download interception, or batch actions.
• Local
  text

  Copy

  openclaw
  profiles auto-assign
  text

  Copy

  cdpPort
  /
  text

  Copy

  cdpUrl
  ; only set those for remote CDP.
• Remote CDP profiles accept
  text

  Copy

  http://
  ,
  text

  Copy

  https://
  ,
  text

  Copy

  ws://
  , and
  text

  Copy

  wss://
  . Use HTTP(S) for
  text

  Copy

  /json/version
  discovery, or WS(S) when your browser service gives you a direct DevTools socket URL.

Related

• Browser
• Browser login
• Browser WSL2 troubleshooting