browser-agent-tool-free

无头浏览器自发化命令行工具,通过可访问性树快照(ref引用)达成确定性元素选择,. 适用于需要browser agent tool相关能力的开发场景,包含结构化的工作流程和可复用的模板,帮助用户快速完成任务并保持代码质量. 适用于需要browser agent tool相关能力的开发场景,包含结构化的工作流程和配置指引.

天轰穿@thcjp

Install

openclaw skills install @thcjp/browser-agent-tool-free

浏览器智能代理工具(免费版)

概述

本工具是一个无头浏览器自动化命令行工具,通过可访问性树(accessibility tree)快照与 ref 引用实现确定性的元素选择,适合 AI 代理在多步骤工作流中稳定地操作网页。免费版面向个人开发者,提供核心导航、交互、信息获取与会话管理能力. 与内置浏览器工具相比,本工具在以下场景更有优势:

多步骤自动化工作流
需要确定性元素选择(避免选择器漂移)
对性能敏感的任务
复杂单页应用(SPA)操作
需要会话隔离的场景

核心能力

能力分类	命令示例	说明
导航	`open` / `back` / `forward` / `reload`	页面跳转与历史控制
快照	`snapshot -i --json`	获取可交互元素的可访问性树
交互	`click` / `fill` / `type` / `select`	基于 ref 的元素操作
获取信息	`get text` / `get html` / `get attr`	提取页面内容
状态检查	`is visible` / `is enabled`	判断元素状态
等待	`wait` / `wait --load networkidle`	同步页面加载
会话	`--session`	多浏览器上下文隔离
状态持久化	`state save` / `state load`	保存/加载 cookies 与 storage

核心功能执行

用input_params参数进行配置.

处理: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回核心功能执行的响应数据,包含状态码、结果和日志.

执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置.

处理: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回参数配置与调用的响应数据,包含状态码、结果和日志.

执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置.

处理: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回结果处理与输出的响应数据,包含状态码、结果和日志.

执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：无头浏览器自动化、支持可访问性树快、照与确定性元素选、适合个人开发者、命令行工具、通过可访问性树快、实现确定性元素选、代理优化的浏览器、操作工作流、核心能力、与可访问性树快照、引用的确定性元素、多会话隔离与状态、PDF、生成与网络控制等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一:每日自动签到

个人用户希望在站点完成每日签到并截图留证.

bash

# 打开签到页面
agent-browser open https://example.com/checkin
# ...
# 获取可交互元素快照
agent-browser snapshot -i --json
# ...
# 点击签到按钮(根据快照返回的 ref)
agent-browser click @e2
# ...
# 等待页面稳定
agent-browser wait --load networkidle
# ...
# 截图保存
agent-browser screenshot checkin_$(date +%Y%m%d).png
# ...
# 关闭浏览器
agent-browser close

场景二:搜索并提取结果

在搜索引擎中查询关键词,提取前几条结果标题与链接.

bash

agent-browser open https://www.google.com
agent-browser snapshot -i --json
agent-browser fill @e1 "AI agents"
agent-browser press Enter
agent-browser wait --load networkidle
agent-browser snapshot -i --json
agent-browser get text @e3 --json
agent-browser get attr @e4 "href" --json

场景三:多会话隔离测试

同时管理两个独立浏览器上下文(例如管理员与普通用户).

bash

# 管理员会话
agent-browser --session admin open https://app.example.com
agent-browser --session admin state load admin-auth.json
agent-browser --session admin snapshot -i --json
# ...
# 普通用户会话
agent-browser --session user open https://app.example.com
agent-browser --session user state load user-auth.json
agent-browser --session user snapshot -i --json
# ...
# 查看所有会话
agent-browser session list

不适用场景

以下场景浏览器智能代理工具-免费版不适合处理：

需要100%确定性的关键决策
医疗诊断
法律判决

触发条件

需要AI模型调用、智能对话、Agent编排、LLM应用时使用。不适用于非本工具能力范围的需求.

快速开始

阅读## 核心能力章节了解skill功能
按## 依赖说明配置环境
执行所需能力对应的命令
参考## 错误处理章节处理异常
查看## FAQ解答常见疑问

依赖详情

bash

npm install -g agent-browser
agent-browser install              # 下载 Chromium 内核
# Linux 系统可一并安装系统依赖:
agent-browser install --with-deps

2. 核心工作流

bash

# 打开页面
# ...
# 获取可交互元素快照(始终使用 -i --json)
agent-browser snapshot -i --json
# ...
# 基于 ref 进行操作
agent-browser click @e2
agent-browser fill @e3 "文本内容"
# ...
# 再次快照以获取新的 ref
agent-browser snapshot -i --json

3. 常用交互命令

bash

agent-browser click @e2               # 点击
agent-browser fill @e3 "text"          # 填入(先清空)
agent-browser type @e3 "text"          # 追加输入
agent-browser hover @e4                # 悬停
agent-browser check @e5                # 勾选
agent-browser uncheck @e5              # 取消勾选
agent-browser select @e6 "value"       # 选择下拉项
agent-browser press "Enter"            # 按键
agent-browser scroll down 500          # 滚动
agent-browser drag @e7 @e8             # 拖拽

响应解析: 完成完成后,查看输出响应确认任务状态。成功时输出包含解析摘要和响应数据;失败时根据错误信息排查问题,查阅错误解析章节获取恢复步骤.

示例

获取信息

bash

agent-browser get text @e1 --json       # 获取文本
agent-browser get html @e2 --json       # 获取 HTML
agent-browser get value @e3 --json      # 获取输入值
agent-browser get attr @e4 "href" --json # 获取属性
agent-browser get title --json          # 获取页面标题
agent-browser get url --json            # 获取当前 URL
agent-browser get count ".item" --json  # 统计元素数量

快照输出格式

json

{
  "success": true,
  "data": {
    "snapshot": "...",
    "refs": {
      "e1": {"role": "heading", "name": "示例标题"},
      "e2": {"role": "button", "name": "提交"},
      "e3": {"role": "textbox", "name": "邮箱"}
    }
  }
}

等待策略

bash

agent-browser wait @e2                       # 等待元素出现
agent-browser wait 1000                      # 等待毫秒
agent-browser wait --text "欢迎"             # 等待文本出现
agent-browser wait --url "**/dashboard"      # 等待 URL 匹配
agent-browser wait --load networkidle        # 等待网络空闲
agent-browser wait --fn "window.ready === true"

状态持久化

bash

# 保存登录态,跳过重复登录
agent-browser state save auth.json
agent-browser state load auth.json

截图与 PDF

bash

agent-browser screenshot page.png
agent-browser screenshot --full page.png    # 全页截图
agent-browser pdf page.pdf                  # 导出 PDF

标签页与框架

bash

agent-browser tab new https://example.com   # 新建标签
agent-browser tab 2                         # 切换到第2个标签
agent-browser frame @e5                     # 进入 iframe
agent-browser frame main                    # 回到主框架

优秀实践

始终使用 -i 参数:聚焦可交互元素,减少快照噪声.
始终使用 --json 参数:便于程序化解析输出.
页面变化后重新快照:每次 DOM 变化后 ref 可能失效,需重新获取.
等待页面稳定:使用 wait --load networkidle 避免竞态.
保存登录态:用 state save/load 跳过重复登录流程.
使用会话隔离:不同任务使用不同 --session,避免上下文污染.
调试时使用 --headed:可视化查看浏览器实际行为.
及时关闭浏览器:任务完成后 close 释放资源.

常见问题

Q1: ref 失效怎么办?

每次页面 DOM 变化后,之前获取的 ref 可能失效。解决方法是在每次交互前重新执行 snapshot -i --json,获取最新的 ref 映射.

Q2: 元素定位不到?

确认页面已加载完成(wait --load networkidle)
使用 snapshot -s "#main" -i 限定范围
检查元素是否在 iframe 内(frame @e5)

Q3: 浏览器启动失败?

bash

# 重新安装内核
agent-browser install
# Linux 安装系统依赖
agent-browser install --with-deps

已知限制

免费版面向个人开发者,提供核心浏览器自动化能力。如需企业级特性(批量任务调度、代理池管理、并发会话上限提升、监控告警等),请升级至 PRO 版.

Q5: 如何调试脚本?

bash

# 使用有头模式查看浏览器
agent-browser --headed open https://example.com
# 截图查看当前状态
agent-browser screenshot debug.png

依赖说明

运行环境

Agent 平台: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
操作系统: Windows / macOS / Linux
Node.js: >= 18.0.0(用于运行 agent-browser CLI)

第三方依赖

依赖项	类型	是否必需	获取方式
agent-browser	CLI 工具	必需	`npm install -g agent-browser`
Chromium	运行时	必需	`agent-browser install` 自动下载
LLM API	API	必需	由Agent内置LLM提供
Node.js	运行环境	必需	系统包管理器安装

API Key 配置

基础LLM由Agent平台内置提供，特定外部API需单独配置密钥
如使用远程浏览器服务(如 Browserbase),需配置对应服务的 API Key

可用性分类

分类: MD+EXEC模式纯Markdown指令,部分功能需exec命令行执行)
说明: 基于Markdown的AI Skill,通过自然语言指令驱动Agent完成操作

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

输出格式

json

{
  "success": true,
  "data": {
    "result": "浏览器智能代理工具-免费版处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "browser agent"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}