Testagent Browser Setup

SKILL.md

---
name: testagent-browser-setup
version: 1.2.0
description: 在新的 openclaw 环境中安装并初始化 Playwright MCP 和 browser-use CLI，含中文字体修复和自动验收。当用户说「初始化测试环境」「安装浏览器工具」「setup browser」或在新机器首次部署测试 agent 时触发。
---

# Browser Setup

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

## 执行顺序

### 第一步：运行安装脚本

```bash
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`，加入以下配置：

```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 域名）也需要单独加入，否则登录跳转被拦截

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

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

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

### 第三步：初始化 TOOLS.md

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

```bash
# 在 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. 写入环境变量：
   ```bash
   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**：
```bash
browser-use --version
# 用 BROWSER_USE_API_KEY 执行一条简单命令，确认鉴权通过
```

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