Appearance
OpenClaw 浏览器 Linux 故障排查指南
OpenClaw 在 Linux 上浏览器控制失败时，常见原因是系统默认的 snap Chromium 受 AppArmor 限制。推荐直接安装官方 Google Chrome 并配置 executablePath，或使用 attachOnly 模式挂载手动启动的 snap Chromium 实例。验证浏览器是否正常工作可通过 curl -s http://127.0.0.1:18791/ | jq 检查运行状态。
问题：「Failed to start Chrome CDP on port 18800」
OpenClaw 浏览器控制服务无法启动 Chrome/Brave/Edge/Chromium，报错如下：
{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}根本原因
在 Ubuntu（及许多 Linux 发行版）上，默认 Chromium 安装是 snap 包。snap 的 AppArmor 沙盒机制会干扰 OpenClaw 启动和监控浏览器进程的方式。
apt install chromium 命令安装的是一个会重定向到 snap 的桩包：
Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).这不是真正的浏览器——只是一个包装器。
其他常见的 Linux 启动失败原因：
The profile appears to be in use by another Chromium process表示 Chrome 在被管理的 profile 目录中发现了过期的Singleton*锁文件。当锁指向一个已死亡或不同主机的进程时，OpenClaw 会移除这些锁并重试一次。Missing X server or $DISPLAY表示在没有桌面会话的主机上显式请求了可见浏览器。默认情况下，当DISPLAY和WAYLAND_DISPLAY都未设置时，本地托管 profile 会在 Linux 上回退到无头模式。如果你设置了OPENCLAW_BROWSER_HEADLESS=0、browser.headless: false或browser.profiles.<name>.headless: false，请移除该头部覆盖设置，设置OPENCLAW_BROWSER_HEADLESS=1、启动Xvfb、运行openclaw browser start --headless进行一次性托管启动，或者在真实的桌面会话中运行 OpenClaw。
方案一：安装 Google Chrome（推荐）
安装官方 Google Chrome .deb 包，它不受 snap 沙盒约束：
bash
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 # 如有依赖错误然后更新 OpenClaw 配置（~/.openclaw/openclaw.json）：
json
{
"browser": {
"enabled": true,
"executablePath": "/usr/bin/google-chrome-stable",
"headless": true,
"noSandbox": true
}
}方案二：以仅挂载模式使用 snap Chromium
如果必须使用 snap Chromium，可以配置 OpenClaw 挂载手动启动的浏览器：
- 更新配置：
json
{
"browser": {
"enabled": true,
"attachOnly": true,
"headless": true,
"noSandbox": true
}
}- 手动启动 Chromium：
bash
chromium-browser --headless --no-sandbox --disable-gpu \
--remote-debugging-port=18800 \
--user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
about:blank &- 可选：创建 systemd 用户服务让浏览器开机自启：
ini
# ~/.config/systemd/user/openclaw-browser.service
[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target
[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target启用服务：systemctl --user enable --now openclaw-browser.service
验证浏览器是否正常工作
检查状态：
bash
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'测试浏览：
bash
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs配置参数参考
| 选项 | 说明 | 默认值 |
|---|---|---|
browser.enabled | 启用浏览器控制 | true |
browser.executablePath | Chromium 内核浏览器二进制路径（Chrome/Brave/Edge/Chromium） | 自动检测（偏好在基于 Chromium 时的默认浏览器） |
browser.headless | 无界面运行 | false |
OPENCLAW_BROWSER_HEADLESS | 针对本地托管浏览器的无头模式按进程覆盖 | 未设置 |
browser.noSandbox | 添加 --no-sandbox 标志（部分 Linux 环境必需） | false |
browser.attachOnly | 不启动浏览器，仅挂载已有实例 | false |
browser.cdpPort | Chrome DevTools Protocol 端口 | 18800 |
browser.localLaunchTimeoutMs | 本地托管 Chrome 发现超时 | 15000 |
browser.localCdpReadyTimeoutMs | 本地托管启动后 CDP 就绪超时 | 8000 |
在树莓派、老旧 VPS 主机或慢速存储上，当 Chrome 需要更长时间暴露其 CDP HTTP 端点时，可以调高 browser.localLaunchTimeoutMs。当启动成功但 openclaw browser start 仍报告 not reachable after start 时，可以调高 browser.localCdpReadyTimeoutMs。值必须是正整数，上限 120000 ms；无效配置值将被拒绝。
问题：「No Chrome tabs found for profile="user"」
你使用了 existing-session / Chrome MCP profile。OpenClaw 能找到本地 Chrome，但没有可挂载的已打开标签页。
解决方式：
- 使用托管浏览器：
openclaw browser start --browser-profile openclaw（或设置browser.defaultProfile: "openclaw"）。 - 使用 Chrome MCP：确保本地 Chrome 已运行且至少有一个打开的标签页，然后用
--browser-profile user重试。
注意：
user仅限主机本地。对于 Linux 服务器、容器或远程主机，优先使用 CDP profiles。user/ 其他existing-sessionprofiles 保持当前 Chrome MCP 限制：基于引用的操作、单文件上传钩子、无对话框超时覆盖、无wait --load networkidle以及无responsebody、PDF 导出、下载拦截或批处理操作。- 本地
openclawprofiles 自动分配cdpPort/cdpUrl；仅对远程 CDP 设置这些值。 - 远程 CDP profiles 接受
http://、https://、ws://和wss://。使用 HTTP(S) 进行/json/version发现，或使用 WS(S) 当浏览器服务提供直接 DevTools 套接字 URL。
常见问题
为什么 Linux 上安装了 Chrome 还是报端口 18800 启动失败？
最常见原因是 browser.executablePath 未指向正确的浏览器二进制文件。确保配置中 executablePath 设置为 /usr/bin/google-chrome-stable（或实际安装路径）。另外，检查是否存在 snap 守护进程冲突，可尝试添加 browser.noSandbox: true。
snap Chromium 在 OpenClaw 中无法正常使用怎么办？
snap Chromium 受 AppArmor 限制，无法被 OpenClaw 直接托管启动。建议改用方案一安装 Google Chrome，如果必须用 snap，则按照方案二配置 attachOnly: true 并手动启动浏览器，或创建 systemd 服务让其自动运行。
如何快速验证浏览器控制是否正常工作？
运行 curl -s http://127.0.0.1:18791/ | jq 检查 running、pid 和 chosenBrowser 字段。如果 running 为 true 且 chosenBrowser 显示正确，说明浏览器控制正常运行。否则，检查 OpenClaw 日志或浏览器进程状态。