在无头 Linux 环境下配置 OpenClaw 浏览器的排障记录

在无头 Linux 环境下完整配置 OpenClaw 浏览器的详细排障指南

问题背景：为何浏览器启动失败

许多开发者在无图形界面（Headless）的 Linux 服务器或 WSL 子系统上部署 OpenClaw 时，常遇到浏览器服务无法启动的问题。执行 openclaw browser status 命令后，状态显示始终为 running: false。这通常是由无头环境下的浏览器调用限制与配置缺失共同导致的。本文将从零开始，详细记录在一个纯净的 Linux 环境中，完成从浏览器安装到解决所有常见报错的完整流程，确保 OpenClaw 能够稳定运行。

问题排查与系统化解决方案

1. 正确安装 Chrome 浏览器及修复依赖报错

首先需要明确一个关键点：通过 Linux 系统包管理器（如 apt 或 yum）直接安装的 Chromium 版本，常受到 snap 沙盒或 AppArmor 安全策略的限制，导致 OpenClaw 无法正常调用其二进制文件。因此，最可靠的方案是手动下载并安装 Google Chrome 官方发布的独立 .deb 安装包，以避免系统级干扰。

通过命令行下载最新的稳定版 Chrome 包：

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

然而，直接安装可能会失败并提示缺少依赖，例如 fonts-liberation 等。无需手动查找缺失包，使用 Linux 的包修复命令可以自动处理所有依赖关系并完成 Chrome 的安装，这是最高效的解决方案：

sudo apt --fix-broken install -y

2. 适配无头环境：配置 OpenClaw 核心参数

浏览器安装成功后，需配置 OpenClaw 使其能够正确识别浏览器路径并适应无桌面环境。标准流程是启用无头模式，并关闭沙盒安全选项，以规避 Headless 系统下的权限问题。

在终端中执行以下配置命令，设定关键参数：

# 设置 Chrome 可执行文件路径
openclaw config set browser.executablePath “/usr/bin/google-chrome-stable”
# 开启无图形界面模式
openclaw config set browser.headless true
# 为Linux无头环境禁用沙盒模式
openclaw config set browser.noSandbox true

3. 解决关键错误 “no tab is connected”

完成基础配置后，若直接尝试启动浏览器服务 (openclaw browser start)，可能遭遇新错误提示：

Error: Chrome extension relay is running, but no tab is connected.

此错误的根源在于，OpenClaw 默认使用了 chrome 配置文件，该模式为“浏览器扩展中继模式”，要求在有图形界面的浏览器中人工点击插件图标建立连接，这在无头服务器上不可行。解决方案是将其切换为由 OpenClaw 自主管理的独立配置文件。

执行命令切换至内置的托管配置文件：

openclaw config set browser.defaultProfile “openclaw”

4. 最终重启与运行状态验证

完成全部配置修改后，必须重启相关服务以使所有新设置生效。这是确保配置成功的关键收尾步骤。

# 重启网关服务以保证配置加载
openclaw gateway restart
# 启动浏览器服务
openclaw browser start
# 验证最终运行状态
openclaw browser status

当终端输出结果显示 profile: openclaw 且 running: true 时，表明无头浏览器已在 OpenClaw 管理下成功启动并稳定运行，配置至此全部完成。