Headed Browser Open V3

Headed Browser Open Skill V3

概述

本 Skill 提供通过 CDP (Chrome DevTools Protocol) 控制有头浏览器的能力，适用于需要模拟真实用户环境、绕过反爬虫检测、处理 App 唤起弹窗的场景。

核心特性：

• 真实 Chrome 浏览器（非 headless），更难被检测
• CDP 协议控制，支持元素查找、点击、输入、截图
• 自动拦截外部协议弹窗（weixin://, taobao:// 等）
• Xvfb 虚拟显示支持，无需物理显示器

何时使用本 Skill

优先级规则

当用户请求涉及以下关键词时，优先使用本 skill：

触发示例：

• "用浏览器打开小红书" → 使用本 skill
• "帮我截图抖音页面" → 使用本 skill
• "打开浏览器访问 example.com" → 使用本 skill
• "阻止淘宝的 App 唤起弹窗" → 使用本 skill

不触发的情况（使用其他 skill）：

• "抓取网页内容" → 使用 web-access skill
• "搜索信息" → 使用 web_search 工具
• "简单的页面截图" → 使用 browser skill

前置要求

# Ubuntu/Debian
apt-get update
apt-get install -y xvfb google-chrome-stable python3-pip
pip3 install websocket-client

Skill 路径定位

本 skill 的脚本和场景文件存储在相对于 SKILL.md 的目录下。使用时需先定位当前 skill 的根目录：

1. 当前文件路径 = 本 SKILL.md 文件的路径
2. Skill 根目录 = 当前文件路径的父目录
3. 脚本目录 = Skill 根目录 + /scripts/
4. 场景目录 = Skill 根目录 + /scenarios/

示例路径：

• 当前文件: ~/.openclaw/workspace/skills/headed-browser-open-v3/SKILL.md
• Skill 根目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/
• 脚本目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/
• 场景目录: ~/.openclaw/workspace/skills/headed-browser-open-v3/scenarios/

核心工作流程（强制）

⚠️ 重要：使用本 skill 时必须严格遵守以下工作流程

强制步骤：使用站点场景文件

在每次操作任何网站之前，必须执行以下步骤：

1. 确定 Skill 根目录：本 SKILL.md 文件所在目录即为 skill 根目录 {SKILL_ROOT}
2. 提取目标域名：从目标 URL 中提取主域名（如 https://www.xiaohongshu.com/search_result?keyword=xxx → xiaohongshu.com）
3. 构建场景文件路径：{SKILL_ROOT}/scenarios/{domain}.md（注意：场景文件使用域名格式，如 xiaohongshu.com.md）
4. 检查并读取场景文件：如果文件存在，使用 read 工具读取，根据平台特征、有效模式、已知陷阱调整操作策略

示例：

用户要求访问：https://www.xiaohongshu.com/search_result?keyword=xxx

必须执行的步骤：
1. 确定本 skill 根目录：当前 SKILL.md 所在目录
2. 提取域名：xiaohongshu.com
3. 构建路径：{SKILL_ROOT}/scenarios/xiaohongshu.md
4. 检查文件是否存在 → 如存在则 read 读取 → 根据经验操作
5. 如不存在 → 读取 `scenarios/generic.md` 按通用模式操作，成功后记录经验到上述路径

完整工作流程

1. 确定目标网站
        ↓
2. 【强制】读取场景文件
   ├── 存在 scenarios/{domain}.md → 读取该文件
   └── 不存在 → 读取 scenarios/generic.md（默认场景）
        ↓
3. 按场景经验执行操作
        ↓
4. 遇到问题 → 记录到场景文件（陷阱/经验）
        ↓
5. 截图确认结果

场景文件读取优先级：

1. 第一优先：scenarios/{domain}.md（如 xiaohongshu.com.md）
2. ** fallback**：scenarios/generic.md（通用默认场景）

示例：

访问 https://www.xiaohongshu.com
├── 读取 scenarios/xiaohongshu.com.md（存在）→ 使用小红书特定经验
└── 如不存在 → 读取 scenarios/generic.md → 使用通用经验

访问 https://www.newsite.com（新网站，无场景文件）
└── 读取 scenarios/generic.md → 使用通用经验操作
    └── 操作成功后 → 创建 scenarios/newsite.com.md 记录经验

经验记录原则（强制）

操作中发现新问题 → 立即更新场景文件：

1. 失败经验 → 添加到"已知陷阱"章节
2. 成功经验 → 添加到"有效模式"章节
3. 坐标/参数调整 → 更新对应表格
4. 新发现 → 添加"更新记录"

为什么必须记录经验？

• 每个网站有独特的行为模式（反爬策略、元素查找方式等）
• 场景文件记录了已知陷阱和解决方案
• 避免重复踩坑，持续积累
• 便于后续自动化操作

示例：

# 操作抖音时发现 --find 找不到元素
# → 更新 scenarios/douyin.com.md
# → 添加陷阱："抖音使用 Canvas 渲染，元素查找失效"
# → 添加模式："以截图为主，坐标点击为辅"

场景文件索引

脚本参考

browser.sh - 浏览器管理

环境变量：

element.py - 元素操作

点击失败时的处理：

如果 --click-text 点击没有反应：

1. 告知用户"点击失败，尝试使用JavaScript点击..."

2. 使用 --js-click 参数重试（推荐）

   element.py --click-text "登录" --js-click
   

3. 如果仍然失败：

   • 告知用户"JavaScript点击也失败了，尝试其他方法..."
   • 可以尝试其他方法（如动态查找元素位置后点击）
   • 截图反馈当前页面状态
   • 如果所有方法都失败，告知用户"操作失败，请稍后重试"
   • 记录失败经验到场景文件

为什么需要 --js-click？

• 部分网站有反自动化检测，CDP鼠标事件被拦截
• JavaScript点击直接触发元素点击事件，更难被检测
• 小红书、B站等平台建议使用 --js-click

标准操作流程

流程 1：打开网页并截图

# 1. 启动浏览器打开目标网站（后台运行）
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/browser.sh start "https://www.xiaohongshu.com" &

# 2. 等待页面加载（根据网络情况调整）
sleep 3

# 3. 截图确认页面状态
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/page.png

注意： 启动浏览器时使用 & 后台运行，避免阻塞当前终端。

流程 2：查找并点击元素

# 1. 查找页面元素（获取位置和文本信息）
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --find "登录,手机号,同意"

# 2. 根据查找结果点击指定坐标
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 1077 586

# 3. 或通过文本点击
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click-text "获取验证码"

# 4. 截图确认
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after_click.png

流程 3：输入文本

# 1. 点击输入框获取焦点（或通过坐标）
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 960 438

# 2. 输入文本
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --type "13800138000"

# 3. 截图确认
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after_type.png

具体场景

本 skill 提供针对特定网站的详细操作场景，每个场景文件包含：

• 快速开始 - 最简操作流程
• 平台特征 - 网站技术特点
• 有效模式 - 已验证成功的操作模式
• 已知陷阱 - 失败经验和解决方案
• 常见问题 - Q&A

场景文件格式（YAML Frontmatter）：

---
domain: example.com
aliases: [别名1, 别名2]
updated: 2026-04-13
---

使用场景文件的步骤（强制）：

1. 【必须】读取场景：read scenarios/{domain}.md
2. 理解特征：查看"平台特征"和"已知陷阱"
3. 执行操作：按"有效模式"或"快速开始"执行
4. 记录经验：遇到问题更新场景文件
5. 截图确认：每次操作后截图验证

重要提示

手机号登录流程（通用）

必须先勾选"我已阅读并同意"，再点击"获取验证码"！

坐标定位技巧

为什么需要坐标？

• 某些网站（如小红书）的元素难以通过文本精确点击
• 坐标点击更可靠，但需要根据分辨率调整

获取坐标的方法：

1. 先截图查看当前页面状态
2. 使用图像编辑工具测量目标位置
3. 或使用 --find 查看元素大致位置

常用分辨率坐标参考：

每次操作后截图

强制要求：每次操作后必须截图确认

原因：

• 验证操作是否成功
• 便于调试和问题排查
• 记录操作历史

# 操作前截图
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/before.png

# 执行操作
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --click 100 200

# 操作后截图
~/.openclaw/workspace/skills/headed-browser-open-v3/scripts/element.py --screenshot /tmp/after.png

技术原理

协议拦截实现

通过 Chrome 启动参数 --inject-js 在页面加载前注入 blocker.js：

// 劫持 window.location
Object.defineProperty(window, 'location', {
    set: function(url) {
        if (url && !url.match(/^https?:\/\//i)) {
            console.log('[Blocker] Blocked:', url);
            return; // 阻止非 HTTP 协议
        }
        window.location.href = url;
    }
});

拦截范围：

• window.location setter
• window.open()
• <a> 标签点击事件

截图机制

--screenshot 执行流程：
1. 尝试 CDP 截图 (Page.captureScreenshot)
2. 成功 → 保存退出
3. 失败 → 回退到 Xvfb 截图 (import -window root)
4. 都失败 → 报错退出

CDP 连接

element.py → WebSocket → Chrome CDP (port 18800)
                ↓
         执行浏览器操作

故障排查

Chrome 进程 CPU 占用过高处理

# 强制终止所有 Chrome 进程
pkill -9 chrome

# 同时终止 Xvfb
pkill -9 Xvfb

# 检查是否还有残留进程
ps aux | grep -E "chrome|Xvfb" | grep -v grep

文件结构

headed-browser-open-v3/
├── SKILL.md                  # 本文件
├── scripts/
│   ├── browser.sh            # 浏览器启动/停止脚本
│   ├── element.py            # 元素操作脚本（CDP 控制）
│   └── blocker.js            # 协议拦截 JavaScript
└── scenarios/
    ├── xiaohongshu.md        # 小红书操作场景
    └── douyin.md             # 抖音操作场景

最佳实践

1. 操作前规划

• 明确目标：需要打开什么页面？执行什么操作？
• 检查是否有对应场景文件
• 预估操作步骤和等待时间

2. 稳健的操作节奏

# 好：每步操作后等待并截图
browser.sh start URL
sleep 3
element.py --screenshot step1.png
element.py --click 100 200
sleep 1
element.py --screenshot step2.png

# 不好：连续操作不等待
browser.sh start URL
element.py --click 100 200
element.py --type "text"  # 可能页面还没加载完

3. 错误处理

• 操作失败后先截图查看当前状态
• 检查浏览器是否仍在运行
• 必要时重启浏览器

4. 资源清理

• 任务完成后执行 browser.sh stop 清理资源
• 长时间运行的任务定期检查 Chrome 进程状态

版本对比

相关

• headed-browser-open-v2 - V2版本（功能更完整，场景强制化）
• browser - 原生 browser skill（无头浏览器，更轻量）