agent-browser

命令

核心功能

agent-browser open <url>              # 导航（别名：goto，navigate）
agent-browser click <sel>             # 点击元素（--new-tab 可在新标签页中打开）
agent-browser dblclick <sel>          # 双击
agent-browser fill <sel> <text>       # 清空并填入内容
agent-browser type <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 focus <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>    # 将元素滚动至可视区域
agent-browser drag <src> <dst>        # 拖拽与释放
agent-browser upload <sel> <files>    # 上传文件
agent-browser screenshot [path]       # 截图（--full 为整页截图）
agent-browser screenshot --annotate   # 带编号元素标签的注释截图
agent-browser pdf <path>              # 将页面保存为 PDF
agent-browser snapshot                # 附带引用的可访问性树
agent-browser eval <js>               # 执行 JavaScript
agent-browser connect <port|url>      # 通过 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 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>        # 检查是否已勾选

查找元素

支持动作的语义化定位器（click、fill、type、hover、focus、check、uncheck、text）：

agent-browser find role <role> <action> [value]
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>
agent-browser find testid <id> <action> [value]
agent-browser find first <sel> <action> [value]
agent-browser find last <sel> <action> [value]
agent-browser find nth <n> <sel> <action> [value]

选项：

  • --name <name> -- 根据可访问名称过滤角色
  • --exact -- 要求精确文本匹配

示例：

agent-browser find role button click --name "提交"
agent-browser find label "邮箱" fill "[email protected]"
agent-browser find alt "Logo" click
agent-browser find first ".item" click
agent-browser find last ".item" text
agent-browser find nth 2 ".card" hover

等待

agent-browser wait <selector>         # 等待元素出现
agent-browser wait <ms>               # 等待指定毫秒数
agent-browser wait --text "欢迎"      # 等待文本出现
agent-browser wait --url "**/dash"    # 等待匹配特定 URL 模式
agent-browser wait --load networkidle # 等待加载状态完成
agent-browser wait --fn "condition"   # 等待满足 JavaScript 条件
agent-browser wait --download [path]  # 等待下载完成

下载

agent-browser download <sel> <path>   # 点击元素以触发下载
agent-browser wait --download [path]  # 等待任意下载完成

使用 --download-path <dir>（或环境变量 AGENT_BROWSER_DOWNLOAD_PATH）设置默认下载目录。若未设置，下载将存放在临时目录中，关闭浏览器后自动删除。

鼠标操作

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>    # 设置视口尺寸
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]  # 模拟颜色方案（会话期间保持不变）

使用 --color-scheme 可在所有命令中持久启用深色/浅色模式：

agent-browser --color-scheme dark open https://example.com

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 --clear         # 清空请求日志
agent-browser network requests --filter <pat>  # 按 URL 模式过滤

标签页与框架

agent-browser tab                     # 列出所有标签页
agent-browser tab new [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 trace start [path]      # 开始录制
agent-browser trace stop [path]       # 停止并保存录制结果
agent-browser profiler start          # 开始 Chrome DevTools 性能分析
agent-browser profiler stop [path]    # 停止并保存性能分析数据（.json 格式）
agent-browser record start <path>     # 开始视频录制（WebM 格式）
agent-browser record stop             # 停止并保存视频
agent-browser record restart <path>   # 停止当前录制并开始新录制
agent-browser console                 # 查看控制台消息
agent-browser console --clear         # 清空控制台日志
agent-browser errors                  # 查看页面错误
agent-browser errors --clear          # 清空错误日志
agent-browser highlight <sel>         # 高亮元素

认证凭据库

agent-browser auth save <name> [opts]    # 保存认证配置
agent-browser auth login <name>          # 使用已保存的凭据登录
agent-browser auth list                  # 列出已保存的配置（仅显示名称和网址）
agent-browser auth show <name>           # 显示配置元数据（不包含密码）
agent-browser auth delete <name>         # 删除已保存的配置

保存选项：

  • --url <url> -- 登录页地址（必需）
  • --username <user> -- 用户名（必需）
  • --password <pass> -- 密码（除非使用 --password-stdin，否则必需）
  • --password-stdin -- 从标准输入读取密码（推荐以避免暴露在命令历史中）
  • --username-selector <sel> -- 自定义用户名输入框的 CSS 选择器
  • --password-selector <sel> -- 自定义密码输入框的 CSS 选择器
  • --submit-selector <sel> -- 自定义提交按钮的 CSS 选择器
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github
agent-browser auth list

确认机制

当启用 --confirm-actions 时，某些操作类别会返回 confirmation_required 响应而非立即执行。使用 confirm 或 deny 来批准或拒绝该操作。

agent-browser confirm <confirmation-id>  # 批准待处理的操作
agent-browser deny <confirmation-id>     # 拒绝待处理的操作

待确认的操作将在 60 秒后自动拒绝。

agent-browser --confirm-actions eval,download eval "document.title"
# 返回 confirmation_required 并附带唯一 ID
agent-browser confirm c_8f3a1234

状态管理

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 session                 # 显示当前会话名称
agent-browser session list            # 列出所有活动会话

导航

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

全局选项

--session <name>         # 独立的浏览器会话
--session-name <name>    # 自动保存/恢复会话状态（包括 Cookie、localStorage）
--profile <path>         # 持久化的浏览器配置文件目录
--state <path>           # 从 JSON 文件加载存储状态
--headers <json>         # 作用于目标域名的请求头
--executable-path <path> # 自定义浏览器可执行文件路径
--extension <path>       # 加载浏览器扩展（可重复使用）
--args <args>            # 浏览器启动参数（用逗号分隔）
--user-agent <ua>        # 自定义 User-Agent 字符串
--proxy <url>            # 代理服务器地址
--proxy-bypass <hosts>   # 需绕过代理的主机列表
--ignore-https-errors    # 忽略 HTTPS 证书错误
--allow-file-access      # 允许 file:// URL 访问本地文件（仅 Chromium 支持）
-p, --provider <name>    # 浏览器提供者（ios, browserbase, kernel, browseruse）
--device <name>          # iOS 设备名称（例如 "iPhone 15 Pro"）
--json                   # JSON 输出格式（适用于脚本调用）
--full, -f               # 完整页面截图
--annotate               # 带编号元素标签的注释截图
--headed                 # 显示浏览器窗口（非无头模式）
--cdp <port|url>         # 通过 Chrome DevTools 协议连接（端口或 WebSocket 地址）
--auto-connect           # 自动发现并连接正在运行的 Chrome
--color-scheme <scheme>  # 颜色主题：dark、light、no-preference
--download-path <path>   # 默认下载目录
--content-boundaries     # 在页面输出周围添加边界标记以增强 LLM 安全性
--max-output <chars>     # 截断页面输出至 N 个字符
--allowed-domains <list> # 逗号分隔的允许域名模式列表
--action-policy <path>   # 动作策略的 JSON 文件路径
--confirm-actions <list> # 需要确认的动作类别列表
--confirm-interactive    # 交互式确认提示（若 stdin 非 TTY，则自动拒绝）
--config <path>          # 使用自定义配置文件
--debug                  # 输出调试信息

命令链式调用

在单个 shell 调用中使用 && 进行命令链式调用。由于浏览器通过后台守护进程持续运行，因此链式调用自然高效，比单独调用更优：

agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "pass" && agent-browser click @e3
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

若无需读取中间输出，建议使用 &&。若需先解析输出（例如，使用 snapshot 发现引用后再操作这些引用），则应分别运行命令。

本地文件

使用 file:// URL 打开本地文件（如 PDF、HTML）：

agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

--allow-file-access 标志允许脚本访问其他本地文件。仅 Chromium 支持。