11.14 浏览器故障排除

OpenClaw 浏览器工具的常见问题诊断与修复指南，特别针对 Linux 系统的问题。

概述

本章节主要解决 Linux 系统上浏览器启动和连接问题，以及跨平台的扩展程序中继连接问题。

问题：Chrome CDP 在端口 18800 启动失败

问题表现

在 Linux 上尝试启动浏览器工具时，遇到以下错误：

Failed to start Chrome CDP on port 18800

根本原因

Snap Chromium 由于沙箱限制，会阻止 OpenClaw 启动浏览器进程。Snap Chromium 不是真正的浏览器，而是一个包装器。

解决方案 1：安装 Google Chrome（推荐）

安装官方的 Google Chrome：

# 下载 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": {
    "executablePath": "/usr/bin/google-chrome-stable",
    "noSandbox": true
  }
}

解决方案 2：使用 Snap Chromium 的附加模式

如果必须使用 Snap Chromium，启用附加模式：

{
  "browser": {
    "attachOnly": true
  }
}

手动启动 Chromium 并开启 CDP：

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

或使用 systemd 用户服务：

systemctl --user enable --now openclaw-browser.service

验证浏览器是否正常工作

检查浏览器状态

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

启动浏览器

curl -s -X POST http://127.0.0.1:18791/start

查看打开的标签页

curl -s http://127.0.0.1:18791/tabs

配置参考

浏览器配置选项

• browser.headless：默认为 false（有头模式）
• browser.noSandbox：某些 Linux 环境需要设置为 true
• browser.executablePath：指定浏览器可执行文件路径
• browser.attachOnly：仅附加到现有浏览器实例

配置文件示例

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

问题：Chrome 扩展中继运行中，但没有标签页连接

问题表现

扩展中继服务显示运行中，但提示：

Chrome extension relay is running, but no tab is connected

原因

没有活跃的浏览器标签页附加了 OpenClaw 扩展程序。

解决方案

方法 1：使用 OpenClaw 浏览器配置文件

openclaw browser --browser-profile openclaw

方法 2：手动安装扩展

1. 在浏览器中安装 OpenClaw 扩展程序
2. 在任意标签页中点击扩展图标
3. 扩展会自动连接到中继服务

浏览器配置文件说明

• "chrome" 配置文件：使用系统默认 Chromium
• "openclaw" 配置文件：自动分配 CDP 端口，预装扩展

常见诊断命令

# 检查浏览器服务状态
openclaw status

# 查看浏览器日志
openclaw logs | grep browser

# 测试浏览器 API
curl -s http://127.0.0.1:18791/

# 重启浏览器服务
openclaw gateway restart

其他常见问题

浏览器启动超时

增加启动超时时间：

{
  "browser": {
    "launchTimeout": 60000
  }
}

浏览器进程未清理

查找并清理残留进程：

# 查找 Chrome/Chromium 进程
ps aux | grep chrome

# 停止 OpenClaw 浏览器服务
openclaw gateway stop

# 手动终止残留进程
pkill -f "chrome.*remote-debugging-port"

权限问题

确保浏览器数据目录有写权限：

chmod -R u+w ~/.openclaw/browser-data

获取帮助

如果问题持续存在，请收集以下信息：

• 操作系统和版本（lsb_release -a）
• 浏览器类型和版本
• 浏览器配置（openclaw config get browser）
• 浏览器中继状态（curl http://127.0.0.1:18791/）
• 相关日志片段

然后在 GitHub Issues 中报告问题。