首页 Agent Browser 速查表
v0.27.0 2026-05-07 vercel-labs/agent-browser
打开 Zread CodeWiki
340px

🧭 快速定位 >>>

面向 AI agent 的浏览器自动化 CLI。核心思路是先打开页面，再通过 snapshot 拿到 `@e1` 这类引用，后续点击、填写、提取信息都围绕这些 ref 展开。
  • 适合场景：网页测试、表单自动化、数据抓取、截图、录屏、CDP 连接现有浏览器
  • open -> snapshot -i -> click/fill/get -> wait -> screenshot/pdf
  • v0.27.0
  • vercel-labs/agent-browser
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "user@example.com"
agent-browser wait --load networkidle
agent-browser screenshot result.png

🚀 起手工作流 >>>

可以把它类比成“浏览器版命令行状态机”。先把页面状态拿到手，再继续发命令，不要跳过 snapshot 直接盲点。

安装与帮助

npx agent-browser --help
npx agent-browser install
agent-browser --version
agent-browser <command> --help

标准操作顺序

# 1. 打开页面
agent-browser open example.com

# 2. 获取可交互元素
agent-browser snapshot -i

# 3. 根据 ref 操作
agent-browser fill @e2 "hello"
agent-browser click @e3

# 4. 等待页面稳定
agent-browser wait --load networkidle

# 5. 再次抓取新状态
agent-browser snapshot -i

连接已打开的浏览器

# Chrome / Edge 开启远程调试端口后连接
agent-browser --cdp 9222 snapshot

# 或者先建立连接，再继续操作
agent-browser connect 9222
agent-browser snapshot -i

页面打开与快照

导航

agent-browser open <url>
agent-browser back
agent-browser forward
agent-browser reload
agent-browser close
agent-browser pushstate <url>

快照选项

agent-browser snapshot
agent-browser snapshot -i
agent-browser snapshot -c
agent-browser snapshot -d 3
agent-browser snapshot -s “#main”
agent-browser snapshot --urls
  • -i：只保留交互元素，日常最常用
  • -c：压缩空结构，适合减少输出噪音
  • -s：只分析某个局部区域，适合大页面
  • -d：深度抓取延迟（毫秒）
  • --urls：快照中包含元素的 href URL（v0.25.0+）
  • -C：已废弃（cursor-interactive 元素现已默认包含）

🖱️ 交互命令 >>>

ref 交互比 CSS 选择器更稳，尤其适合给 agent 用。只有在 snapshot 不方便时，再退回 `find` 或普通 selector。

常见点击与输入

agent-browser click @e1
agent-browser dblclick @e1
agent-browser hover @e1
agent-browser focus @e1

agent-browser fill @e2 "text"
agent-browser type @e2 "text"
agent-browser press Enter
agent-browser press Control+a

表单与拖拽

agent-browser check @e1
agent-browser uncheck @e1
agent-browser select @e1 "value"
agent-browser select @e1 "a" "b"
agent-browser upload @e1 ./file.pdf
agent-browser drag @e1 @e2
agent-browser download @e3 ./report.pdf

滚动与鼠标

agent-browser scroll down 500
agent-browser scroll right 240
agent-browser scrollintoview @e1

agent-browser mouse move 100 200
agent-browser mouse down left
agent-browser mouse up left
agent-browser mouse wheel 600

语义定位

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "agent-browser"
agent-browser find testid "submit-btn" click
agent-browser find nth 2 "a" hover

抓取与状态检查

读取页面信息

agent-browser get text @e1
agent-browser get html @e1
agent-browser get value @e1
agent-browser get attr @e1 href
agent-browser get title
agent-browser get url
agent-browser get count ".item"
agent-browser get box @e1
agent-browser get styles @e1

状态判断

agent-browser is visible @e1
agent-browser is enabled @e1
agent-browser is checked @e1

等待页面稳定

agent-browser wait @e1
agent-browser wait 1500
agent-browser wait --text "Success"
agent-browser wait --url "**/dashboard"
agent-browser wait --load networkidle
agent-browser wait --fn "window.appReady === true"

⌨️ 键盘、剪贴板与 Diff >>>

不依赖元素引用的全局操作，以及快照/截图对比能力。

纯键盘输入

agent-browser keyboard type "hello world"
agent-browser keyboard inserttext "hello"

剪贴板操作

agent-browser clipboard read
agent-browser clipboard write "text to copy"
agent-browser clipboard copy @e1
agent-browser clipboard paste

Diff 对比

agent-browser diff snapshot
agent-browser diff screenshot --baseline
agent-browser diff url <url1> <url2>

性能分析

agent-browser profiler start
agent-browser profiler stop profile.json

HAR 抓包

agent-browser network har start
agent-browser network har stop output.har

🔐 认证保险库 >>>

保存和复用登录凭证，支持密码管理和自动填充。
agent-browser auth save myapp --url https://example.com --username user --password pass
agent-browser auth login myapp
agent-browser auth list
agent-browser auth show myapp
agent-browser auth delete myapp

📋 批量执行与动作确认 >>>

批量执行命令和动作确认流程。

批量执行

agent-browser batch [--bail]
# 输入 JSON 数组命令
echo '[["open","example.com"],["snapshot","-i"]]' | agent-browser batch

# v0.25.0+ 支持内联参数
agent-browser batch open example.com snapshot -i

动作确认

agent-browser confirm <id>
agent-browser deny <id>

🗂️ 会话、存储与网络 >>>

会话相关功能决定了“状态能不能复用”。需要保留登录态时，优先考虑 `--profile` 或 `--state`，而不是每次重登。

会话与标签页

agent-browser --session qa open site-a.com
agent-browser --session qa snapshot -i
agent-browser session
agent-browser session list
agent-browser close --all

agent-browser tab
agent-browser tab new https://example.com
agent-browser tab new --label mytab https://example.com
agent-browser tab t1
agent-browser tab close t1

Chrome Profile 管理（v0.24.1+）

# 列出本机可用的 Chrome profile
agent-browser profiles

# 使用指定 profile 目录
agent-browser --profile "Profile 5" open https://example.com

Cookies 与 Storage

agent-browser cookies
agent-browser cookies set token abc123 --url https://example.com
agent-browser cookies set --curl ./cookies.txt
agent-browser cookies clear

agent-browser storage local
agent-browser storage local auth
agent-browser storage local set theme dark
agent-browser storage local clear

浏览器设置

agent-browser set viewport 1440 900
agent-browser set device "iPhone 12"
agent-browser set geo 37.7749 -122.4194
agent-browser set offline on
agent-browser set headers '{"X-Test":"1"}'
agent-browser set credentials admin secret123
agent-browser set media dark
agent-browser set media light reduced-motion

网络拦截

agent-browser network route "**/api/*" --abort
agent-browser network route "**/data.json" --body '{"mock":true}'
agent-browser network route "**/analytics*" --resource-type script,fetch
agent-browser network requests
agent-browser network requests --filter "api"
agent-browser network requests --type xhr
agent-browser network requests --method POST
agent-browser network requests --status 200
agent-browser network request <requestId>
agent-browser network requests --clear
agent-browser network unroute

📊 仪表板、流与 Dialog >>>

v0.23+ 新增可视化仪表板和 WebSocket 流管理。dialog 命令用于检查和处理 JavaScript 弹窗。

可视化仪表板

agent-browser dashboard start
agent-browser dashboard stop
agent-browser dashboard install

WebSocket 流管理

agent-browser stream enable
agent-browser stream disable
agent-browser stream status

Dialog 处理

agent-browser dialog status
agent-browser --no-auto-dialog open example.com
  • --no-auto-dialog：禁用自动接受 alert/beforeunload
  • 自动 dialog 接受默认开启，防止弹窗阻塞
  • --auto-connect agent-browser --auto-connect state save ./auth.json：自动发现并连接已运行的 Chrome，复用其认证状态（Tip: ）

🤖 AI 对话（v0.25.0+） >>>

v0.25.0 新增 AI chat 命令，可通过自然语言对话方式控制浏览器，适合需要多轮交互的复杂场景。
# 进入 AI 对话模式，控制浏览器执行任务
agent-browser chat "滚动到页面底部，点击注册按钮"

# 对话过程中可随时截图确认
agent-browser screenshot
  • AI chat 内嵌于 CLI 内，无需单独启动服务
  • 结合 dashboard 可视化调试 AI 决策链路
  • 适合复杂多步操作，比单条命令链更灵活

⚛️ React DevTools 集成（v0.27.0+） >>>

v0.27.0 新增 React 组件树检查、fiber 调试、渲染分析和 Suspense 边界诊断，是前端开发和调试的利器。

组件树与检查

agent-browser react tree
agent-browser react inspect <fiberId>

渲染分析

agent-browser react renders start
agent-browser react renders stop

Suspense 边界诊断

agent-browser react suspense
  • react tree
  • react renders
  • react suspense

📊 Web Vitals（v0.27.0+） >>>

v0.27.0 新增 Web Vitals 命令，报告 LCP/CLS/TTFB/FCP/INP 等核心指标及 React 水合阶段。
agent-browser vitals
agent-browser vitals https://example.com

🔀 SPA 导航（v0.27.0+） >>>

v0.27.0 新增 pushstate 命令，支持客户端路由跳转而不触发整页刷新。
agent-browser pushstate /dashboard
agent-browser pushstate /products/123

🧩 初始化脚本与特性开关（v0.27.0+） >>>

v0.27.0 新增 --init-script 和 --enable 全局选项，用于首次导航前注册脚本和启用内置特性。
# 初始化脚本（可重复）
agent-browser --init-script ./setup.js open example.com
agent-browser --init-script ./auth.js open example.com

# 启用内置特性
agent-browser --enable react-devtools open example.com
  • AGENT_BROWSER_INIT_SCRIPTS
  • AGENT_BROWSER_ENABLE --enable
  • react-devtools：等

🩺 doctor 命令（v0.26.0+） >>>

v0.26.0 新增 doctor 命令，一键诊断环境、Chrome、守护进程、配置文件、安全和 providers 问题。
agent-browser doctor
agent-browser doctor --offline
agent-browser doctor --quick
agent-browser doctor --fix
agent-browser doctor --json
  • --offline：跳过网络探测
  • --quick：跳过启动测试
  • --fix：自动修复（安装 Chrome、关闭版本不匹配的守护进程、清理过期状态文件）
  • --json：结构化输出

🛠️ 调试、截图与录制 >>>

这部分适合排查”为什么 agent 没点对””为什么页面状态不对”。思路和前端排查问题很像，先看页面表现，再看控制台和 trace。

截图与 PDF

agent-browser screenshot
agent-browser screenshot page.png
agent-browser screenshot --full
agent-browser pdf page.pdf

调试命令

agent-browser console
agent-browser console --clear
agent-browser errors
agent-browser errors --clear
agent-browser highlight @e1
agent-browser eval "document.title"

Trace 与录屏

agent-browser trace start
agent-browser trace stop trace.zip

agent-browser record start ./demo.webm
agent-browser click @e1
agent-browser record stop

⚙️ 全局选项与环境变量 >>>

全局选项主要控制浏览器来源、状态复用和输出格式。脚本场景里最常见的是 `--json`、`--session`、`--profile`、`--cdp`。

常用全局选项

agent-browser --json snapshot -i
agent-browser --headed open example.com
agent-browser --session test open example.com
agent-browser --profile ~/.browser-profile open example.com
agent-browser --state ./auth.json open example.com
agent-browser --auto-connect open example.com
agent-browser --proxy http://127.0.0.1:7890 open example.com
agent-browser --proxy-bypass "localhost,*.internal.com" open example.com
agent-browser --ignore-https-errors open https://localhost:8443
agent-browser --allow-file-access open file:///tmp/demo.html
agent-browser --user-agent "Custom UA" open example.com
agent-browser --args "--no-sandbox,--disable-blink-features=AutomationControlled" open example.com
agent-browser --no-auto-dialog open example.com
agent-browser --idle-timeout 10s open example.com
agent-browser --with-deps install
agent-browser --annotate screenshot annotated.png
agent-browser --extension ./my-extension open example.com
agent-browser --color-scheme dark open example.com
agent-browser --download-path ~/Downloads open example.com
agent-browser --engine lightpanda open example.com
agent-browser --debug open example.com

Provider 相关

agent-browser -p browserbase open example.com
agent-browser -p browseruse open example.com
agent-browser -p browserless open example.com
agent-browser -p kernel open example.com
agent-browser -p agentcore open example.com

# iOS 模拟器场景
agent-browser -p ios open example.com
agent-browser -p ios --device "iPhone 15 Pro" open example.com

环境变量

# 配置文件与会话
AGENT_BROWSER_CONFIG=~/.agent-browser/config.json  # 配置文件路径（--config）
AGENT_BROWSER_SESSION=qa                             # 默认会话名称
AGENT_BROWSER_SESSION_NAME=myapp                     # 自动保存/恢复状态名称
AGENT_BROWSER_STATE=./auth.json                      # 加载保存的认证状态文件

# 浏览器来源与模式
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chrome        # 自定义浏览器路径
AGENT_BROWSER_HEADED=1                               # 显示浏览器窗口（非 headless）
AGENT_BROWSER_ENGINE=chrome                          # 浏览器引擎：chrome / lightpanda
AGENT_BROWSER_AUTO_CONNECT=1                         # 自动发现并连接运行中的 Chrome

# 输出与调试
AGENT_BROWSER_JSON=1                                 # JSON 输出
AGENT_BROWSER_ANNOTATE=1                             # 带编号标签的截图
AGENT_BROWSER_DEBUG=1                                # 调试输出
AGENT_BROWSER_SCREENSHOT_DIR=~/screenshots           # 默认截图目录
AGENT_BROWSER_SCREENSHOT_QUALITY=85                  # JPEG 质量 0-100
AGENT_BROWSER_SCREENSHOT_FORMAT=png                  # 截图格式：png / jpeg
AGENT_BROWSER_CONTENT_BOUNDARIES=1                   # 页面输出边界标记（LLM 安全）
AGENT_BROWSER_MAX_OUTPUT=5000                        # 页面输出最大字符数

# 安全与权限
AGENT_BROWSER_IGNORE_HTTPS_ERRORS=1                  # 忽略 HTTPS 证书错误
AGENT_BROWSER_ALLOW_FILE_ACCESS=1                   # 允许 file:// URLs 访问本地文件
AGENT_BROWSER_ALLOWED_DOMAINS=*.example.com          # 逗号分隔的允许域名模式

# 动作策略与确认
AGENT_BROWSER_ACTION_POLICY=./policy.json            # 动作策略 JSON 文件路径
AGENT_BROWSER_CONFIRM_ACTIONS=delete,exec           # 需要确认的动作类别
AGENT_BROWSER_CONFIRM_INTERACTIVE=1                 # 启用交互式确认提示
AGENT_BROWSER_NO_AUTO_DIALOG=1                      # 禁用自动关闭 alert/beforeunload

# 代理与网络
AGENT_BROWSER_PROXY=http://127.0.0.1:7890            # 代理服务器 URL
AGENT_BROWSER_PROXY_BYPASS=localhost,*.internal.com  # 跳过代理的主机
HTTP_PROXY=http://127.0.0.1:7890                     # 标准代理环境变量
HTTPS_PROXY=http://127.0.0.1:7890                    # 标准代理环境变量
ALL_PROXY=socks5://127.0.0.1:7890                    # SOCKS 代理
NO_PROXY=localhost,127.0.0.1                         # 跳过代理的主机

# 扩展与自定义
AGENT_BROWSER_EXTENSIONS=/ext1,/ext2                  # 逗号分隔的扩展路径
AGENT_BROWSER_USER_AGENT="Custom UA"                 # 自定义 User-Agent
AGENT_BROWSER_ARGS=--no-sandbox,--disable-blink-features=AutomationControlled  # 浏览器启动参数

# 流与性能
AGENT_BROWSER_STREAM_PORT=9223                       # WebSocket 流式传输端口覆盖
AGENT_BROWSER_IDLE_TIMEOUT_MS=60000                  # 空闲后自动关闭（毫秒）

# iOS 模拟器
AGENT_BROWSER_IOS_DEVICE="iPhone 15 Pro"             # 默认 iOS 设备名称
AGENT_BROWSER_IOS_UDID=<simulator-udid>              # iOS 设备 UDID

# 时间与超时
AGENT_BROWSER_DEFAULT_TIMEOUT=25000                  # 默认超时毫秒

# Provider（云浏览器）
AGENT_BROWSER_PROVIDER=browserbase                   # 云浏览器提供商

# 状态加密（可选）
AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>       # AES-256-GCM 加密密钥
AGENT_BROWSER_STATE_EXPIRE_DAYS=30                   # 自动删除旧状态的天数

# AgentCore provider（v0.24.0+）
AGENTCORE_REGION=us-west-2
AGENTCORE_PROFILE_ID=<profile-id>
AGENTCORE_BROWSER_ID=<browser-id>

📄 配置文件 >>>

agent-browser 查找 agent-browser.json 在多个位置，按优先级覆盖。配置文件 + 环境变量 + CLI 标志三者配合，实现灵活的本地固定 CDP 服务配置。

配置位置与优先级

agent-browser 按以下顺序查找配置文件（从低到高优先级，后面的覆盖前面的）：

配置示例

// ~/.agent-browser/config.json
{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "cdp": "9222",
  "sessionName": "default-session"
}

布尔标志

布尔标志接受可选的 true/false 值来覆盖配置：
--headed           # 启用 headed 模式
--headed false     # 禁用 headed，即使配置文件中设为 true

🧪 高频 Recipes >>>

下面这些组合更接近真实使用。不要把命令拆开死记，记“套路”更高效，就像前端里你记的是调试链路，不是单个 API 名字。

登录后复用状态

# 首次登录
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"

# 后续执行直接复用 profile
agent-browser --profile ./.agent-browser-profile open https://app.example.com/dashboard

连接本地 Chrome 做人工接管

# 先用远程调试端口启动 Chrome / Edge
chrome.exe --remote-debugging-port=9222

# 再由 agent-browser 接管
agent-browser --cdp 9222 snapshot -i
agent-browser click @e1
agent-browser screenshot attached.png

设置本地固定 CDP 服务作为默认连接器

不想每次下载浏览器？想复用本地 Chrome 的配置和扩展？设置固定 CDP 服务：

抓取列表页文本

agent-browser open https://example.com/list
agent-browser wait --load networkidle
agent-browser snapshot -i -c
agent-browser get count ".item"
agent-browser get text @e4

不要混淆：agent-browser vs playwright-cli

agent-browserplaywright-cli
出品方Vercel LabsMicrosoft
元素引用语法@e1（at-e1）e15（纯数字后缀）
连接已有浏览器--auto-connect（推荐）/ --cdp 9222（手动）--cdp via 配置文件
Provider 生态Browserbase、Browserless、Kernel、AgentCore、iOS 模拟器等传统 Playwright Provider
AI 集成v0.25.0+ 内嵌 chat 命令，支持自然语言控制无
OAuth MCP支持（v0.24.0+）无
适用场景AI agent 驱动、需要会话复用、云端浏览器、多 Provider测试驱动、session 状态管理、Playwright 生态深度用户
两者功能有较大重叠（open/snapshot/click/fill/screenshot 等），但定位不同：
  • agent-browser 更适合 AI agent 场景，强调会话复用、Provider 生态、OAuth MCP 和自然语言交互
  • playwright-cli 更适合测试和 Playwright 生态深度用户，强调 session/profile 管理和传统测试工作流

🧾 版本变更 >>>

按官方发布说明整理本次跨版本更新中对速查用户最重要的变化。

v0.27.0

  • react tree react inspect <fiberId> react renders start|stop react suspense
  • vitals [url]
  • pushstate <url>
  • --init-script <path> --enable <feature> react-devtools
  • network route --resource-type <csv>
  • cookies set --curl <file>
  • Dashboard 代理支持 — 可观测仪表板现在支持反向代理部署

v0.26.0

  • agent-browser doctor --offline --quick --fix --json
  • t1 t2 tab new --label <name>
  • agent-browser skills get core
  • agent-browser.schema.json
  • --state AGENT_BROWSER_STATE