Troubleshooting: Browser Won’t Start Inside the OpenClaw Container

Problem description

OpenClaw runs inside a Docker container, and the browser tool can’t launch Chrome. It throws: timed out. Restart the OpenClaw gateway.

Running chromium --headless --no-sandbox by hand on the host works fine, but the Chrome instance OpenClaw starts always times out.

Investigation

1. First attempt: noSandbox

Added browser.noSandbox: true per the docs. No effect.

2. Attempt: adding extraArgs

"browser": {
  "noSandbox": true,
  "extraArgs": [
    "--disable-setuid-sandbox",
    "--disable-namespace-sandbox"
  ]
}

Still timing out after a restart.

3. The key finding: headless mode

The logs showed Browser control service ready, so the browser service itself was fine — but Chrome was timing out on startup.

Running the following command by hand worked perfectly:

chromium --headless --no-sandbox --disable-gpu --dump-dom "data:text/html,<h1>test</h1>"

The key clue: browser.status reported headless: false — the change in the config file (headless: true) never took effect through a SIGUSR1 hot restart. The container needed a full restart.

4. The fix: restart the Gateway completely

After restarting the container, headless: true took effect and the browser worked immediately.

Root cause

The core issue: a snap chromium stub inside a container needs headless mode. With headless: false, Chrome tries to open a GUI window, and since the container has no display device, it times out.

Final configuration

"browser": {
  "enabled": true,
  "headless": true,
  "noSandbox": true,
  "extraArgs": [
    "--disable-setuid-sandbox",
    "--disable-namespace-sandbox"
  ]
}

Lessons learned

1. A SIGUSR1 hot restart can’t fully apply some browser config fields (headless)
2. When running Chrome inside a container, headless: true is mandatory
3. The headless value in browser.status reflects the currently running config, not the config file value — which makes it useful for diagnosing whether a config change actually took effect

Related docs

• /app/docs/tools/browser.md
• /app/docs/tools/browser-linux-troubleshooting.md