OpenClaw 容器内浏览器无法启动问题排查

问题描述

OpenClaw 运行在 Docker 容器内，浏览器工具（browser tool）无法启动 Chrome，报错：timed out. Restart the OpenClaw gateway.

手动执行 chromium --headless --no-sandbox 可以在宿主机正常工作，但 OpenClaw 启动的 Chrome 始终超时。

排查过程

1. 初步尝试：noSandbox

根据文档添加 browser.noSandbox: true，无效。

2. 尝试：添加 extraArgs

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

重启后仍然超时。

3. 关键发现：headless 模式

日志显示 Browser control service ready，说明 browser 服务正常，但 Chrome 启动超时。

手动执行以下命令完全正常：

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

关键线索：browser.status 显示 headless: false —— 配置文件的修改（headless: true）通过 SIGUSR1 热重启没有生效，需要完整重启容器。

4. 解决：完整重启 Gateway

容器重启后，headless: true 生效，浏览器立即正常工作。

根本原因

参数	作用	状态
`noSandbox: true`	禁用 Chrome sandbox	✅ 之前已加
`extraArgs: ["--disable-setuid-sandbox", "--disable-namespace-sandbox"]`	禁用 Linux namespace sandbox	✅ 本次加
`headless: true`	无头模式（不尝试打开 GUI 窗口）	❌ 热重启未生效，完整重启后生效

核心问题： snap chromium stub 在容器里需要 headless 模式。headless: false 时 Chrome 尝试打开 GUI 窗口，容器无显示设备导致超时。

最终配置

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

教训

SIGUSR1 热重启对 browser 配置的部分字段（headless）不能完全生效
容器内跑 Chrome，headless: true 是必须的
browser.status 的 headless 值反映的是当前运行配置，不是配置文件值——可用于诊断配置是否真正生效