OpenClaw 浏览器 WSL 附加模式

通过在启用远程调试的前提下，以 attachOnly 模式运行 Chromium，来构建一个稳定的 OpenClaw 浏览器会话。在 WSL、无头 Linux 环境或以 root 权限运行 OpenClaw 的场景下，若直接启动浏览器不稳定，推荐采用此工作流。

工作流程

1. 在修改任何配置前，先检查浏览器就绪状态。
2. 如果 OpenClaw 浏览器已成功附加且状态健康，则复用现有会话。
3. 如果系统中已安装 Chromium，但 OpenClaw 自动启动浏览器不稳定，则切换至 attachOnly 模式。
4. 运行 python3 scripts/configure-browser.py 并重启 gateway。
5. 手动启动 Chromium，并通过 Chrome DevTools Protocol（CDP）监听端口 18800。
6. 验证 curl http://127.0.0.1:18800/json/version 与 openclaw browser status 命令的输出结果。
7. 此后即可通过 OpenClaw 正常执行各类浏览器操作。

快速检查

请首先运行以下检查命令：

openclaw browser status
command -v chromium || command -v chromium-browser || command -v google-chrome
curl -s http://127.0.0.1:18800/json/version

结果解读：

• 若 openclaw browser status 显示 running: true，说明浏览器已就绪。
• 若 CDP 接口可正常返回 JSON，但 OpenClaw 仍无法自行启动浏览器，则优先启用 attachOnly 模式。
• 若系统中未安装 Chromium，请先安装，或在配置中将 browser.executablePath 指向一个有效的基于 Chromium 的浏览器可执行文件路径。

推荐配置

在 WSL / root / 无头 Linux 环境中，请将以下浏览器配置写入 ~/.openclaw/openclaw.json：

"browser": {
  "enabled": true,
  "executablePath": "/usr/bin/chromium",
  "headless": true,
  "noSandbox": true,
  "attachOnly": true
}

说明：

• 当 Chromium 以 root 用户运行时，必须设置 noSandbox: true。
• 当 OpenClaw 自动管理的浏览器启动超时或不可靠时，应启用 attachOnly: true。
• 只要 running: true 且 CDP 可用，即使显示 browser: unknown 或 detectedBrowser: custom，也属于可接受状态。

手动启动 Chromium

按如下顺序使用本项目附带的脚本：

python3 scripts/configure-browser.py
# 配置变更后需重启 gateway
bash scripts/start-browser.sh
bash scripts/healthcheck.sh

各脚本功能说明：

• configure-browser.py：为 WSL / root / 无头环境配置 ~/.openclaw/openclaw.json 中的 attachOnly 模式，并生成带时间戳的备份文件
• start-browser.sh：创建 OpenClaw 浏览器配置文件目录；必要时终止占用端口 18800 的残留 Chromium 进程；启动无头 Chromium；并打印验证信息
• healthcheck.sh：输出二进制文件路径、运行状态、CDP 连通性、进程信息及环境诊断数据

验证是否成功

健康状态通常表现为：

• curl http://127.0.0.1:18800/json/version 返回合法 JSON
• openclaw browser status 显示 running: true
• openclaw browser tabs 可正常列出标签页

确认状态健康后，即可继续正常使用 OpenClaw 浏览器相关功能。

修复工作流

若后续浏览器控制失效，请按以下步骤排查修复：

1. 重新运行 openclaw browser status
2. 重新运行 bash scripts/start-browser.sh
3. 运行 bash scripts/healthcheck.sh
4. 如有必要，查看日志文件 /tmp/openclaw-browser.log
5. 确认端口 18800 未被其他进程占用
6. 仅在配置发生变更后才需重启 gateway

面向用户的使用指引

完成配置后，用户可直接使用自然语言发起浏览器任务请求，例如：

• 打开一个 URL
• 搜索某个关键词
• 登录某网站
• 点击某个按钮
• 提取网页内容
• 截取当前页面截图

若在标准流程执行完毕后，浏览器附加仍失败，请查阅 references/troubleshooting.md 获取进一步排障指南。

当目标是在本机上长期稳定地实现 OpenClaw 浏览器自动化（而不仅是一次性使用浏览器工具），请优先选用该能力。