headed-browser-open-v3

name	headed-browser-open-v3
description	使用有头浏览器(headed browser)打开网页，通过CDP协议进行元素点击和自动化操作。V3优化版：简化架构，保留核心功能（协议拦截、元素操作、截图），适用于小红书、抖音等需要绕过App唤起提示的网站。
type	skill
tools	["exec","browser"]

Headed Browser Open Skill V3

概述

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

核心特性：

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

何时使用本 Skill

场景	是否适用	说明
需要绕过反爬虫检测	✅	有头浏览器更接近真实用户
网站触发 App 唤起弹窗	✅	自动拦截外部协议
小红书、抖音等国内平台	✅	已验证兼容
简单的页面抓取	❌	优先使用 browser skill
需要多标签页并行	⚠️	支持但需手动管理

优先级规则

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

关键词类型	示例	说明
浏览器操作	"打开浏览器"、"用浏览器访问"、"浏览器打开"	用户明确要求使用浏览器
网站名称	"小红书"、"抖音"、"xiaohongshu"、"douyin"	已验证兼容的网站
协议拦截	"阻止弹窗"、"拦截 App 唤起"、"去掉打开 App 提示"	需要协议拦截功能
反爬需求	"绕过检测"、"模拟真人"、"有头浏览器"	需要真实浏览器环境
自动化操作	"点击"、"输入"、"登录"、"截图"	需要 CDP 控制页面

触发示例：

• "用浏览器打开小红书" → 使用本 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 渲染，元素查找失效"
# → 添加模式："以截图为主，坐标点击为辅"

场景文件索引

文件	何时加载	说明
scenarios/xiaohongshu.com.md	访问小红书相关页面	小红书平台特征、登录流程、坐标参考
scenarios/douyin.com.md	访问抖音相关页面	抖音平台特征、Canvas渲染处理
scenarios/zhihu.com.md	访问知乎相关页面	知乎平台特征、登录流程
scenarios/bilibili.com.md	访问B站相关页面	B站平台特征、登录点击经验
scenarios/generic.md	通用参考	通用原则和最佳实践

脚本参考

browser.sh - 浏览器管理

命令	说明	示例
start [URL]	启动浏览器，可选打开URL	browser.sh start "https://xiaohongshu.com"
status	检查运行状态	browser.sh status
stop	停止浏览器	browser.sh stop

环境变量：

变量	默认值	说明
CDP_PORT	18800	CDP 调试端口
DISPLAY_NUM	99	Xvfb 显示号
SCREEN_WIDTH	1920	屏幕宽度
SCREEN_HEIGHT	1080	屏幕高度

element.py - 元素操作

参数	说明	示例
--find TEXT	查找包含指定文本的元素	--find "登录,手机号"
--click X Y	点击指定坐标	--click 1077 586
--click-text TEXT	点击包含指定文本的元素	--click-text "获取验证码"
--js-click	使用JavaScript点击（绕过反爬）	--click-text "登录" --js-click
--type TEXT	在当前焦点元素输入文本	--type "13800138000"
--screenshot PATH	截图保存	--screenshot /tmp/page.png
--port PORT	CDP端口	--port 18800
--display NUM	Xvfb显示号	--display 99

点击失败时的处理：

如果 --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

网站	场景文件	特征	状态
小红书	scenarios/xiaohongshu.com.md	DOM+Canvas混合，支持元素查找	✅ 已验证
抖音	scenarios/douyin.com.md	纯Canvas渲染，需截图+坐标	✅ 已验证
知乎	scenarios/zhihu.com.md	标准DOM渲染，支持动态查找	✅ 已验证
B站	scenarios/bilibili.com.md	标准DOM，建议使用JS点击	✅ 已验证
通用	scenarios/generic.md	通用原则和最佳实践	📋 参考

场景文件格式（YAML Frontmatter）：

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

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

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

重要提示

手机号登录流程（通用）

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

顺序	操作	说明
1	输入手机号	在手机号输入框输入
2	勾选同意协议	⚠️ 必须先勾选，否则验证码按钮无响应
3	点击获取验证码	此时按钮才可点击

坐标定位技巧

为什么需要坐标？

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

获取坐标的方法：

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

常用分辨率坐标参考：

网站	元素	1920x1080	1366x768
小红书	同意协议复选框	(1077, 586)	(768, 420)
小红书	获取验证码按钮	(1256, 438)	(896, 315)

每次操作后截图

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

原因：

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

# 操作前截图
~/.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)
                ↓
         执行浏览器操作

故障排查

问题	可能原因	解决方案
浏览器启动失败	Xvfb 未安装	apt-get install xvfb
CDP 连接失败	浏览器未启动或端口冲突	检查 browser.sh status，更换 CDP_PORT
元素找不到	页面未加载完成	增加 sleep 等待时间
点击无反应	坐标不正确	先截图确认元素位置，调整坐标
输入文本失败	输入框未获得焦点	先点击输入框再输入
截图失败	CDP 和 Xvfb 都不可用	检查 DISPLAY 环境变量
Chrome CPU 占用高	页面卡死或内存泄漏	pkill -9 chrome 强制终止

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 进程状态

版本对比

特性	V2	V3
核心功能	✅	✅
代码复杂度	较高	简化
场景文件	强制使用	参考使用
架构	复杂	精简
维护性	一般	更好

相关

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