使用 agent-browser 进行浏览器自动化
该 CLI 通过 CDP 直接使用 Chrome/Chromium。通过 npm i -g agent-browser、brew install agent-browser 或 cargo install agent-browser 安装。运行 agent-browser install 下载 Chrome。
核心工作流
所有浏览器自动化遵循以下模式:
- 导航:
agent-browser open <url> - 快照:
agent-browser snapshot -i(获取元素引用,如@e1、@e2) - 交互:使用引用点击、填写、选择
- 重新快照:导航或 DOM 更改后,获取新的引用
agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出:@e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # 检查结果
命令链
命令可以通过 && 在单个 shell 调用中链接。浏览器通过后台守护进程在命令之间保持持久化,因此链接比单独调用更安全、更高效。
# 在单次调用中链接 open + wait + snapshot
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# 链接多个交互
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# 导航并截图
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
何时链接: 当不需要在继续之前读取中间命令的输出时使用 &&(例如,open + wait + screenshot)。当需要先解析输出时,请单独运行命令(例如,快照以发现引用,然后使用这些引用进行交互)。
处理认证
在自动化需要登录的网站时,选择适合的方法:
选项 1:从用户浏览器导入身份验证(一次性任务最快)
# 连接到用户正在运行的 Chrome(他们已登录)
agent-browser --auto-connect state save ./auth.json
# 使用该身份验证状态
agent-browser --state ./auth.json open https://app.example.com/dashboard
状态文件以明文形式包含会话令牌——将其添加到 .gitignore 中,并在不再需要时删除。设置 AGENT_BROWSER_ENCRYPTION_KEY 以进行静态加密。
选项 2:持久化配置文件(重复任务最简单)
# 首次运行:手动或通过自动化登录
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 填写凭据,提交 ...
# 所有后续运行:已认证
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
选项 3:会话名称(自动保存/恢复 cookie 和 localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... 登录流程 ...
agent-browser close # 状态自动保存
# 下次:状态自动恢复
agent-browser --session-name myapp open https://app.example.com/dashboard
选项 4:认证保险库(凭据加密存储,按名称登录)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
选项 5:状态文件(手动保存/加载)
# 登录后:
agent-browser state save ./auth.json
# 在未来的会话中:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
参见 references/authentication.md 了解 OAuth、2FA、基于 cookie 的身份验证和令牌刷新模式。
基本命令
# 导航
agent-browser open <url> # 导航(别名:goto, navigate)
agent-browser close # 关闭浏览器
# 快照
agent-browser snapshot -i # 带引用的交互式元素(推荐)
agent-browser snapshot -i -C # 包含光标交互元素(带有 onclick、cursor:pointer 的 div)
agent-browser snapshot -s "#selector" # 限定到 CSS 选择器
# 交互(使用来自快照的 @refs)
agent-browser click @e1 # 点击元素
agent-browser click @e1 --new-tab # 点击并在新标签页中打开
agent-browser fill @e2 "text" # 清除并输入文本
agent-browser type @e2 "text" # 输入但不清除
agent-browser select @e1 "option" # 选择下拉选项
agent-browser check @e1 # 选中复选框
agent-browser press Enter # 按键
agent-browser keyboard type "text" # 在当前焦点输入(无选择器)
agent-browser keyboard inserttext "text" # 插入但不触发键盘事件
agent-browser scroll down 500 # 滚动页面
agent-browser scroll down 500 --selector "div.content" # 在特定容器内滚动
# 获取信息
agent-browser get text @e1 # 获取元素文本
agent-browser get url # 获取当前 URL
agent-browser get title # 获取页面标题
agent-browser get cdp-url # 获取 CDP WebSocket URL
# 等待
agent-browser wait @e1 # 等待元素
agent-browser wait --load networkidle # 等待网络空闲
agent-browser wait --url "**/page" # 等待 URL 模式
agent-browser wait 2000 # 等待毫秒数
agent-browser wait --text "Welcome" # 等待文本出现(子字符串匹配)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # 等待文本消失
agent-browser wait "#spinner" --state hidden # 等待元素消失
# 下载
agent-browser download @e1 ./file.pdf # 点击元素触发下载
agent-browser wait --download ./output.zip # 等待任何下载完成
agent-browser --download-path ./downloads open <url> # 设置默认下载目录
# 视口与设备模拟
agent-browser set viewport 1920 1080 # 设置视口大小(默认:1280x720)
agent-browser set viewport 1920 1080 2 # 2 倍视网膜(相同 CSS 大小,更高分辨率截图)
agent-browser set device "iPhone 14" # 模拟设备(视口 + 用户代理)
# 捕获
agent-browser screenshot # 截图到临时目录
agent-browser screenshot --full # 整页截图
agent-browser screenshot --annotate # 带编号元素标签的带注释截图
agent-browser screenshot --screenshot-dir ./shots # 保存到自定义目录
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # 保存为 PDF
# 剪贴板
agent-browser clipboard read # 从剪贴板读取文本
agent-browser clipboard write "Hello, World!" # 向剪贴板写入文本
agent-browser clipboard copy # 复制当前选择
agent-browser clipboard paste # 从剪贴板粘贴
# 差异(比较页面状态)
agent-browser diff snapshot # 比较当前与上次快照
agent-browser diff snapshot --baseline before.txt # 比较当前与保存的文件
agent-browser diff screenshot --baseline before.png # 视觉像素差异
agent-browser diff url <url1> <url2> # 比较两个页面
agent-browser diff url <url1> <url2> --wait-until networkidle # 自定义等待策略
agent-browser diff url <url1> <url2> --selector "#main" # 限定到元素
常见模式
表单提交
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
使用认证保险库进行认证(推荐)
# 保存凭据一次(使用 AGENT_BROWSER_ENCRYPTION_KEY 加密)
# 推荐:通过 stdin 传递密码以避免 shell 历史记录暴露
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# 使用已保存的配置文件登录(LLM 永远不会看到密码)
agent-browser auth login github
# 列出/显示/删除配置文件
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
使用状态持久化的认证
# 登录一次并保存状态
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json
# 在将来的会话中重复使用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
会话持久化
# 在浏览器重启之间自动保存/恢复 cookie 和 localStorage
agent-browser --session-name myapp open https://app.example.com/login
# ... 登录流程 ...
agent-browser close # 状态自动保存到 ~/.agent-browser/sessions/
# 下次,状态自动加载
agent-browser --session-name myapp open https://app.example.com/dashboard
# 加密静态状态
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# 管理已保存的状态
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
数据提取
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # 获取特定元素文本
agent-browser get text body > page.txt # 获取所有页面文本
# JSON 输出用于解析
agent-browser snapshot -i --json
agent-browser get text @e1 --json
并行会话
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i
agent-browser session list
连接到现有 Chrome
# 自动发现启用了远程调试的正在运行的 Chrome
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# 或使用显式 CDP 端口
agent-browser --cdp 9222 snapshot
配色方案(暗黑模式)
# 通过标志持久化暗黑模式(适用于所有页面和新标签页)
agent-browser --color-scheme dark open https://example.com
# 或通过环境变量
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# 或在会话期间设置(对后续命令持久化)
agent-browser set media dark
视口与响应式测试
# 设置自定义视口大小(默认为 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# 测试移动宽度布局
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI:相同 CSS 布局,2 倍像素密度
# 截图保持逻辑视口大小,但内容以更高 DPI 渲染
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# 设备模拟(一步设置视口 + 用户代理)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
scale 参数(第三个参数)设置 window.devicePixelRatio,无需更改 CSS 布局。在测试视网膜渲染或捕获更高分辨率截图时使用它。
可视化浏览器(调试)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # 高亮元素
agent-browser inspect # 打开活动页面的 Chrome DevTools
agent-browser record start demo.webm # 录制会话
agent-browser profiler start # 启动 Chrome DevTools 分析
agent-browser profiler stop trace.json # 停止并保存分析文件(路径可选)
使用 AGENT_BROWSER_HEADED=1 通过环境变量启用有头模式。浏览器扩展在有头和无头模式下均可工作。
本地文件(PDF、HTML)
# 使用 file:// URL 打开本地文件
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
iOS 模拟器(移动 Safari)
# 列出可用的 iOS 模拟器
agent-browser device list
# 在特定设备上启动 Safari
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# 与桌面相同的工作流——快照、交互、重新快照
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # 点击(click 的别名)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up # 移动专用手势
# 截图
agent-browser -p ios screenshot mobile.png
# 关闭会话(关闭模拟器)
agent-browser -p ios close
要求: macOS 带 Xcode、Appium(npm install -g appium && appium driver install xcuitest)
真实设备: 如果预先配置,可与物理 iOS 设备配合使用。使用 --device "<UDID>",其中 UDID 来自 xcrun xctrace list devices。
安全
所有安全功能均为可选启用。默认情况下,agent-browser 对导航、操作或输出不施加任何限制。
内容边界(推荐用于 AI 代理)
启用 --content-boundaries 将页面来源的输出包装在标记中,帮助 LLM 区分工具输出和不受信任的页面内容:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# 输出:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [可访问性树]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
域名白名单
将导航限制到受信任的域名。诸如 *.example.com 的通配符也匹配裸域名 example.com。对非白名单域名的子资源请求、WebSocket 和 EventSource 连接也将被阻止。包括您的目标页面依赖的 CDN 域名:
export AGENT_BROWSER_ALLOWLIST="example.com,*.example.com,cdn.example.com"
敏感内容注入时间
默认情况下,快照中的输入值会被混淆(显示为 ******)。禁用此功能以显示实际值:
export AGENT_BROWSER_SHOW_PASSWORD_VALUES=true
环境变量
export AGENT_BROWSER_HEADED=1 # 启用有头模式
export AGENT_BROWSER_CONTENT_BOUNDARIES=1 # 启用内容边界标记
export AGENT_BROWSER_COLOR_SCHEME=dark # 默认暗黑模式
export AGENT_BROWSER_ENCRYPTION_KEY=... # 静态加密密钥
export AGENT_BROWSER_ALLOWLIST="*.example.com" # 域名白名单
export AGENT_BROWSER_SHOW_PASSWORD_VALUES=true # 在快照中显示密码值
export AGENT_BROWSER_TIMEOUT_DEFAULT=30000 # 以毫秒为单位的默认超时(默认:30000)
代码示例
使用状态文件进行认证
// 保存身份验证状态
const { execSync } = require('child_process');
execSync('agent-browser open https://app.example.com/login');
execSync('agent-browser fill @e1 process.env.USERNAME');
execSync('agent-browser fill @e2 process.env.PASSWORD');
execSync('agent-browser click @e3');
execSync('agent-browser state save auth.json');
// 以后重用时...
execSync('agent-browser state load auth.json');
execSync('agent-browser open https://app.example.com/dashboard');
认证保险库(推荐用于 AI 代理)
此方法是首选的,因为 AI 代理(LLM)永远不会看到凭据——它们由 agent-browser 安全存储的配置文件处理。
# 首次设置:安全存储凭据(AI 代理看不到密码)
echo "$PASSWORD" | agent-browser auth save myapp \
--url https://app.example.com/login \
--username $USERNAME \
--password-stdin
# 按名称登录(AI 代理只指定配置文件名称)
agent-browser auth login myapp
使用会话的完整自动化脚本
#!/bin/bash
# 带有认证的端到端 Web 测试
set -e
# 使用会话名称登录
agent-browser --session e2e-test open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard" --timeout 10000
# 与仪表板交互并截图
agent-browser screenshot --full --screenshot-dir ./screenshots dashboard.png
# 清理
agent-browser close
如果看不到交互式元素
如果在快照后没有交互式元素:
- 检查 DOM 是否已加载:使用
agent-browser wait --load networkidle - 尝试展开的快照:
agent-browser snapshot -i -C包含光标交互式元素(带有onclick处理程序、cursor:pointer等的 div) - 检查 iframe 或 Shadow DOM:使用
agent-browser open后跟agent-browser snapshot -i -C - 检查慢速渲染:
agent-browser wait 2000等待 XHR 或 CSS 动画完成 - 使用 CSS 选择器限制:
agent-browser snapshot -s "#main-content"在已知包含交互式元素的区域内获取元素 - 在 page.html 中转储页面 HTML:
agent-browser get text body > page.html(作为辅助工具使用,但首选基于 refs 的交互,因为它更可靠) - 使用有头模式调试:
agent-browser --headed open查看正在发生的事情 - 启用完整协议日志记录:
export AGENT_BROWSER_VERBOSE=1
如果看到错误或意外行为
- 在日志中搜索错误:设置
export AGENT_BROWSER_VERBOSE=1查看协议级日志 - 使用有头模式:
agent-browser --headed open查看实际操作 - 测试 while 循环策略:对于最终用户测试,可以安全地重试操作。使用 while 循环重试、使用
wait命令等待元素出现并重新快照。请参阅while_loop_guide.py。 - 打开浏览器检查工具:
agent-browser inspect在活动页面上打开 Chrome DevTools - 回退到纯 JavaScript:对于复杂情况,使用
agent-browser evaluate "document.querySelector('#app').shadowRoot.querySelector('my-component').shadowRoot.innerHTML"深入到 Shadow DOM。