Troubleshooting Browser Control Not Working

Fixing Browser Control Issues

Browser control relies on a headless Chromium instance. If it is not working, the issue is usually related to missing dependencies or incorrect configuration.

Error: Chromium Not Found

Error: Could not find Chromium binary

Fix: Install Chromium dependencies:

# Ubuntu/Debian
sudo apt-get install -y chromium-browser

# Or let Puppeteer install its own Chromium
npx puppeteer browsers install chrome

Error: Display Not Available (Linux)

Error: No usable sandbox / Failed to launch browser

Fix: On headless Linux servers, you need a virtual display:

# Install xvfb
sudo apt-get install xvfb

# Run OpenClaw with virtual display
xvfb-run openclaw start

Alternatively, ensure headless mode is enabled in your config:

{
  "browserControl": {
    "headless": true,
    "sandboxEnabled": false
  }
}

Error: Navigation Timeout

Cause: The page takes too long to load, or the URL is blocked.

Fix:

• Increase the navigation timeout: "navigationTimeout": 60000 (60 seconds)
• Check that the target URL is in your domain allowlist
• Verify your server has internet access and DNS resolution works