OpenClawSkills
GitHub
Tools & Skills • TutorialHeader.readTime

Browser Troubleshooting

Fix Chrome/Brave/Edge/Chromium CDP startup issues for OpenClaw browser control on Linux

Tutorial.step

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

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

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

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:

Terminal
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.

Tutorial.step

Solution 1: Install Google Chrome (Recommended)

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

Bash
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''):

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

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
{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}

2. Start Chromium manually:

Bash
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
[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: ''systemctl --user enable --now openclaw-browser.service''

Tutorial.step

Verifying the Browser Works

Check status:

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

Test browsing:

Bash
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs
Tutorial.step

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 default browser when Chromium-based) |

| ''browser.headless'' | Run without GUI | ''false'' |

| ''browser.noSandbox'' | Add ''--no-sandbox'' flag (needed for some Linux setups) | ''false'' |

| ''browser.attachOnly'' | Don't launch browser, only attach to existing | ''false'' |

| ''browser.cdpPort'' | Chrome DevTools Protocol port | ''18800'' |

Tutorial.step

Problem: "Chrome extension relay is running, but no tab is connected"

You're using the ''chrome'' profile (extension relay). It expects the OpenClaw browser extension to be attached to a live tab.

Fix options:

1. ''Use the managed browser:'' ''openclaw browser start --browser-profile openclaw''

(or set ''browser.defaultProfile: "openclaw"'').

2. Use the extension relay: install the extension, open a tab, and click the OpenClaw extension icon to attach it.

Notes:

- The ''chrome'' profile uses your ''system default Chromium browser'' when possible.

- Local ''openclaw'' profiles auto-assign ''cdpPort''/''cdpUrl''; only set those for remote CDP.