Fix: Browser Control Server Hangs on /start (Ubuntu x64)

The OpenClaw browser control server starts a Chromium/Chrome instance when it receives a POST to/start. On Ubuntu x64 servers, Chrome often fails silently due to missing sandbox permissions, no display server, or absent system dependencies — leaving the /start request hanging until the 15-second timeout. Other endpoints like /snapshot and/open may work fine because they don't require Chrome to be fully running.

Step 1: Check What Chrome Is Actually Failing On

# Find the Chrome/Chromium binary OpenClaw uses
which google-chrome || which chromium-browser || which chromium

# Run it manually with verbose output
google-chrome --no-first-run --headless=new --disable-gpu --no-sandbox about:blank 2>&1 | head -30

The output will reveal the actual failure — missing libraries, sandbox error, or no display.

Step 2: Install Missing System Dependencies

Chromium on Ubuntu requires several libraries that are not installed by default on minimal server images:

sudo apt-get update && sudo apt-get install -y   chromium-browser   libasound2   libatk-bridge2.0-0   libatk1.0-0   libcups2   libdbus-1-3   libgbm1   libgtk-3-0   libnspr4   libnss3   libxcomposite1   libxdamage1   libxrandr2   xdg-utils

Step 3: Fix Chromium Sandbox on Servers

Many Ubuntu server configurations disable user namespaces, which Chromium's sandbox requires. Add --no-sandbox to the OpenClaw browser args:

{
  "browser": {
    "args": ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"]
  }
}

Step 4: Add a Virtual Display (if Chromium Requires One)

Some Chromium versions on Ubuntu refuse to start without a display, even in headless mode. Run a virtual framebuffer:

sudo apt-get install -y xvfb

# Start virtual display
Xvfb :99 -screen 0 1280x720x24 &
export DISPLAY=:99

# Add to your shell profile or systemd service for persistence

Step 5: Use Headless Mode in OpenClaw Config

If Chrome can run headless, configure OpenClaw to always use headless mode:

{
  "browser": {
    "headless": true,
    "args": ["--no-sandbox", "--disable-dev-shm-usage"]
  }
}