使用 agent-browser 进行浏览器自动化
该 CLI 通过 CDP 直接使用 Chrome/Chromium。通过 npm i -g agent-browser、brew install agent-browser 或 cargo install agent-browser 安装。运行 agent-browser install 下载 Chrome。系统上现有的 Chrome、Brave、Playwright 和 Puppeteer 安装会被自动检测。运行 agent-browser upgrade 更新至最新版本。
核心工作流
每个浏览器自动化任务都遵循以下模式:
- 导航:
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 2000
agent-browser snapshot -i # 检查结果
命令链式执行
命令可以通过 && 在单个 shell 调用中链式执行。浏览器通过后台守护进程在命令之间保持持久化,因此链式执行既安全又比单独调用更高效。
# 在单次调用中链式执行 open + snapshot(open 已等待页面加载完成)
agent-browser open https://example.com && 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 screenshot
何时链式执行: 当您无需在继续之前读取中间命令的输出时,使用 &&(例如,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:Chrome 配置文件复用(零配置)
# 列出可用的 Chrome 配置文件
agent-browser profiles
# 复用用户现有的 Chrome 登录状态
agent-browser --profile Default open https://gmail.com
选项 3:持久化配置文件(用于重复任务)
# 首次运行:手动或通过自动化登录
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 填写凭据,提交 ...
# 所有后续运行:已验证
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
选项 4:会话名称(自动保存/恢复 cookies + 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
选项 5:身份验证保管库(凭据加密存储,按名称登录)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login 使用 load 导航,然后在填充/点击之前等待登录表单选择器出现,这在延迟的 SPA 登录屏幕上更可靠。
选项 6:状态文件(手动保存/加载)
# 登录后:
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 的身份验证和令牌刷新模式。
基本命令
# 批量:对于 2 个或更多顺序命令,始终使用 batch。命令按顺序执行。
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 导航
agent-browser open <url> # 导航(别名:goto、navigate)
agent-browser close # 关闭浏览器
agent-browser close --all # 关闭所有活动会话
# 快照
agent-browser snapshot -i # 带有引用的交互元素(推荐)
agent-browser snapshot -i --urls # 为链接包含 href URL
agent-browser snapshot -s "#selector" # 限定 CSS 选择器范围
# 交互(使用快照中的 @ref)
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 2000 # 等待毫秒数
agent-browser wait --url "**/page" # 等待 URL 模式匹配
agent-browser wait --text "Welcome" # 等待文本出现(子字符串匹配)
agent-browser wait --load networkidle # 等待网络空闲(注意:参见陷阱)
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 tab list # 列出所有打开的标签页
agent-browser tab new # 打开一个空白新标签页
agent-browser tab new https://example.com # 在新标签页中打开 URL
agent-browser tab 2 # 按索引切换标签页(从0开始)
agent-browser tab close # 关闭当前标签页
agent-browser tab close 2 # 按索引关闭标签页
# 网络
agent-browser network requests # 检查跟踪的请求
agent-browser network requests --type xhr,fetch # 按资源类型过滤
agent-browser network requests --method POST # 按 HTTP 方法过滤
agent-browser network requests --status 2xx # 按状态码过滤(200、2xx、400-499)
agent-browser network request <requestId> # 查看完整的请求/响应详情
agent-browser network route "**/api/*" --abort # 阻止匹配的请求
agent-browser network har start # 开始 HAR 录制
agent-browser network har stop ./capture.har # 停止并保存 HAR 文件
# 视口和设备模拟
agent-browser set viewport 1920 1080 # 设置视口大小(默认:1280x720)
agent-browser set viewport 1920 1080 2 # 2x 视网膜(相同 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 stream enable # 在自动选择的端口上启动运行时 WebSocket 流式传输
agent-browser stream enable --port 9223 # 绑定特定的 localhost 端口
agent-browser stream status # 检查启用状态、端口、连接和屏幕投射
agent-browser stream disable # 停止运行时流式传输并移除 .stream 元数据文件
# 剪贴板
agent-browser clipboard read # 从剪贴板读取文本
agent-browser clipboard write "Hello, World!" # 向剪贴板写入文本
agent-browser clipboard copy # 复制当前选择
agent-browser clipboard paste # 从剪贴板粘贴
# 对话框(alert、confirm、prompt、beforeunload)
# 默认情况下,alert 和 beforeunload 对话框会自动接受,因此它们不会阻塞代理。
# confirm 和 prompt 对话框仍然需要显式处理。
# 使用 --no-auto-dialog(或 AGENT_BROWSER_NO_AUTO_DIALOG=1)禁用自动处理。
agent-browser dialog accept # 接受对话框
agent-browser dialog accept "my input" # 接受带文本的 prompt 对话框
agent-browser dialog dismiss # 关闭/取消对话框
agent-browser dialog status # 检查当前是否有打开的对话框
# 差异比较(比较页面状态)
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" # 限定元素范围
# 聊天(AI 自然语言控制)
agent-browser chat "open google.com and search for cats" # 单次指令
agent-browser chat # 交互式 REPL 模式
agent-browser -q chat "summarize this page" # 安静模式(仅文本,无工具调用)
agent-browser -v chat "fill in the login form" # 详细模式(显示命令输出)
agent-browser --model openai/gpt-4o chat "take a screenshot" # 覆盖模型
流式传输
每个会话自动在操作系统分配的端口上启动一个 WebSocket 流服务器。使用 agent-browser stream status 查看绑定的端口和连接状态。使用 stream disable 关闭它,使用 stream enable --port <port> 在特定端口上重新启用。
批量执行
运行 2 个或更多顺序命令时,始终使用 batch。Batch 按顺序执行命令,因此依赖命令(如导航然后截图)能够正确工作。每个引用的参数都是一个单独的命令。
# 导航并获取快照
agent-browser batch "open https://example.com" "snapshot -i"
# 在单次调用中导航、快照和截图
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# 点击、等待、然后截图
agent-browser batch "click @e1" "wait 1000" "screenshot"
# 使用 --bail 在第一个错误时停止
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
仅在需要读取输出以决定下一个命令时,才使用单个命令(而非 batch)。例如,当您需要读取引用以决定点击什么时,必须将 snapshot -i 作为单个命令运行。读取快照后,将剩余步骤批量执行。
还支持 stdin 模式用于程序化使用:
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
效率策略
这些模式最大限度地减少工具调用次数和令牌消耗。
使用 --urls 避免重新导航。 当需要访问页面中的链接时,使用 snapshot -i --urls 一次获取所有 href URL。然后直接 open 每个 URL,而不是点击引用并导航回退。
快照一次,多次操作。 永远不要对同一页面重新快照。从单个快照中提取所有需要的信息(引用、URL、文本),然后批量执行剩余操作。
多页面工作流(例如“访问 N 个站点并截取每个站点的截图”):
# 1. 在单次调用中获取所有 URL
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 读取输出以提取 URL,然后直接访问每个 URL:
# 2. 每个目标站点一个 batch
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"
这种方法使用 4 次工具调用而不是 14 次以上。永远不要在访问之间返回列表页面。
常见模式
表单提交
# 导航并获取表单结构
agent-browser batch "open https://example.com/signup" "snapshot -i"
# 读取快照输出以识别表单引用,然后填写并提交
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
使用身份验证保管库进行身份验证(推荐)
# 保存凭据一次(使用 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://example.com/settings
agent-browser snapshot -i
# 截取期望状态的截图
agent-browser screenshot --screenshot-dir ./baselines
# 稍后:比较当前页面状态与基线
agent-browser diff screenshot --baseline ./baselines/screenshot.png
完整文档请访问 agent-browser 文档