vercel-labs--agent-browser/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

agent-browser

面向 AI 智能体的浏览器自动化 CLI。原生 Rust CLI，运行快速。

安装

全局安装（推荐）

安装原生 Rust 二进制文件：

npm install -g agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

项目安装（本地依赖）

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

npm install agent-browser
agent-browser install

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

Homebrew（macOS）

brew install agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

Cargo（Rust）

cargo install agent-browser
agent-browser install  # Download Chrome from Chrome for Testing (first time only)

从源码构建

需要 Node.js 24+、pnpm 11+ 和 Rust。

git clone https://github.com/vercel-labs/agent-browser
cd agent-browser
pnpm install
pnpm build
pnpm build:native   # Requires Rust (https://rustup.rs)
pnpm link --global  # Makes agent-browser available globally
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 安装会被自动检测。守护进程（daemon）无需 Playwright 或 Node.js。
• Node.js 24+ 和 pnpm 11+ — 仅在从源码构建时需要。
• Rust — 仅在从源码构建时需要（参见上文「从源码构建」）。

快速入门

agent-browser open example.com
agent-browser snapshot                    # Get accessibility tree with refs
agent-browser click @e2                   # Click by ref from snapshot
agent-browser fill @e3 "test@example.com" # Fill by ref
agent-browser get text @e1                # Get text by ref
agent-browser screenshot page.png
agent-browser close

当其他元素遮挡目标的点击位置时（例如同意横幅或模态框），点击会提前失败。请先关闭或与报告中的遮挡元素交互，然后重新获取快照，再重试原始 ref。

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

传统选择器（同样支持）

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

命令

核心命令

agent-browser open                    # Launch browser (no navigation); stays on about:blank
agent-browser open <url>              # Launch + navigate to URL (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 element
agent-browser focus <sel>             # Focus element
agent-browser type <sel> <text>       # Type into element
agent-browser fill <sel> <text>       # Clear and fill
agent-browser press <key>             # Press key (Enter, Tab, Control+a) (alias: key)
agent-browser keyboard type <text>    # Type with real keystrokes (no selector, current focus)
agent-browser keyboard inserttext <text>  # Insert text without key events (no selector)
agent-browser keydown <key>           # Hold key down
agent-browser keyup <key>             # Release key
agent-browser hover <sel>             # Hover element
agent-browser select <sel> <val>      # Select dropdown option
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 (alias: scrollinto)
agent-browser drag <src> <tgt>        # Drag and drop
agent-browser upload <sel> <files>    # Upload files
agent-browser screenshot [path]       # Take screenshot (--full for full page, saves to a temporary directory if no path)
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser screenshot --screenshot-dir ./shots    # Save to custom directory
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf <path>              # Save as PDF
agent-browser snapshot                # Accessibility tree with refs (best for AI)
agent-browser eval <js>               # Run JavaScript (-b for base64, --stdin for piped input)
agent-browser connect <port>          # Connect to browser via CDP
agent-browser stream enable [--port <port>]  # Start runtime WebSocket streaming
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 chat "<instruction>"    # AI chat: natural language browser control (single-shot)
agent-browser chat                    # AI chat: interactive REPL mode

获取信息

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 (for DevTools, debugging)
agent-browser get count <sel>         # Count matching elements
agent-browser get box <sel>           # Get bounding box
agent-browser get styles <sel>        # Get computed styles

读取对智能体友好的文本

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 等全局保护措施同样适用于读取请求与输出。

检查状态（Check State）

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

查找元素（语义定位器 Semantic Locators）

agent-browser find role <role> <action> [value]       # By ARIA role
agent-browser find text <text> <action>               # By text content
agent-browser find label <label> <action> [value]     # By label
agent-browser find placeholder <ph> <action> [value]  # By placeholder
agent-browser find alt <text> <action>                # By alt text
agent-browser find title <text> <action>              # By title attr
agent-browser find testid <id> <action> [value]       # By data-testid
agent-browser find first <sel> <action> [value]       # First match
agent-browser find last <sel> <action> [value]        # Last match
agent-browser find nth <n> <sel> <action> [value]     # Nth match

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

选项： --name <name>（按可访问名称 accessible name 筛选角色 role）、--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

等待（Wait）

agent-browser wait <selector>         # Wait for element to be visible
agent-browser wait <ms>               # Wait for time (milliseconds)
agent-browser wait --text "Welcome"   # Wait for text to appear (substring match)
agent-browser wait --url "**/dash"    # Wait for URL pattern
agent-browser wait --load networkidle # Wait for load state
agent-browser wait --fn "window.ready === true"  # Wait for JS condition

# Wait for text/element to disappear
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"
agent-browser wait "#spinner" --state hidden

加载状态： load、domcontentloaded、networkidle

批量执行（Batch Execution）

在单次调用中执行多条命令。命令可作为带引号的参数传入，或通过 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

剪贴板（Clipboard）

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)

鼠标控制（Mouse Control）

agent-browser mouse move <x> <y>      # Move mouse
agent-browser mouse down [button]     # Press button (left/right/middle)
agent-browser mouse up [button]       # Release button
agent-browser mouse wheel <dy> [dx]   # Scroll wheel

浏览器设置（Browser Settings）

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
agent-browser set media [dark|light]  # Emulate color scheme

Cookie 与存储（Cookies & Storage）

agent-browser cookies                 # Get all cookies
agent-browser cookies set <name> <val> # Set cookie
agent-browser cookies set --curl <file> # Import cookies from a Copy-as-cURL dump,
                                        # JSON array, or bare Cookie header (auto-detected)
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

网络（Network）

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 '*' --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 --filter api    # Filter requests
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
agent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)

标签页与窗口（Tabs & Windows）

agent-browser tab                              # List tabs (shows `tabId` and optional label)
agent-browser tab new [url]                    # New tab (optionally with URL)
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                       # New window

标签页 id 是形如 t1、t2、t3 的稳定字符串。在同一会话内它们不会被复用，因此即使其他标签页被打开或关闭，脚本和 agent 仍可继续引用同一标签页。像 tab 2 这样的位置整数不被接受；t 前缀用于将句柄与索引区分开，并与元素引用所使用的 @e1 约定保持一致。

你也可以指定一个易记的标签（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

框架（Frames）

agent-browser frame <sel>             # Switch to iframe
agent-browser frame main              # Back to main frame

对话框（Dialogs）

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

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

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

差异对比（Diff）

agent-browser diff snapshot                              # Compare current vs last snapshot
agent-browser diff snapshot --baseline before.txt        # Compare current vs saved snapshot file
agent-browser diff snapshot --selector "#main" --compact # Scoped snapshot diff
agent-browser diff screenshot --baseline before.png      # Visual pixel diff against baseline
agent-browser diff screenshot --baseline b.png -o d.png  # Save diff image to custom path
agent-browser diff screenshot --baseline b.png -t 0.2    # Adjust color threshold (0-1)
agent-browser diff url https://v1.com https://v2.com     # Compare two URLs (snapshot diff)
agent-browser diff url https://v1.com https://v2.com --screenshot  # Also visual diff
agent-browser diff url https://v1.com https://v2.com --wait-until networkidle  # Custom wait strategy
agent-browser diff url https://v1.com https://v2.com --selector "#main"  # Scope to element

Debug

agent-browser trace start             # Start recording 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 console                 # View console messages (log, error, warn, info)
agent-browser console --json          # JSON output with raw CDP args for programmatic access
agent-browser console --clear         # Clear console
agent-browser errors                  # View page errors (uncaught JavaScript exceptions)
agent-browser errors --clear          # Clear errors
agent-browser highlight <sel>         # Highlight element
agent-browser inspect                 # Open Chrome DevTools for the active page
agent-browser state save <path>       # Save auth state
agent-browser state load <path>       # Load auth state
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
agent-browser state clear --all       # Clear all saved states
agent-browser state clean --older-than <days>  # Delete old states

Navigation

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

导航前准备

部分流程（SSR 调试、受保护来源的 auth cookies、init scripts）需要在首次导航之前完成状态设置。使用不带 URL 的 open 启动浏览器，然后配置 cookies / routes / init scripts，再进行导航。batch 可在一次 CLI 调用中完成上述全部操作：

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

若不使用 batch，相同流程需要三条命令，但都会复用同一 daemon（速度快，但不是一轮完成）。

React / Web Vitals

agent-browser 内置一流的 React 内省（introspection）和通用的 Web Vitals 指标。React 命令需要在启动时安装 React DevTools hook；Web 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>              # props, hooks, state, source
agent-browser react renders start                  # Begin fiber render recording
agent-browser react renders stop [--json]          # Stop and print profile (--json for raw data)
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 summary

每个 react ... 子命令都要求启动时传入 --enable react-devtools（React DevTools installHook.js 已嵌入二进制文件）。未传入时，命令会报错：`React DevTools hook not installed

• relaunch with --enable react-devtools`。

适用于任意 React 应用 — Next.js、Remix、Vite+React、CRA、TanStack Start、React Native Web 等。vitals 和 pushstate 与框架无关。vitals 默认打印摘要；传入 --json 可获取完整的结构化 payload。

Init scripts

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

Setup

agent-browser install                 # Download Chrome from Chrome for Testing (Google's official automation channel)
agent-browser install --with-deps     # Also install system deps (Linux)
agent-browser upgrade                 # Upgrade agent-browser to the latest version
agent-browser doctor                  # Diagnose the install and auto-clean stale daemon files
agent-browser doctor --fix            # Also run destructive repairs (reinstall Chrome, purge old state, ...)
agent-browser doctor --offline --quick  # Skip network probes and the live launch test
agent-browser mcp                     # Start an MCP stdio server

doctor 会检查你的环境、Chrome 安装、daemon 状态、配置文件、加密密钥、providers、网络可达性，并运行一次实时的无头浏览器启动测试。过期的 socket/pid sidecar 文件会自动清理。输出也可通过 --json 供 agents 使用。

Skills

agent-browser skills                  # List available skills
agent-browser skills list             # Same as above
agent-browser skills get <name>       # Output a skill's full content
agent-browser skills get <name> --full  # Include references and templates
agent-browser skills get --all        # Output every skill
agent-browser skills path [name]      # Print skill directory path

提供与已安装 CLI 版本始终一致的捆绑 skill 内容。AI agents 通过此方式获取最新指令，而不是依赖缓存副本。设置 AGENT_BROWSER_SKILLS_DIR 可覆盖 skills 目录路径。

MCP Server

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

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

默认 tools profile 为 core，可保持 MCP 上下文精简，适用于日常浏览器自动化。使用 --tools all 可获取完整的 typed CLI 对等能力，或用逗号组合多个 profile，例如 --tools core,network,react。

Profiles：

• core — 默认。导航、快照、交互、等待、读取、截图、JavaScript eval、close、标签页基础操作，以及 profile 发现
• network — 网络 routes、请求检查、HAR、headers、credentials、offline
• state — Cookies、storage、auth、saved state、sessions、profiles、skills
• debug — Console/errors、tracing、profiling、recording、clipboard、plugins、doctor、dashboard、install、upgrade、chat、diff、batch、confirm/deny
• tabs — 后退/前进/刷新、tabs、windows、frames、dialogs
• react — React tree/inspect/renders/suspense、vitals、pushstate
• mobile — Viewport/device/geolocation/media、touch、swipe、mouse、keyboard
• all — 全部 MCP tool，包括完整的 typed CLI 对等能力

常用 tools 包括：

• 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

每个 tool 都有类型化字段，例如 url、selector、text、key 和 session，因此 MCP 客户端会显示有意义的审批提示，而不是原始命令数组。每个 tool 也接受 extraArgs，用于高级 CLI flags 和精确的 CLI 对等。Tool 发现支持分页，并包含只读/open-world 注解，以便现代 MCP 客户端可增量加载庞大的 typed 能力面。

MCP 客户端配置示例：

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

完整对等 MCP 客户端配置：

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

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

身份验证

agent-browser 提供多种方式来持久化登录会话，这样你就不必在每次运行时都重新进行身份验证。

快速概览

方式	适用场景	标志 / 环境变量
Chrome profile reuse	零配置即可复用你现有的 Chrome 登录状态（cookie、会话）	--profile <name> / AGENT_BROWSER_PROFILE
Persistent profile	在重启后保留完整浏览器状态（cookie、IndexedDB、service worker、缓存）	--profile <path> / AGENT_BROWSER_PROFILE
Session persistence	通过稳定的会话键自动保存/恢复 cookie 与 localStorage	--session <id> --restore / AGENT_BROWSER_RESTORE
Import from your browser	从你已登录的 Chrome 会话中获取身份验证信息	--auto-connect + state save
State file	启动时加载先前保存的状态 JSON	--state <path> / AGENT_BROWSER_STATE
Auth vault	在本地存储凭据（加密），按名称登录	auth save / auth login

从浏览器导入身份验证信息

如果你已在 Chrome 中登录某个网站，可以获取该身份验证状态并重复使用：

# 1. Launch Chrome with remote debugging enabled
#    macOS:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
#    Or use --auto-connect to discover an already-running Chrome

# 2. Connect and save the authenticated state
agent-browser --auto-connect state save ./my-auth.json

# 3. Use the saved auth in future sessions
agent-browser --state ./my-auth.json open https://app.example.com/dashboard

# 4. Or use --restore for automatic persistence
SESSION="$(agent-browser session id --scope worktree --prefix myapp)"
agent-browser --session "$SESSION" --restore --state ./my-auth.json open https://app.example.com/dashboard
# From now on, --session "$SESSION" --restore auto-saves/restores this state

安全说明：

• --remote-debugging-port 会在 localhost 上暴露完整的浏览器控制能力。任何本地进程都可以连接。仅在受信任的机器上使用，用完后关闭 Chrome。
• 状态文件以明文形式包含会话令牌。请将它们加入 .gitignore，并在不再需要时删除。若要对静态存储进行加密，请设置 AGENT_BROWSER_ENCRYPTION_KEY（参见状态加密）。

有关登录流程、OAuth、2FA、基于 cookie 的身份验证以及 auth vault 的完整说明，请参阅 Authentication 文档。

会话

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

# Different sessions
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# Or via environment variable
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"

# List active sessions
agent-browser session list
# Output:
# Active sessions:
# -> default
#    agent1

# Show current session
agent-browser session

# Generate a stable worktree-scoped session id
agent-browser session id --scope worktree --prefix next-dev-loop

# Inspect daemon, launch, and restore status
agent-browser session info --json

每个会话都拥有独立的：

• 浏览器实例
• Cookie 与存储
• 导航历史
• 身份验证状态

复用 Chrome 配置文件

使用现有登录状态的最快方式：向 --profile 传入 Chrome 配置文件名称：

# List available Chrome profiles
agent-browser profiles

# Reuse your default Chrome profile's login state
agent-browser --profile Default open https://gmail.com

# Use a named profile (by display name or directory name)
agent-browser --profile "Work" open https://app.example.com

# Or via environment variable
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com

这会将你的 Chrome 配置文件复制到临时目录（只读快照，不会修改原始配置文件），因此浏览器启动时会带上你现有的 cookie 和会话。

注意： 在 Windows 上，如果 Chrome 正在运行，使用 --profile <name> 前请先关闭 Chrome，因为部分配置文件可能被锁定。

持久化配置文件

若要在浏览器重启后仍保留状态，请向 --profile 传入持久化自定义配置文件目录的路径：

# Use a persistent profile directory
agent-browser --profile ~/.myapp-profile open myapp.com

# Login once, then reuse the authenticated session
agent-browser --profile ~/.myapp-profile open myapp.com/dashboard

# Or via environment variable
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com

配置文件目录会存储：

• Cookie 与 localStorage
• IndexedDB 数据
• Service Worker
• 浏览器缓存
• 登录会话

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

会话持久化

将 --restore 与稳定的 --session 配合使用，可在浏览器重启后自动保存并恢复 cookie 与 localStorage：

# Generate a stable id for this worktree and auto-save/load state
SESSION="$(agent-browser session id --scope worktree --prefix twitter)"
agent-browser --session "$SESSION" --restore open twitter.com

# Login once, then state persists automatically
# State files stored in ~/.agent-browser/sessions/

# Optional: validate restored state before auto-saving again
agent-browser --session "$SESSION" --restore --restore-check-text Dashboard open twitter.com

浏览器关闭时会保存状态（显式 close、空闲超时或守护进程关闭），在浏览器运行期间也会定期保存，因此你手动关闭的浏览器窗口仍会留下最近的保存记录。定期自动保存会等待命令执行完毕，然后最多每 AGENT_BROWSER_AUTOSAVE_INTERVAL_MS 保存一次（默认 30000；设为 0 则仅在关闭时保存）。空闲会话仍按相同间隔保存，因此页面自行产生的变更（令牌刷新、后台请求）也会被捕获。它会遵循 --restore-save 策略。

状态加密

使用 AES-256-GCM 对静态存储的会话数据进行加密：

# Generate key: openssl rand -hex 32
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>

# State files are now encrypted automatically
agent-browser --session secure --restore open example.com

变量	说明
AGENT_BROWSER_RESTORE	自动保存/加载状态持久化名称
AGENT_BROWSER_RESTORE_SAVE	恢复保存策略：auto、always 或 never
AGENT_BROWSER_AUTOSAVE_INTERVAL_MS	定期自动保存之间的最小毫秒数（默认：30000，0 表示禁用）
AGENT_BROWSER_NAMESPACE	守护进程套接字与恢复状态的命名空间
AGENT_BROWSER_SESSION_NAME	旧版自动保存/加载状态持久化名称
AGENT_BROWSER_ENCRYPTION_KEY	用于 AES-256-GCM 加密的 64 字符十六进制密钥
AGENT_BROWSER_STATE_EXPIRE_DAYS	自动删除超过 N 天的状态（默认：30）

安全

agent-browser 包含用于安全部署 AI agent 的安全功能。所有功能均为可选启用，在你显式启用某项功能之前，现有工作流不受影响：

• Authentication Vault（身份验证保险库）：在本地存储凭据（始终加密），按名称引用。LLM 永远不会看到密码。auth login 使用 load 导航，然后等待登录表单选择器出现（适配 SPA，超时遵循默认操作超时）。若未设置 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
• Plugin System（插件系统）：通过外部可执行插件扩展 agent-browser。插件通过 agent-browser.plugin.v1 stdio JSON 协议在进程外运行，并声明 credential.read、browser.provider、launch.mutate 或 command.run 等能力。
• Content Boundary Markers（内容边界标记）：用分隔符包裹页面输出，使 LLM 能区分工具输出与不受信任的内容：--content-boundaries
• Domain Allowlist（域名允许列表）：将导航限制在受信任域名（通配符如 *.example.com 也会匹配裸域名）：--allowed-domains "example.com,*.example.com"。对非允许域名的子资源请求（脚本、图片、fetch）以及 WebSocket/EventSource 连接也会被阻止。请包含目标页面所依赖的任何 CDN 域名（例如 *.cdn.example.com）。
• Action Policy（操作策略）：通过静态策略文件管控破坏性操作：--action-policy ./policy.json
• Action Confirmation（操作确认）：对敏感操作类别要求显式批准：--confirm-actions eval,download
• Output Length Limits（输出长度限制）：防止上下文泛滥：--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	启用交互式确认提示
AGENT_BROWSER_PLUGINS	JSON 插件注册表覆盖

详见安全文档 了解详情。

插件系统

插件允许第三方工具集成，而无需成为 agent-browser 的内置依赖。从 npm 或 GitHub 添加插件：

agent-browser plugin add agent-browser-plugin-captcha
agent-browser plugin add @company/agent-browser-plugin-vault --name vault
agent-browser plugin add org/agent-browser-plugin-cloud-browser

引用按形态解析：name 使用 npm，@scope/name 使用 npm，owner/repo 使用 GitHub。plugin add 默认写入 ./agent-browser.json；对 ~/.agent-browser/config.json 使用 --global。

插件包应支持 plugin.manifest，以便 plugin add 能自动发现其名称和功能。若插件不支持清单（manifest），在添加时传入 --capability <name>。

也可以在 agent-browser.json 中手动配置插件：

{
  "plugins": [
    {
      "name": "vault",
      "command": "agent-browser-plugin-vault",
      "capabilities": ["credential.read"]
    },
    {
      "name": "cloud-browser",
      "command": "agent-browser-plugin-cloud-browser",
      "capabilities": ["browser.provider"]
    },
    {
      "name": "stealth",
      "command": "agent-browser-plugin-stealth",
      "capabilities": ["launch.mutate"]
    },
    {
      "name": "captcha",
      "command": "agent-browser-plugin-captcha",
      "capabilities": ["command.run", "captcha.solve"]
    }
  ]
}

检查已配置的插件：

agent-browser plugin list
agent-browser plugin show vault

使用凭据提供方（credential provider）插件进行单次登录：

agent-browser auth login my-app --credential-provider vault --item "My App"
agent-browser auth login my-app --credential-provider vault --item "My App" --url https://app.example.com/login --username-selector "#email" --password-selector "#password" --submit-selector "button[type=submit]"

使用浏览器提供方（browser provider）插件：

agent-browser --provider cloud-browser open https://example.com

使用启动变更（launch mutator）插件实现隐身或本地启动自定义。浏览器启动前，插件可追加 Chrome 参数、扩展和初始化脚本：

agent-browser open https://example.com

对 CAPTCHA 求解器等特定领域工具，使用通用插件命令：

agent-browser plugin run captcha captcha.solve --payload '{"siteKey":"...","url":"https://example.com"}'

协议请求始终包含 protocol、type、capability 和 request。凭据插件接收 credential.resolve，浏览器提供方接收 browser.launch，启动变更器接收 launch.mutate，通用命令接收所提供的请求类型。plugin run 用于 command.run 及自定义能力；核心能力和协议请求类型使用其专用命令路径。agent-browser 将浏览器自动化、脱敏敏感输出和策略强制执行保留在核心中。

按能力操作限制插件访问：

agent-browser --confirm-actions plugin:vault:credential.read auth login my-app --credential-provider vault --item "My App"
agent-browser --confirm-actions plugin:cloud-browser:browser.provider --provider cloud-browser open https://example.com
agent-browser --confirm-actions plugin:stealth:launch.mutate open https://example.com

不要在插件命令参数中放置保管库（vault）令牌或密码。请使用保管库供应商自身的登录/会话机制，或在 agent-browser 配置之外的环境变量中配置。

快照选项

snapshot 命令支持过滤以减小输出体积：

agent-browser snapshot                    # Full accessibility tree
agent-browser snapshot -i                 # Interactive elements only (buttons, inputs, links)
agent-browser snapshot -i --urls          # Interactive elements with link URLs
agent-browser snapshot -c                 # Compact (remove empty structural elements)
agent-browser snapshot -d 3               # Limit depth to 3 levels
agent-browser snapshot -s "#main"         # Scope to CSS selector
agent-browser snapshot -i -c -d 5         # Combine options

选项	说明
-i, --interactive	仅显示交互元素（按钮、链接、输入框）
-u, --urls	为链接元素包含 href URL
-c, --compact	移除空的结构元素
-d, --depth <n>	限制树深度
-s, --selector <sel>	限定为 CSS 选择器范围

标注截图

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

基于 CDP（Chrome DevTools Protocol）的浏览器路径（Chrome/Lightpanda）支持标注截图。Safari/WebDriver 后端尚不支持 --annotate。

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

标注截图后，ref 会被缓存，便于立即与元素交互：

agent-browser screenshot --annotate ./page.png
agent-browser click @e2     # Click the "Home" link labeled [2]

这对能够推理视觉布局、无文字图标按钮、canvas 元素或文本无障碍树无法捕获的视觉状态的多模态 AI 模型很有用。

选项

选项	说明
--session <name>	使用隔离会话（或 AGENT_BROWSER_SESSION 环境变量）
--restore [name]	自动保存/恢复会话状态。单独的 --restore 以 --session 作为键
--restore-save <policy>	恢复保存策略：auto、always 或 never
--restore-check-url <glob>	根据 URL 模式验证恢复的状态
--restore-check-text <text>	根据页面文本验证恢复的状态
--restore-check-fn <js>	根据为真的 JavaScript 表达式验证恢复的状态
--namespace <name>	隔离守护进程套接字和恢复状态目录
--session-name <name>	恢复持久化键的旧版别名
--profile <name|path>	Chrome 配置文件名称或持久目录路径（或 AGENT_BROWSER_PROFILE 环境变量）
--state <path>	从 JSON 文件加载存储状态（或 AGENT_BROWSER_STATE 环境变量）
--headers <json>	设置限定于 URL 源（origin）的 HTTP 标头
--executable-path <path>	自定义浏览器可执行文件（或 AGENT_BROWSER_EXECUTABLE_PATH 环境变量）
--extension <path>	加载浏览器扩展（可重复；或 AGENT_BROWSER_EXTENSIONS 环境变量）
--init-script <path>	在首次导航前注册页面初始化脚本（可重复；或 AGENT_BROWSER_INIT_SCRIPTS 环境变量）
--enable <feature>	内置初始化脚本：react-devtools（可重复或逗号分隔列表；或 AGENT_BROWSER_ENABLE 环境变量）
--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）
--hide-scrollbars <bool>	在无头 Chromium 截图中隐藏原生滚动条，默认启用（或 AGENT_BROWSER_HIDE_SCROLLBARS 环境变量）
-p, --provider <name>	浏览器提供方，包括已配置的 browser.provider 插件（或 AGENT_BROWSER_PROVIDER 环境变量）
--device <name>	iOS 设备名称，例如 "iPhone 15 Pro"（或 AGENT_BROWSER_IOS_DEVICE 环境变量）
--json	JSON 输出（供 agent 使用）
--annotate	带编号元素标签的标注截图（或 AGENT_BROWSER_ANNOTATE 环境变量）
--screenshot-dir <path>	默认截图输出目录（或 AGENT_BROWSER_SCREENSHOT_DIR 环境变量）
--screenshot-quality <n>	JPEG 质量 0-100（或 AGENT_BROWSER_SCREENSHOT_QUALITY 环境变量）
--screenshot-format <fmt>	截图格式：png、jpeg（或 AGENT_BROWSER_SCREENSHOT_FORMAT 环境变量）
--headed	显示浏览器窗口（非无头模式）（或 AGENT_BROWSER_HEADED 环境变量）
--cdp <port|url>	通过 Chrome DevTools Protocol（CDP）连接（端口或 WebSocket URL）
--auto-connect	自动发现并连接正在运行的 Chrome（或 AGENT_BROWSER_AUTO_CONNECT 环境变量）
--color-scheme <scheme>	配色方案：dark、light、no-preference（或 AGENT_BROWSER_COLOR_SCHEME 环境变量）
--download-path <path>	默认下载目录（或 AGENT_BROWSER_DOWNLOAD_PATH 环境变量）
--content-boundaries	为 LLM 安全在页面输出外包装边界标记（或 AGENT_BROWSER_CONTENT_BOUNDARIES 环境变量）
--max-output <chars>	将页面输出截断至 N 个字符（或 AGENT_BROWSER_MAX_OUTPUT 环境变量）
--allowed-domains <list>	逗号分隔的允许域名模式（或 AGENT_BROWSER_ALLOWED_DOMAINS 环境变量）
--action-policy <path>	操作策略 JSON 文件路径（或 AGENT_BROWSER_ACTION_POLICY 环境变量）
--confirm-actions <list>	需要确认的操作类别（或 AGENT_BROWSER_CONFIRM_ACTIONS 环境变量）
--confirm-interactive	交互式确认提示；若 stdin 不是 TTY 则自动拒绝（或 AGENT_BROWSER_CONFIRM_INTERACTIVE 环境变量）
--engine <name>	浏览器引擎：chrome（默认）、lightpanda（或 AGENT_BROWSER_ENGINE 环境变量）
--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	调试输出

可观测性仪表板（Observability Dashboard）

通过本地 Web 仪表板实时监控 agent-browser 会话，展示实时视口和命令活动流。

# Start the dashboard server (runs in background on port 4848)
agent-browser dashboard start
agent-browser dashboard start --port 8080   # Custom port

# All sessions are automatically visible in the dashboard
agent-browser open example.com

# Stop the dashboard
agent-browser dashboard stop

仪表板在 4848 端口作为独立后台进程运行，与浏览器会话无关。即使没有会话在运行，它仍保持可用，并且可从 http://localhost:4848 或能访问仪表板服务器的代理/转发 URL（例如 https://dashboard.agent-browser.localhost 或 Coder 工作区 URL）使用。浏览器始终停留在仪表板源站；会话专属的标签页、状态和流式流量在内部被代理，因此无需暴露会话端口。

仪表板展示：

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

AI 聊天

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

export AI_GATEWAY_API_KEY=gw_your_key_here
export AI_GATEWAY_MODEL=anthropic/claude-sonnet-4.6           # optional, this is the default
export AI_GATEWAY_URL=https://ai-gateway.vercel.sh           # optional, this is the default

CLI 用法：

agent-browser chat "open google.com and search for cats"     # Single-shot
agent-browser chat                                           # Interactive REPL
agent-browser -q chat "summarize this page"                  # Quiet mode (text only)
agent-browser -v chat "fill in the login form"               # Verbose (show command output)
agent-browser --model openai/gpt-4o chat "take a screenshot" # Override model

chat 命令将自然语言指令转换为 agent-browser 命令、执行它们并流式传输 AI 响应。在交互模式下，输入 quit 退出。使用 --json 获取适合代理消费的结构化输出。

仪表板用法：

聊天选项卡在仪表板中始终可见。当设置 AI_GATEWAY_API_KEY 时，Rust 服务器将请求代理到网关，并使用 Vercel AI SDK 的 UI Message Stream 协议流式返回响应。未设置密钥时，发送消息会在界面内显示错误。

配置

创建 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",
  "hideScrollbars": false,
  "ignoreHttpsErrors": true,
  "plugins": [
    {
      "name": "vault",
      "command": "agent-browser-plugin-vault",
      "capabilities": ["credential.read"]
    }
  ]
}

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

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

上表中的所有选项均可在配置文件中使用 camelCase 键设置（例如，--executable-path 变为 "executablePath"，--proxy-bypass 变为 "proxyBypass"）。插件通过上文所示的 "plugins" 数组配置。为向前兼容，未知键会被忽略。

提供 JSON Schema 供 IDE 自动补全和校验。在配置文件中添加 $schema 键以启用：

{
  "$schema": "https://agent-browser.dev/schema.json",
  "headed": true
}

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

自动发现的缺失配置文件会被静默忽略。若 --config <path> 指向缺失或无效文件，agent-browser 会以错误退出。用户级与项目级配置中的扩展会合并（拼接），而非替换。

提示： 若项目级 agent-browser.json 包含环境相关值（路径、代理等），建议将其加入 .gitignore。

默认超时

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

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

# Set a longer timeout for slow pages (in milliseconds)
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000

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

变量	说明
AGENT_BROWSER_DEFAULT_TIMEOUT	默认操作超时（毫秒，默认：25000）

选择器

Refs（推荐用于 AI）

Refs 从快照提供确定性的元素选择：

# 1. Get snapshot with refs
agent-browser snapshot
# Output:
# - heading "Example Domain" [ref=e1] [level=1]
# - button "Submit" [ref=e2]
# - textbox "Email" [ref=e3]
# - link "Learn more" [ref=e4]

# 2. Use refs to interact
agent-browser click @e2                   # Click the button
agent-browser fill @e3 "test@example.com" # Fill the textbox
agent-browser get text @e1                # Get heading text
agent-browser hover @e4                   # Hover the link

当 ref 点击被遮罩层阻挡时，错误信息会包含遮盖元素，例如 covered by <div#consent-banner>。请先点击横幅或对话框控件，再重新运行 snapshot，然后方可复用 refs。

为何使用 refs？

• 确定性：Ref 指向快照中的精确元素
• 快速：无需重新查询 DOM
• AI 友好：快照 + ref 工作流最适合 LLM

CSS 选择器

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

文本与 XPath

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

语义定位器

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

代理模式

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

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

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

最佳 AI 工作流

# 1. Navigate and get snapshot
agent-browser open example.com
agent-browser snapshot -i --json   # AI parses tree and refs

# 2. AI identifies target refs from snapshot
# 3. Execute actions using refs
agent-browser click @e2
agent-browser fill @e3 "input text"

# 4. Get new snapshot if page changed
agent-browser snapshot -i --json

命令链

可在单次 shell 调用中使用 && 将多条命令串联起来。浏览器通过后台守护进程保持运行，因此串联执行既安全又更高效：

# Open, wait for load, and snapshot in one call
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Chain multiple interactions
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3

# Navigate and screenshot
agent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

当你不需要中间输出时，请使用 &&。若需要先解析输出（例如，先快照以发现引用再交互），请分别运行各条命令。

有界面模式（Headed Mode）

显示浏览器窗口以便调试：

agent-browser open example.com --headed

这将打开可见的浏览器窗口，而非以无头（headless）方式运行。

注意： 浏览器扩展在有界面和无头模式下均可使用（Chrome 的 --headless=new）。

已认证会话

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

# Headers are scoped to api.example.com only
agent-browser open api.example.com --headers '{"Authorization": "Bearer <token>"}'

# Requests to api.example.com include the auth header
agent-browser snapshot -i --json
agent-browser click @e2

# Navigate to another domain - headers are NOT sent (safe!)
agent-browser open other-site.com

适用于：

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

要为多个源设置请求头，请在每条 open 命令中使用 --headers：

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

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

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

自定义浏览器可执行文件

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

• Serverless 部署：使用轻量级 Chromium 构建，如 @sparticuz/chromium（约 50MB，对比约 684MB）
• 系统浏览器：使用已有的 Chrome/Chromium 安装
• 自定义构建：使用修改过的浏览器构建

CLI 用法

# Via flag
agent-browser --executable-path /path/to/chromium open example.com

# Via environment variable
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com

Serverless（Vercel）

在临时的 Vercel Sandbox microVM 中运行 agent-browser 与 Chrome。无需外部服务器：

import { runAgentBrowserCommand, withAgentBrowserSandbox } from "@agent-browser/sandbox/vercel";

const result = await withAgentBrowserSandbox(async (sandbox) => {
  await runAgentBrowserCommand(sandbox, ["open", "https://example.com"]);
  return runAgentBrowserCommand(sandbox, ["screenshot"]);
});

在消费端应用中安装 @agent-browser/sandbox 和 @vercel/sandbox。请参阅 sandbox helper 示例 了解 Eve 与 Vercel Sandbox 的最小用法，或参阅 environments 示例 查看带「部署到 Vercel」按钮的完整 UI 演示。

全新的 Vercel 和 Eve 沙箱默认会安装 Chromium 系统依赖。仅当你的沙箱镜像已包含这些库时，才传入 installSystemDependencies: false。

Serverless（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 等）：

# Enable file access (required for JavaScript to access local files)
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html

# Take screenshot of a local 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 Protocol（CDP）连接到现有浏览器：

# Start Chrome with: google-chrome --remote-debugging-port=9222

# Connect once, then run commands without --cdp
agent-browser connect 9222
agent-browser snapshot
agent-browser tab
agent-browser close

# Or pass --cdp on each command
agent-browser --cdp 9222 snapshot

# Connect to remote browser via 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 实例，无需指定端口：

# Auto-discover running Chrome with remote debugging
agent-browser --auto-connect open example.com
agent-browser --auto-connect snapshot

# Or via environment variable
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 流式传输浏览器视口，用于实时预览或「结对浏览」（pair browsing），让人类可与 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   # Re-enable on a specific port
agent-browser stream disable              # Stop streaming for the session

WebSocket 服务器会流式传输浏览器视口并接收输入事件。

WebSocket 协议

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

接收帧：

{
  "type": "frame",
  "data": "<base64-encoded-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 采用客户端-守护进程（client-daemon）架构：

1. Rust CLI - 解析命令，并与守护进程通信
2. Rust Daemon - 纯 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	Native Rust
macOS x64	Native Rust
Linux ARM64	Native Rust
Linux x64	Native Rust
Windows x64	Native Rust

与 AI Agent 配合使用

直接让 Agent 使用

最简单的方式是告诉你的 Agent 使用它：

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

--help 的输出内容很全面，大多数 Agent 都能据此自行掌握用法。

AI 编程助手（推荐）

将 skill 添加到你的 AI 编程助手中，以获得更丰富的上下文：

npx skills add vercel-labs/agent-browser

适用于 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Goose、OpenCode 和 Windsurf。该 skill 从仓库获取，因此会自动保持最新。请勿从 node_modules 复制 SKILL.md，否则内容会过时。

Claude Code

安装为 Claude Code skill：

npx skills add vercel-labs/agent-browser

这会在 .claude/skills/agent-browser/SKILL.md 添加一个轻量的发现桩（discovery stub）。该桩有意保持精简——它会在运行时引导 Claude Code 加载 agent-browser skills get core 中的实际工作流内容。这样，指令始终与已安装的 CLI 版本一致，而不会在版本发布之间过时。

AGENTS.md / CLAUDE.md

为获得更稳定的结果，请添加到你的项目或全局指令文件中：

## Browser Automation

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

Core workflow:

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

集成

iOS 模拟器

在 iOS 模拟器中控制真实的 Mobile Safari，以进行真实的移动端 Web 测试。需要安装了 Xcode 的 macOS。

设置：

# Install Appium and XCUITest driver
npm install -g appium
appium driver install xcuitest

用法：

# List available iOS simulators
agent-browser device list

# Launch Safari on a specific device
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# Same commands as desktop
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

# Mobile-specific commands
agent-browser -p ios swipe up
agent-browser -p ios swipe down 500

# Close session
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
# or
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"

2. 签名 WebDriverAgent（一次性）：

# Open the WebDriverAgent Xcode project
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
open WebDriverAgent.xcodeproj

在 Xcode 中：

• 选择 WebDriverAgentRunner 目标
• 前往 Signing & Capabilities
• 选择你的 Team（需要 Apple Developer 账户，免费套餐即可）
• 让 Xcode 自动管理签名

3. 与 agent-browser 配合使用：

# Connect device via USB, then:
agent-browser -p ios --device "<DEVICE_UDID>" open https://example.com

# Or use the device name if unique
agent-browser -p ios --device "John's iPhone" open https://example.com

真机注意事项：

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

Browserless

Browserless provides cloud browser infrastructure with a Sessions API. Use it when running agent-browser in environments where a local browser isn't available.

要启用 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	Base API URL（用于自定义区域或自托管）	https://production-sfo.browserless.io
BROWSERLESS_BROWSER_TYPE	要使用的浏览器类型（chromium 或 chrome）	chromium
BROWSERLESS_TTL	会话 TTL（毫秒）	300000
BROWSERLESS_STEALTH	启用隐身模式（true/false）	true

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

从 Browserless Dashboard. 获取你的 API 令牌

Browserbase

Browserbase provides remote browser infrastructure to make deployment of agentic browsing agents easy. Use it when running the agent-browser CLI in an environment where a local browser isn't feasible.

要启用 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 Dashboard. 获取你的 API 密钥

Browser Use

Browser Use provides cloud browser infrastructure for AI agents. Use it when running agent-browser in environments where a local browser isn't available (serverless, CI/CD, etc.).

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

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

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

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

启用后，agent-browser 会连接到 Browser Use 云端会话，而不是启动本地浏览器。所有命令的行为保持一致。

从 Browser Use Cloud Dashboard. 获取 API 密钥。提供免费额度可供上手，之后按量计费。

Kernel

Kernel 为 AI 智能体提供云端浏览器基础设施，具备隐身模式（stealth mode）和持久化配置（persistent profiles）等功能。

要启用 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	以无头模式（headless）运行浏览器（true/false）	true
KERNEL_STEALTH	启用隐身模式以避免机器人检测（true/false）	false
KERNEL_TIMEOUT_SECONDS	会话超时时间（秒）	300
KERNEL_PROFILE_NAME	用于持久化 Cookie/登录信息的浏览器配置名称（不存在时将自动创建）	（无）

启用后，agent-browser 会连接到 Kernel 云端会话，而不是启动本地浏览器。所有命令的行为保持一致。

配置持久化（Profile Persistence）： 设置 KERNEL_PROFILE_NAME 后，若该配置尚不存在，将自动创建。浏览器会话结束时，Cookie、登录信息和会话数据会自动保存回该配置，供后续会话使用。

从 Kernel Dashboard. 获取 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	用于持久化状态（cookies、localStorage）的浏览器配置	（无）
AGENTCORE_SESSION_TIMEOUT	会话超时时间（秒）	3600
AWS_PROFILE	用于解析凭证的 AWS CLI 配置文件	default

浏览器配置（Browser profiles）： 设置 AGENTCORE_PROFILE_ID 后，浏览器状态（cookies、localStorage）会在各会话间自动持久化。

启用后，agent-browser 会连接到 AgentCore 云端浏览器会话，而不是启动本地浏览器。所有命令的行为保持一致。

许可证

Apache-2.0