agent-browser

面向 AI 代理的无头浏览器自动化 CLI。快速的本地 Rust CLI。

安装

全局安装（推荐）

安装本地 Rust 二进制文件：

npm install -g agent-browser
agent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次需要）

项目安装（本地依赖）

适用于希望在 package.json 中固定版本的项目：

npm install agent-browser
agent-browser install

然后通过 package.json 脚本使用或直接调用 agent-browser。

Homebrew（macOS）

brew install agent-browser
agent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次需要）

Cargo（Rust）

cargo install agent-browser
agent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次需要）

从源码构建

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native   # 需要 Rust（https://rustup.rs）
pnpm link --global  # 使 agent-browser 全局可用
agent-browser install

Linux 依赖

在 Linux 上，安装系统依赖：

agent-browser install --with-deps

要求

Chrome - 运行 agent-browser install 从 Chrome for Testing 下载 Chrome（Google 官方自动化通道）。守护进程不需要 Playwright 或 Node.js。
Rust - 仅在从源码构建时需要（参见上面的"从源码构建"）。

快速开始

agent-browser open example.com
agent-browser snapshot                    # 获取带引用的可访问性树
agent-browser click @e2                   # 通过快照中的引用点击
agent-browser fill @e3 "test@example.com" # 通过引用填充
agent-browser get text @e1                # 通过引用获取文本
agent-browser screenshot page.png
agent-browser close

传统选择器（也支持）

agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"
agent-browser find role button click --name "Submit"

命令

核心命令

agent-browser open <url>              # 导航到 URL（别名：goto, navigate）
agent-browser click <sel>             # 点击元素（--new-tab 在新标签页打开）
agent-browser dblclick <sel>          # 双击元素
agent-browser focus <sel>             # 聚焦元素
agent-browser type <sel> <text>       # 在元素中输入
agent-browser fill <sel> <text>       # 清空并填充
agent-browser press <key>             # 按键（Enter, Tab, Control+a）（别名：key）
agent-browser keyboard type <text>    # 使用真实按键输入（无选择器，当前焦点）
agent-browser keyboard inserttext <text>  # 插入文本而不触发按键事件（无选择器）
agent-browser keydown <key>           # 按下按键
agent-browser keyup <key>             # 释放按键
agent-browser hover <sel>             # 悬停元素
agent-browser select <sel> <val>      # 选择下拉选项
agent-browser check <sel>             # 勾选复选框
agent-browser uncheck <sel>           # 取消勾选复选框
agent-browser scroll <dir> [px]       # 滚动（up/down/left/right，--selector <sel>）
agent-browser scrollintoview <sel>    # 滚动元素到可视区域（别名：scrollinto）
agent-browser drag <src> <tgt>        # 拖放
agent-browser upload <sel> <files>    # 上传文件
agent-browser screenshot [path]       # 截图（--full 全页面，无路径时保存到临时目录）
agent-browser screenshot --annotate   # 带编号元素标签的注释截图
agent-browser screenshot --screenshot-dir ./shots    # 保存到自定义目录
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # 保存为 PDF
agent-browser snapshot                # 带引用的可访问性树（最适合 AI）
agent-browser eval <js>               # 运行 JavaScript（-b 表示 base64，--stdin 用于管道输入）
agent-browser connect <port>          # 通过 CDP 连接浏览器
agent-browser close                   # 关闭浏览器（别名：quit, exit）

获取信息

agent-browser get text <sel>          # 获取文本内容
agent-browser get html <sel>          # 获取 innerHTML
agent-browser get value <sel>         # 获取输入值
agent-browser get attr <sel> <attr>   # 获取属性
agent-browser get title               # 获取页面标题
agent-browser get url                 # 获取当前 URL
agent-browser get cdp-url             # 获取 CDP WebSocket URL（用于 DevTools、调试）
agent-browser get count <sel>         # 统计匹配元素
agent-browser get box <sel>           # 获取边界框
agent-browser get styles <sel>        # 获取计算样式

检查状态

agent-browser is visible <sel>        # 检查是否可见
agent-browser is enabled <sel>        # 检查是否启用
agent-browser is checked <sel>        # 检查是否勾选

查找元素（语义定位器）

agent-browser find role <role> <action> [value]       # 按 ARIA 角色
agent-browser find text <text> <action>               # 按文本内容
agent-browser find label <label> <action> [value]     # 按标签
agent-browser find placeholder <ph> <action> [value]  # 按占位符
agent-browser find alt <text> <action>                # 按 alt 文本
agent-browser find title <text> <action>              # 按 title 属性
agent-browser find testid <id> <action> [value]       # 按 data-testid
agent-browser find first <sel> <action> [value]       # 第一个匹配
agent-browser find last <sel> <action> [value]        # 最后一个匹配
agent-browser find nth <n> <sel> <action> [value]     # 第 N 个匹配

操作： click、fill、type、hover、focus、check、uncheck、text

选项： --name <name>（按可访问名称过滤角色），--exact（要求精确文本匹配）

示例：

agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find label "Email" fill "test@test.com"
agent-browser find first ".item" click
agent-browser find nth 2 "a" text

等待

agent-browser wait <selector>         # 等待元素可见
agent-browser wait <ms>               # 等待时间（毫秒）
agent-browser wait --text "Welcome"   # 等待文本出现（子串匹配）
agent-browser wait --url "**/dash"    # 等待 URL 模式
agent-browser wait --load networkidle # 等待加载状态
agent-browser wait --fn "window.ready === true"  # 等待 JS 条件

# 等待文本/元素消失
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"
agent-browser wait "#spinner" --state hidden

加载状态： load、domcontentloaded、networkidle

剪贴板

agent-browser clipboard read                      # 从剪贴板读取文本
agent-browser clipboard write "Hello, World!"     # 写入文本到剪贴板
agent-browser clipboard copy                      # 复制当前选择（Ctrl+C）
agent-browser clipboard paste                     # 从剪贴板粘贴（Ctrl+V）

鼠标控制

agent-browser mouse move <x> <y>      # 移动鼠标
agent-browser mouse down [button]     # 按下按钮（left/right/middle）
agent-browser mouse up [button]       # 释放按钮
agent-browser mouse wheel <dy> [dx]   # 滚动滚轮

浏览器设置

agent-browser set viewport <w> <h> [scale]  # 设置视口大小（scale 用于 retina，例如 2）
agent-browser set device <name>       # 模拟设备（"iPhone 14"）
agent-browser set geo <lat> <lng>     # 设置地理位置
agent-browser set offline [on|off]    # 切换离线模式
agent-browser set headers <json>      # 额外 HTTP 头
agent-browser set credentials <u> <p> # HTTP 基本认证
agent-browser set media [dark|light]  # 模拟配色方案

Cookie 和存储

agent-browser cookies                 # 获取所有 cookie
agent-browser cookies set <name> <val> # 设置 cookie
agent-browser cookies clear           # 清除 cookie

agent-browser storage local           # 获取所有 localStorage
agent-browser storage local <key>     # 获取特定键
agent-browser storage local set <k> <v>  # 设置值
agent-browser storage local clear     # 清除所有

agent-browser storage session         # sessionStorage 同理

网络

agent-browser network route <url>              # 拦截请求
agent-browser network route <url> --abort      # 阻止请求
agent-browser network route <url> --body <json>  # 模拟响应
agent-browser network unroute [url]            # 移除路由
agent-browser network requests                 # 查看跟踪的请求
agent-browser network requests --filter api    # 过滤请求

标签页和窗口

agent-browser tab                     # 列出标签页
agent-browser tab new [url]           # 新建标签页（可选带 URL）
agent-browser tab <n>                 # 切换到标签页 n
agent-browser tab close [n]           # 关闭标签页
agent-browser window new              # 新建窗口

框架

agent-browser frame <sel>             # 切换到 iframe
agent-browser frame main              # 返回主框架

对话框

agent-browser dialog accept [text]    # 接受（可选提示文本）
agent-browser dialog dismiss          # 取消

差异对比

agent-browser diff snapshot                              # 比较当前与上一次快照
agent-browser diff snapshot --baseline before.txt        # 比较当前与保存的快照文件
agent-browser diff snapshot --selector "#main" --compact # 限定范围的快照差异
agent-browser diff screenshot --baseline before.png      # 与基准进行视觉像素差异对比
agent-browser diff screenshot --baseline b.png -o d.png  # 保存差异图像到自定义路径
agent-browser diff screenshot --baseline b.png -t 0.2    # 调整颜色阈值（0-1）
agent-browser diff url https://v1.com https://v2.com     # 比较两个 URL（快照差异）
agent-browser diff url https://v1.com https://v2.com --screenshot  # 同时进行视觉差异对比
agent-browser diff url https://v1.com https://v2.com --wait-until networkidle  # 自定义等待策略
agent-browser diff url https://v1.com https://v2.com --selector "#main"  # 限定到元素

调试

agent-browser trace start [path]      # 开始记录追踪
agent-browser trace stop [path]       # 停止并保存追踪
agent-browser profiler start          # 启动 Chrome DevTools 分析
agent-browser profiler stop [path]    # 停止并保存分析文件（.json）
agent-browser console                 # 查看控制台消息（log, error, warn, info）
agent-browser console --clear         # 清除控制台
agent-browser errors                  # 查看页面错误（未捕获的 JavaScript 异常）
agent-browser errors --clear          # 清除错误
agent-browser highlight <sel>         # 高亮元素
agent-browser inspect                 # 为活动页面打开 Chrome DevTools
agent-browser state save <path>       # 保存认证状态
agent-browser state load <path>       # 加载认证状态
agent-browser state list              # 列出保存的状态文件
agent-browser state show <file>       # 显示状态摘要
agent-browser state rename <old> <new> # 重命名状态文件
agent-browser state clear [name]      # 清除会话的状态
agent-browser state clear --all       # 清除所有保存的状态
agent-browser state clean --older-than <days>  # 删除旧状态

设置

agent-browser install                 # 从 Chrome for Testing 下载 Chrome（Google 官方自动化通道）
agent-browser install --with-deps     # 同时安装系统依赖（Linux）

身份验证

agent-browser 提供多种方式持久化登录会话，避免每次运行都重新认证。

快速摘要

方法	适用场景	标志 / 环境变量
持久化配置文件	跨重启的完整浏览器状态（cookie、IndexedDB、service worker、缓存）	`--profile <path>` / `AGENT_BROWSER_PROFILE`
会话持久化	按名称自动保存/恢复 cookie + localStorage	`--session-name <name>` / `AGENT_BROWSER_SESSION_NAME`
从浏览器导入	从已登录的 Chrome 会话获取认证	`--auto-connect` + `state save`
状态文件	启动时加载之前保存的状态 JSON	`--state <path>` / `AGENT_BROWSER_STATE`
认证保险库	本地存储凭据（加密），按名称登录	`auth save` / `auth login`

从浏览器导入认证

如果您已经在 Chrome 中登录了某个站点，可以获取该认证状态并重复使用：

# 1. 启用远程调试启动 Chrome
#    macOS:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
#    或使用 --auto-connect 发现已运行的 Chrome

# 2. 连接并保存认证状态
agent-browser --auto-connect state save ./my-auth.json

# 3. 在未来的会话中使用保存的认证
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

# 4. 或使用 --session-name 自动持久化
agent-browser --session-name myapp state load ./my-auth.json
# 从此以后，--session-name myapp 自动保存/恢复此状态

安全提示：

--remote-debugging-port 在 localhost 上暴露完整的浏览器控制。任何本地进程都可以连接。仅在受信任的机器上使用，完成后关闭 Chrome。

状态文件包含明文会话令牌。将它们添加到 .gitignore，不再需要时删除。若要静态加密，请设置 AGENT_BROWSER_ENCRYPTION_KEY（参见状态加密）。

有关登录流程、OAuth、2FA、基于 cookie 的认证和认证保险库的完整详细信息，请参阅身份验证文档。

会话

运行多个隔离的浏览器实例：

# 不同会话
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# 或通过环境变量
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

# 列出活动会话
agent-browser session list
# 输出:
# Active sessions:
# -> default
#    agent1

# 显示当前会话
agent-browser session

每个会话都有自己的：

浏览器实例
Cookie 和存储
导航历史
认证状态

持久化配置文件

默认情况下，浏览器状态（cookie、localStorage、登录会话）是临时的，浏览器关闭时丢失。使用 --profile 跨浏览器重启持久化状态：

# 使用持久化配置文件目录
agent-browser --profile ~/.myapp-profile open myapp.com

# 登录一次，然后重用认证会话
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

# 或通过环境变量
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

配置文件目录存储：

Cookie 和 localStorage
IndexedDB 数据
Service worker
浏览器缓存
登录会话

提示： 为不同项目使用不同的配置文件路径，以保持浏览器状态隔离。

会话持久化

或者，使用 --session-name 跨浏览器重启自动保存和恢复 cookie 和 localStorage：

# 为 "twitter" 会话自动保存/加载状态
agent-browser --session-name twitter open twitter.com

# 登录一次，然后状态自动持久化
# 状态文件存储在 ~/.agent-browser/sessions/

# 或通过环境变量
export AGENT_BROWSER_SESSION_NAME=twitter
agent-browser open twitter.com

状态加密

使用 AES-256-GCM 静态加密保存的会话数据：

# 生成密钥：openssl rand -hex 32
export AGENT_BROWSER_ENCRYPTION_KEY=<64字符十六进制密钥>

# 状态文件现在自动加密
agent-browser --session-name secure open example.com

变量	描述
`AGENT_BROWSER_SESSION_NAME`	自动保存/加载状态持久化名称
`AGENT_BROWSER_ENCRYPTION_KEY`	AES-256-GCM 加密的 64 字符十六进制密钥
`AGENT_BROWSER_STATE_EXPIRE_DAYS`	自动删除超过 N 天的状态（默认：30）

安全

agent-browser 包含安全功能，用于安全的 AI 代理部署。所有功能都是可选的——在您显式启用功能之前，现有工作流不受影响：

认证保险库 -- 本地存储凭据（始终加密），按名称引用。LLM 永远不会看到密码。如果未设置 AGENT_BROWSER_ENCRYPTION_KEY，会自动在 ~/.agent-browser/.encryption-key 生成密钥：echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin 然后 agent-browser auth login github
内容边界标记 -- 用分隔符包装页面输出，以便 LLM 区分工具输出和不受信任的内容：--content-boundaries
域名白名单 -- 将导航限制为受信任的域名（通配符如 *.example.com 也匹配裸域名）：--allowed-domains "example.com,*.example.com"。对非允许域名的子资源请求（脚本、图像、fetch）和 WebSocket/EventSource 连接也会被阻止。包括目标页面依赖的任何 CDN 域名（例如 *.cdn.example.com）。
操作策略 -- 使用静态策略文件把关破坏性操作：--action-policy ./policy.json
操作确认 -- 对敏感操作类别需要显式批准：--confirm-actions eval,download
输出长度限制 -- 防止上下文泛滥：--max-output 50000

变量	描述
`AGENT_BROWSER_CONTENT_BOUNDARIES`	在边界标记中包装页面输出
`AGENT_BROWSER_MAX_OUTPUT`	页面输出的最大字符数
`AGENT_BROWSER_ALLOWED_DOMAINS`	逗号分隔的允许域名模式
`AGENT_BROWSER_ACTION_POLICY`	操作策略 JSON 文件路径
`AGENT_BROWSER_CONFIRM_ACTIONS`	需要确认的操作类别
`AGENT_BROWSER_CONFIRM_INTERACTIVE`	启用交互式确认提示

详情请参阅安全文档。

快照选项

snapshot 命令支持过滤以减少输出大小：

agent-browser snapshot                    # 完整可访问性树
agent-browser snapshot -i                 # 仅交互元素（按钮、输入、链接）
agent-browser snapshot -i -C              # 包含光标交互元素（带 onclick 的 div 等）
agent-browser snapshot -c                 # 紧凑（移除空的结构元素）
agent-browser snapshot -d 3               # 限制深度为 3 层
agent-browser snapshot -s "#main"         # 范围限定到 CSS 选择器
agent-browser snapshot -i -c -d 5         # 组合选项

选项	描述
`-i, --interactive`	仅显示交互元素（按钮、链接、输入）
`-C, --cursor`	包含光标交互元素（cursor:pointer、onclick、tabindex）
`-c, --compact`	移除空的结构元素
`-d, --depth <n>`	限制树深度
`-s, --selector <sel>`	范围限定到 CSS 选择器

-C 标志对于使用自定义可点击元素（div、span）而不是标准按钮/链接的现代 Web 应用非常有用。

注释截图

--annotate 标志在截图中的交互元素上叠加编号标签。每个标签 [N] 对应引用 @eN，因此相同的引用适用于视觉和基于文本的工作流。

注释截图在 CDP 支持的浏览器路径（Chrome/Lightpanda）上受支持。Safari/WebDriver 后端尚不支持 --annotate。

agent-browser screenshot --annotate
# -> Screenshot saved to /tmp/screenshot-2026-02-17T12-00-00-abc123.png
#    [1] @e1 button "Submit"
#    [2] @e2 link "Home"
#    [3] @e3 textbox "Email"

注释截图后，引用会被缓存，因此您可以立即与元素交互：

agent-browser screenshot --annotate ./page.png
agent-browser click @e2     # 点击标记为 [2] 的 "Home" 链接

这对于可以推理视觉布局、未标记图标按钮、canvas 元素或文本可访问性树无法捕获的视觉状态的多模态 AI 模型非常有用。

选项

选项	描述
`--session <name>`	使用隔离会话（或 `AGENT_BROWSER_SESSION` 环境变量）
`--session-name <name>`	自动保存/恢复会话状态（或 `AGENT_BROWSER_SESSION_NAME` 环境变量）
`--profile <path>`	持久化浏览器配置文件目录（或 `AGENT_BROWSER_PROFILE` 环境变量）
`--state <path>`	从 JSON 文件加载存储状态（或 `AGENT_BROWSER_STATE` 环境变量）
`--headers <json>`	设置作用域为 URL 来源的 HTTP 头
`--executable-path <path>`	自定义浏览器可执行文件（或 `AGENT_BROWSER_EXECUTABLE_PATH` 环境变量）
`--extension <path>`	加载浏览器扩展（可重复；或 `AGENT_BROWSER_EXTENSIONS` 环境变量）
`--args <args>`	浏览器启动参数，逗号或换行分隔（或 `AGENT_BROWSER_ARGS` 环境变量）
`--user-agent <ua>`	自定义 User-Agent 字符串（或 `AGENT_BROWSER_USER_AGENT` 环境变量）
`--proxy <url>`	代理服务器 URL，可选认证（或 `AGENT_BROWSER_PROXY` 环境变量）
`--proxy-bypass <hosts>`	绕过代理的主机（或 `AGENT_BROWSER_PROXY_BYPASS` 环境变量）
`--ignore-https-errors`	忽略 HTTPS 证书错误（对自签名证书有用）
`--allow-file-access`	允许 file:// URL 访问本地文件（仅限 Chromium）
`-p, --provider <name>`	云浏览器提供商（或 `AGENT_BROWSER_PROVIDER` 环境变量）
`--device <name>`	iOS 设备名称，例如 "iPhone 15 Pro"（或 `AGENT_BROWSER_IOS_DEVICE` 环境变量）
`--json`	JSON 输出（用于代理）
`--full, -f`	全页面截图
`--annotate`	带编号元素标签的注释截图（或 `AGENT_BROWSER_ANNOTATE` 环境变量）
`--screenshot-dir <path>`	默认截图输出目录（或 `AGENT_BROWSER_SCREENSHOT_DIR` 环境变量）
`--screenshot-quality <n>`	JPEG 质量 0-100（或 `AGENT_BROWSER_SCREENSHOT_QUALITY` 环境变量）
`--screenshot-format <fmt>`	截图格式：`png`、`jpeg`（或 `AGENT_BROWSER_SCREENSHOT_FORMAT` 环境变量）
`--headed`	显示浏览器窗口（非无头）（或 `AGENT_BROWSER_HEADED` 环境变量）
`--cdp <port\|url>`	通过 Chrome DevTools 协议连接（端口或 WebSocket URL）
`--auto-connect`	自动发现并连接到运行中的 Chrome（或 `AGENT_BROWSER_AUTO_CONNECT` 环境变量）
`--color-scheme <scheme>`	配色方案：`dark`、`light`、`no-preference`（或 `AGENT_BROWSER_COLOR_SCHEME` 环境变量）
`--download-path <path>`	默认下载目录（或 `AGENT_BROWSER_DOWNLOAD_PATH` 环境变量）
`--content-boundaries`	为 LLM 安全在边界标记中包装页面输出（或 `AGENT_BROWSER_CONTENT_BOUNDARIES` 环境变量）
`--max-output <chars>`	将页面输出截断为 N 个字符（或 `AGENT_BROWSER_MAX_OUTPUT` 环境变量）
`--allowed-domains <list>`	逗号分隔的允许域名模式（或 `AGENT_BROWSER_ALLOWED_DOMAINS` 环境变量）
`--action-policy <path>`	操作策略 JSON 文件路径（或 `AGENT_BROWSER_ACTION_POLICY` 环境变量）
`--confirm-actions <list>`	需要确认的操作类别（或 `AGENT_BROWSER_CONFIRM_ACTIONS` 环境变量）
`--confirm-interactive`	交互式确认提示；如果 stdin 不是 TTY 则自动拒绝（或 `AGENT_BROWSER_CONFIRM_INTERACTIVE` 环境变量）
`--engine <name>`	浏览器引擎：`chrome`（默认）、`lightpanda`（或 `AGENT_BROWSER_ENGINE` 环境变量）
`--config <path>`	使用自定义配置文件（或 `AGENT_BROWSER_CONFIG` 环境变量）
`--debug`	调试输出

配置

创建 agent-browser.json 文件来设置持久化默认值，而不是在每个命令上重复标志。

位置（从低到高优先级）：

~/.agent-browser/config.json -- 用户级默认值
./agent-browser.json -- 项目级覆盖（在工作目录中）
AGENT_BROWSER_* 环境变量覆盖配置文件值
CLI 标志覆盖所有

示例 agent-browser.json：

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data",
  "userAgent": "my-agent/1.0",
  "ignoreHttpsErrors": true
}

使用 --config <path> 或 AGENT_BROWSER_CONFIG 加载特定配置文件而不是默认值：

agent-browser --config ./ci-config.json open example.com
AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

上表中的所有选项都可以使用 camelCase 键在配置文件中设置（例如 --executable-path 变为 "executablePath"，--proxy-bypass 变为 "proxyBypass"）。未知键被忽略以实现向前兼容。

布尔标志接受可选的 true/false 值来覆盖配置设置。例如，--headed false 禁用配置中的 "headed": true。裸 --headed 等同于 --headed true。

自动发现的缺失配置文件会被静默忽略。如果 --config <path> 指向缺失或无效的文件，agent-browser 会退出并报错。来自用户和项目配置的扩展会被合并（连接），而不是替换。

提示： 如果项目级 agent-browser.json 包含环境特定值（路径、代理），考虑将其添加到 .gitignore。

默认超时

标准操作（点击、等待、填充等）的默认超时为 25 秒。这有意低于 CLI 的 30 秒 IPC 读取超时，以便守护进程返回正确的错误，而不是 CLI 因 EAGAIN 超时。

通过环境变量覆盖默认超时：

# 为慢速页面设置更长的超时（毫秒）
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000

注意： 将此设置为高于 30000（30秒）可能会导致慢操作出现 EAGAIN 错误，因为 CLI 的读取超时会在守护进程响应之前过期。CLI 会自动重试瞬态错误，但响应时间会增加。

变量	描述
`AGENT_BROWSER_DEFAULT_TIMEOUT`	默认操作超时（毫秒）（默认：25000）

选择器

引用（推荐用于 AI）

引用提供从快照进行确定性元素选择：

# 1. 获取带引用的快照
agent-browser snapshot
# 输出:
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

# 2. 使用引用进行交互
agent-browser click @e2                   # 点击按钮
agent-browser fill @e3 "test@example.com" # 填充文本框
agent-browser get text @e1                # 获取标题文本
agent-browser hover @e4                   # 悬停链接

为什么使用引用？

确定性：引用指向快照中的精确元素
快速：无需重新查询 DOM
AI 友好：快照 + 引用工作流对 LLM 最优

CSS 选择器

agent-browser click "#id"
agent-browser click ".class"
agent-browser click "div > button"

文本和 XPath

agent-browser click "text=Submit"
agent-browser click "xpath=//button"

语义定位器

agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"

代理模式

使用 --json 获取机器可读输出：

agent-browser snapshot --json
# 返回：{"success":true,"data":{"snapshot":"...","refs":{"e1":{"role":"heading","name":"Title"},...}}}

agent-browser get text @e1 --json
agent-browser is visible @e2 --json

最佳 AI 工作流

# 1. 导航并获取快照
agent-browser open example.com
agent-browser snapshot -i --json   # AI 解析树和引用

# 2. AI 从快照识别目标引用
# 3. 使用引用执行操作
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. 如果页面更改，获取新快照
agent-browser snapshot -i --json

命令链

命令可以在单个 shell 调用中用 && 链接。浏览器通过后台守护进程持久化，因此链接是安全且更高效的：

# 在一次调用中打开、等待加载和快照
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 链接多个交互
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3

# 导航并截图
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

当您不需要中间输出时使用 &&。当您需要先解析输出时（例如快照以在交互前发现引用），单独运行命令。

有头模式

显示浏览器窗口进行调试：

agent-browser open example.com --headed

这会打开一个可见的浏览器窗口，而不是无头运行。

注意： 浏览器扩展在有头和无头模式下都可以工作（Chrome 的 --headless=new）。

认证会话

使用 --headers 为特定来源设置 HTTP 头，无需登录流程即可实现认证：

# 头仅作用域于 api.example.com
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# 对 api.example.com 的请求包含认证头
agent-browser snapshot -i --json
agent-browser click @e2

# 导航到另一个域名 - 不会发送头（安全！）
agent-browser open other-site.com

这适用于：

跳过登录流程 - 通过头而不是 UI 进行认证
切换用户 - 使用不同的认证令牌启动新会话
API 测试 - 直接访问受保护的端点
安全 - 头作用域限于来源，不会泄露到其他域名

要为多个来源设置头，请对每个 open 命令使用 --headers：

agent-browser open api.example.com --headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com --headers '{"Authorization": "Bearer token2"}'

对于全局头（所有域名），使用 set headers：

agent-browser set headers '{"X-Custom-Header": "value"}'

自定义浏览器可执行文件

使用自定义浏览器可执行文件而不是捆绑的 Chromium。这适用于：

无服务器部署：使用轻量级 Chromium 构建如 @sparticuz/chromium（约 50MB vs 约 684MB）
系统浏览器：使用现有的 Chrome/Chromium 安装
自定义构建：使用修改过的浏览器构建

CLI 用法

# 通过标志
agent-browser --executable-path /path/to/chromium open example.com

# 通过环境变量
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

无服务器（Vercel）

在临时 Vercel Sandbox 微型 VM 中运行 agent-browser + Chrome。无需外部服务器：

import { Sandbox } from "@vercel/sandbox";

const sandbox = await Sandbox.create({ runtime: "node24" });
await sandbox.runCommand("agent-browser", ["open", "https://example.com"]);
const result = await sandbox.runCommand("agent-browser", ["screenshot", "--json"]);
await sandbox.stop();

有关带有 UI 和部署到 Vercel 按钮的工作演示，请参阅 environments 示例。

无服务器（AWS Lambda）

import chromium from '@sparticuz/chromium';
import { BrowserManager } from 'agent-browser';

export async function handler() {
  const browser = new BrowserManager();
  await browser.launch({
    executablePath: await chromium.executablePath(),
    headless: true,
  });
  // ... 使用浏览器
}

本地文件

使用 file:// URL 打开并交互本地文件（PDF、HTML 等）：

# 启用文件访问（JavaScript 访问本地文件所需）
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html

# 对本地 PDF 截图
agent-browser --allow-file-access open file:///Users/me/report.pdf
agent-browser screenshot report.png

--allow-file-access 标志添加 Chromium 标志（--allow-file-access-from-files、--allow-file-access），允许 file:// URL：

加载和渲染本地文件
通过 JavaScript（XHR、fetch）访问其他本地文件
加载本地资源（图像、脚本、样式表）

注意： 此标志仅适用于 Chromium。出于安全考虑，默认禁用。

CDP 模式

通过 Chrome DevTools 协议连接到现有浏览器：

# 启动 Chrome：google-chrome --remote-debugging-port=9222

# 连接一次，然后无需 --cdp 运行命令
agent-browser connect 9222
agent-browser snapshot
agent-browser tab
agent-browser close

# 或在每个命令上传递 --cdp
agent-browser --cdp 9222 snapshot

# 通过 WebSocket URL 连接远程浏览器
agent-browser --cdp "wss://your-browser-service.com/cdp?token=..." snapshot

--cdp 标志接受：

端口号（例如 9222）通过 http://localhost:{port} 进行本地连接
完整的 WebSocket URL（例如 wss://... 或 ws://...）用于远程浏览器服务

这可以控制：

Electron 应用
带远程调试的 Chrome/Chromium 实例
WebView2 应用程序
任何暴露 CDP 端点的浏览器

自动连接

使用 --auto-connect 自动发现并连接到运行中的 Chrome 实例，无需指定端口：

# 自动发现带远程调试的运行中 Chrome
agent-browser --auto-connect open example.com
agent-browser --auto-connect snapshot

# 或通过环境变量
AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot

自动连接通过以下方式发现 Chrome：

从默认用户数据目录读取 Chrome 的 DevToolsActivePort 文件
回退到探测常见调试端口（9222、9229）

这在以下情况下很有用：

Chrome 144+ 通过 chrome://inspect/#remote-debugging 启用了远程调试（使用动态端口）
您想要零配置连接到现有浏览器
您不想跟踪 Chrome 使用哪个端口

流式传输（浏览器预览）

通过 WebSocket 流式传输浏览器视口，用于实时预览或"配对浏览"，人类可以观看并与 AI 代理一起交互。

启用流式传输

设置 AGENT_BROWSER_STREAM_PORT 环境变量：

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

这会在指定端口启动 WebSocket 服务器，流式传输浏览器视口并接受输入事件。

WebSocket 协议

连接到 ws://localhost:9223 以接收帧并发送输入：

接收帧：

{
  "type": "frame",
  "data": "<base64编码的jpeg>",
  "metadata": {
    "deviceWidth": 1280,
    "deviceHeight": 720,
    "pageScaleFactor": 1,
    "offsetTop": 0,
    "scrollOffsetX": 0,
    "scrollOffsetY": 0
  }
}

发送鼠标事件：

{
  "type": "input_mouse",
  "eventType": "mousePressed",
  "x": 100,
  "y": 200,
  "button": "left",
  "clickCount": 1
}

发送键盘事件：

{
  "type": "input_keyboard",
  "eventType": "keyDown",
  "key": "Enter",
  "code": "Enter"
}

发送触摸事件：

{
  "type": "input_touch",
  "eventType": "touchStart",
  "touchPoints": [{ "x": 100, "y": 200 }]
}

编程 API

对于高级用途，通过协议直接控制流式传输：

import { BrowserManager } from 'agent-browser';

const browser = new BrowserManager();
await browser.launch({ headless: true });
await browser.navigate('https://example.com');

// 启动屏幕广播
await browser.startScreencast(
  (frame) => {
    // frame.data 是 base64 编码的图像
    // frame.metadata 包含视口信息
    console.log('收到帧:', frame.metadata.deviceWidth, 'x', frame.metadata.deviceHeight);
  },
  {
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  }
);

// 注入鼠标事件
await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
});

// 注入键盘事件
await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
});

// 完成后停止
await browser.stopScreencast();

架构

agent-browser 使用客户端-守护进程架构：

Rust CLI - 解析命令，与守护进程通信
Rust 守护进程 - 使用直接 CDP 的纯 Rust 守护进程，不需要 Node.js

守护进程在第一个命令时自动启动，并在命令之间持久化以实现快速的后续操作。要在一段时间不活动后自动关闭守护进程，请设置 AGENT_BROWSER_IDLE_TIMEOUT_MS（值以毫秒为单位）。设置后，守护进程在指定持续时间内未收到命令后会关闭浏览器并退出。

浏览器引擎： 默认使用 Chrome（来自 Chrome for Testing）。--engine 标志在 chrome 和 lightpanda 之间选择。支持的浏览器：Chromium/Chrome（通过 CDP）和 Safari（通过 WebDriver for iOS）。

平台

平台	二进制
macOS ARM64	原生 Rust
macOS x64	原生 Rust
Linux ARM64	原生 Rust
Linux x64	原生 Rust
Windows x64	原生 Rust

与 AI 代理一起使用

直接告诉代理

最简单的方法——直接告诉您的代理使用它：

Use agent-browser to test the login flow. Run agent-browser --help to see available commands.

--help 输出很全面，大多数代理可以从那里弄清楚。

AI 编程助手（推荐）

为您的 AI 编程助手添加技能以获得更丰富的上下文：

npx skills add vercel-labs/agent-browser

这适用于 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Goose、OpenCode 和 Windsurf。技能从仓库中获取，因此会自动保持最新——不要从 node_modules 复制 SKILL.md，因为它会过时。

Claude Code

作为 Claude Code 技能安装：

npx skills add vercel-labs/agent-browser

这会将技能添加到项目中的 .claude/skills/agent-browser/SKILL.md。该技能教会 Claude Code 完整的 agent-browser 工作流，包括快照-引用交互模式、会话管理和超时处理。

AGENTS.md / CLAUDE.md

为了获得更一致的结果，添加到您的项目或全局指令文件：

## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:

1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page changes

集成

iOS 模拟器

控制 iOS 模拟器中的真实 Mobile Safari 进行真实的移动 Web 测试。需要带 Xcode 的 macOS。

设置：

# 安装 Appium 和 XCUITest 驱动
npm install -g appium
appium driver install xcuitest

用法：

# 列出可用的 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
agent-browser -p ios fill @e2 "text"
agent-browser -p ios screenshot mobile.png

# 移动特定命令
agent-browser -p ios swipe up
agent-browser -p ios swipe down 500

# 关闭会话
agent-browser -p ios close

或使用环境变量：

export AGENT_BROWSER_PROVIDER=ios
export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"
agent-browser open https://example.com

变量	描述
`AGENT_BROWSER_PROVIDER`	设置为 `ios` 启用 iOS 模式
`AGENT_BROWSER_IOS_DEVICE`	设备名称（例如 "iPhone 16 Pro"、"iPad Pro"）
`AGENT_BROWSER_IOS_UDID`	设备 UDID（替代设备名称）

支持的设备： Xcode 中可用的所有 iOS 模拟器（iPhone、iPad），以及真实的 iOS 设备。

注意： iOS 提供商会启动模拟器、启动 Appium 并控制 Safari。首次启动约需 30-60 秒；后续命令很快。

真实设备支持

Appium 也支持通过 USB 连接的真实 iOS 设备。这需要额外的一次性设置：

1. 获取设备 UDID：

xcrun xctrace list devices
# 或
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"

2. 签名 WebDriverAgent（一次性）：

# 打开 WebDriverAgent Xcode 项目
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
open WebDriverAgent.xcodeproj

在 Xcode 中：

选择 WebDriverAgentRunner 目标
进入 Signing & Capabilities
选择您的 Team（需要 Apple Developer 账户，免费层级可用）
让 Xcode 自动管理签名

3. 与 agent-browser 一起使用：

# 通过 USB 连接设备，然后：
agent-browser -p ios --device "<DEVICE_UDID>" open https://example.com

# 或使用设备名称（如果唯一）
agent-browser -p ios --device "John's iPhone" open https://example.com

真实设备说明：

首次运行将 WebDriverAgent 安装到设备（可能需要信任提示）
设备必须解锁并通过 USB 连接
初始连接比模拟器稍慢
测试真实的 Safari 性能和行为

Browserless

Browserless 提供带 Sessions API 的云浏览器基础设施。在无法使用本地浏览器的环境中运行 agent-browser 时使用它。

要启用 Browserless，使用 -p 标志：

export BROWSERLESS_API_KEY="your-api-token"
agent-browser -p browserless open https://example.com

或使用环境变量用于 CI/脚本：

export AGENT_BROWSER_PROVIDER=browserless
export BROWSERLESS_API_KEY="your-api-token"
agent-browser open https://example.com

通过环境变量可选配置：

变量	描述	默认值
`BROWSERLESS_API_URL`	基础 API URL（用于自定义区域或自托管）	`https://production-sfo.browserless.io`
`BROWSERLESS_BROWSER_TYPE`	浏览器类型（chromium 或 chrome）	chromium
`BROWSERLESS_TTL`	会话 TTL（毫秒）	`300000`
`BROWSERLESS_STEALTH`	启用隐身模式（`true`/`false`）	`true`

启用后，agent-browser 连接到 Browserless 云会话而不是启动本地浏览器。所有命令工作方式相同。

从 Browserless 仪表板获取您的 API 令牌。

Browserbase

Browserbase 提供远程浏览器基础设施，使部署代理浏览代理变得容易。在无法使用本地浏览器的环境中运行 agent-browser CLI 时使用它。

要启用 Browserbase，使用 -p 标志：

export BROWSERBASE_API_KEY="your-api-key"
agent-browser -p browserbase open https://example.com

或使用环境变量用于 CI/脚本：

export AGENT_BROWSER_PROVIDER=browserbase
export BROWSERBASE_API_KEY="your-api-key"
agent-browser open https://example.com

启用后，agent-browser 连接到 Browserbase 会话而不是启动本地浏览器。所有命令工作方式相同。

从 Browserbase 仪表板获取您的 API 密钥。

Browser Use

Browser Use 为 AI 代理提供云浏览器基础设施。在无法使用本地浏览器的环境（无服务器、CI/CD 等）中运行 agent-browser 时使用它。

要启用 Browser Use，使用 -p 标志：

export BROWSER_USE_API_KEY="your-api-key"
agent-browser -p browseruse open https://example.com

或使用环境变量用于 CI/脚本：

export AGENT_BROWSER_PROVIDER=browseruse
export BROWSER_USE_API_KEY="your-api-key"
agent-browser open https://example.com

启用后，agent-browser 连接到 Browser Use 云会话而不是启动本地浏览器。所有命令工作方式相同。

从 Browser Use Cloud 仪表板获取您的 API 密钥。有免费额度可供开始，之后按需付费。

Kernel

Kernel 为 AI 代理提供云浏览器基础设施，具有隐身模式和持久化配置文件等功能。

要启用 Kernel，使用 -p 标志：

export KERNEL_API_KEY="your-api-key"
agent-browser -p kernel open https://example.com

或使用环境变量用于 CI/脚本：

export AGENT_BROWSER_PROVIDER=kernel
export KERNEL_API_KEY="your-api-key"
agent-browser open https://example.com

通过环境变量可选配置：

变量	描述	默认值
`KERNEL_HEADLESS`	在无头模式下运行浏览器（`true`/`false`）	`false`
`KERNEL_STEALTH`	启用隐身模式以避免机器人检测（`true`/`false`）	`true`
`KERNEL_TIMEOUT_SECONDS`	会话超时（秒）	`300`
`KERNEL_PROFILE_NAME`	用于持久化 cookie/登录的浏览器配置文件名称（如果不存在则创建）	(无)

启用后，agent-browser 连接到 Kernel 云会话而不是启动本地浏览器。所有命令工作方式相同。

配置文件持久化： 当设置 KERNEL_PROFILE_NAME 时，如果配置文件不存在则会创建。当浏览器会话结束时，cookie、登录和会话数据会自动保存回配置文件，使其可用于未来的会话。

从 Kernel 仪表板获取您的 API 密钥。

许可证

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
CNAME		CNAME
LICENSE		LICENSE
README.md		README.md
index.html		index.html

Folders and files

Latest commit

History

Repository files navigation

agent-browser

安装

全局安装（推荐）

项目安装（本地依赖）

Homebrew（macOS）

Cargo（Rust）

从源码构建

Linux 依赖

要求

快速开始

传统选择器（也支持）

命令

核心命令

获取信息

检查状态

查找元素（语义定位器）

等待

剪贴板

鼠标控制

浏览器设置

Cookie 和存储

网络

标签页和窗口

框架

对话框

差异对比

调试

导航

设置

身份验证

快速摘要

从浏览器导入认证

会话

持久化配置文件

会话持久化

状态加密

安全

快照选项

注释截图

选项

配置

默认超时

选择器

引用（推荐用于 AI）

CSS 选择器

文本和 XPath

语义定位器

代理模式

最佳 AI 工作流

命令链

有头模式

认证会话

自定义浏览器可执行文件

CLI 用法

无服务器（Vercel）

无服务器（AWS Lambda）

本地文件

CDP 模式

自动连接

流式传输（浏览器预览）

启用流式传输

WebSocket 协议

编程 API

架构

平台

与 AI 代理一起使用

直接告诉代理

AI 编程助手（推荐）

Claude Code

AGENTS.md / CLAUDE.md

集成

iOS 模拟器

真实设备支持

Browserless

Browserbase

Browser Use

Packages