OpenClaw + Google Chrome（deb）+ WSLg：可视化浏览器自动化与人工接管教程

目标：在WSL2 + Ubuntu + WSLg环境中，使用OpenClaw控制Linux 浏览器 GUI（非无头），实现自动登录/浏览网页/操作网页，并在遇到验证码（扫码、滑块、人机验证）时支持人工直接接管浏览器窗口完成认证。

1. 方案概览

本教程采用组合：

• OpenClaw：Agent/工具编排与浏览器控制入口
• Google Chrome（deb 官方安装）：Linux 版浏览器，避免 snap 带来的限制与不稳定
• WSLg：让 WSL 内的 GUI 应用直接显示在 Windows 桌面（可视化 + 人工接管）

关键特性：

• 必须 GUI（headed）：确保验证码出现时可以人工直接看到浏览器页面并操作。
• 通过 OpenClaw 托管 profile + CDP 端口：便于复用同一实例、复用登录态，并进行基本的 tab 管理。

2. 环境要求

• Windows 11（推荐）或支持 WSLg 的环境
• WSL2 + Ubuntu（示例以 Ubuntu 24.04 为主）
• OpenClaw 已安装并可运行（openclaw --version正常）

3. 为什么不推荐 snap Chromium

在 Ubuntu 24.04 上，apt install chromium-browser通常安装的是snap 包装器，实际浏览器来自 snap。snap 的权限/沙箱机制在一些场景会干扰“程序启动并监控浏览器进程（CDP）”的稳定性，导致调试成本显著增加。

因此，推荐直接使用Google Chrome 官方 deb，可获得更可预测的启动与 CDP 行为。

4. 卸载 snap Chromium

如果系统已安装 snap chromium，建议先卸载（可选，但强烈推荐）。

snap list|grep-ichromium||truesudosnap remove chromiumsudoaptremove-ychromium-browsersudoaptautoremove-y

验证旧入口已移除：

whichchromium||truewhichchromium-browser||true

5. 安装 Google Chrome 官方 deb

安装基础工具：

sudoaptupdatesudoaptinstall-ywgetca-certificates gnupg

下载并安装 Google Chrome deb：

cd/tmpwget-Ogoogle-chrome-stable_current_amd64.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudoaptinstall-y./google-chrome-stable_current_amd64.debsudoapt-finstall-y

验证安装成功：

whichgoogle-chrome-stable google-chrome-stable--version

验证 WSLg GUI 能正常弹出：

google-chrome-stable

如果可以在 Windows 桌面看到 Chrome 窗口，则 WSLg 图形链路正常。

6. 配置 OpenClaw（重点）

OpenClaw 配置文件通常位于：

• ~/.openclaw/openclaw.json

6.1 必须启用 GUI：headless=false

浏览器必须使用 GUI 模式，确保人工能接管：

"browser": { "enabled": true, "defaultProfile": "openclaw", "headless": false, "noSandbox": true, "executablePath": "/usr/bin/google-chrome-stable", "profiles": { "openclaw": { "cdpPort": 18800, "color": "#0000FF" } } }

color只是标识用途（主题色），此处使用蓝色#0000FF。

6.2 解决 systemd 服务缺 DISPLAY：启用 shell 环境导入

openclaw browser start通常由openclaw-gateway（systemd 服务）负责拉起浏览器进程；而 systemd 服务默认不会继承交互 shell 的DISPLAY/WAYLAND_DISPLAY/XDG_RUNTIME_DIR。

因此，需要在配置文件顶层加入：

"env": { "shellEnv": { "enabled": true, "timeoutMs": 15000 } }

建议将env与browser合并在同一配置文件中，例如：

{ "env": { "shellEnv": { "enabled": true, "timeoutMs": 15000 } }, "browser": { "enabled": true, "defaultProfile": "openclaw", "headless": false, "noSandbox": true, "executablePath": "/usr/bin/google-chrome-stable", "profiles": { "openclaw": { "cdpPort": 18800, "color": "#0000FF" } } } }

7. 同步 token 并重启 gateway

如果看到提示：

• Config token differs from service token...

说明配置 token 与服务 token 不一致，需要同步（否则会出现“以为配置生效但服务仍用旧 token”的现象）。

执行：

openclaw gatewayinstall--forceopenclaw gateway restart

8. 启动与验证

启动托管浏览器：

openclaw browser --browser-profile openclaw start

打开页面验证控制：

openclaw browser --browser-profile openclawopenhttps://example.com

成功标志：

• Windows 桌面出现 Chrome GUI 窗口（WSLg）
• 页面能被 OpenClaw 打开与操控

9. 人工介入（验证码/扫码）工作流

推荐的人机协作流程：

1. Agent 自动执行登录/跳转/填表等步骤
2. 如果出现验证码/扫码/安全验证页：
   • Agent 停止自动操作（进入等待态）
   • 提示人工接管（例如“请在浏览器窗口完成验证”）
3. 人工直接在当前 GUI Chrome 窗口完成扫码/点选/滑块等验证
4. 验证通过后，Agent 继续后续自动流程

这个流程的关键前提就是：浏览器必须GUI 可见（headless=false）。

若遇到中文无法显示，则需要安装一下中文包

sudoaptupdatesudoaptinstall-yfonts-noto-cjk fonts-noto-color-emoji fontconfig fc-cache-f-v

10. 常见问题排查

10.1Missing X server or $DISPLAY

表现：

Missing X server or $DISPLAY The platform failed to initialize.

排查与修复：

1. 验证 WSLg 环境变量与 X socket（在交互终端里）：

echo"DISPLAY=$DISPLAY"echo"WAYLAND_DISPLAY=$WAYLAND_DISPLAY"echo"XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"ls-la/tmp/.X11-unix

假如这几个变量都不为空，却仍报Missing X server or $DISPLAY
请尝试执行

cat>~/.openclaw/.env<<'EOF' DISPLAY=:0 WAYLAND_DISPLAY=wayland-0 XDG_RUNTIME_DIR=/run/user/1000 EOF

将变量直接写入openclaw目录优先读取。

2. 确保~/.openclaw/openclaw.json顶层启用：

"env": { "shellEnv": { "enabled": true, "timeoutMs": 15000 } }

3. 同步并重启：

openclaw gatewayinstall--forceopenclaw gateway restart

10.2Failed to start Chrome CDP on port 18800

常见原因：

• 端口被占用
• 浏览器启动失败（通常伴随 DISPLAY 错误）

解决方式：

• 更换cdpPort
• 确认env.shellEnv已启用并重启 gateway