agent-browser

用于 AI 代理的浏览器自动化命令行工具。快速的原生 Rust 命令行工具。

安装

全局安装（推荐）

安装原生 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

更新

升级到最新版本：

agent-browser upgrade

它会自动检测您的安装方式（npm、Homebrew 或 Cargo），并运行相应的更新命令。

要求

• Chrome - 运行 agent-browser install 以从 Chrome for Testing（Google 的官方自动化渠道）下载 Chrome。现有的 Chrome、Brave、Playwright 和 Puppeteer 安装会被自动检测到。守护进程不需要 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]       # 滚动页面（向上/向下/向左/向右，--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 stream enable [--port <port>]  # 启动运行时 WebSocket 流媒体
agent-browser stream status           # 显示运行时流媒体状态和绑定端口
agent-browser stream disable          # 停止运行时 WebSocket 流媒体
agent-browser close                   # 关闭浏览器（别名：quit、exit）
agent-browser close --all             # 关闭所有活动会话
agent-browser chat "<instruction>"    # AI 聊天：自然语言浏览器控制（一次性操作）
agent-browser chat                    # AI 聊天：交互式 REPL 模式

获取信息

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>                # 按替代文本查找
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"  # 等待 JavaScript 条件满足

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

加载状态： load、domcontentloaded、networkidle

批量执行

在一次调用中执行多个命令。命令可以作为带引号的参数传递，也可以通过标准输入以 JSON 格式管道传输。这样可以在运行多步骤工作流时避免每次执行命令时启动进程的开销。

# 参数模式：每个带引号的参数代表一个完整命令
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"

# 使用 --bail 在遇到第一个错误时停止
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"

# 标准输入模式：将命令以 JSON 格式管道传输
echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

剪贴板

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]     # 按下鼠标按钮（左/右/中）
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    # 过滤 API 请求
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 har start                # 开始记录 HAR 日志
agent-browser network har stop [output.har]    # 停止并保存 HAR 日志（未指定路径时使用临时路径）

标签页和窗口

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 dialog status           # 检查是否有对话框正在打开

默认情况下，alert 和 beforeunload 对话框会自动被接受，因此不会阻塞代理程序。而 confirm 和 prompt 对话框仍需显式处理。可以使用 --no-auto-dialog（或设置 AGENT_BROWSER_NO_AUTO_DIALOG=1）来禁用自动处理功能。

当有 JavaScript 对话框待处理时，所有命令响应都会包含一个 warning 字段，其中显示对话框的类型和消息。

差异比较

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 [路径]      # 开始记录跟踪信息
agent-browser trace stop [路径]       # 停止并保存跟踪信息
agent-browser profiler start          # 开始 Chrome DevTools 性能分析
agent-browser profiler stop [路径]    # 停止并保存性能分析文件 (.json)
agent-browser console                 # 查看控制台消息（日志、错误、警告、信息）
agent-browser console --json          # 以 JSON 格式输出原始 CDP 参数，便于程序化访问
agent-browser console --clear         # 清空控制台
agent-browser errors                  # 查看页面错误（未捕获的 JavaScript 异常）
agent-browser errors --clear          # 清除错误
agent-browser highlight <选择器>     # 高亮显示元素
agent-browser inspect                 # 打开当前页面的 Chrome DevTools
agent-browser state save <路径>       # 保存认证状态
agent-browser state load <路径>       # 加载认证状态
agent-browser state list              # 列出已保存的状态文件
agent-browser state show <文件>       # 显示状态摘要
agent-browser state rename <旧名> <新名> # 重命名状态文件
agent-browser state clear [名称]      # 清除指定会话的状态
agent-browser state clear --all       # 清除所有已保存的状态
agent-browser state clean --older-than <天数>  # 删除过期的状态

导航

agent-browser back                    # 后退
agent-browser forward                 # 前进
agent-browser reload                  # 重新加载页面

设置

agent-browser install                 # 从 Chrome for Testing（Google 官方自动化渠道）下载 Chrome 浏览器
agent-browser install --with-deps     # 同时安装系统依赖项（Linux）
agent-browser upgrade                 # 将 agent-browser 升级到最新版本

认证

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

快速总结

方法	适用场景	标志/环境变量
复用 Chrome 配置文件	复用您现有的 Chrome 登录状态（Cookie、会话），无需任何设置	--profile <名称> / AGENT_BROWSER_PROFILE
持久化配置文件	在浏览器重启后仍保留完整状态（Cookie、IndexedDB、Service Worker、缓存）	--profile <路径> / AGENT_BROWSER_PROFILE
会话持久化	按名称自动保存和恢复 Cookie 和 localStorage	--session-name <名称> / AGENT_BROWSER_SESSION_NAME
从您的浏览器导入	直接从已登录的 Chrome 会话中获取认证信息	--auto-connect + state save
状态文件	在启动时加载之前保存的状态 JSON 文件	--state <路径> / 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 会在本地主机上暴露完整的浏览器控制权限。任何本地进程都可以连接。请仅在受信任的机器上使用，并在完成后关闭 Chrome。
• 状态文件以明文形式存储会话令牌。请将其添加到 .gitignore 文件中，并在不再需要时删除。如需静态加密，请设置 AGENT_BROWSER_ENCRYPTION_KEY（参见 状态加密）。

有关登录流程、OAuth、双因素认证、基于 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
# 输出：
# 活动会话：
# -> default
#    agent1

# 显示当前会话
agent-browser session

每个会话都有自己的：

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

复用 Chrome 配置文件

最快捷地使用现有登录状态的方法是将 Chrome 配置文件名称传递给 --profile：

# 列出可用的 Chrome 配置文件
agent-browser profiles

# 复用默认 Chrome 配置文件的登录状态
agent-browser --profile Default open https://gmail.com

# 使用命名配置文件（按显示名称或目录名称）
agent-browser --profile "Work" open https://app.example.com

# 或通过环境变量
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com

此操作会将您的 Chrome 配置文件复制到一个临时目录中（只读快照，不会修改原始配置文件），从而使浏览器在启动时带有您现有的 Cookie 和会话。

注意： 在 Windows 系统上，如果 Chrome 正在运行，请先关闭后再使用 --profile <名称>，因为某些配置文件可能被锁定。

持久化配置文件

若需创建一个持久化的自定义配置文件目录，在浏览器重启后仍能保留状态，可将路径传递给 --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 永远不会看到密码。auth login 命令会先加载凭据，然后等待登录表单选择器出现（适用于单页应用，超时时间遵循默认操作超时）。如果未设置 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 --urls          # 显示带有链接 URL 的交互元素
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	仅显示交互元素（按钮、链接、输入框）
-u, --urls	包含链接元素的 href URL
-c, --compact	移除空的结构元素
-d, --depth <n>	限制树的深度
-s, --selector <sel>	限定到 CSS 选择器

带标注的截图

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

带标注的截图仅在基于 CDP 的浏览器路径（Chrome/Lightpanda）上受支持。Safari/WebDriver 后端目前尚不支持 --annotate。

agent-browser screenshot --annotate
# -> 截图已保存到 /tmp/screenshot-2026-02-17T12-00-00-abc123.png
#    [1] @e1 按钮“提交”
#    [2] @e2 链接“首页”
#    [3] @e3 文本框“邮箱”

生成带标注的截图后，引用会被缓存，您可以立即与元素交互：

agent-browser screenshot --annotate ./page.png
agent-browser click @e2     # 点击标有 [2] 的“首页”链接

这对于能够推理视觉布局、未标注的图标按钮、画布元素或文本无障碍树无法捕捉的视觉状态的多模态 AI 模型非常有用。

选项

选项	描述
--session <name>	使用隔离会话（或 AGENT_BROWSER_SESSION 环境变量）
--session-name <name>	自动保存/恢复会话状态（或 AGENT_BROWSER_SESSION_NAME 环境变量）
--profile <name|path>	Chrome 配置文件名称或持久化目录路径（或 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 格式输出（用于代理）
--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 开发者工具协议连接（端口或 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	交互式确认提示；若标准输入不是 TTY，则自动拒绝（或 AGENT_BROWSER_CONFIRM_INTERACTIVE 环境变量）
--engine <name>	浏览器引擎：chrome（默认）、lightpanda（或 AGENT_BROWSER_ENGINE 环境变量）
--no-auto-dialog	禁用自动关闭 alert/beforeunload 对话框（或 AGENT_BROWSER_NO_AUTO_DIALOG 环境变量）
--model <name>	用于聊天命令的 AI 模型（或 AI_GATEWAY_MODEL 环境变量）
-v, --verbose	显示工具命令及其原始输出（聊天）
-q, --quiet	仅显示 AI 文本回复，隐藏工具调用（聊天）
--config <path>	使用自定义配置文件（或 AGENT_BROWSER_CONFIG 环境变量）
--debug	调试输出

可观测性仪表板

使用本地 Web 仪表板实时监控 agent-browser 会话，该仪表板显示实时视口和命令活动信息流。

# 启动仪表板服务器（在后台端口 4848 上运行）
agent-browser dashboard start
agent-browser dashboard start --port 8080   # 自定义端口

# 所有会话都会自动显示在仪表板上
agent-browser open example.com

# 停止仪表板
agent-browser dashboard stop

仪表板作为一个独立的后台进程在端口 4848 上运行，与浏览器会话无关。即使没有会话运行，它仍然可用。所有会话会自动流式传输到仪表板。

仪表板显示：

• 实时视口 -- 来自浏览器的实时 JPEG 帧
• 活动信息流 -- 按时间顺序排列的命令/结果流，包含时间戳和可展开的详细信息
• 控制台输出 -- 浏览器控制台消息（log、warn、error）
• 会话创建 -- 可通过 UI 创建新会话，支持本地引擎（Chrome、Lightpanda）或云提供商（AgentCore、Browserbase、Browserless、Browser Use、Kernel）
• AI 聊天 -- 直接在仪表板中与 AI 助手聊天（需配置 Vercel AI Gateway）

AI 聊天

仪表板包含一个可选的 AI 聊天面板，由 Vercel AI Gateway 提供支持。相同的功能也可通过 CLI 中的 chat 命令直接使用。设置以下环境变量以启用 AI 聊天：

export AI_GATEWAY_API_KEY=gw_your_key_here
export AI_GATEWAY_MODEL=anthropic/claude-sonnet-4.6           # 可选，默认为该值
export AI_GATEWAY_URL=https://ai-gateway.vercel.sh           # 可选，默认为该值

CLI 使用方法：

agent-browser chat "打开 google.com 并搜索猫"     # 单次指令
agent-browser chat                                           # 交互式 REPL
agent-browser -q chat "总结此页面"                  # 静默模式（仅文本）
agent-browser -v chat "填写登录表单"               # 详细模式（显示命令输出）
agent-browser --model openai/gpt-4o chat "拍摄截图" # 替换模型

chat 命令会将自然语言指令转换为 agent-browser 命令，执行这些命令，并流式传输 AI 回复。在交互模式下，输入 quit 即可退出。使用 --json 可获得适合代理消费的结构化输出。

仪表板使用方法：

聊天选项卡始终在仪表板上可见。当设置了 AI_GATEWAY_API_KEY 时，Rust 服务器会将请求代理到网关，并使用 Vercel AI SDK 的 UI 消息流协议将响应流式传输回来。如果没有设置密钥，发送消息时会直接显示错误。

配置

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

配置文件加载顺序（优先级从低到高）：

1. ~/.agent-browser/config.json -- 用户级默认值
2. ./agent-browser.json -- 项目级覆盖配置（位于工作目录）
3. AGENT_BROWSER_* 环境变量会覆盖配置文件中的值
4. 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

上表中的所有选项都可以在配置文件中以驼峰命名法的键来设置（例如，--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
# 输出：
# - 标题“Example Domain” [ref=e1] [level=1]
# - 按钮“Submit” [ref=e2]
# - 文本框“Email” [ref=e3]
# - 链接“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：快照加引用的工作流对大型语言模型来说是最优的

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

这在以下场景中非常有用：

• 跳过登录流程：通过 HTTP 头部直接认证，无需通过 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，而原版约为 684MB）
• 系统浏览器：使用已安装的 Chrome/Chromium
• 定制构建：使用经过修改的浏览器版本

CLI 使用方法

agent-browser --executable /path/to/custom-chromium open example.com

请注意，使用自定义浏览器可执行文件可能会影响某些功能的兼容性，因此请确保所选的浏览器版本与工具兼容。

通过标志位

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 微型虚拟机中运行 agent-browser + Chrome。无需外部服务器：

```typescript
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();

请参阅 environments 示例 以获取带有 UI 和部署到 Vercel 按钮的可运行演示。

无服务器（AWS Lambda）

import chromium from '@sparticuz/chromium';
import { execSync } from 'child_process';

export async function handler() {
  const executablePath = await chromium.executablePath();
  const result = execSync(
    `AGENT_BROWSER_EXECUTABLE_PATH=${executablePath} agent-browser open https://example.com && agent-browser snapshot -i --json`,
    { encoding: 'utf-8' }
  );
  return JSON.parse(result);
}

本地文件

使用 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：

1. 读取默认用户数据目录中的 Chrome DevToolsActivePort 文件
2. 回退到探测常见调试端口（9222、9229）
3. 如果基于 HTTP 的发现方法（/json/version、/json/list）失败，则回退到直接的 WebSocket 连接

这在以下情况下非常有用：

• 当 Chrome 144+ 版本通过 chrome://inspect/#remote-debugging 启用了远程调试功能时（该功能使用动态端口）
• 当您希望与现有浏览器建立零配置连接时
• 当您不想跟踪 Chrome 正在使用的端口时

流媒体（浏览器预览）

通过 WebSocket 流传输浏览器视口，以实现实时预览或“配对浏览”，让人类与 AI 代理同时观看并交互。

流媒体

每次会话都会自动在操作系统分配的端口上启动一个 WebSocket 流媒体服务器。使用 stream status 命令查看绑定的端口和连接状态：

agent-browser stream status

若要绑定到特定端口，可设置 AGENT_BROWSER_STREAM_PORT：

AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com

您还可以在运行时使用 stream enable、stream disable 和 stream status 命令来管理流媒体：

agent-browser stream enable --port 9223   # 在特定端口重新启用流媒体
agent-browser stream disable              # 停止当前会话的流媒体

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 }]
}

架构

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

1. Rust CLI - 解析命令，与守护进程通信
2. Rust 守护进程 - 纯 Rust 守护进程，直接使用 CDP，无需 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 代理一起使用

直接让代理使用

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

使用 agent-browser 测试登录流程。运行 agent-browser --help 查看可用命令。

--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

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

## 浏览器自动化

使用 `agent-browser` 进行网页自动化。运行 `agent-browser --help` 查看所有命令。

核心工作流程：

1. `agent-browser open <url>` - 导航到页面
2. `agent-browser snapshot -i` - 获取带有引用的可交互元素（@e1、@e2）
3. `agent-browser click @e1` / `fill @e2 "text"` - 使用引用进行交互
4. 页面变化后重新截图

集成

iOS 模拟器

在 iOS 模拟器中控制真实的 Mobile Safari，以进行真实的移动网页测试。需要 macOS 系统并安装 Xcode。

设置：

# 安装 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 目标
• 转到“签名与功能”
• 选择您的团队（需要 Apple 开发者账户，免费层级即可）
• 让 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 地址（用于自定义区域或自托管）	https://production-sfo.browserless.io
BROWSERLESS_BROWSER_TYPE	使用的浏览器类型（chromium 或 chrome）	chromium
BROWSERLESS_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 代理提供云浏览器基础设施。当在无法使用本地浏览器的环境中运行 agent-browser（例如无服务器环境、CI/CD 等）时，可以使用它。

要启用 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 云控制台 获取 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 密钥。

AgentCore

AWS Bedrock AgentCore 提供支持 SigV4 认证的云浏览器会话。

要启用 AgentCore，请使用 -p 标志：

agent-browser -p agentcore open https://example.com

或者在 CI/脚本中使用环境变量：

export AGENT_BROWSER_PROVIDER=agentcore
agent-browser open https://example.com

凭据会自动从环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）或 AWS CLI（aws configure export-credentials）中解析，支持 SSO、配置文件和 IAM 角色。

可通过环境变量进行可选配置：

变量	描述	默认值
AGENTCORE_REGION	AgentCore 终端节点所在的 AWS 区域	us-east-1
AGENTCORE_BROWSER_ID	浏览器标识符	aws.browser.v1
AGENTCORE_PROFILE_ID	用于保存持久化状态（Cookie、localStorage）的浏览器配置文件	（无）
AGENTCORE_SESSION_TIMEOUT	会话超时时间（秒）	3600
AWS_PROFILE	用于解析凭据的 AWS CLI 配置文件	default

浏览器配置文件： 当设置了 AGENTCORE_PROFILE_ID 时，浏览器状态（Cookie、localStorage）将在不同会话之间自动保持一致。

启用后，agent-browser 将连接到 AgentCore 的云浏览器会话，而不是启动本地浏览器。所有命令的功能完全相同。

许可证

Apache-2.0

agent-browser 快速上手指南

agent-browser 是一款专为 AI Agent 设计的高性能浏览器自动化命令行工具，基于 Rust 原生开发。它支持通过自然语言或语义化选择器控制浏览器，无需 Node.js 运行时即可运行守护进程。

环境准备

系统要求

• 操作系统：macOS, Linux, Windows
• 浏览器内核：工具会自动下载专用的 Chrome for Testing 版本，也支持自动检测系统中已安装的 Chrome、Brave、Playwright 或 Puppeteer。
• Rust：仅当你需要从源码构建时才需要安装（普通用户无需安装）。

Linux 用户特别提示

在 Linux 系统上首次使用时，需安装系统级依赖库：

agent-browser install --with-deps

安装步骤

推荐根据你的使用场景选择以下一种安装方式：

方式一：全局安装（推荐）

适用于直接在终端使用命令。

通过 npm 安装：

npm install -g agent-browser
agent-browser install  # 首次运行需下载 Chrome

通过 Homebrew (macOS)：

brew install agent-browser
agent-browser install

通过 Cargo (Rust)：

cargo install agent-browser
agent-browser install

方式二：项目局部安装

适用于需要在 package.json 中锁定版本的工程项目。

npm install agent-browser
agent-browser install
# 使用时可通过 npx agent-browser 或在 package.json scripts 中调用

升级工具

无论通过何种方式安装，均可使用以下命令自动检测并升级到最新版本：

agent-browser upgrade

基本使用

1. 启动与导航

打开指定网址：

agent-browser open example.com

2. 获取页面状态（AI 友好）

获取带有引用 ID 的无障碍树（Accessibility Tree），这是让 AI 理解页面结构的关键步骤：

agent-browser snapshot

3. 元素操作

利用 snapshot 生成的引用 ID（如 @e2）进行精准操作：

• 点击元素：

  agent-browser click @e2
  

• 填充表单：

  agent-browser fill @e3 "test@example.com"
  

• 获取文本：

  agent-browser get text @e1
  

• 截图保存：

  agent-browser screenshot page.png
  

4. 传统选择器支持

如果不使用快照引用，也支持标准的 CSS 选择器和语义化查找：

# CSS 选择器
agent-browser click "#submit"
agent-browser fill "#email" "test@example.com"

# 语义化查找 (推荐用于动态页面)
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click

5. 结束会话

操作完成后关闭浏览器：

agent-browser close

进阶：AI 自然语言控制

直接使用自然语言指令让 AI 代理执行操作（单条指令模式）：

agent-browser chat "登录网站并截图首页"