目标在WSL2 Ubuntu WSLg环境中使用OpenClaw控制Linux 浏览器 GUI非无头实现自动登录/浏览网页/操作网页并在遇到验证码扫码、滑块、人机验证时支持人工直接接管浏览器窗口完成认证。目录1. 方案概览2. 环境要求3. 为什么不推荐 snap Chromium4. 卸载 snap Chromium5. 安装 Google Chrome 官方 deb6. 配置 OpenClaw重点6.1 必须启用 GUIheadlessfalse6.2 解决 systemd 服务缺 DISPLAY启用 shell 环境导入7. 同步 token 并重启 gateway8. 启动与验证9. 人工介入验证码/扫码工作流10. 常见问题排查10.1 Missing X server or $DISPLAY10.2 Failed to start Chrome CDP on port 188001. 方案概览本教程采用组合OpenClawAgent/工具编排与浏览器控制入口Google Chromedeb 官方安装Linux 版浏览器避免 snap 带来的限制与不稳定WSLg让 WSL 内的 GUI 应用直接显示在 Windows 桌面可视化 人工接管关键特性必须 GUIheaded确保验证码出现时可以人工直接看到浏览器页面并操作。通过 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||true5. 安装 Google Chrome 官方 deb安装基础工具sudoaptupdatesudoaptinstall-ywgetca-certificates gnupg下载并安装 Google Chrome debcd/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.json6.1 必须启用 GUIheadlessfalse浏览器必须使用 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-gatewaysystemd 服务负责拉起浏览器进程而 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 restart8. 启动与验证启动托管浏览器openclaw browser --browser-profile openclaw start打开页面验证控制openclaw browser --browser-profile openclawopenhttps://example.com成功标志Windows 桌面出现 Chrome GUI 窗口WSLg页面能被 OpenClaw 打开与操控9. 人工介入验证码/扫码工作流推荐的人机协作流程Agent 自动执行登录/跳转/填表等步骤如果出现验证码/扫码/安全验证页Agent 停止自动操作进入等待态提示人工接管例如“请在浏览器窗口完成验证”人工直接在当前 GUI Chrome 窗口完成扫码/点选/滑块等验证验证通过后Agent 继续后续自动流程这个流程的关键前提就是浏览器必须GUI 可见headlessfalse。若遇到中文无法显示则需要安装一下中文包sudoaptupdatesudoaptinstall-yfonts-noto-cjk fonts-noto-color-emoji fontconfig fc-cache-f-v10. 常见问题排查10.1Missing X server or $DISPLAY表现Missing X server or $DISPLAY The platform failed to initialize.排查与修复验证 WSLg 环境变量与 X socket在交互终端里echoDISPLAY$DISPLAYechoWAYLAND_DISPLAY$WAYLAND_DISPLAYechoXDG_RUNTIME_DIR$XDG_RUNTIME_DIRls-la/tmp/.X11-unix假如这几个变量都不为空却仍报Missing X server or $DISPLAY请尝试执行cat~/.openclaw/.envEOF DISPLAY:0 WAYLAND_DISPLAYwayland-0 XDG_RUNTIME_DIR/run/user/1000 EOF将变量直接写入openclaw目录优先读取。确保~/.openclaw/openclaw.json顶层启用env: { shellEnv: { enabled: true, timeoutMs: 15000 } }同步并重启openclaw gatewayinstall--forceopenclaw gateway restart10.2Failed to start Chrome CDP on port 18800常见原因端口被占用浏览器启动失败通常伴随 DISPLAY 错误解决方式更换cdpPort确认env.shellEnv已启用并重启 gateway