命令

核心¶

未知命令以状态 1 退出，包括当你请求命令帮助时。

当顶层 Chrome/CDP eval 结果是 JSON 无法表示的值时，普通输出会打印其精确的 JavaScript 标记，包括 NaN、Infinity、-Infinity、-0、BigInt 字面量和 undefined。使用 --json 时，data.result 保持为 null，同级 data.unserializable 包含该标记。MCP 文本输出打印该标记，结构化响应在 structuredContent.response.data.unserializable 中暴露它。

agent-browser open                    # Launch browser (no nav); stays on about:blank
agent-browser open <url>              # Launch + navigate (aliases: goto, navigate)
agent-browser read [url]              # Fetch agent-readable text, or read rendered active-tab DOM
agent-browser click <sel>             # Click element (--new-tab to open in new tab)
agent-browser dblclick <sel>          # Double-click
agent-browser fill <sel> <text>       # Clear and fill
agent-browser type <sel> <text>       # Type into element
agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text>    # Type at current focus (no selector needed)
agent-browser keyboard inserttext <text>  # Insert text without key events
agent-browser keydown <key>           # Hold key down
agent-browser keyup <key>             # Release key
agent-browser hover <sel>             # Hover element
agent-browser focus <sel>             # Focus element
agent-browser select <sel> <val>      # Select dropdown by value or visible label
agent-browser check <sel>             # Check checkbox
agent-browser uncheck <sel>           # Uncheck checkbox
agent-browser scroll <dir> [px]       # Scroll (up/down/left/right, --selector <sel>)
agent-browser scrollintoview <sel>    # Scroll element into view
agent-browser drag <src> <dst>        # Drag and drop
agent-browser upload <sel> <files>    # Upload files
agent-browser screenshot [path]       # Screenshot (--full for full page)
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser screenshot --if-changed # Recommended: skip unchanged images to save tokens
agent-browser screenshot --threshold 0.01 # Ignore changes affecting at most 1% of pixels
agent-browser screenshot --screenshot-dir ./shots    # Save to custom directory
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # Save page as PDF
agent-browser snapshot                # Accessibility tree with refs
agent-browser eval <js>               # Run JavaScript
agent-browser connect <port|url>      # Connect to browser via CDP
agent-browser stream enable [--port <port>]  # Start runtime WebSocket streaming
agent-browser webmcp list                     # List experimental page tools
agent-browser webmcp invoke <tool> --params @input.json
agent-browser stream status           # Show runtime streaming state and bound port
agent-browser stream disable          # Stop runtime WebSocket streaming
agent-browser close                   # Close browser (aliases: quit, exit)
agent-browser close --all             # Close all active sessions
agent-browser mcp                     # Start an MCP stdio server
agent-browser mcp call <tool> <json>  # Run one MCP tool and print its result

对于 fill 和 type，请将选项放在可选的 -- 标记之前。标记之后的文本是字面量，包括看起来像标志的值。例如，agent-browser fill "#search" -- --json 会填充 --json，而 agent-browser --json type "#search" --clear --delay 10 -- --clear 会先清空字段，然后输入 --clear。MCP agent_browser_fill 和 agent_browser_type 按字面量传递输入的 text 值，因此它们不需要该标记。

浏览器响应会在首次发现以及目录更改时自动通告 WebMCP 工具。摘要仅包含名称、简短描述、来源和 frame ID。选择相关工具后，在调用它之前，使用 agent-browser webmcp list <tool> --frame <frame-id> --json 获取其完整模式。模式和注解永远不会主动包含。未更改的目录以及没有工具的页面不会增加上下文。JSON 将更新暴露为 data.webmcp；CLI 和 MCP 文本包含相同的受限摘要。有关更新语义和安全性，请参阅 WebMCP。

当另一个元素覆盖目标元素的点击点时，点击会在分发前失败。错误会指出覆盖元素，例如 covered by <div#consent-banner>。请关闭或与该元素交互，获取新的快照，然后重试原始操作。当元素处于隐藏、禁用或视口之外时，click 和 dblclick 会失败，而不是报告成功。click --new-tab 直接打开链接的 URL，因此这些检查不适用于它。

无头 Chromium 截图会隐藏原生滚动条，以获得一致的图像输出。启动时传递 --hide-scrollbars false 可保持原生滚动条可见。

获取信息¶

agent-browser get text <sel>          # Get text content
agent-browser get html <sel>          # Get innerHTML
agent-browser get value <sel>         # Get input value
agent-browser get attr <sel> <attr>   # Get attribute
agent-browser get title               # Get page title
agent-browser get url                 # Get current URL
agent-browser get cdp-url             # Get CDP WebSocket URL
agent-browser get count <sel>         # Count matching elements
agent-browser get box <sel>           # Get bounding box
agent-browser get styles <sel>        # Get computed styles

get cdp-url 报告已在运行的浏览器的 CDP WebSocket URL。它要求浏览器已在运行，并且绝不会启动浏览器。仅包含 get cdp-url 命令的批处理也会跳过浏览器启动。混合批处理可以为其其他命令启动浏览器。

读取面向代理的文本¶

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 时，会尝试附加 .md 的相同 URL，向 / 方向遍历祖先路径以找到最近的 llms.txt 来匹配文档链接，在有可用时打印 markdown 或纯文本，并在无法获取时回退到从 HTML 提取的可读文本。--llms 和 --require-md 如果不带 URL，则使用活动标签页的 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 获取和输出。

检查状态¶

agent-browser is visible <sel>        # Check if visible
agent-browser is enabled <sel>        # Check if enabled
agent-browser is checked <sel>        # Check if checked

查找元素¶

带有动作（click、fill、check、hover、text）的语义定位器：

agent-browser find role <role> <action> [value]
agent-browser find text <text> <action> [value]
agent-browser find label <label> <action> [value]
agent-browser find placeholder <ph> <action> [value]
agent-browser find alt <text> <action> [value]
agent-browser find title <text> <action> [value]
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>：按可访问名称筛选 role
--exact：精确、区分大小写的匹配。对于 role，它适用于可访问名称，默认是不区分大小写的子字符串。

示例：

agent-browser find role button click --name "Submit"
agent-browser find role heading text --name "Skills"     # implicit roles work: <h2>=heading, <ul>=list, top-level <header>=banner
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

等待¶

agent-browser wait <selector>         # Wait for element
agent-browser wait <ms>               # Wait for time
agent-browser wait --text "Welcome"   # Wait for text (substring match)
agent-browser wait --url "**/dash"    # Wait for URL pattern
agent-browser wait --load domcontentloaded # Wait for DOMContentLoaded
agent-browser wait --load load        # Wait for the load event
agent-browser wait --load networkidle # Use only for pages known to become quiet
agent-browser wait --fn "condition"   # Wait for JS condition
agent-browser wait --download [path]  # Wait for download
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
agent-browser wait "#spinner" --state hidden           # Wait for element to disappear

对于选择器等待，--state 接受 visible、hidden、attached 或 detached，并且不能与 URL、加载、函数、文本、下载或毫秒等待模式结合使用。全局认证状态 --state <path> 在 wait 之前仍然可用，就像在其他命令之前一样。

页面更改后，请优先选择代表所需状态的选择器、文本、URL 或 JavaScript 条件。仅当页面已知会静下来时才使用 networkidle，因为 SSE、WebSockets、轮询和长轮询可能会使其无法完成解析。

加载状态等待会消耗其整个超时预算，该预算取自 --timeout 或 AGENT_BROWSER_DEFAULT_TIMEOUT，超时后返回错误。

下载¶

agent-browser download <sel> <path>   # Click element to trigger download
agent-browser wait --download [path]  # Wait for any download to complete

wait --download 返回未被先前 wait 认领的最早下载，包括在命令运行之前就已完成的下载，因此它可以跟在触发该下载的命令之后。使用 [path] 时，文件会被移动到那里；不使用它时，输出位置就是浏览器保存的位置。保存到本地路径仅适用于由 agent-browser 启动的浏览器：通过 --cdp、--auto-connect 或提供方时，保存的文件由远程端点命名，因此 download 和 wait --download [path] 会被拒绝。

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

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

鼠标¶

agent-browser mouse move <x> <y>      # Move mouse instantly
agent-browser mouse move 600 400 --duration 250 --steps 24
agent-browser mouse move 600 400 --human --seed 42
agent-browser mouse down [button]     # Press button
agent-browser mouse up [button]       # Release button
agent-browser mouse wheel <dy> [dx]   # Scroll wheel

滚轮会在当前跟踪的指针位置滚动，该指针初始位于 0,0。失败的滚轮派发会使跟踪指针保持不变。

鼠标坐标和滚轮增量接受有限的十进制值；提供的无效值会被拒绝。对于 mouse wheel，省略的 dy 和 dx 分别默认为 100 和 0，显式的 0 值会被保留。

要在其他位置滚动，请先移动指针：

agent-browser mouse move 600 400
agent-browser mouse wheel 100

将 --human 与 click、drag 或 mouse move 一起使用，可从当前光标位置进行曲线、缓和的移动。对于 mouse move，--duration 设置目标总毫秒数（包括浏览器响应时间），--steps 设置事件数量，--seed 使路径可重现。浏览器响应较慢时仍可能延长所请求的持续时间。

剪贴板¶

agent-browser clipboard read                      # Read text from clipboard
agent-browser clipboard write "Hello, World!"     # Write text to clipboard
agent-browser clipboard copy                      # Copy current selection (Ctrl+C)
agent-browser clipboard paste                     # Paste from clipboard (Ctrl+V)

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

设置¶

agent-browser set viewport <w> <h> [scale]  # Set viewport size (scale for retina, e.g. 2)
agent-browser set device <name>       # Emulate device ("iPhone 14")
agent-browser set geo <lat> <lng>     # Set geolocation
agent-browser set offline [on|off]    # Toggle offline mode
agent-browser set headers <json>      # Extra HTTP headers
agent-browser set credentials <u> <p> # HTTP basic auth for current and future tabs
agent-browser set media [dark|light]  # Emulate color scheme (persists for session)

视口缩放比例和地理位置坐标必须是有限数值。

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

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

Cookies 与存储¶

agent-browser cookies                 # Get all cookies
agent-browser cookies set <name> <val> # Set cookie
agent-browser cookies clear           # Clear cookies

agent-browser storage local           # Get all localStorage
agent-browser storage local <key>     # Get specific key
agent-browser storage local set <k> <v>  # Set value
agent-browser storage local clear     # Clear all

agent-browser storage session         # Same for sessionStorage

读取操作最多接受一个键，设置操作需要一个键和一个值，清除操作不接受操作数。仅提供一个键即可作为单键读取的简写。

Cookie 操作包括 get（默认）、set 和 clear；未知操作会返回错误。Cookie 属性使用 kebab-case 风格的标志，例如 --http-only 和 --same-site。旧版的 --httpOnly 和 --sameSite 拼写仍被接受。设置单个 Cookie 时，未知标志和多余参数会返回错误。

agent-browser cookies set session_id abc123 --http-only --same-site Strict

网络¶

agent-browser network route <url>              # Intercept requests
agent-browser network route <url> --abort      # Block requests
agent-browser network route <url> --body <json>  # Mock response
agent-browser network route <url> --body <json> --allow-origin <origin>  # Mock readable cross-origin
agent-browser network route '*' --abort --resource-type script  # Block scripts only
agent-browser network unroute [url]            # Remove routes
agent-browser network requests                 # View tracked requests
agent-browser network requests --clear         # Clear request log
agent-browser network requests --filter <pat>  # Filter by URL pattern
agent-browser network requests --type xhr,fetch  # Filter by resource type
agent-browser network requests --method POST   # Filter by HTTP method
agent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)
agent-browser network request <requestId>      # View full request/response detail
agent-browser network har start                # Start HAR recording (embeds text response bodies)
agent-browser network har start --content all  # Embed all response bodies (binary as base64)
agent-browser network har start --content none # Metadata only, no bodies
agent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)

如果 HAR 导出失败，录制内容与已捕获的请求仍然可用。请修复目标路径，然后重试 network har stop。

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

标签页与框架¶

agent-browser tab                              # List tabs (each row shows tabId and label)
agent-browser tab new [url]                    # New tab
agent-browser tab new --label docs [url]       # New tab with a user-assigned label
agent-browser tab <t<N>|label>                 # Switch to a tab by id or label
agent-browser tab close [t<N>|label]           # Close a tab (defaults to active)
agent-browser window new                       # Open new browser window
agent-browser frame <sel>                      # Switch to iframe by CSS selector
agent-browser frame @e3                        # Switch to iframe by element ref
agent-browser frame main                       # Back to main frame

稳定的标签页 ID 与标签¶

标签页 ID 是形如 t1、t2、t3 的稳定字符串。它们在会话内不会被重复使用，因此即使其他标签页被打开或关闭，t2 始终指向同一个标签页。t 前缀与 @e1 元素引用约定相对应，且不能与位置整数互换——使用 agent-browser tab 2 会返回一条带教学提示的错误；请改用 t2。

你还可以在创建标签页时指定一个易记的标签（docs、app、admin），并在任何接受 ID 的地方使用该标签：

agent-browser tab new --label docs https://docs.example.com
agent-browser tab docs          # switch to the docs tab
agent-browser snapshot          # populate refs for docs
agent-browser click @e3         # click uses docs's refs
agent-browser tab close docs    # close by label

标签永远不会自动生成，也绝不会在导航时被重写——将标签页命名为 docs 的智能体会一直保留该名称，直到标签页被关闭。标签在会话内是唯一的；使用已有标签创建第二个标签页会报错。

标签必须以字母开头，且只能包含字母、数字、- 或 _，并且不能使用保留的 t<N> 或 T<N> 标签页 ID 形式。被拒绝的标签会保留当前标签页的引用和选定的框架。

通过 tab new 或 click --new-tab 打开的标签页会在其首个文档加载之前继承会话的设置：用户代理、set headers、set credentials、按来源限定的 --headers、初始化脚本、route 规则以及模拟覆盖（颜色方案、时区、语言环境、地理位置、离线）。关闭离线模式或将 headers 设置为 {} 即可为将来的标签页恢复默认设置。

tab list --json 还报告每个标签页的 CDP targetId，并且在任何接受标签页引用的地方都接受目标 ID（tab <targetId>、tab close <targetId>）。与 t<N> ID（它们是每个守护进程的计数器）不同，目标 ID 在守护进程重启后保持稳定。每个会话通过目标 ID 绑定到其活动标签页，并在守护进程重启后返回到该标签页；使用 --pin-tab 时，绑定是严格的，如果关闭了已绑定的标签页，会产生 tab_gone 错误而不是静默回退。JSON 错误包含 code: "tab_gone"、data.targetId，以及可选的经过净化的 data.lastUrl。批量输出在 result 下携带恢复对象。多会话工作流请参阅 CDP 模式。

引用（@e1 等）的作用域是快照运行时处于活动状态的标签页，因此请先切换标签页，再进行快照和交互：

agent-browser tab docs          # switch first
agent-browser snapshot          # refs for docs
agent-browser click @e3         # uses docs's refs

被丢弃标签页的恢复¶

浏览器会丢弃后台标签页以节省内存，从而留下一个没有渲染器可驱动的标签页。切换到被丢弃的标签页会重新激活它，这会重新加载页面并重置其未保存的状态；切换结果会添加 "revived": true，使重新加载可见而不是静默发生。如果标签页的页面被 JavaScript 对话框暂停，则该标签页仍然存活，而不是被丢弃：切换会保持其不变，并添加 "dialogBlocked": true。使用 dialog accept 或 dialog dismiss 处理对话框后，标签页会保留其状态。关闭活动标签页并切换到被丢弃的后继标签页时，也会以相同方式恢复它，并报告 "activeTabRevived": true。

快照增量¶

agent-browser snapshot --delta
agent-browser snapshot --delta --full

snapshot --delta 会按标签页和选项集返回 full、unchanged 或增量更新。URL 变化或大的增量会返回完整状态；--full 会重置基线。将增量的 changes 应用到引用元数据，将 treeChange 应用到之前的树：按换行符拆分，将从零开始的 startLine 处的 deleteCount 行替换为 lines，然后重新拼接。在推进到 revision 之前，将两者都应用到 baseRevision。

Iframe 支持¶

在快照期间会自动检测 Iframe。Iframe 节点会被解析，其内容会内联到快照输出中 iframe 元素的下方。分配给 iframe 内元素的引用会携带帧上下文，因此 click、fill 和其他交互无需手动切换帧即可工作。

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 命令接受元素引用（@e3）、CSS 选择器（"#my-iframe"）或帧名称/URL。

对话框¶

agent-browser dialog accept [text]    # Accept dialog (with optional prompt text)
agent-browser dialog dismiss          # Dismiss dialog
agent-browser dialog status           # Check if a dialog is currently open

默认情况下，alert 和 beforeunload 对话框会自动接受，因此它们永远不会阻塞智能体。confirm 和 prompt 对话框仍需要显式处理。使用 --no-auto-dialog（或 AGENT_BROWSER_NO_AUTO_DIALOG=1）可禁用自动处理。

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

流式传输¶

agent-browser stream enable           # Start runtime WebSocket streaming on an auto-selected port
agent-browser stream enable --port 9223  # Bind a specific localhost port
agent-browser stream status           # Show enabled state, port, browser connection, screencasting
agent-browser stream disable          # Stop runtime streaming and remove the .stream metadata file

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

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

调试¶

agent-browser trace start             # Start trace
agent-browser trace stop [path]       # Stop and save trace
agent-browser profiler start          # Start Chrome DevTools profiling
agent-browser profiler stop [path]    # Stop and save profile (.json)
agent-browser record start <path>     # Start video recording (.webm/.mp4, 30 fps; needs ffmpeg)
agent-browser record start <path> --fps 60  # Record at 60 fps (--fps accepts 1-60)
agent-browser record start <path> --cursor  # Include an animated mouse pointer
agent-browser record start <path> --contact-sheet # Also save a timestamped PNG summary
agent-browser record start <path> --contact-sheet-threshold 0.02 # Tune changed-frame selection
agent-browser record stop             # Stop and save video
agent-browser record restart <path>   # Stop current and start new recording
agent-browser console                 # View console messages
agent-browser console --json          # JSON output with raw CDP args
agent-browser console --clear         # Clear console log
agent-browser errors                  # View page errors
agent-browser errors --clear          # Clear error log
agent-browser highlight <sel>         # Highlight element
agent-browser inspect                 # Open Chrome DevTools for the active page

录制需要 ffmpeg 位于 PATH 中。控制台、错误、对话框、跟踪、高亮显示和 DevTools 工作流请参阅调试。录制要求和 record 工作流请参阅视频录制，性能分析请参阅 Profiler。

认证保险库¶

agent-browser auth save <name> [opts]    # Save auth profile
agent-browser auth login <name>          # Login using saved credentials
agent-browser auth login <name> --no-navigate
                                          # Use active page after origin validation
agent-browser auth login <name> --credential-provider <plugin> [--item <ref>] [--url <url>]
                                          # Resolve credentials from plugin
agent-browser auth login <name> --username-selector <s> --password-selector <s> [--submit-selector <s>]
                                          # Override selectors for one login
agent-browser auth list                  # List saved profiles (names and URLs only)
agent-browser auth show <name>           # Show profile metadata (no passwords)
agent-browser auth delete <name>         # Delete a saved profile
agent-browser plugin add <ref>           # Add a plugin from npm or GitHub
agent-browser plugin list                # List configured plugins
agent-browser plugin show <name>         # Show one configured plugin
agent-browser plugin run <name> <type> --payload <json>
                                          # Run an arbitrary plugin request

保存选项：

--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 会根据匹配控件的布局尺寸、计算后的可见性与透明度，以及禁用/只读状态进行过滤，自定义 CSS 选择器也不例外。如果选中的凭据字段在输入前被替换或转移了焦点，命令将失败且不会提交。

auth login 使用 load 事件导航，然后等待用户名/密码/提交选择器出现后再进行交互。这提高了在单页应用（SPA）登录页面上的可靠性，因为此类页面的字段会在初始页面加载完成后才渲染。

在页面内点击、通过挑战验证、关闭同意提示，或完成其他需要在凭据输入后仍然保持的状态设置之后，请使用 --no-navigate：

agent-browser open https://example.com/
agent-browser click "a[href='/login']"
agent-browser auth login work --no-navigate

该标志仅抑制最初的 auth-login 导航。它要求有一个当前处于活动状态的顶层 HTTP(S) 页面，并将该页面与有效凭据 URL 按协议（scheme）、主机和有效端口进行比较。路径、查询参数和片段可以不同。等待、填写、点击提交以及任何由提交触发的导航均不受影响。命令级别的 --url 会覆盖配置文件或提供者的 URL 元数据，并充当预期来源（origin）约束，而非导航目标。

插件登录选项：

--credential-provider <plugin>：从已配置的插件解析凭据
--item <ref>：提供者特定的保管库（vault）条目引用
--url <url>：登录 URL 覆盖
--no-navigate：在针对有效凭据来源进行验证后，使用当前处于活动状态的顶层页面
--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 启动前追加本地启动参数、扩展或初始化脚本
command.run：通过 agent-browser plugin run 运行任意命名空间的请求

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

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 auth login my-app --credential-provider vault --item "My App" --no-navigate --url https://identity.example.com/login
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 来批准或拒绝该操作。

agent-browser confirm <confirmation-id>  # Approve a pending action
agent-browser deny <confirmation-id>     # Deny a pending action

待处理的确认请求会在 60 秒后自动拒绝。

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

状态管理¶

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

会话¶

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

会话名称仅接受 Unicode 字母和数字、连字符以及下划线。例如，café-東京_7 是有效的，而 my session 因包含空格而被拒绝。

Chrome 配置文件¶

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

仪表盘¶

agent-browser dashboard [start]       # Start the dashboard server (default port: 4848)
agent-browser dashboard start --port <n>  # Start on a specific port
agent-browser dashboard start --allowed-origins <origins> # Allow exact HTTPS reverse-proxied browser origins
agent-browser dashboard stop          # Stop the dashboard server

默认情况下，回环（loopback）仪表盘来源无需访问令牌即可接受。对于反向代理或转发 URL，请通过 --allowed-origins 传入其确切的浏览器来源，或设置 AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS。每个配置的来源都必须是有效的确切 HTTPS 来源。端口必须是 1 到 65535 之间的整数。未知选项、缺失值、无效端口以及格式错误的来源都会导致启动失败。该命令仅对外部来源打印私有的令牌化访问 URL；请打开匹配的 URL 一次以建立浏览器会话，并且不要分享它。对于本地访问，请打开常规的 http://localhost:<port> URL。浏览器会停留在仪表盘来源上；每个会话的标签页、状态和流流量都在内部代理，因此无需暴露会话端口。在更改端口或允许的来源之前，请先停止正在运行的仪表盘。

Doctor¶

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

agent-browser doctor                     # Full diagnosis (env, Chrome, daemons, config, providers, network, launch test)
agent-browser doctor --offline --quick   # Local-only, fastest
agent-browser doctor --fix               # Also run destructive repairs (reinstall Chrome, purge old state, ...)
agent-browser doctor --webgpu            # Also run a live WebGPU render probe (see the WebGPU page)
agent-browser doctor --json              # Structured JSON output for agents

如果所有检查均通过（有警告也无妨），退出码为 0；任一检查失败则为 1。完整检查目录请参见安装页面。

Chat¶

通过 AI 使用自然语言控制浏览器。chat 命令将指令转换为 agent-browser 命令并执行，同时流式输出 AI 响应。需要设置 AI_GATEWAY_API_KEY。

agent-browser chat "open google.com and search for cats"     # Single-shot instruction
agent-browser chat                                           # Interactive REPL (type quit to exit)
echo "summarize this page" | agent-browser chat              # Piped input
agent-browser -q chat "summarize this page"                  # Quiet: text only, no tool calls shown
agent-browser -v chat "fill in the login form"               # Verbose: show commands and their output
agent-browser --model openai/gpt-4o chat "take a screenshot" # Override the default AI model
agent-browser --json chat "open example.com"                 # Structured JSON output

Chat 专属选项：

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

agent-browser back                    # Go back
agent-browser forward                 # Go forward
agent-browser reload                  # Reload page
agent-browser pushstate <url>         # SPA client-side nav; auto-detects window.next.router.push,
                                      # falls back to history.pushState + popstate

某些流程需要在首次导航之前配置路由、Cookie 或初始化脚本（例如 SSR 调试、受保护来源的认证等）。不带 URL 的 open 会启动浏览器但停留在 about:blank，从而可以在导航前预先配置状态。batch 可以将其合并为一次 CLI 调用：

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 适用于任何网站。

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 tree 会将其打印出来。如果响应中只包含标题，则说明未收集到组件树。请确认页面使用 React 且 React root 已挂载。

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

完整的命令详情和示例请参见 React & Web Vitals。

无障碍审计¶

对当前页面运行内置的 axe-core 审计，或先导航到某个 URL。内置引擎无需 CDN 请求即可工作，并且可以在严格的页面 CSP 下运行。它会在页面的 frame 树中运行私有部分审计，并无需页面消息传递即可合并序列化结果，因此页面提供的 window.axe 值保持不变，iframe 违规也会保留其 frame 选择器路径。无障碍审计需要 CDP 浏览器，不适用于 Safari 或 iOS WebDriver 会话。

agent-browser a11y                                 # Audit the current page
agent-browser a11y https://example.com             # Navigate, then audit
agent-browser a11y --tags wcag2a,wcag2aa           # Filter by axe rule tags
agent-browser a11y --selector "#main"              # Scope to a subtree
agent-browser a11y https://example.com --json      # Structured results

默认输出列出违规和不完整检查，包括影响级别、规则 ID、修复指南以及失败节点路径。JSON 输出保留 axe 的 target 选择器路径数组，包括 shadow DOM 边界的嵌套数组和 frame 边界的多个条目。

初始化脚本¶

agent-browser --init-script <path> open <url>  # Register before first navigation (repeatable)
agent-browser removeinitscript <identifier>

启动时脚本、脚本移除、内置 React DevTools 和扩展请参见初始化脚本与扩展。

全局选项¶

--session <name>         # Isolated browser session
--restore [name]         # Auto-save/restore session state, defaults to --session
--restore-save <policy>  # Restore save policy: auto, always, never
--namespace <name>       # Isolate daemon sockets and restore-state directories
--profile <path>         # Persistent browser profile directory
--state <path>           # Load storage state from JSON file
--headers <json>         # HTTP headers scoped to URL's origin
--executable-path <path> # Custom browser executable
--extension <path>       # Load browser extension (repeatable)
--init-script <path>     # Register a page init script before first navigation (repeatable)
--enable <feature>       # Built-in init scripts: react-devtools (repeatable or comma-list)
--args <args>            # Browser launch args (commas inside a value are kept)
--user-agent <ua>        # Custom User-Agent string
--proxy <url>            # Proxy server URL
--proxy-bypass <hosts>   # Hosts to bypass proxy
--ignore-https-errors    # Ignore HTTPS certificate errors
--ca-cert <path>         # Trust a CA for CLI requests, and for local Chromium on Linux
--no-ca-cert             # Clear CA trust retained by the running session
--use-system-ca          # Use the OS trust store for CLI requests (read, install, upgrade, doctor)
--allow-file-access      # Allow file:// URLs to access local files (Chromium only)
--hide-scrollbars <bool> # Hide native scrollbars in headless Chromium screenshots
-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)
--webgpu                 # Enable WebGPU (software Vulkan on Linux, no GPU needed)
--no-webmcp              # Disable default experimental WebMCP Chrome features (or AGENT_BROWSER_NO_WEBMCP env)
--cdp <port|url>         # Connect via CDP; root WebSocket query slash is optional
--cdp-headers <json>     # Headers for --cdp discovery and WebSocket handshake (or AGENT_BROWSER_CDP_HEADERS env)
--auto-connect           # Auto-discover and connect to running Chrome
--color-scheme <scheme>  # Color scheme: dark, light, no-preference
--download-path <path>   # Default download directory
--content-boundaries     # Wrap page output in boundary markers for LLM safety
--max-output <chars>     # Truncate page output to N characters
--allowed-domains <list> # Allowed domains; rejects restore/state replay, profile/session startup args, and direct-page providers
--action-policy <path>   # Path to action policy JSON file
--confirm-actions <list> # Action categories requiring confirmation
--confirm-interactive    # Interactive confirmation prompts (auto-denies if stdin is not a TTY)
--engine <name>          # Browser engine: chrome (default), lightpanda, obscura (experimental)
--input-mode <mode>      # Pointer movement: instant (default), smooth, human
--idle-timeout <time>    # Auto-shutdown daemon after inactivity (default: 1h; 0 disables)
--no-auto-dialog         # Disable auto-accept for alert and beforeunload dialogs
--model <name>           # AI model for chat (or AI_GATEWAY_MODEL env)
-v, --verbose            # Show tool commands and their raw output (chat)
-q, --quiet              # Show only AI text responses (chat)
--config <path>          # Use a custom config file
--debug                  # Debug output

参见配置了解配置文件和环境变量。参见代理了解代理服务器、绕过和凭据设置。

批量执行¶

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

# Argument mode: each quoted argument is a full command
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"

# With --bail to stop on first error
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"

# Stdin mode: pipe commands as JSON
echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

echo '[["fill", "#password", "secret"]]' | agent-browser batch --json --omit-command

选项	描述
`--bail`	在第一个错误时停止（默认：继续执行所有命令）
`--json`	将结果输出为 JSON 数组
`--omit-command`	与 `--json` 一起使用时，将每个 `command` 数组替换为稳定的从零开始的 `index` 字段

使用 --json --omit-command 时，无论成功、失败还是使用 --bail，行都会使用稳定的从零开始的 index 字段；默认的 JSON 输出会保留 command 字段。这只是移除命令数组，并不会让输出对机密信息安全。错误和响应数据保持不变：type 会回显输入的文本，get value/eval 可能返回输入值。MCP agent_browser_batch 工具接受 omitCommand: true。

MCP 服务器¶

agent-browser mcp
agent-browser mcp --tools all
agent-browser mcp --tools core,network,react
agent-browser mcp call agent_browser_open '{"url":"https://example.com"}'
agent-browser mcp --config /path/to/trusted-config.json
agent-browser mcp call agent_browser_open '{"url":"https://example.com"}' --config /path/to/trusted-config.json
echo '{"selector":"@e2"}' | agent-browser mcp call agent_browser_click -

通过 stdio 启动模型上下文协议（Model Context Protocol）服务器。MCP 客户端会以子进程方式启动此命令，并在 stdin 和 stdout 上交换换行符分隔的 JSON-RPC 消息。服务器默认使用 MCP 协议 2025-11-25，并在初始化期间接受受支持的旧版客户端协议版本。如果工具调用包含了其 schema 未声明的参数，则会以 invalid-params 错误失败，该错误会指出未知键并列出工具自身的参数。

mcp call 在没有 stdio 会话的情况下运行一个 MCP 工具，并将其 tools/call 结果以 JSON 形式打印出来，_meta.agentBrowserVersion 中带有 agent-browser 版本。将工具参数作为 JSON 对象传入，或使用 - 从 stdin 读取。除非 --tools 将调用限制为特定配置文件，否则所有工具均可用。退出码在成功时为 0，工具报告错误时为 1，未知工具或参数无效时为 2。适用于无法在工具调用之间保持 stdio 会话的运行时，例如无服务器智能体。类似 AGENT_BROWSER_ALLOWED_DOMAINS 的访问设置来自环境，与服务器一样。

对于运行 CLI 的工具调用，structuredContent.response 包含解析后的 CLI JSON。stdout 仅在输出无法解析为 JSON 时包含；exitCode 和 stderr 始终包含。

在 Vercel Sandbox 中，startAgentBrowserMcp 通过沙箱命令的 stdin 运行服务器。参见 Next.js + Vercel。

默认工具配置文件是 core，它保持 MCP 上下文精简，适合日常浏览器自动化。使用 --tools all 以获得与 CLI 完全对等的完整类型化接口，或使用逗号组合配置文件，例如 --tools core,network,react。

配置文件：

core - 默认。导航、快照、交互、等待、读取、截图、JavaScript 求值、关闭、标签页基础操作和配置文件发现
network - 网络路由、请求检查、HAR、标头、凭据、离线
state - Cookie、存储、认证、已保存状态、会话、配置文件、技能
debug - 控制台/错误、追踪、性能分析、录制、无障碍审计、剪贴板、插件、doctor、仪表盘、安装、升级、聊天、diff、批处理、确认/拒绝
tabs - 后退/前进/重新加载、标签页、窗口、框架、对话框
react - React 树/检查/渲染/挂起、vitals、pushstate
mobile - 视口/设备/地理定位/媒体、触摸、滑动、鼠标、键盘
all - 所有 MCP 工具，包括与 CLI 完全对等的完整类型化接口

示例 MCP 客户端配置：

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

使用 --tools all 时，服务器会公开覆盖整个 CLI 命令体系的类型化工具，包括导航、快照、输入、等待、截图/PDF、get/is/find、鼠标、网络、存储、Cookie、标签页、窗口、框架、对话框、追踪、录制、无障碍审计、剪贴板、认证、状态、iOS、diff、React、vitals、会话、技能、插件、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，因此 MCP 客户端可以显示有意义的审批提示，而不是原始命令数组。工具发现是分页的，并包含只读/open-world 注解，以便现代 MCP 客户端可以增量加载大型类型化表面。

每个工具还接受共享参数 session、restore、allowedDomains、extraArgs、timeoutMs、namespace、restoreSave、restoreCheckUrl、restoreCheckText、restoreCheckFn、caCert、useSystemCa、clearCaCert 和 idleTimeout。工具的 schema 只列出通常对其重要的参数：每个工具都有 session，open 和 tab_new 上有 restore，open、tab_new 和 read 上有 allowedDomains 和 extraArgs，而 timeoutMs 则出现在导航、等待或运行脚本的工具上。服务器的 initialize 指令会描述所有这些参数。allowedDomains 映射到 --allowed-domains，会激活相同的 WebRTC 隔离和启动模式限制，并且当服务器已设置允许的域名时会被拒绝。idleTimeout 映射到 --idle-timeout，接受 30s、5m、1h 或原始毫秒值等值，并接受 0 来禁用空闲关闭。extraArgs 携带每命令选项以及显示或模拟标志，如 --engine；它不能设置 --config 或改变网络、文件、策略或主机访问的全局标志。请在 MCP 服务器的环境或选定配置中设置主机级选项。

默认情况下，工具调用使用与 CLI 相同的配置发现逻辑和环境变量。在工具参数中使用 session，或设置 AGENT_BROWSER_SESSION，以隔离浏览器状态。

将 --config <trusted-path> 传给 agent-browser mcp 或 agent-browser mcp call，以选择单个受信任的配置文件。MCP 工具子进程仅加载该文件，取代默认的用户/项目配置发现。将任何必需的安全策略放入该文件中。环境变量和每个工具可接受的 CLI 参数保持其正常的优先级。

命令串联¶

在单次 shell 调用中使用 && 串联命令。浏览器通过后台守护进程保持运行，因此串联可自然工作，并且比单独调用更高效：

agent-browser open example.com && agent-browser wait --load domcontentloaded && 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 load && agent-browser screenshot page.png

当不需要读取中间输出时，使用 &&。当你需要先解析输出时（例如先运行 snapshot 发现 refs，再与这些 refs 交互），请单独运行命令。

本地文件¶

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

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

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser

命令

核心¶