openclaw-openclaw/docs/tools/browser-linux-troubleshooting.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-06 16:05:11 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green.

Closes #100141

2026-07-05 00:32:47 -04:00

6.7 KiB

Raw Permalink Blame History

summary, read_when, title

summary	read_when	title
Fix Chrome/Brave/Edge/Chromium CDP startup issues for OpenClaw browser control on Linux	Browser control fails on Linux, especially with snap Chromium	Browser troubleshooting

Problem: Failed to start Chrome CDP on port 18800

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

Root cause

On Ubuntu and most Linux distros, apt install chromium installs a snap wrapper, not a real browser:

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

Snap's AppArmor confinement interferes with how OpenClaw spawns and monitors the browser process.

Other common Linux launch failures:

The profile appears to be in use by another Chromium process: stale Singleton* lock files in the managed profile directory. OpenClaw removes these locks and retries once when the lock points at a dead or different-host process.
Missing X server or $DISPLAY: a visible browser was explicitly requested on a host without a desktop session. Local managed profiles fall back to headless mode on Linux when both DISPLAY and WAYLAND_DISPLAY are unset. If you set OPENCLAW_BROWSER_HEADLESS=0, browser.headless: false, or browser.profiles.<name>.headless: false, remove that headed override, set OPENCLAW_BROWSER_HEADLESS=1, start Xvfb, run openclaw browser start --headless for a one-shot managed launch, or run OpenClaw in a real desktop session.

Solution 1: install Google Chrome (recommended)

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

Update ~/.openclaw/openclaw.json:

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

Solution 2: use snap Chromium in attach-only mode

If you must keep snap Chromium, configure OpenClaw to attach to a manually-started browser instead of launching it:

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

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 &

Optionally auto-start it with a systemd user service:

# ~/.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

systemctl --user enable --now openclaw-browser.service

Verify the browser works

curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'
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 (Chrome/Brave/Edge/Chromium)	auto-detected (prefers the OS default browser when Chromium-based)
`browser.headless`	Run without GUI	`false`
`OPENCLAW_BROWSER_HEADLESS`	Per-process override for local managed browser headless mode	unset
`browser.noSandbox`	Add `--no-sandbox` flag (needed for some Linux setups)	`false`
`browser.attachOnly`	Do not launch a browser; only attach to an existing one	`false`
`browser.cdpPortRangeStart`	Starting local CDP port for auto-assigned profiles	`18800` (derived from the gateway port)
`browser.localLaunchTimeoutMs`	Local managed Chrome discovery timeout, up to `120000`	`15000`
`browser.localCdpReadyTimeoutMs`	Local managed post-launch CDP readiness timeout, up to `120000`	`8000`

Both timeout values must be positive integers up to 120000 ms; other values are rejected at config load. On Raspberry Pi, older VPS hosts, or slow storage, raise browser.localLaunchTimeoutMs when Chrome needs more time to expose its CDP HTTP endpoint. Raise browser.localCdpReadyTimeoutMs when launch succeeds but openclaw browser start still reports not reachable after start.

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

You are using the user (existing-session / Chrome MCP) profile and no tabs are open to attach to.

Fix options:

Use the managed browser instead: openclaw browser --browser-profile openclaw start (or set browser.defaultProfile: "openclaw").
Keep local Chrome running with at least one open tab, then retry with --browser-profile user.

Notes:

user is host-only. On Linux servers, containers, or remote hosts, prefer CDP profiles instead.
user and other existing-session profiles share the current Chrome MCP limits: ref-driven actions only, one file per upload, no dialog timeoutMs overrides, no wait --load networkidle, and no responsebody, PDF export, download interception, or batch actions.
Local openclaw-driver profiles auto-assign cdpPort/cdpUrl; only set those manually for remote CDP.
Remote CDP profiles accept http://, https://, ws://, and wss://. Use HTTP(S) for /json/version discovery, or WS(S) when your browser service gives you a direct DevTools socket URL.

6.7 KiB Raw Permalink Blame History