保姆级 OpenClaw 浏览器配置教程Linux、WSL2 环境下 Chrome 安装与配置完整指南，让你的OpenC

Linux、WSL2 环境下 Chrome 安装与配置完整指南

问题背景

在 WSL2 环境中配置 OpenClaw 浏览器遇到以下问题：

问题	原因	解决方案
Snap 版 Chromium 无法启动	缺少依赖库（libpxbackend-1.0.so、xdg-settings）	安装官方 Chrome
OpenClaw 自动启动失败	检测到的浏览器不可用	配置 executablePath
CDP 连接失败	WSL2 网络/权限问题	使用 attachOnly 模式

初始状态（配置前）

用户在飞书中发送指令（如「帮我打开 xxx 网站」），OpenClaw 会提示： 我的环境目前没有安装可用的浏览器，无法进行交互式操作 😅

配置成功后

完成所有配置后，浏览器可以正常使用：

执行 `openclaw browser status`

profile: openclaw
enabled: true
running: true
cdpPort: 18800
cdpUrl: http://127.0.0.1:18800
browser: chrome
detectedBrowser: custom
detectedPath: /usr/bin/google-chrome-stable

running: true → 浏览器正常运行

执行 `openclaw browser start`

✅ Browser started successfully

成功启动，无报错

使用 browser 工具

browser action: navigate, profile: openclaw, url: http://www.sina.com.cn
# 结果：成功打开页面

可以正常打开网页、执行自动化操作

环境说明

操作系统：WSL2 (Ubuntu)
OpenClaw 版本：2026.3.8
目标浏览器：Google Chrome

第一步：安装 Chrome

1.1 检查现有浏览器

首先检查系统中是否有可用的浏览器：

# 检查 Chromium 路径
which chromium
which chromium-browser

# 检查版本（如果有的话）
chromium-browser --version 2>&1

可能的结果：

无输出 → 未安装 Chromium
显示版本号（如 Chromium 145.0.7632.116 snap）→ 已安装 Snap 版（有问题）
报错（缺少依赖库）→ Snap 版不完整，需要安装官方 Chrome

发现问题：如果显示 Snap 版本，说明 chromium-browser 是 Snap 版本，缺少依赖库，运行会报错。

卸载 Snap 版 Chromium（可选，如果需要彻底清除）：

sudo snap remove chromium

/usr/bin/chromium-browser: line 12: xdg-settings: command not found
libpxbackend-1.0.so: cannot open shared object file: No such file or directory
Chromium 145.0.7632.116 snap

这是因为 Ubuntu 的 Chromium 是 Snap 版本，打包不完整，缺少必要的共享库。

1.2 下载 Google Chrome

从 Google 官方网站下载最新的稳定版 Chrome：

cd /tmp
wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb -O chrome.deb

1.3 安装 Chrome

sudo dpkg -i chrome.deb

可能出现依赖报错（正常现象）：

dpkg: dependency problems prevent configuration of google-chrome-stable:
 google-chrome-stable depends on fonts-liberation; however:
  Package fonts-liberation is not installed.
 google-chrome-stable depends on libasound2 (>= 1.0.17); however:
  Package libasound2 is not installed.
 google-chrome-stable depends on libnspr4 (>= 2:4.9-2~); however:
  Package libnspr4 is not installed.
 google-chrome-stable depends on libnss3 (>= 2:3.35); however:
  Package libnss3 is not installed.
 google-chrome-stable depends on xdg-utils (>= 1.0.2); however:
  Package xdg-utils is not installed.

这是正常现象，Chrome 依赖一些额外的包。使用以下命令修复：

sudo apt-get install -f -y

可能出现的警告：安装过程中可能出现 needrestart is being skipped since dpkg has failed，这是正常现象，表示需要重启的服务被暂时跳过，可以忽略。

1.4 验证安装

google-chrome --version

成功输出：

Google Chrome 146.0.7680.71

第二步：配置 OpenClaw

安装好 Chrome 后，需要配置 OpenClaw。

2.1 为什么要设置 profile: "openclaw"？

OpenClaw 支持两种浏览器模式：

Profile	说明	使用场景
chrome	使用系统默认浏览器或 Chrome 扩展	需要登录账号、保持会话（如日常使用）
openclaw	OpenClaw 自己管理的浏览器	自动化操作、无需登录

为什么选择 openclaw：

独立环境：openclaw 使用独立的数据目录（/tmp/chrome-openclaw），不会影响你日常使用的 Chrome
自动化友好：专为自动化设计，不会弹出登录提示
状态可控：每次启动都是干净的环境，易于调试
CDP 稳定：使用独立的调试端口，连接更稳定

使用方式：

在 OpenClaw 中使用 browser 工具时，通过 profile: "openclaw" 指定使用哪个浏览器：

# 使用 openclaw 浏览器
browser action: navigate, profile: openclaw, url: http://example.com

# 使用 chrome 浏览器（默认）
browser action: navigate, url: http://example.com

2.2 为什么要设置 headless？

headless 参数控制浏览器是否以"无头模式"运行：

模式	说明	优缺点
headless: true	无头模式，不显示浏览器窗口	节省资源，但看不到界面
headless: false	有头模式，显示浏览器窗口	可以看到浏览器操作过程

为什么通常设为 true：

节省资源：不需要渲染图形界面，节省 CPU 和内存
后台运行：适合服务器环境，不需要显示器更快启动
****：跳过界面渲染，启动更快

什么时候设为 false：

调试时：想看到浏览器的操作过程
复杂交互：页面有复杂的动画或交互需要观察
首次配置：不确定问题在哪，需要观察浏览器行为

推荐设置：

# 服务器环境，推荐 true
openclaw config set browser.headless true

# 调试环境，可以设为 false
openclaw config set browser.headless false

2.3 使用命令行配置（推荐）

这是最简单的方式，使用 openclaw config set 命令：

# 设置默认浏览器为 openclaw
openclaw config set browser.defaultProfile openclaw

# 设置无头模式
openclaw config set browser.headless true

# 设置 Chrome 路径
openclaw config set browser.executablePath /usr/bin/google-chrome-stable

# WSL2 必须开启
openclaw config set browser.noSandbox true

⚠️ 重要：配置完成后必须重启 Gateway

openclaw gateway restart

不重启会导致配置不生效，启动浏览器时会报错。

2.4 手动编辑配置文件

也可以直接编辑 ~/.openclaw/openclaw.json：

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

第三步：选择连接方案

配置完成后，有两种方案可以选择：

方案一：自动启动（推荐）

OpenClaw 自动管理浏览器生命周期。

步骤 1：确保 attachOnly 为 false（默认）

openclaw config set browser.attachOnly false

或者在配置文件中确保没有 "attachOnly": true

步骤 2：重启 OpenClaw

openclaw gateway restart

步骤 3：测试

openclaw browser status

正常情况下应该显示 running: true

方案二：手动启动（备用）

当方案一失败时使用。浏览器由用户手动启动，OpenClaw 仅连接控制。

步骤 1：设置 attachOnly 为 true

openclaw config set browser.attachOnly true
openclaw config set browser.cdpPort 18800

步骤 2：重启 OpenClaw

openclaw gateway restart

步骤 3：手动启动 Chrome

/usr/bin/google-chrome-stable \
  --headless \
  --no-sandbox \
  --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=/tmp/chrome-openclaw &

参数说明：

参数	说明
--headless	无头模式运行，不显示窗口
--no-sandbox	WSL2 必须加，否则权限错误
--disable-gpu	禁用 GPU 加速
--remote-debugging-port	CDP 调试端口
--user-data-dir	用户数据目录

步骤 4：验证 Chrome 启动

curl -s http://127.0.0.1:18800/json/version

成功返回 JSON：

{
   "Browser": "Chrome/146.0.7680.71",
   "Protocol-Version": "1.3",
   "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36...",
   "V8-Version": "14.6.202.11",
   "webSocketDebuggerUrl": "ws://127.0.0.1:18800/devtools/browser/..."
}

完整配置命令汇总

方案一（自动启动）

# 1. 安装 Chrome（见第一步）

# 2. 配置 OpenClaw
openclaw config set browser.defaultProfile openclaw
openclaw config set browser.headless true
openclaw config set browser.executablePath /usr/bin/google-chrome-stable
openclaw config set browser.noSandbox true
openclaw config set browser.attachOnly false

# 3. 重启
openclaw gateway restart

# 4. 测试
openclaw browser status

方案二（手动启动）

# 1. 安装 Chrome（见第一步）

# 2. 配置 OpenClaw
openclaw config set browser.defaultProfile openclaw
openclaw config set browser.headless true
openclaw config set browser.executablePath /usr/bin/google-chrome-stable
openclaw config set browser.noSandbox true
openclaw config set browser.attachOnly true
openclaw config set browser.cdpPort 18800

# 3. 重启
openclaw gateway restart

# 4. 手动启动 Chrome
/usr/bin/google-chrome-stable --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=/tmp/chrome-openclaw &

# 5. 验证
curl -s http://127.0.0.1:18800/json/version

使用方法

基本语法

在 OpenClaw 中使用 browser 工具时，必须指定 profile: "openclaw"：

browser action: <操作>, profile: openclaw, url: <网址>

常用操作

操作	说明	示例
navigate	打开网页	navigate, profile: openclaw, url: example.com
open	在新标签页打开	open, profile: openclaw, url: example.com
snapshot	截图/获取页面内容	snapshot, profile: openclaw
click	点击元素	click, profile: openclaw, ref: e12
type	输入文字	type, profile: openclaw, ref: e10, text: hello
act	综合操作	act, kind: click, profile: openclaw, ref: e34

验证步骤

按顺序执行以下命令验证配置是否正确：

# 1. 检查 Chrome 版本
google-chrome --version

# 2. 检查配置文件
openclaw browser status

# 3. 检查 Chrome 进程
ps aux | grep chrome

# 4. 检查 CDP 端口
curl -s http://127.0.0.1:18800/json/version

# 5. 测试打开网页
browser action: open, profile: openclaw, url: http://www.sina.com.cn

常见问题

Q1: Chrome 安装后仍无法启动

解决：执行 sudo apt-get install -f -y 修复依赖

Q2: openclaw browser start 显示 running: false

解决：使用方案二（手动启动 + attachOnly）

Q3: 无法访问内网网站

解决：确保 WSL2 网络可达，可能需要 VPN/代理

Q4: CDP 端口连接失败

解决：确认配置文件中的端口与启动 Chrome 时的端口一致

配置参数说明

参数	命令	说明	推荐值
defaultProfile	browser.defaultProfile	默认浏览器配置（chrome 或 openclaw）	openclaw
executablePath	browser.executablePath	Chrome 路径	/usr/bin/google-chrome-stable
headless	browser.headless	无头模式（true=无窗口，false=有窗口）	true
noSandbox	browser.noSandbox	WSL2 必须开启	true
attachOnly	browser.attachOnly	手动模式（true=只连接已启动的浏览器）	false
cdpPort	browser.cdpPort	调试端口	18800

关键教训

Snap 版 Chromium 有问题：Ubuntu 的 Snap 版存在依赖问题，必须安装官方 Chrome
apt 仓库没有 Chromium：必须从 Google 官网下载 .deb 包
WSL2 必须加 --no-sandbox：否则会报权限错误
attachOnly + 手动启动最稳定：避免自动启动的各种权限问题

保姆级 OpenClaw 浏览器配置教程