Browser Linux 故障排查

概述

Linux 环境下 OpenClaw 浏览器控制启动失败的排查指南，主要针对 snap 版 Chromium 的 AppArmor 限制问题。

核心功能

常见问题与根因

问题：Failed to start Chrome CDP on port 18800

根因：Ubuntu 默认 apt install chromium 安装的是 snap 包装器（非真实浏览器），snap 的 AppArmor 限制干扰 OpenClaw 的进程管理。

其他常见失败：

• The profile appears to be in use by another Chromium process：stale Singleton* 锁文件，OpenClaw 会自动清理并重试
• Missing X server or $DISPLAY：无桌面环境时请求有头浏览器，Linux 上默认自动回退到 headless 模式

解决方案

方案一（推荐）：安装 Google Chrome .deb 包

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

配置：

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

方案二：snap Chromium + attach-only 模式

chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &

配置 attachOnly: true，可选创建 systemd user service 自动启动。

配置/权限

配置项	说明	默认值
browser.executablePath	浏览器二进制路径	自动检测
browser.headless	无 GUI 运行	false
browser.noSandbox	添加 --no-sandbox	false
browser.attachOnly	仅附加，不启动	false
browser.cdpPort	CDP 端口	18800
browser.localLaunchTimeoutMs	启动超时（慢机器需调大）	15000

验证：

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

相关页面

• tool-browser — 浏览器工具概述
• tool-browser-wsl2-troubleshooting — WSL2/Windows 故障排查