OpenClaw 浏览器自动化测试的那些坑（一）：Linux Snap 版本的 Chromium 无法使用托管模式

本文记录了在 Linux 服务器上配置 OpenClaw 浏览器自动化功能时，遇到的 Snap 版本 Chromium 无法使用托管模式的坑及解决方案

前言

在部署 OpenClaw AI 助手时，浏览器自动化功能是一个非常强大的特性。它能让 AI 拥有"眼睛"和"双手"，实现网页自动化操控。然而，在 Ubuntu 24.04 服务器上配置这个功能时，却遇到一个意想不到的坑——Snap 版本的 Chromium 无法使用托管模式。

问题现象

在腾讯云 Ubuntu 24.04 LTS 服务器上部署 OpenClaw 后，尝试通过 AI 打开网页时遇到错误：

我无法访问浏览器控制服务。请先启动 OpenClaw 网关...

检查浏览器服务状态：

openclaw browser status

输出显示：

profile: openclaw
enabled: true
running: false
cdpReady: false
detectedBrowser: Chromium
detectedPath: /usr/bin/chromium-browser

尝试手动启动浏览器：

openclaw browser start

依然报错：

Error: Browser attachOnly is enabled and profile "openclaw" is not running.

根因分析

Ubuntu 24.04 的 Chromium 其实是 Snap 版本

执行以下命令验证：

file /usr/bin/chromium-browser

输出：

/usr/bin/chromium-browser: POSIX shell script, ASCII text executable

原来 chromium-browser 只是一个 shell 脚本，用于启动 Snap 容器中的 Chromium！

为什么 Snap 版本无法工作？

Snap 是一种沙盒化的包管理系统，Snap 版本的 Chromium 运行在独立的沙盒环境中，有以下限制：

1. CDP 端口无法暴露：OpenClaw 需要通过 Chrome DevTools Protocol (CDP) 控制浏览器，但 Snap 版本的 Chromium 由于安全隔离，无法将 CDP 端口映射到主机
2. 沙盒限制：Snap 应用的沙盒机制会阻止外部进程对浏览器进行控制
3. 存根程序：/usr/bin/chromium-browser 只是一个启动器，真正的浏览器在 Snap 容器的另一端

这导致 OpenClaw 的托管模式（managed mode）完全无法使用，因为 OpenClaw 需要直接启动和控制浏览器进程。

解决方案

方案一：安装官方 Google Chrome（推荐）

这是最直接有效的解决方案。

1. 下载安装包

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

2. 安装 Chrome

sudo dpkg -i google-chrome-stable_current_amd64.deb

如果遇到依赖问题，执行：

sudo apt --fix-broken install -y

3. 验证安装

which google-chrome-stable
# 输出：/usr/bin/google-chrome-stable

google-chrome-stable --version
# 输出：Google Chrome 144.0.7559.132

方案二：安装系统级的 Chromium（通过仓库）

如果不希望安装 Google Chrome，可以添加 Debian/Untrusted 仓库：

sudo apt update
sudo apt install chromium

注意：Ubuntu 24.04 默认仓库中的 chromium 依然是 Snap 版本，需要使用 Debian 的仓库。

配置 OpenClaw

编辑 OpenClaw 配置文件，指定 Chrome 可执行文件路径：

nano ~/.openclaw/openclaw.json

添加或修改 browser 配置段：

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

配置项说明

配置项	值	说明
enabled	true	启用浏览器功能
executablePath	/usr/bin/google-chrome-stable	指定 Chrome 路径，避免使用 Snap 版
headless	true	无头模式，服务器环境必须开启
noSandbox	true	禁用沙盒，服务器环境需要
attachOnly	false	允许 OpenClaw 自动启动浏览器
defaultProfile	openclaw	使用托管模式

重启服务

openclaw gateway restart

验证测试

检查浏览器状态

openclaw browser status

正确输出：

profile: openclaw
enabled: true
running: true
cdpReady: true
detectedBrowser: custom
detectedPath: /usr/bin/google-chrome-stable

测试打开网页

openclaw browser open https://www.baidu.com

测试截图

openclaw browser screenshot

输出：

MEDIA:~/.openclaw/media/browser/xxx.png

常见问题排查

问题 1：attachOnly 模式

如果遇到错误：

Error: Browser attachOnly is enabled and profile "openclaw" is not running.

说明配置文件中 attachOnly 设置为 true。需要将其改为 false 或删除该字段，让 OpenClaw 能够自动启动浏览器。

问题 2：中文显示为方块

如果截图中的中文显示为 □□□，需要安装中文字体：

sudo apt install -y fonts-noto-cjk fonts-wqy-zenhei

问题 3：配置文件字段错误

如果重启时报错：

Invalid config: browser: Unrecognized key: "mode"

说明使用了不存在的字段。查阅官方文档，使用正确的配置字段。

总结

Ubuntu 24.04 默认的 Chromium 是 Snap 版本，由于沙盒隔离和 CDP 端口无法暴露的原因，无法在 OpenClaw 的托管模式下工作。解决方案是安装官方的 Google Chrome 或系统级的 Chromium，并在配置文件中指定正确的可执行文件路径。

这个问题的根本原因在于 Snap 应用的沙盒化设计与传统浏览器控制需求的冲突。在服务器环境下，选择非 Snap 版本的浏览器是确保功能正常的关键。

---

系列文章预告：

• OpenClaw 浏览器自动化测试的那些坑（二）：计划中
• OpenClaw 浏览器自动化测试的那些坑（三）：计划中

如果你觉得这篇文章对你有帮助，欢迎点赞、收藏！

本文记录于 2026 年 2 月，基于 OpenClaw v2026.2.13 版本