一句话定位agent-browser 是 Vercel Labs 开源的浏览器自动化 CLI用 Rust 编写专为 AI Agent 设计。核心特点是Snapshot Ref 机制让 LLM 能精准操作网页同时支持命令链式调用、批量执行、实时画面流、Dashboard 监控以及多种云浏览器提供商接入。目前 34.8k Stars。一、安装npm推荐npminstall-gagent-browser agent-browserinstall# 首次下载 Chrome for TestingHomebrewmacOSbrewinstallagent-browser agent-browserinstallCargoRustcargoinstallagent-browser agent-browserinstall首次需要跑agent-browser install下载自动化专用 Chrome。如果你本地已有 Chrome、Brave、Playwright 或 Puppeteer 的 Chrome它会自动检测复用。升级也很简单agent-browser upgrade# 自动识别安装方式并更新二、核心设计Snapshot Ref这是 agent-browser 和传统自动化工具Puppeteer/Playwright最大的区别。传统方式是用 CSS 选择器或 XPath 定位元素容易因为页面结构变化而失效。agent-browser 的做法是1. 先拍快照Snapshotagent-browseropenexample.com agent-browser snapshot输出是一个 accessibility tree每个交互元素都带有一个 ref- headingExample Domain[refe1][level1]- buttonSubmit[refe2]- textboxEmail[refe3]-linkLearn more[refe4]2. 用 ref 精准操作agent-browser click e2 agent-browser fill e3testexample.comagent-browser get text e1为什么这种方式更适合 AI确定性ref 绑定的是快照里的具体元素不会因为页面动态变化而错位快速不需要重新查询 DOMLLM 友好AI 先读 snapshot再决定操作哪个 ref整个流程自然畅通加上-i参数可以只输出交互元素减少噪音agent-browser snapshot-i三、基础操作命令agent-browser 的命令设计得很直观基本覆盖日常自动化需求导航与页面操作agent-browseropenexample.com# 打开页面agent-browseropen# 只启动浏览器停在 about:blankagent-browser back# 后退agent-browser forward# 前进agent-browser reload# 刷新agent-browser pushstate /new-path# SPA 客户端路由元素交互agent-browser click e1# 点击agent-browser dblclick e2# 双击agent-browser fill e3text# 清空并填充agent-browsertypee3text# 输入不清空agent-browser hover e4# 悬停agent-browserselecte5option# 下拉框选择agent-browser check e6# 勾选复选框agent-browser uncheck e6# 取消勾选agent-browser scroll down500# 滚动agent-browser scrollintoview e7# 滚动到元素可见agent-browser drag src tgt# 拖拽agent-browser upload e8./file.pdf# 上传文件键盘操作agent-browser press Enter# 按键agent-browser pressControla# 组合键agent-browser keyboardtypehello# 模拟真实按键输入agent-browser keydown Shift# 按住agent-browser keyup Shift# 释放截图与 PDFagent-browser screenshot page.png# 截图当前视口agent-browser screenshot--fullpage.png# 整页截图agent-browser screenshot--annotate# 带元素编号标注的截图方便 AI 识别agent-browser pdf page.pdf# 保存为 PDF四、等待机制处理异步加载现代网页很多内容是异步加载的agent-browser 提供了多种等待方式# 等待元素出现agent-browserwait#submit-button# 等待固定时间agent-browserwait3000# 等待文本出现agent-browserwait--textWelcome# 等待 URL 匹配agent-browserwait--url**/dashboard# 等待页面加载完成agent-browserwait--loadnetworkidle# 等待 JS 条件满足agent-browserwait--fnwindow.ready true# 等待元素消失agent-browserwait#spinner--statehidden加载状态选项load页面完全加载、domcontentloadedDOM 就绪、networkidle网络空闲五、批量执行减少进程启动开销每个 agent-browser 命令默认会复用后台 daemon已经比传统方案快很多。但如果要执行一连串操作用batch可以进一步减少开销# 参数模式agent-browser batchopen https://example.comsnapshot -iscreenshot# 出错即停agent-browser batch--bailopen https://example.comclick e1screenshot# JSON 管道模式echo[ [open, https://example.com], [snapshot, -i], [click, e1], [screenshot, result.png] ]|agent-browser batch--json六、命令链式调用在 shell 里用串联命令browser session 会在后台保持# 打开、等加载、截图一气呵成agent-browseropenexample.comagent-browserwait--loadnetworkidleagent-browser screenshot page.png# 填表单并提交agent-browser fill e1userexample.comagent-browser fill e2passagent-browser click e3适合不需要解析中间输出的场景。如果需要先读 snapshot 再决定操作哪个 ref就得分步执行。七、信息获取与状态检查# 获取元素内容agent-browser get text e1# 文本内容agent-browser get html e1# innerHTMLagent-browser get value e2# input 值agent-browser get attr e1 href# 属性值agent-browser get title# 页面标题agent-browser get url# 当前 URLagent-browser get count.item# 匹配元素数量agent-browser get box e1# 元素边界框# 状态检查agent-browser is visible e1# 是否可见agent-browser is enabled e1# 是否可用agent-browser is checked e1# 是否勾选加上--json参数可以输出结构化数据方便程序解析agent-browser snapshot--jsonagent-browser get text e1--json八、语义化定位不用选择器也能找元素除了 CSS 选择器和 refagent-browser 还支持语义化定位对可读性很友好# 按 ARIA roleagent-browserfindrole button click--nameSubmit# 按文本内容agent-browserfindtextSign Inclick# 按 labelagent-browserfindlabelEmailfilltesttest.com# 按 placeholderagent-browserfindplaceholderSearchfillquery# 按 alt 文本agent-browserfindaltLogoclick# 按 testidagent-browserfindtestidsubmit-btnclick# 取第 N 个匹配agent-browserfindnth2atext# 第一个/最后一个agent-browserfindfirst.itemclick agent-browserfindlast.itemclick支持的动作click,fill,type,hover,focus,check,uncheck,text九、网络拦截与监控# 拦截特定 URLagent-browser network route*api*# 阻断请求agent-browser network route*google-analytics*--abort# 模拟响应agent-browser network route*api/users--body{users:[]}# 按资源类型阻断如屏蔽所有脚本agent-browser network route*--abort--resource-type script# 查看请求列表agent-browser network requests agent-browser network requests--filterapi agent-browser network requests--typexhr,fetch agent-browser network requests--methodPOST agent-browser network requests--status2xx# 查看单个请求详情agent-browser network requestrequestId# HAR 录制agent-browser network har start agent-browser network har stop output.har十、Tab 与窗口管理# 列出所有 tabagent-browser tab# 新建 tabagent-browser tab new https://docs.example.com# 新建 tab 并加标签方便后续引用agent-browser tab new--labeldocs https://docs.example.com# 切换 tab用 id 或 labelagent-browser tab t2 agent-browser tab docs# 关闭 tabagent-browser tab close t2 agent-browser tab close docs# 新建窗口agent-browser window newTab id 是稳定的如t1,t2关闭其他 tab 后 id 也不会重用脚本里可以放心引用。十一、Cookie 与存储# Cookieagent-browser cookies# 获取所有agent-browser cookiessetsessionId abc123# 设置单个agent-browser cookiesset--curlcookies.txt# 从 cURL dump 导入agent-browser cookiesclear# 清空# localStorageagent-browser storagelocal# 获取全部agent-browser storagelocalmyKey# 获取某个 keyagent-browser storagelocalsetmyKey myValue# 设置agent-browser storagelocalclear# 清空# sessionStorage同上agent-browser storage session十二、Diff 功能对比页面变化agent-browser 内置了 diff 能力很适合做回归测试# 对比当前 snapshot 和上一次agent-browserdiffsnapshot# 对比当前 snapshot 和基准文件agent-browserdiffsnapshot--baselinebefore.txt# 截图对比像素级agent-browserdiffscreenshot--baselinebefore.png# 对比两个 URLagent-browserdiffurl https://v1.com https://v2.com agent-browserdiffurl https://v1.com https://v2.com--screenshot十三、调试与诊断# 诊断环境agent-browser doctor agent-browser doctor--fix# 自动修复agent-browser doctor--offline--quick# 跳过网络检查# 追踪录制agent-browser trace start agent-browser trace stop trace.zip# 性能分析agent-browser profiler start agent-browser profiler stop profile.json# 查看控制台输出agent-browser console agent-browser console--json# 查看页面错误agent-browser errors# 高亮元素agent-browser highlight e1# 打开 Chrome DevToolsagent-browser inspect十四、AI Chat自然语言控制浏览器agent-browser 集成了 Vercel AI Gateway可以直接用自然语言控制浏览器# 单轮指令agent-browser chatopen google.com and search for cats# 交互式 REPLagent-browser chat# take a screenshot# click the first result# 安静模式只输出 AI 回复agent-browser-qchatsummarize this page# 详细模式显示底层命令执行agent-browser-vchatfill in the login form需要配置环境变量exportAI_GATEWAY_API_KEY***exportAI_GATEWAY_MODELanthropic/claude-sonnet-4.6# 默认exportAI_GATEWAY_URLhttps://ai-gateway.vercel.sh# 默认十五、Dashboard 实时监控启动本地 Web Dashboard可以在浏览器里实时观看 AI 操作agent-browser dashboard start# 默认端口 4848agent-browser dashboard start--port8080# 之后正常执行命令画面会自动同步到 dashboardagent-browseropenexample.com agent-browser snapshot# 停止 dashboardagent-browser dashboard stopDashboard 显示内容实时画面浏览器视口的 JPEG 帧流活动流命令执行历史和时间线控制台输出log / warn / error会话管理创建新会话AI Chat在 Dashboard 里直接和 AI 对话十六、Streaming实时画面流每个 session 默认会启动一个 WebSocket server可以通过 WebSocket 接收浏览器画面或发送输入事件# 查看当前流的端口agent-browser stream status# 指定端口AGENT_BROWSER_STREAM_PORT9223agent-browseropenexample.com# 启停控制agent-browser streamenable--port9223agent-browser stream disableWebSocket 协议支持接收framebase64 JPEG、发送input_mouse、input_keyboard、input_touch事件。适合做人机协同的 “pair browsing” 场景。十七、配置持久化不想每次敲一堆参数用配置文件// agent-browser.json项目级{headed:true,proxy:http://localhost:8080,screenshotFormat:jpeg,screenshotQuality:80}配置优先级低到高~/.agent-browser/config.json— 用户级默认./agent-browser.json— 项目级覆盖AGENT_BROWSER_*环境变量CLI 参数十八、云浏览器提供商如果本地不能跑浏览器比如 serverless 环境agent-browser 支持直接接入云浏览器提供商启用方式Browserbase-p browserbaseBROWSERBASE_API_KEYBrowserless-p browserlessBROWSERLESS_API_KEYBrowser Use-p browseruseBROWSER_USE_API_KEYKernel-p kernelKERNEL_API_KEYAgentCore-p agentcoreAWS Bedrock自动读 AWS 凭证切换后所有命令行为完全一致只是后端换成了云端浏览器。十九、iOS 模拟器支持agent-browser 可以控制 iOS Simulator 里的 Safari做真机移动测试# 列出可用设备agent-browser device list# 在 iPhone 16 Pro 上打开页面agent-browser-pios--deviceiPhone 16 Proopenhttps://example.com# 同样的命令agent-browser-pios snapshot-iagent-browser-pios tap e1 agent-browser-pios swipe up agent-browser-pios screenshot mobile.png需要提前安装 Appium 和 XCUITest driver。首次启动模拟器大约 30-60 秒后续命令很快。二十、典型 AI Agent 工作流把上面的命令组合起来一个完整的 AI 浏览器自动化工作流是这样的# 1. 打开目标页面agent-browseropenhttps://example.com/login# 2. 获取带 ref 的快照agent-browser snapshot-i--json# 3. AI 从 snapshot 里识别出# e1 Email 输入框, e2 Password 输入框, e3 Submit 按钮# 4. 执行操作agent-browser fill e1userexample.comagent-browser fill e2passwordagent-browser click e3# 5. 等待页面跳转agent-browserwait--url**/dashboard# 6. 重新快照确认状态agent-browser snapshot-i--json# 7. 截图留存agent-browser screenshot result.png或者写成 batchagent-browser batch\[open,https://example.com/login]\[snapshot,-i]\[fill,e1,userexample.com]\[fill,e2,password]\[click,e3]\[wait,--url,**/dashboard]\[screenshot,result.png]写在最后agent-browser 的定位不是替代 Puppeteer/Playwright而是做专为 AI Agent 优化的浏览器 CLI。它的 Snapshot Ref 机制、原生 Rust 性能、命令链式调用、batch 批量执行、内置 AI Chat、Dashboard 监控都是围绕「让 AI 更高效地操作浏览器」这个核心目标设计的。如果你在做 AI Agent、自动化测试、网页爬虫、或者需要让 LLM 能看懂并操作网页agent-browser 值得投入时间试试。GitHubhttps://github.com/vercel-labs/agent-browser文档https://agent-browser.dev相关工具如果你在用 agent-browser 做 AI 浏览器自动化后续通常也会遇到多模型接入、API Key 管理和用量统计的问题。可以了解一下 EbeeAI它提供统一的 AI API 网关新用户注册后有 $10 试用额度适合先用小规模自动化任务验证成本和稳定性。