Browser Setup

一次性环境初始化，在新 openclaw 容器/机器上执行。需要 root 权限。

执行顺序

第一步：运行安装脚本

bash scripts/setup.sh

脚本按顺序完成：

1. Playwright Chromium 安装 + 注册到 openclaw MCP（统一 --browser chromium，ARM64/x86 通用）
2. 中文字体安装 + fontconfig 配置（截图无乱码）
3. openclaw gateway restart（让字体生效，Chromium 重载 fontconfig 缓存）
4. browser-use CLI 安装
5. browser-use skill 安装

第二步：配置内置浏览器（容器必须）

重要：browser 相关配置必须直接编辑 ~/.openclaw/openclaw.json，config.patch 无法修改 browser 配置（受保护路径）。

编辑 ~/.openclaw/openclaw.json，加入以下配置：

{
  "browser": {
    "noSandbox": true,
    "ssrfPolicy": {
      "allowedHostnames": [
        "你的目标产品域名（如 app.example.com）",
        "对应的 Auth0 / 登录域名（如 xxx.us.auth0.com）"
      ]
    }
  }
}

• noSandbox: true：容器内 root 运行 Chromium 必须，否则报 Timeout waiting for browser
• allowedHostnames：内置浏览器默认启用 SSRF 防护，未列入白名单的域名会报 blocked by policy；登录页（Auth0 等 SSO 域名）也需要单独加入，否则登录跳转被拦截

配置生效的完整重启序列（顺序不能错）：

browser stop
openclaw gateway restart
# 等待约 15 秒
browser start

仅 gateway restart 或仅 browser stop/start 都不够，必须三步完整执行。

第三步：初始化 TOOLS.md

将工具使用指南复制到项目根目录（与 SOUL.md、IDENTITY.md 同级），供 agent 在任意会话中随时查阅：

# 在 openclaw 项目根目录执行
cp "$(dirname "$0")/../TOOLS.md" ./TOOLS.md

若已存在则覆盖，确保版本与 skill 一致。

第四步：自动注册 browser-use API Key

脚本跑完后，agent 执行注册流程（无需人工介入）：

1. 检查 CLI 是否有内置注册命令：browser-use register
2. 若无，参考 https://docs.browser-use.com 的 Self-Registration API，流程为：
   • 请求 challenge（返回一道数学题）
   • 计算答案并提交验证
   • 拿到 bu_ 开头的 API Key
3. 写入环境变量：

   echo 'export BROWSER_USE_API_KEY=bu_xxx' >> ~/.bashrc
   export BROWSER_USE_API_KEY=bu_xxx
   

第五步：Smoke Test（自动验收）

验证 Playwright MCP：

调用 playwright__browser_navigate → https://example.com
调用 playwright__browser_take_screenshot → filename="/root/.openclaw/workspace/smoke_test.png"
确认文件存在且大小 > 0

验证 browser-use：

browser-use --version
# 用 BROWSER_USE_API_KEY 执行一条简单命令，确认鉴权通过

任一验收失败时，输出具体错误信息，提示修复方向，不要静默跳过。