agent-browser

命令#

核心#

bash
agent-browser open                    # 启动浏览器（不导航）；停留在 about:blank
agent-browser open <url>              # 启动并导航（别名：goto, navigate）
agent-browser read [url]              # 获取可供 agent 读取的文本，或读取已渲染的活动标签页 DOM
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 screenshot --screenshot-dir ./shots    # 保存到自定义目录
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # 将页面保存为 PDF
agent-browser snapshot                # 带 ref 的无障碍树
agent-browser eval <js>               # 运行 JavaScript
agent-browser connect <port|url>      # 通过 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 mcp                     # 启动 MCP stdio 服务器

当另一个元素覆盖目标点击点时，点击会在分发前失败。错误会指出覆盖元素，例如 covered by <div#consent-banner>。先关闭或处理该元素，重新生成快照，然后重试原始操作。

无头 Chromium 截图会隐藏原生滚动条，以确保图像输出一致。启动时传入 --hide-scrollbars false 可以保留原生滚动条可见。

获取信息#

bash
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
agent-browser get count <sel>         # 统计匹配元素数量
agent-browser get box <sel>           # 获取边界框
agent-browser get styles <sel>        # 获取计算后的样式

读取适合 agent 的文本#

bash
agent-browser read
agent-browser read https://example.com/article
agent-browser read https://example.com/article --filter overview
agent-browser read https://example.com/article --outline
agent-browser read https://docs.example.com --llms index --filter auth
agent-browser read https://docs.example.com --llms full --filter auth
agent-browser read example.com/article --require-md
agent-browser read https://example.com/article --json

read 会在不启动 Chrome 的情况下获取 URL。若省略 URL，则会读取当前浏览器会话中活动标签页已渲染的 DOM，包括浏览器认证状态和客户端更新。显式 URL 读取默认发送 Accept: text/markdown，如果首次响应不是 markdown，会尝试在同一 URL 后追加 .md；它还会向上遍历祖先路径，查找与匹配文档链接对应的最近 llms.txt，在可用时输出 markdown 或纯文本，并在最后回退到从 HTML 中提取的可读文本。没有 URL 时，--llms 和 --require-md 会使用活动标签页的 URL，因为它们依赖 HTTP 资源。除非你明确要求，read 不会读取 llms-full.txt。

选项：--raw 会直接打印响应体而不做 HTML 提取，--require-md 会在服务器未返回 Content-Type: text/markdown 时失败，--outline 会打印单页的紧凑标题大纲，--llms index 会打印最近祖先 llms.txt 的紧凑链接列表，--llms full 会读取最近祖先的 llms-full.txt，--filter <text> 会缩小页面分区、llms 链接/分区或大纲标题范围，--timeout <ms> 会更改请求超时。--allowed-domains、--content-boundaries 和 --max-output 等全局保护也同样适用于 read 的抓取和输出。

检查状态#

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

查找元素#

Semantic locators with actions (click, fill, type, hover, focus, check, uncheck, text):

bash
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：要求文本精确匹配

示例：

bash
agent-browser find role button click --name "Submit"
agent-browser find label "Email" fill "test@test.com"
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

等待#

bash
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 "condition"   # 等待 JS 条件
agent-browser wait --download [path]  # 等待下载
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # 等待文本消失
agent-browser wait "#spinner" --state hidden           # 等待元素消失

下载#

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

使用 --download-path <dir>（或 AGENT_BROWSER_DOWNLOAD_PATH 环境变量）可设置默认下载目录。否则下载会进入临时目录，并在浏览器关闭时删除。

有关上传、下载、本地文件、截图、PDF 和剪贴板工作流，请参见 Files & Clipboard。

鼠标#

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

剪贴板#

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

有关剪贴板、上传、下载、本地文件、截图和 PDF 工作流，请参见 Files & Clipboard。

设置#

bash
agent-browser set viewport <w> <h> [scale]  # 设置视口大小（retina 可传 scale，例如 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]  # 模拟配色方案（对本次会话生效）

使用 --color-scheme 可让所有命令持久保持深色/浅色模式：

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

Cookies 与存储#

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

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

agent-browser storage session         # sessionStorage 同理

网络#

bash
agent-browser network route <url>              # 拦截请求
agent-browser network route <url> --abort      # 阻止请求
agent-browser network route <url> --body <json>  # 模拟响应
agent-browser network route '*' --abort --resource-type script  # 仅阻止脚本
agent-browser network unroute [url]            # 移除路由
agent-browser network requests                 # 查看已跟踪请求
agent-browser network requests --clear         # 清除请求日志
agent-browser network requests --filter <pat>  # 按 URL 模式过滤
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（省略则使用临时路径）

有关导航前路由、请求过滤、HAR 导出以及 SSR/无 JavaScript 调试，请参见 Network。

标签页与框架#

bash
agent-browser tab                              # 列出标签页（每行显示 tabId 和标签）
agent-browser tab new [url]                    # 新建标签页
agent-browser tab new --label docs [url]       # 用用户指定标签新建标签页
agent-browser tab <t<N>|label>                 # 按 id 或标签切换到标签页
agent-browser tab close [t<N>|label]           # 关闭标签页（默认当前活动标签页）
agent-browser window new                       # 打开新的浏览器窗口
agent-browser frame <sel>                      # 通过 CSS 选择器切换到 iframe
agent-browser frame @e3                        # 通过元素 ref 切换到 iframe
agent-browser frame main                       # 返回主框架

稳定的标签页 ID 和标签#

标签页 ID 是稳定的字符串，形式为 t1、t2、t3。它们在同一会话内不会复用，因此即使其他标签页被打开或关闭，t2 仍然指向同一个标签页。t 前缀与 @e1 元素 ref 约定一致，不能与位置整数互换使用 - agent-browser tab 2 会报出教学提示；请使用 t2。

你也可以在创建标签页时分配一个容易记住的标签（docs、app、admin），并在任何接受 id 的地方使用它：

bash
agent-browser tab new --label docs https://docs.example.com
agent-browser tab docs          # 切换到 docs 标签页
agent-browser snapshot          # 为 docs 生成 refs
agent-browser click @e3         # 点击时使用 docs 的 refs
agent-browser tab close docs    # 按标签关闭

标签不会自动生成，也不会在导航时被重写 - 一个将标签页命名为 docs 的 agent 会一直保留这个名字，直到标签页关闭。标签在同一会话内必须唯一；如果创建第二个使用相同标签的标签页，会报错。

Refs（@e1 等）作用域只限于运行 snapshot 时处于活动状态的标签页，因此请先切换标签页，再 snapshot 并交互：

bash
agent-browser tab docs          # 先切换
agent-browser snapshot          # docs 的 refs
agent-browser click @e3         # 使用 docs 的 refs

Iframe 支持#

在 snapshot 期间会自动检测 Iframe。Iframe 节点会被解析，其内容会以内联方式显示在 snapshot 输出中的 iframe 元素下方。分配给 iframe 内元素的 refs 会携带 frame 上下文，因此 click、fill 和其他交互无需手动切换框架即可工作。

bash
agent-browser snapshot -i
# @e3 [Iframe] "payment-frame"
#   @e4 [input] "Card number"
#   @e5 [button] "Pay"

# Interact directly using refs — no frame switch needed
agent-browser fill @e4 "4111111111111111"
agent-browser click @e5

# Or switch frame context for scoped snapshots
agent-browser frame @e3
agent-browser snapshot -i             # Only elements inside that iframe
agent-browser frame main              # Return to main frame

frame 命令接受元素 ref（@e3）、CSS 选择器（"#my-iframe"）或 frame 名称/URL。

对话框#

bash
agent-browser dialog accept [text]    # 接受对话框（可选提示文本）
agent-browser dialog dismiss          # 关闭对话框
agent-browser dialog status           # 检查当前是否有对话框打开

默认情况下，alert 和 beforeunload 对话框会被自动接受，因此不会阻塞 agent。confirm 和 prompt 对话框仍然需要显式处理。使用 --no-auto-dialog（或 AGENT_BROWSER_NO_AUTO_DIALOG=1）可以关闭自动处理。

当有 JavaScript 对话框（alert、confirm、prompt）待处理时，所有命令响应都会包含一个 warning 字段，带有对话框类型和消息。

流式传输#

bash
agent-browser stream enable           # 在自动选择的端口上启动运行时 WebSocket 流
agent-browser stream enable --port 9223  # 绑定到指定的 localhost 端口
agent-browser stream status           # 显示启用状态、端口、浏览器连接和 screencasting
agent-browser stream disable          # 停止运行时流并移除 .stream 元数据文件

所有会话都会自动启用流式传输。可使用这些命令检查状态、在指定端口上重新启用，或关闭流式传输。

流式传输与基于文件的录制是分开的。当你需要保存的 WebM 产物时，请使用 Video Recording。

调试#

bash
agent-browser trace start             # 开始 trace
agent-browser trace stop [path]       # 停止并保存 trace
agent-browser profiler start          # 启动 Chrome DevTools profiling
agent-browser profiler stop [path]    # 停止并保存 profile（.json）
agent-browser record start <path>     # 开始视频录制（WebM）
agent-browser record stop             # 停止并保存视频
agent-browser record restart <path>   # 停止当前录制并开始新录制
agent-browser console                 # 查看控制台消息
agent-browser console --json          # 带原始 CDP 参数的 JSON 输出
agent-browser console --clear         # 清除控制台日志
agent-browser errors                  # 查看页面错误
agent-browser errors --clear          # 清除错误日志
agent-browser highlight <sel>         # 高亮元素
agent-browser inspect                 # 为活动页面打开 Chrome DevTools

有关控制台、错误、对话框、trace、高亮和 DevTools 工作流，请参见 Debugging。有关 record 工作流，请参见 Video Recording；有关性能 profile，请参见 Profiler。

Auth vault#

bash
agent-browser auth save <name> [opts]    # 保存 auth 配置文件
agent-browser auth login <name>          # 使用已保存的凭据登录
agent-browser auth login <name> --credential-provider <plugin> [--item <ref>] [--url <url>]
                                          # 从插件解析凭据
agent-browser auth login <name> --username-selector <s> --password-selector <s> [--submit-selector <s>]
                                          # 为单次登录覆盖选择器
agent-browser auth list                  # 列出已保存配置文件（仅名称和 URL）
agent-browser auth show <name>           # 显示配置文件元数据（不含密码）
agent-browser auth delete <name>         # 删除已保存的配置文件
agent-browser plugin add <ref>           # 从 npm 或 GitHub 添加插件
agent-browser plugin list                # 列出已配置插件
agent-browser plugin show <name>         # 显示一个已配置插件
agent-browser plugin run <name> <type> --payload <json>
                                          # 运行任意插件请求

Save options:

  • --url <url>：登录页 URL（必需）
  • --username <user>：用户名（必需）
  • --password <pass>：密码（除非使用 --password-stdin，否则必需）
  • --password-stdin：从 stdin 读取密码（推荐，避免暴露在 shell 历史中）
  • --username-selector <sel>：用户名字段的自定义 CSS 选择器
  • --password-selector <sel>：密码字段的自定义 CSS 选择器
  • --submit-selector <sel>：提交按钮的自定义 CSS 选择器

auth login 会在 load 后导航，然后等待用户名/密码/提交选择器出现再进行交互。这能提升 SPA 登录页的可靠性，因为这些页面上的字段通常在初始加载后才渲染。

插件登录选项：

  • --credential-provider <plugin>：从已配置插件解析凭据
  • --item <ref>：提供商特定的 vault 项引用
  • --url <url>：覆盖登录 URL
  • --username-selector <sel>：本次登录的选择器覆盖项
  • --password-selector <sel>：本次登录的选择器覆盖项
  • --submit-selector <sel>：本次登录的选择器覆盖项

凭据提供器插件通过 agent-browser.plugin.v1 stdio JSON 协议在进程外运行。它们会把凭据返回给守护进程用于单次登录，agent-browser 不会在本地保存这些凭据。

其他插件能力使用同一协议：

  • browser.provider：配合 --provider <name> 使用插件，返回 CDP WebSocket URL
  • launch.mutate：在 Chrome 启动前附加本地启动参数、扩展或 init scripts
  • command.run：通过 agent-browser plugin run 运行任意命名空间请求

plugin run 用于 command.run 和自定义能力。核心能力和协议请求类型会使用各自专用的命令路径。

bash
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github
agent-browser plugin add agent-browser-plugin-vault --name vault
agent-browser auth login my-app --credential-provider vault --item "My App"
agent-browser --provider cloud-browser open https://example.com
agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'
agent-browser auth list

确认#

当设置了 --confirm-actions 时，某些动作类别不会立即执行，而是返回 confirmation_required 响应。使用 confirm 或 deny 来批准或拒绝该动作。

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

Pending confirmations auto-deny after 60 seconds.

bash
agent-browser --confirm-actions eval,download eval "document.title"
# Returns confirmation_required with ID
agent-browser confirm c_8f3a1234

状态管理#

bash
agent-browser state save <path>       # Save auth state to file
agent-browser state load <path>       # Load auth state from file
agent-browser state list              # List saved state files
agent-browser state show <file>       # Show state summary
agent-browser state rename <old> <new> # Rename state file
agent-browser state clear [name]      # Clear states for session name
agent-browser state clear --all       # Clear all saved states
agent-browser state clean --older-than <days>  # Delete old states

会话#

bash
agent-browser session                 # Show current session name
agent-browser session list            # List active sessions

Chrome 配置文件#

bash
agent-browser profiles               # List available Chrome profiles
agent-browser profiles --json        # List profiles as JSON
agent-browser --profile Default open https://gmail.com  # Reuse a profile's login state

仪表盘#

bash
agent-browser dashboard [start]       # 启动仪表盘服务器（默认端口：4848）
agent-browser dashboard start --port <n>  # 在指定端口启动
agent-browser dashboard stop          # 停止仪表盘服务器

通过 http://localhost:4848 或经代理/转发后的仪表盘 URL（例如 https://dashboard.agent-browser.localhost）打开仪表盘。浏览器会停留在仪表盘来源下；每个会话的标签页、状态和流量都会在内部代理，因此无需暴露会话端口。

Doctor#

诊断安装情况、自动清理过期的守护进程文件，并可选择修复常见问题。

bash
agent-browser doctor                     # 完整诊断（环境、Chrome、守护进程、配置、提供商、网络、启动测试）
agent-browser doctor --offline --quick   # 仅本地，最快
agent-browser doctor --fix               # 还会执行破坏性修复（重装 Chrome、清除旧状态等）
agent-browser doctor --json              # 面向 agent 的结构化 JSON 输出

如果所有检查都通过（警告也算通过），退出码为 0；若有任一项失败，则为 1。完整检查目录请参见 Installation page。

聊天#

使用自然语言通过 AI 控制浏览器。chat 命令会把指令翻译为 agent-browser 命令、执行它们，并流式返回 AI 响应。需要设置 AI_GATEWAY_API_KEY。

bash
agent-browser chat "open google.com and search for cats"     # 单次指令
agent-browser chat                                           # 交互式 REPL（输入 quit 退出）
echo "summarize this page" | agent-browser chat              # 管道输入
agent-browser -q chat "summarize this page"                  # 安静模式：只输出文本，不显示工具调用
agent-browser -v chat "fill in the login form"               # 详细模式：显示命令及其输出
agent-browser --model openai/gpt-4o chat "take a screenshot" # 覆盖默认 AI 模型
agent-browser --json chat "open example.com"                 # 结构化 JSON 输出

聊天专用选项：

bash
--model <name>           # AI model (or AI_GATEWAY_MODEL env, default: anthropic/claude-sonnet-4.6)
-v, --verbose            # Show tool commands and their raw output
-q, --quiet              # Show only the AI text response (hide tool calls)

导航#

bash
agent-browser back                    # 后退
agent-browser forward                 # 前进
agent-browser reload                  # 重新加载页面
agent-browser pushstate <url>         # SPA client-side nav; auto-detects window.next.router.push,
                                      # 否则回退到 history.pushState + popstate

导航前设置#

有些流程需要在首次导航 之前 配置路由、cookie 或 init script（例如 SSR 调试、受保护来源上的认证等）。不带 URL 的 open 会启动浏览器但停留在 about:blank，为预置状态留出空间。batch 可以把这些步骤放进一次 CLI 调用中：

bash
agent-browser batch \
  '["open"]' \
  '["network","route","*","--abort","--resource-type","script"]' \
  '["cookies","set","--curl","cookies.curl","--domain","localhost"]' \
  '["navigate","http://localhost:3000/target"]'

React / Web Vitals#

React 命令需要在启动时使用 --enable react-devtools（会在任何页面 JS 运行前安装 React DevTools hook）。vitals 和 pushstate 可在任何站点上工作。

bash
agent-browser open --enable react-devtools <url>   # Launch with React hook installed
agent-browser react tree                           # Full component tree
agent-browser react inspect <fiberId>              # Inspect one component
agent-browser react renders start                  # Begin fiber render recording
agent-browser react renders stop [--json]          # Stop + print profile
agent-browser react suspense [--only-dynamic] [--json]  # Suspense boundaries + classifier
                                                         # --only-dynamic hides the "static" list
agent-browser vitals [url] [--json]                # LCP/CLS/TTFB/FCP/INP + hydration

适用于任何 React 应用（Next.js、Remix、Vite+React、CRA、TanStack Start、React Native Web 等）。vitals 和 pushstate 与框架无关。

完整命令细节和示例请参见 React & Web Vitals。

Init scripts#

bash
agent-browser open --init-script <path>           # Register before first navigation (repeatable)
agent-browser addinitscript <js>                  # Register at runtime (returns identifier)
agent-browser removeinitscript <identifier>       # Remove a previously registered init script

有关启动时脚本、运行时脚本、内置 React DevTools 和扩展，请参见 Init Scripts & Extensions。

全局选项#

bash
--session <name>         # 隔离的浏览器会话
--restore [name]         # 自动保存/恢复会话状态，默认使用 --session
--restore-save <policy>  # 恢复保存策略：auto、always、never
--namespace <name>       # 隔离守护进程 socket 和恢复状态目录
--profile <path>         # 持久化浏览器配置文件目录
--state <path>           # 从 JSON 文件加载存储状态
--headers <json>         # 作用于 URL 来源的 HTTP 头
--executable-path <path> # 自定义浏览器可执行文件
--extension <path>       # 加载浏览器扩展（可重复）
--init-script <path>     # 在首次导航前注册页面 init script（可重复）
--enable <feature>       # 内置 init script：react-devtools（可重复或逗号列表）
--args <args>            # 浏览器启动参数（逗号分隔）
--user-agent <ua>        # 自定义 User-Agent 字符串
--proxy <url>            # 代理服务器 URL
--proxy-bypass <hosts>   # 绕过代理的主机
--ignore-https-errors    # 忽略 HTTPS 证书错误
--allow-file-access      # 允许 file:// URL 访问本地文件（仅 Chromium）
--hide-scrollbars <bool> # 在无头 Chromium 截图中隐藏原生滚动条
-p, --provider <name>    # Browser provider or configured provider plugin
--device <name>          # iOS device name (e.g., "iPhone 15 Pro")
--json                   # JSON output (for scripts)
--annotate               # Annotated screenshot with numbered element labels
--screenshot-dir <path>   # Default screenshot output directory (or AGENT_BROWSER_SCREENSHOT_DIR)
--screenshot-quality <n>  # JPEG quality 0-100 (or AGENT_BROWSER_SCREENSHOT_QUALITY)
--screenshot-format <fmt> # Format: png (default), jpeg (or AGENT_BROWSER_SCREENSHOT_FORMAT)
--headed                 # Show browser window (not headless)
--cdp <port|url>         # 通过 Chrome DevTools Protocol 连接（端口或 WebSocket URL）
--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，则自动拒绝）
--engine <name>          # 浏览器引擎：chrome（默认）、lightpanda
--idle-timeout <time>    # 空闲后自动关闭守护进程（10s、3m、1h 或 ms）
--no-auto-dialog         # 禁用对 alert 和 beforeunload 对话框的自动接受
--model <name>           # 聊天使用的 AI 模型（或 AI_GATEWAY_MODEL 环境变量）
-v, --verbose            # 显示工具命令及其原始输出（聊天）
-q, --quiet              # 仅显示 AI 文本响应（聊天）
--config <path>          # 使用自定义配置文件
--debug                  # 调试输出

有关配置文件和环境变量，请参见 Configuration。有关代理服务器、绕过和凭据设置，请参见 Proxy。

批量执行#

在一次调用中执行多个命令。命令可以作为带引号的参数传入，也可以通过 stdin 以 JSON 形式传入。

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

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

# stdin 模式：以 JSON 管道传入命令
echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json
选项说明
--bail在第一个错误处停止（默认：继续执行所有命令）
--json以 JSON 数组输出结果

MCP 服务器#

bash
agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,react

通过 stdio 启动一个 Model Context Protocol 服务器。MCP 客户端会将此命令作为子进程启动，并在 stdin 和 stdout 上交换以换行分隔的 JSON-RPC。服务器默认使用 MCP 协议 2025-11-25，并在初始化期间接受旧版受支持的客户端协议版本。

默认工具配置文件是 core，适合日常浏览器自动化，并能保持 MCP 上下文较小。使用 --tools all 可获得完整的类型化 CLI 对等能力；也可以用逗号组合配置文件，例如 --tools core,network,react。

配置文件：

  • core - 默认。导航、快照、交互、等待、读取、截图、JavaScript eval、关闭、基础标签页以及配置文件发现
  • network - 网络路由、请求检查、HAR、headers、凭据、离线
  • state - Cookies、存储、auth、已保存状态、会话、配置文件、skills
  • debug - 控制台/错误、跟踪、分析、录制、剪贴板、插件、doctor、仪表盘、安装、升级、聊天、diff、batch、确认/拒绝
  • tabs - 后退/前进/重载、标签页、窗口、框架、对话框
  • react - React 树/检查/渲染/suspense、vitals、pushstate
  • mobile - 视口/设备/地理位置/媒体、触摸、滑动、鼠标、键盘
  • all - 每一个 MCP 工具，包括完整的类型化 CLI 对等能力

MCP 客户端配置示例：

json
{
  "mcpServers": {
    "agent-browser": {
      "command": "agent-browser",
      "args": ["mcp"]
    }
  }
}

使用 --tools all 时，服务器会在整个 CLI 命令面上暴露类型化工具，包括导航、快照、输入、等待、截图/PDF、get/is/find、鼠标、网络、存储、cookies、标签页、窗口、框架、对话框、跟踪、录制、剪贴板、auth、state、iOS、diff、React、vitals、会话、skills、插件、doctor、仪表盘、安装、升级、聊天、eval 和关闭。

常见工具包括：

  • agent_browser_tools_profiles
  • agent_browser_open
  • agent_browser_snapshot
  • agent_browser_click
  • agent_browser_fill
  • agent_browser_type
  • agent_browser_press
  • agent_browser_wait_for_selector
  • agent_browser_screenshot
  • agent_browser_get_url
  • agent_browser_eval
  • agent_browser_close

每个工具都有类型化字段，例如 url、selector、text、key 和 session，因此 MCP 客户端会显示有意义的批准提示，而不是原始命令数组。每个工具还接受 extraArgs，用于高级 CLI 标志和完全的 CLI 对等。工具发现是分页的，并包含只读/开放世界注释，因此现代 MCP 客户端可以逐步加载庞大的类型化表面。

工具调用会使用与 CLI 相同的配置文件和环境变量。可在工具参数中使用 session，或设置 AGENT_BROWSER_SESSION，以隔离浏览器状态。

命令串联#

在一次 shell 调用中使用 && 串联命令。浏览器会通过后台守护进程保持持久化，因此串联自然可用，也比分开调用更高效：

bash
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

当你不需要读取中间输出时使用 &&。如果需要先解析输出再继续操作，请分开运行命令（例如先 snapshot 发现 refs，再用这些 refs 交互）。

本地文件#

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

bash
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 标志允许 JavaScript 访问其他本地文件。仅限 Chromium。

有关本地文件、上传、下载、截图、PDF 和剪贴板工作流，请参见 Files & Clipboard。