通过自然语言指令实现网页自动化，快速获取页面数据并执行交互操作。
详细介绍
agent-browser
专为 AI 智能体打造的浏览器自动化命令行工具。快速的原生 Rust 命令行工具。
功能简介
agent-browser 是一个命令行工具，可让你以编程方式控制网页浏览器。它专为 AI 智能体、自动化脚本以及需要与网页交互（导航、点击、填写表单、截图、提取文本等）的开发者而设计，无需图形界面。
适用人群
需要浏览网页的 AI 智能体和编程助手
自动化浏览器任务（测试、爬取、监控）的开发者
任何希望从命令行或脚本中控制浏览器的人
快速开始
agent-browser open example.com
agent-browser snapshot # 获取无障碍树及引用
agent-browser click @e2 # 通过快照中的引用点击
agent-browser fill @e3 "test@example.com" # 通过引用填写
agent-browser get text @e1 # 通过引用获取文本
agent-browser screenshot page.png
agent-browser close
当另一个元素（例如同意横幅或弹窗）覆盖了目标的点击点时，点击操作会提前失败。请先关闭或与覆盖元素交互，然后重新拍摄快照，再重试原始的引用。
无头 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 — 启动浏览器（不导航）；停留在 about:blank
agent-browser open <url> — 启动并导航到 URL（别名：goto, navigate）
agent-browser read [url] — 获取智能体可读的文本，或读取当前活动标签页的渲染 DOM
agent-browser back — 后退
agent-browser forward — 前进
agent-browser reload — 刷新页面
agent-browser pushstate <url> — SPA 客户端导航
agent-browser close — 关闭浏览器（别名：quit, exit）
agent-browser close –all — 关闭所有活动会话
元素交互
agent-browser click <sel> — 点击元素（–new-tab 在新标签页中打开）
agent-browser dblclick <sel> — 双击元素
agent-browser focus <sel> — 聚焦元素
agent-browser type <sel> <text> — 向元素中输入
agent-browser fill <sel> <text> — 清空并填写
agent-browser press <key> — 按下按键（Enter, Tab, Control+a）（别名：key）
agent-browser keyboard type <text> — 使用真实按键输入（无选择器，当前焦点）
agent-browser keyboard inserttext <text> — 插入文本，不触发按键事件（无选择器）
agent-browser keydown <key> — 按住按键
agent-browser keyup <key> — 释放按键
agent-browser hover <sel> — 悬停元素
agent-browser select <sel> <val> — 选择下拉选项
agent-browser check <sel> — 勾选复选框
agent-browser uncheck <sel> — 取消勾选复选框
agent-browser scroll <dir> [px] — 滚动（up/down/left/right，–selector ）
agent-browser scrollintoview <sel> — 将元素滚动到视图中（别名：scrollinto）
agent-browser drag <src> <tgt> — 拖放
agent-browser upload <sel> <files> — 上传文件
截图与 PDF
agent-browser screenshot [path] — 截图（–full 为整页，未指定路径时保存到临时目录）
agent-browser screenshot –annotate — 带编号元素标签的注释截图
agent-browser screenshot –screenshot-dir ./shots — 保存到自定义目录
agent-browser screenshot –screenshot-format jpeg –screenshot-quality 80
agent-browser pdf <path> — 保存为 PDF
快照（无障碍树）
agent-browser snapshot — 带引用的无障碍树（最适合 AI）
获取信息
agent-browser get text <sel> — 获取文本内容
agent-browser get html <sel> — 获取 innerHTML
agent-browser get value <sel> — 获取输入值
agent-browser get attr <sel> <attr> — 获取属性
agent-browser get title — 获取页面标题
agent-browser get url — 获取当前 URL
agent-browser get cdp-url — 获取 CDP WebSocket URL（用于 DevTools、调试）
agent-browser get count <sel> — 统计匹配元素数量
agent-browser get box <sel> — 获取边界框
agent-browser get styles <sel> — 获取计算样式
读取智能体友好文本
agent-browser 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 获取 URL 时不启动 Chrome。省略 URL 则读取当前浏览器会话中活动标签页的渲染 DOM，包括浏览器认证状态和客户端更新。显式 URL 读取默认发送 Accept: text/markdown ，当首次响应不是 markdown 时，会尝试附加 .md 的相同 URL，并向 / 路径的祖先目录查找最近的 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 获取和输出。
检查状态
agent-browser is visible <sel> — 检查是否可见
agent-browser is enabled <sel> — 检查是否启用
agent-browser is checked <sel> — 检查是否已勾选
查找元素（语义定位器）
agent-browser find role <role> <action> [value] # 按 ARIA 角色
agent-browser find text <text> <action> [value] # 按文本内容
agent-browser find label <label> <action> [value] # 按标签
agent-browser find placeholder <ph> <action> [value] # 按占位符
agent-browser find alt <text> <action> [value] # 按 alt 文本
agent-browser find title <text> <action> [value] # 按 title 属性
agent-browser find testid <id> <action> [value] # 按 data-testid
agent-browser find first <sel> <action> [value] # 第一个匹配
agent-browser find last <sel> <action> [value] # 最后一个匹配
agent-browser find nth <n> <sel> <action> [value] # 第 N 个匹配
动作： click , fill , check , hover , text
选项： –name <name> （按无障碍名称过滤角色）， –exact （精确、区分大小写匹配；对于 role 应用于无障碍名称，默认为不区分大小写的子字符串）
等待
agent-browser wait <selector> — 等待元素可见
agent-browser wait <ms> — 等待时间（毫秒）
agent-browser wait –text "Welcome" — 等待文本出现（子字符串匹配）
agent-browser wait –url "**/dash" — 等待 URL 模式
agent-browser wait –load networkidle — 等待加载状态
agent-browser wait –fn "window.ready === true" — 等待 JS 条件
加载状态： load , domcontentloaded , networkidle
批量执行
在一次调用中执行多个命令。命令可以作为引号参数传递，或通过 stdin 以 JSON 形式管道输入。
# 参数模式：每个引号参数是一个完整命令
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
剪贴板
agent-browser clipboard read — 从剪贴板读取文本
agent-browser clipboard write "Hello, World!" — 向剪贴板写入文本
agent-browser clipboard copy — 复制当前选择（Ctrl+C）
agent-browser clipboard paste — 从剪贴板粘贴（Ctrl+V）
鼠标控制
agent-browser mouse move <x> <y> — 移动鼠标
agent-browser mouse down [button] — 按下按钮（left/right/middle）
agent-browser mouse up [button] — 释放按钮
agent-browser mouse wheel <dy> [dx] — 滚动滚轮
浏览器设置
agent-browser set viewport <w> <h> [scale] — 设置视口大小（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] — 模拟配色方案
Cookie 与存储
agent-browser cookies — 获取所有 cookie
agent-browser cookies set <name> <val> — 设置 cookie
agent-browser cookies set –curl <file> — 从 Copy-as-cURL 转储、JSON 数组或裸 Cookie 头部导入 cookie（自动检测）
agent-browser cookies clear — 清除 cookie
agent-browser storage local — 获取所有 localStorage
agent-browser storage local <key> — 获取特定键
agent-browser storage local set <k> <v> — 设置值
agent-browser storage local clear — 清除所有
agent-browser storage session — 同上，用于 sessionStorage
网络
agent-browser network route <url> — 拦截请求
agent-browser network route <url> –abort — 阻止请求
agent-browser network route <url> –body <json> — 模拟响应
agent-browser network route '*' –abort –resource-type script — 仅阻止脚本
agent-browser network unroute [url] — 移除路由
agent-browser network requests — 查看已追踪的请求
agent-browser network requests –filter api — 过滤请求
agent-browser network requests –type xhr,fetch — 按资源类型过滤
agent-browser network requests –method POST — 按 HTTP 方法过滤
agent-browser network requests –status 2xx — 按状态过滤（200, 2xx, 400-499）
agent-browser network request <requestId> — 查看完整的请求/响应详情
agent-browser network har start — 开始 HAR 录制（嵌入文本响应体）
agent-browser network har start –content all — 嵌入所有响应体（二进制为 base64）
agent-browser network har start –content none — 仅元数据，无响应体
agent-browser network har stop [output.har] — 停止并保存 HAR（省略路径则使用临时路径）
标签页与窗口
agent-browser tab — 列出标签页（显示 tabId 和可选标签）
agent-browser tab new [url] — 新标签页（可选 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 — 新窗口
标签页 id 是稳定的字符串，形式为 t1 、 t2 、 t3 。它们在会话中不会被重复使用，因此脚本和智能体可以持续引用同一个标签页，即使其他标签页被打开或关闭。位置整数如 tab 2 不被接受 ； t 前缀将句柄与索引区分开来，并与元素引用使用的 @e1 约定一致。
你还可以分配一个易记的标签（ docs 、 app 、 admin ），并可以将其与 id 互换使用。标签不会自动生成，也不会在导航时被重写——它们由你命名和保留。
切换到被 Chrome 内存节省器丢弃的标签页会重新激活它，因为丢弃的标签页没有渲染器来驱动。重新激活会重新加载被丢弃的页面并重置其未保存的状态，切换结果会报告 "revived": true 。如果标签页的页面被 JavaScript 对话框暂停，则它是活跃的而不是被丢弃的，因此切换会保持其不变并报告 "dialogBlocked": true ；在交互前使用 dialog accept 或 dialog dismiss 解决对话框。关闭活动标签页到被丢弃的后继标签页会以相同方式重新激活，并报告 "activeTabRevived": true 。
框架
agent-browser frame <sel> — 切换到 iframe
agent-browser frame main — 返回主框架
对话框
agent-browser dialog accept [text] — 接受（可选提示文本）
agent-browser dialog dismiss — 取消
agent-browser dialog status — 检查对话框当前是否打开
默认情况下， alert 和 beforeunload 对话框会自动接受，因此它们不会阻塞智能体。 confirm 和 prompt 对话框仍需要显式处理。使用 –no-auto-dialog （或 AGENT_BROWSER_NO_AUTO_DIALOG=1 ）禁用自动处理。
当 JavaScript 对话框挂起时，所有命令响应都会包含一个 warning 字段，包含对话框类型和消息。
差异对比
agent-browser diff snapshot — 比较当前与上次快照
agent-browser diff snapshot –baseline before.txt — 比较当前与保存的快照文件
agent-browser diff snapshot –selector "#main" –compact — 限定范围的快照差异
agent-browser diff screenshot –baseline before.png — 与基线进行视觉像素差异比较
agent-browser diff screenshot –baseline b.png -o d.png — 将差异图像保存到自定义路径
agent-browser diff screenshot –baseline b.png -t 0.2 — 调整颜色阈值（0-1）
agent-browser diff url https://v1.com https://v2.com — 比较两个 URL（快照差异）
agent-browser diff url https://v1.com https://v2.com –screenshot — 同时进行视觉差异比较
agent-browser diff url https://v1.com https://v2.com –wait-until networkidle — 自定义等待策略
agent-browser diff url https://v1.com https://v2.com –selector "#main" — 限定范围到元素
调试
agent-browser trace start — 开始录制追踪
agent-browser trace stop [path] — 停止并保存追踪
agent-browser profiler start — 开始 Chrome DevTools 性能分析
agent-browser profiler stop [path] — 停止并保存性能分析文件（.json）
agent-browser console — 查看控制台消息（log, error, warn, info）
agent-browser console –json — JSON 输出，包含原始 CDP 参数，便于程序化访问
agent-browser console –clear — 清除控制台
agent-browser errors — 查看页面错误（未捕获的 JavaScript 异常）
agent-browser errors –clear — 清除错误
agent-browser highlight <sel> — 高亮元素
agent-browser inspect — 为当前活动页面打开 Chrome DevTools
agent-browser state save <path> — 保存认证状态
agent-browser state load <path> — 加载认证状态
agent-browser state list — 列出已保存的状态文件
agent-browser state show <file> — 显示状态摘要
agent-browser state rename <old> <new> — 重命名状态文件
agent-browser state clear [name] — 清除会话的状态
agent-browser state clear –all — 清除所有已保存的状态
agent-browser state clean –older-than <days> — 删除旧状态
React / Web Vitals
Agent-browser 自带一流的 React 内省和通用 Web Vitals 指标。React 命令需要在启动时安装 React DevTools 钩子；Web Vitals 和 pushstate 与框架无关。
agent-browser open –enable react-devtools <url> — 启动时安装 React 钩子
agent-browser react tree — 完整组件树
agent-browser react inspect <fiberId> — props, hooks, state, source
agent-browser react renders start — 开始 fiber 渲染录制
agent-browser react renders stop [–json] — 停止并打印性能分析文件（–json 获取原始数据）
agent-browser react suspense [–only-dynamic] [–json] — Suspense 边界 + 分类器
agent-browser vitals [url] [–json] — LCP/CLS/TTFB/FCP/INP + 水合摘要
每个 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 获取完整结构化数据。
无障碍审计
对当前页面或 URL 运行 axe-core 无障碍审计。axe-core 引擎嵌入在二进制文件中，因此可以在离线环境下以及严格 CSP 下工作。它会在页面的框架树上运行私有部分审计，并合并序列化结果而不使用页面消息，因此页面提供的 window.axe 值保持不变，iframe 违规保留其框架选择器路径。无障碍审计需要 CDP 浏览器，Safari 或 iOS WebDriver 会话中不可用。
agent-browser a11y — 审计当前页面
agent-browser a11y https://example.com — 导航，然后审计
agent-browser a11y –tags wcag2a,wcag2aa — 仅包含这些 axe 标签的规则
agent-browser a11y –selector "#main" — 限定审计范围到子树
agent-browser a11y example.com –json — 完整结构化结果
默认输出列出每个违规，包括其影响、规则 ID、修复指导 URL 以及失败节点的 CSS 选择器。
初始化脚本
agent-browser open –init-script <path> — 在首次导航前注册页面初始化脚本（可重复；也支持 AGENT_BROWSER_INIT_SCRIPTS 环境变量）
agent-browser addinitscript <js> — 运行时注册（返回标识符）
agent-browser removeinitscript <identifier> — 移除之前注册的初始化脚本
导航前设置
某些流程（SSR 调试、受保护源的身份验证 cookie、初始化脚本）需要在首次导航之前设置状态。使用不带 URL 的 open 启动浏览器，然后配置 cookie/路由/初始化脚本，再导航。 batch 在一次 CLI 调用中完成所有操作。
设置
agent-browser install — 从 Chrome for Testing（Google 官方自动化渠道）下载 Chrome
agent-browser install –with-deps — 同时安装系统依赖（Linux）
agent-browser upgrade — 升级 agent-browser 到最新版本
agent-browser doctor — 诊断安装并自动清理过时的守护进程文件
agent-browser doctor –fix — 同时也执行破坏性修复（重新安装 Chrome、清除旧状态等）
agent-browser doctor –offline –quick — 跳过网络探测和实时启动测试
doctor 检查你的环境、Chrome 安装、守护进程状态、配置文件、加密密钥、提供商、网络可达性，并运行实时无头浏览器启动测试。过时的 socket/pid 辅助文件会被自动清理。输出也可通过 –json 获取。
Skills
agent-browser skills — 列出可用的技能
agent-browser skills list — 同上
agent-browser skills get <name> — 输出技能的全部内容
agent-browser skills get <name> –full — 包含引用和模板
agent-browser skills get –all — 输出每个技能
agent-browser skills path [name] — 打印技能目录路径
提供捆绑的技能内容，始终与安装的 CLI 版本匹配。AI 智能体使用此功能获取当前指令，而不是依赖缓存副本。设置 AGENT_BROWSER_SKILLS_DIR 可覆盖技能目录路径。
MCP 服务器
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 执行、关闭、标签页基础操作和配置文件发现
network — 网络路由、请求检查、HAR、头部、凭据、离线
state — Cookie、存储、认证、已保存状态、会话、配置文件、Skills
debug — 控制台/错误、追踪、性能分析、录制、无障碍审计、剪贴板、插件、doctor、仪表盘、安装、升级、聊天、差异、批量、确认/拒绝
tabs — 后退/前进/刷新、标签页、窗口、框架、对话框
react — React 树/检查/渲染/Suspense、Web Vitals、pushstate
mobile — 视口/设备/地理位置/媒体、触摸、滑动、鼠标、键盘
all — 所有 MCP 工具，包括完整的类型化 CLI 等价表面
常用工具包括：
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 和 allowedDomains ，因此 MCP 客户端会显示有意义的批准提示，而不是原始命令数组。通用的 allowedDomains 数组映射到 –allowed-domains 并激活相同的 WebRTC 包含和启动模式限制。每个工具还接受 extraArgs 用于高级 CLI 标志和精确的 CLI 等价。工具发现是分页的，并包含只读/开放世界注释，以便现代 MCP 客户端可以增量加载大型类型化表面。
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 配置文件复用
零设置复用现有 Chrome 登录状态（cookie、会话）
–profile <name> / AGENT_BROWSER_PROFILE
持久配置文件
跨重启保留完整浏览器状态（cookie、IndexedDB、Service Worker、缓存）
–profile <path> / AGENT_BROWSER_PROFILE
会话持久化
通过稳定会话键自动保存/恢复 cookie 和 localStorage
–session <id> –restore / AGENT_BROWSER_RESTORE
从浏览器导入
从你已经登录的 Chrome 会话中获取认证状态
–auto-connect + state save
状态文件
启动时加载之前保存的状态 JSON
–state <path> / AGENT_BROWSER_STATE
认证保险库
在本地加密存储凭据，按名称登录
auth save / auth login
从浏览器导入认证
如果你已经登录了某个网站，可以获取该认证状态并复用：
# 1. 启动 Chrome 并启用远程调试
# macOS:
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" –remote-debugging-port=9222
# 或者使用 –auto-connect 发现已运行的 Chrome
# 2. 连接并保存认证状态
agent-browser –auto-connect state save ./my-auth.json
# 3. 在未来的会话中使用保存的认证
agent-browser –state ./my-auth.json open https://app.example.com/dashboard
# 4. 或者使用 –restore 进行自动持久化
SESSION="$(agent-browser session id –scope worktree –prefix myapp)"
agent-browser –session "$SESSION" –restore –state ./my-auth.json open https://app.example.com/dashboard
# 从现在开始，–session "$SESSION" –restore 会自动保存/恢复此状态
安全说明：
–remote-debugging-port 会在 localhost 上暴露完整的浏览器控制权。任何本地进程都可以连接。仅在可信机器上使用，使用后关闭 Chrome。
状态文件以明文形式包含会话令牌。请将其添加到 .gitignore ，并在不再需要时删除。如需静态加密，请设置 AGENT_BROWSER_ENCRYPTION_KEY 。
会话
运行多个隔离的浏览器实例：
# 不同会话
agent-browser –session agent1 open site-a.com
agent-browser –session agent2 open site-b.com
# 或者通过环境变量
AGENT_BROWSER_SESSION=agent1 agent-browser click "#btn"
# 列出活动会话
agent-browser session list
# 输出：
# Active sessions:
# -> default
# agent1
# 显示当前会话
agent-browser session
# 生成稳定的工作树范围会话 ID
agent-browser session id –scope worktree –prefix next-dev-loop
# 检查守护进程、启动和恢复状态
agent-browser session info –json
每个会话拥有自己的：
浏览器实例
Cookie 和存储
导航历史
认证状态
Chrome 配置文件复用
最快的方式是使用现有登录状态：传递 Chrome 配置文件名称给 –profile ：
# 列出可用的 Chrome 配置文件
agent-browser profiles
# 复用默认 Chrome 配置文件的登录状态
agent-browser –profile Default open https://gmail.com
# 使用命名配置文件（按显示名称或目录名称）
agent-browser –profile "Work" open https://app.example.com
# 或者通过环境变量
AGENT_BROWSER_PROFILE=Default agent-browser open https://gmail.com
这会将你的 Chrome 配置文件复制到临时目录（只读快照，不会更改原始配置文件），因此浏览器会以你现有的 cookie 和会话启动。
注意： 在 Windows 上，如果 Chrome 正在运行，请在使用 –profile <name> 前关闭 Chrome，因为某些配置文件文件可能被锁定。
持久配置文件
对于跨浏览器重启保留状态的自定义配置文件目录，传递路径给 –profile ：
# 使用持久配置文件目录
agent-browser –profile ~/.myapp-profile open myapp.com
# 登录一次，然后复用已认证的会话
agent-browser –profile ~/.myapp-profile open myapp.com/dashboard
# 或者通过环境变量
AGENT_BROWSER_PROFILE=~/.myapp-profile agent-browser open myapp.com
配置文件目录存储：
Cookie 和 localStorage
IndexedDB 数据
Service Worker
浏览器缓存
登录会话
提示： 为不同项目使用不同的配置文件路径，以保持浏览器状态隔离。
会话持久化
使用 –restore 和稳定的 –session 自动在浏览器重启之间保存和恢复 cookie 和 localStorage：
# 为这个工作树生成稳定的 ID 并自动保存/加载状态
SESSION="$(agent-browser session id –scope worktree –prefix twitter)"
agent-browser –session "$SESSION" –restore open twitter.com
# 登录一次，状态自动持久化
# 状态文件存储在 ~/.agent-browser/sessions/
# 可选：在自动保存前验证恢复的状态
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 对保存的会话数据进行静态加密：
# 生成密钥：openssl rand -hex 32
export AGENT_BROWSER_ENCRYPTION_KEY=<64-char-hex-key>
# 状态文件现在自动加密
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
64 字符十六进制密钥，用于 AES-256-GCM 加密
AGENT_BROWSER_STATE_EXPIRE_DAYS
自动删除超过 N 天的状态（默认 30）
安全
agent-browser 包含用于安全 AI 智能体部署的安全功能。所有功能都是可选的，在显式启用之前，现有工作流不受影响：
认证保险库 ：在本地存储凭据（始终加密），按名称引用。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
插件系统 ：通过外部可执行插件扩展 agent-browser。插件通过 agent-browser.plugin.v1 stdio JSON 协议在进程外运行，并声明能力，如 credential.read 、 browser.provider 、 launch.mutate 或 command.run 。
内容边界标记 ：将页面输出包裹在分隔符中，以便 LLM 区分工具输出和不受信任的内容： –content-boundaries
域名白名单 ：将导航限制到受信任的域名（通配符如 *.example.com 也匹配裸域名）： –allowed-domains "example.com,*.example.com" 。子资源请求（脚本、图像、fetch）、WebSocket/EventSource 连接以及到非白名单域名的 sendBeacon 调用将被阻止。在白名单激活时，受支持的 Chromium 会话中会禁用 WebRTC 对等连接，以防止 STUN、TURN 和 DNS 流量绕过 HTTP 拦截。专用和共享工作线程通过引导包装器进行保护；如果页面 CSP 禁止该包装器，则工作线程会以关闭失败的方式运行，而不是在没有白名单保护的情况下运行。预先存在的 CDP 会话、自动连接、Chrome 配置文件、直接页面提供程序插件、agent-browser 恢复或状态文件重放、选择配置文件、恢复会话或打开启动页面的原始 Chrome 参数、iOS 和 Safari 拒绝此选项，因为 agent-browser 无法在页面脚本运行之前安装等效的包含。请包含目标页面依赖的任何 CDN 域名（例如 *.cdn.example.com ）。
操作策略 ：通过静态策略文件限制破坏性操作： –action-policy ./policy.json
操作确认 ：要求对敏感操作类别进行显式批准： –confirm-actions eval,download
输出长度限制 ：防止上下文泛滥： –max-output 50000
变量
描述
AGENT_BROWSER_CONTENT_BOUNDARIES
在页面输出周围包裹边界标记
AGENT_BROWSER_MAX_OUTPUT
页面输出的最大字符数
AGENT_BROWSER_ALLOWED_DOMAINS
逗号分隔的允许域名模式；需要全新的可控浏览器上下文，没有配置文件/会话启动参数、恢复/状态重放或直接页面提供程序插件
AGENT_BROWSER_ACTION_POLICY
操作策略 JSON 文件的路径
AGENT_BROWSER_CONFIRM_ACTIONS
需要确认的操作类别
AGENT_BROWSER_CONFIRM_INTERACTIVE
启用交互式确认提示
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 ；使用 –global 写入 ~/.agent-browser/config.json 。
插件包应支持 plugin.manifest ，以便 plugin add 自动发现其名称和能力。如果插件不支持清单，请在添加时传递 –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
使用凭据提供程序插件进行一次登录：
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]"
使用浏览器提供程序插件：
agent-browser –provider cloud-browser open https://example.com
使用启动修改器插件进行隐身或本地启动自定义。插件可以在浏览器启动之前附加 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
不要将保险库令牌或密码放在插件命令参数中。使用保险库供应商自己的登录/会话机制或 agent-browser 配置之外的环境。
快照选项
snapshot 命令支持过滤以减少输出大小：
agent-browser snapshot # 完整无障碍树
agent-browser snapshot -i # 仅交互元素（按钮、输入、链接）
agent-browser snapshot -i –urls # 交互元素及链接 URL
agent-browser snapshot -c # 紧凑（移除空的结构元素）
agent-browser snapshot -d 3 # 限制深度为 3 层
agent-browser snapshot -s "#main" # 限定到 CSS 选择器
agent-browser snapshot -i -c -d 5 # 组合选项
选项
描述
-i, –interactive
仅显示交互元素（按钮、链接、输入）
-u, –urls
包含链接元素的 href URL
-c, –compact
移除空的结构元素
-d, –depth <n>
限制树深度
-s, –selector <sel>
限定到 CSS 选择器
注释截图
–annotate 标志会在截图中将编号标签叠加在交互元素上。每个标签 [N] 对应引用 @eN ，因此相同的引用既适用于视觉工作流，也适用于基于文本的工作流。
注释截图在基于 CDP 的浏览器路径（Chrome/Lightpanda）上受支持。Safari/WebDriver 后端尚不支持 –annotate 。
agent-browser screenshot –annotate
# -> Screenshot saved to /tmp/screenshot-2026-02-17T12-00-00-abc123.png
# [1] @e1 button "Submit"
# [2] @e2 link "Home"
# [3] @e3 textbox "Email"
注释截图后，引用会被缓存，因此你可以立即与元素交互：
agent-browser screenshot –annotate ./page.png
agent-browser click @e2 # 点击标签为 [2] 的 "Home" 链接
这对于多模态 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>`
–state <path>
从 JSON 文件加载存储状态（或 AGENT_BROWSER_STATE 环境变量）
–headers <json>
设置作用域到 URL 来源的 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 输出（用于智能体）
–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 环境变量）
–webgpu
启用 WebGPU；Linux 上使用 SwiftShader 软件 Vulkan，无需 GPU（或 AGENT_BROWSER_WEBGPU 环境变量）
`–cdp <port
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>
逗号分隔的允许域名模式；同时会在受支持的 Chromium 会话中禁用 WebRTC 对等连接，并拒绝 CDP、自动连接、Chrome 配置文件、恢复/状态重放、直接页面提供程序插件、不安全的启动 –args 、iOS 和 Safari（或 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 环境变量）
–idle-timeout <time>
空闲后关闭守护进程（ 10s 、 3m 、 1h 或原始毫秒）。默认为 1h ；使用 0 禁用（或 AGENT_BROWSER_IDLE_TIMEOUT_MS 环境变量）
–no-auto-dialog
禁用 alert / beforeunload 对话框的自动关闭（或 AGENT_BROWSER_NO_AUTO_DIALOG 环境变量）
–model <name>
chat 命令的 AI 模型（或 AI_GATEWAY_MODEL 环境变量）
-v , –verbose
显示工具命令及其原始输出（chat）
-q , –quiet
仅显示 AI 文本响应，隐藏工具调用（chat）
–config <path>
使用自定义配置文件（或 AGENT_BROWSER_CONFIG 环境变量）
–debug
调试输出
可观测性仪表盘
通过本地 Web 仪表盘实时监控 agent-browser 会话，显示实时视口和命令活动流。
# 启动仪表盘服务器（后台运行，端口 4848）
agent-browser dashboard start
agent-browser dashboard start –port 8080 # 自定义端口
# 所有会话自动在仪表盘中可见
agent-browser open example.com
# 停止仪表盘
agent-browser dashboard stop
仪表盘作为独立后台进程运行在端口 4848 上，独立于浏览器会话。即使没有正在运行的会话，它仍然可用，并且可以通过 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 聊天
仪表盘包含一个可选的 AI 聊天面板，由 Vercel AI Gateway 驱动。相同的功能也可以通过 CLI 的 chat 命令直接使用。设置以下环境变量以启用 AI 聊天：
export AI_GATEWAY_API_KEY=gw_your_key_here
export AI_GATEWAY_MODEL=anthropic/claude-sonnet-4.6 # 可选，这是默认值
export AI_GATEWAY_URL=https://ai-gateway.vercel.sh # 可选，这是默认值
CLI 用法：
agent-browser chat "open google.com and search for cats" # 单次执行
agent-browser chat # 交互式 REPL
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" # 覆盖模型
chat 命令将自然语言指令转换为 agent-browser 命令，执行它们，并流式传输 AI 响应。在交互模式下，输入 quit 退出。使用 –json 获取适合智能体使用的结构化输出。
仪表盘用法：
仪表盘中始终显示聊天标签页。当设置了 AI_GATEWAY_API_KEY 时，Rust 服务器将请求代理到网关，并使用 Vercel AI SDK 的 UI Message Stream 协议流式传输响应。如果没有密钥，发送消息会显示内联错误。
配置
创建 agent-browser.json 文件以设置持久化默认值，不必在每个命令上重复标志。
位置（从低到高优先级）：
~/.agent-browser/config.json ：用户级默认值
./agent-browser.json ：项目级覆盖（在工作目录中）
AGENT_BROWSER_* 环境变量覆盖配置文件值
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 超时。
通过环境变量覆盖默认超时：
# 为慢速页面设置更长的超时时间（毫秒）
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
注意： 将此值设置为 30000（30 秒）以上可能会导致慢速操作出现 EAGAIN 错误，因为 CLI 的读取超时会在守护进程响应之前到期。CLI 会自动重试瞬时错误，但响应时间会增加。
变量
描述
AGENT_BROWSER_DEFAULT_TIMEOUT
默认操作超时时间（毫秒，默认 25000）
选择器
引用（推荐用于 AI）
引用提供从快照中确定性的元素选择：
# 1. 获取带引用的快照
agent-browser snapshot
# 输出：
# – heading "Example Domain" [ref=e1] [level=1]
# – button "Submit" [ref=e2]
# – textbox "Email" [ref=e3]
# – link "Learn more" [ref=e4]
# 2. 使用引用进行交互
agent-browser click @e2 # 点击按钮
agent-browser fill @e3 "test@example.com" # 填写文本框
agent-browser get text @e1 # 获取标题文本
agent-browser hover @e4 # 悬停链接
当引用点击被覆盖层阻止时，错误会包含覆盖元素，例如 covered by <div#consent-banner> 。先点击横幅或对话框控件，然后再次运行 snapshot ，再重用引用。
为什么使用引用？
确定性 ：引用指向快照中的确切元素
快速 ：无需重新查询 DOM
AI 友好 ：快照 + 引用工作流最适合 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
# 返回：{"success":true,"data":{"snapshot":"…","refs":{"e1":{"role":"heading","name":"Title"},…}}}
agent-browser get text @e1 –json
agent-browser is visible @e2 –json
最佳 AI 工作流
# 1. 导航并获取快照
agent-browser open example.com
agent-browser snapshot -i –json # AI 解析树和引用
# 2. AI 从快照中识别目标引用
# 3. 使用引用执行操作
agent-browser click @e2
agent-browser fill @e3 "input text"
# 4. 如果页面发生变化，获取新快照
agent-browser snapshot -i –json
命令链
命令可以在单个 shell 调用中使用 && 链接。浏览器通过后台守护进程持久化，因此链接是安全且更高效的：
# 一次调用打开、等待加载并快照
agent-browser open example.com && agent-browser wait –load networkidle && agent-browser snapshot -i
# 链接多个交互
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
# 导航并截图
agent-browser open example.com && agent-browser wait –load networkidle && agent-browser screenshot page.png
当你不需要中间输出时使用 && 。当需要先解析输出时（例如，快照以发现引用后再交互），请分别运行命令。
有头模式
显示浏览器窗口以进行调试：
agent-browser open example.com –headed
这会打开一个可见的浏览器窗口，而不是无头运行。
在没有显示器的 Linux 主机（服务器、容器）上， –headed 仍然有效：当 DISPLAY 未设置且安装了 Xvfb 时，agent-browser 会为浏览器启动一个私有虚拟显示器，并在关闭时清理（使用 AGENT_BROWSER_NO_XVFB=1 退出）。
注意： 浏览器扩展在有头和无头模式下都有效（Chrome 的 –headless=new ）。
WebGPU
无头 Chrome 默认不暴露 WebGPU，因此使用它的页面（three.js WebGPURenderer 、Babylon.js 等）会静默渲染为黑色。 –webgpu 标志启用一个启动预设，使 WebGPU 在无 GPU 的容器和 CI 中也能工作：
agent-browser –webgpu open https://my-webgpu-app.example.com
agent-browser screenshot app.png
在 macOS 和 Windows 上，这使用硬件 Metal/D3D 后端。在 Linux 上，它通过 SwiftShader 的软件 Vulkan 路由 WebGPU（无需 GPU），这需要系统 Vulkan 加载器和 Mesa ICD：
apt-get install -y libvulkan1 mesa-vulkan-drivers
一个上游注意事项：无头 Chrome 无法在 Windows 和 Linux 上捕获 WebGPU 画布呈现的截图（渲染和页面内读取回工作；捕获为黑色）。WebGPU 页面的截图在 macOS 上无头时有效；在 Windows 上，请在已登录的桌面会话中运行 –headed ；在 Linux 上，只需添加 –headed ——当没有设置 DISPLAY 且安装了 Xvfb 时，agent-browser 会自动启动私有虚拟显示器（使用 AGENT_BROWSER_NO_XVFB=1 退出）。
使用以下命令验证完整流水线（适配器、渲染通道和截图捕获）：
agent-browser doctor –webgpu
WebGPU 页面注意事项：
WebGPU 仅存在于安全上下文中（ https:// 、 http://localhost 或 file:// ）。
three.js WebGPURenderer 异步初始化，并在没有适配器可用时静默回退到 WebGL2——等待应用渲染其第一帧后再截图。
要在 Linux 上优先使用真实 GPU 而非 SwiftShader，请使用 –args "–use-vulkan=native,–use-webgpu-adapter=default" 同时覆盖 Vulkan 驱动程序和适配器（用户参数优先于预设；仅 –use-webgpu-adapter 仍然只枚举 SwiftShader）。
已认证会话
使用 –headers 为特定来源设置 HTTP 头部，实现无需登录流程的认证：
# 头部仅作用域到 api.example.com
agent-browser open api.example.com –headers '{"Authorization": "Bearer <token>"}'
# 对 api.example.com 的请求包含认证头部
agent-browser snapshot -i –json
agent-browser click @e2
# 导航到另一个域——头部不会发送（安全！）
agent-browser open other-site.com
这对于以下场景很有用：
跳过登录流程 – 通过头部而非 UI 进行认证
切换用户 – 使用不同的认证令牌启动新会话
API 测试 – 直接访问受保护端点
安全 – 头部作用域限定到来源，不会泄露到其他域
要为多个来源设置头部，请在每个 open 命令中使用 –headers ：
agent-browser open api.example.com –headers '{"Authorization": "Bearer token1"}'
agent-browser open api.acme.com –headers '{"Authorization": "Bearer token2"}'
对于全局头部（所有域），请使用 set headers ：
agent-browser set headers '{"X-Custom-Header": "value"}'
自定义浏览器可执行文件
使用自定义浏览器可执行文件替代捆绑的 Chromium。这对于以下场景很有用：
无服务器部署 ：使用轻量级 Chromium 构建，如 @sparticuz/chromium （约 50MB vs 约 684MB）
系统浏览器 ：使用现有的 Chrome/Chromium 安装
自定义构建 ：使用修改后的浏览器构建
CLI 用法
# 通过标志
agent-browser –executable-path /path/to/chromium open example.com
# 通过环境变量
AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium agent-browser open example.com
本地文件
使用 file:// URL 打开和交互本地文件（PDF、HTML 等）：
# 启用文件访问（JavaScript 访问本地文件所需）
agent-browser –allow-file-access open file:///path/to/document.pdf
agent-browser –allow-file-access open file:///path/to/page.html
# 截取本地 PDF 的截图
agent-browser –allow-file-access open file:///Users/me/report.pdf
agent-browser screenshot report.png
–allow-file-access 标志添加 Chromium 标志（ –allow-file-access-from-files 、 –allow-file-access ），允许 file:// URL：
加载和渲染本地文件
通过 JavaScript（XHR、fetch）访问其他本地文件
加载本地资源（图像、脚本、样式表）
注意： 此标志仅适用于 Chromium。出于安全考虑，默认禁用。
CDP 模式
通过 Chrome DevTools Protocol 连接到现有浏览器：
# 启动 Chrome：google-chrome –remote-debugging-port=9222
# 连接一次，然后无需 –cdp 即可运行命令
agent-browser connect 9222
agent-browser snapshot
agent-browser tab
agent-browser close
# 或者在每个命令上传递 –cdp
agent-browser –cdp 9222 snapshot
# 通过 WebSocket URL 连接到远程浏览器
agent-browser –cdp "wss://your-browser-service.com/cdp?token=…" snapshot
–cdp 标志接受：
端口号（例如 9222 ），用于通过 http://localhost:{port} 进行本地连接
完整的 WebSocket URL（例如 wss://… 或 ws://… ），用于远程浏览器服务
这使得可以控制：
Electron 应用
开启远程调试的 Chrome/Chromium 实例
WebView2 应用程序
任何暴露 CDP 端点的浏览器
自动连接
使用 –auto-connect 自动发现并连接到正在运行的 Chrome 实例，无需指定端口：
# 自动发现正在运行且开启远程调试的 Chrome
agent-browser –auto-connect open example.com
agent-browser –auto-connect snapshot
# 或者通过环境变量
AGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot
自动连接通过以下方式发现 Chrome：
从默认用户数据目录读取 Chrome 的 DevToolsActivePort 文件
回退到探测常见调试端口（9222、9229）
如果基于 HTTP 的发现（ /json/version 、 /json/list ）失败，则回退到直接 WebSocket 连接
流式传输（浏览器预览）
通过 WebSocket 流式传输浏览器视口，用于实时预览或“配对浏览”，其中人类可以观看并与 AI 智能体一起交互。
流式传输
每个会话都会自动在操作系统分配的端口上启动 WebSocket 流服务器。使用 stream status 查看绑定的端口和连接状态：
agent-browser stream status
要绑定到特定端口，请设置 AGENT_BROWSER_STREAM_PORT ：
AGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com
帧编码是守护进程范围的：
变量
默认值
描述
AGENT_BROWSER_STREAM_QUALITY
80
JPEG 质量，0 到 100
AGENT_BROWSER_STREAM_MAX_WIDTH
视口
限制帧宽度（像素）
AGENT_BROWSER_STREAM_MAX_HEIGHT
视口
限制帧高度（像素）
宽度和高度会限制编码帧，但保持页面大小不变，因此纵向或 HiDPI 视口会保留其分辨率，除非你对其进行限制。实时流请求 jpeg。显式的 screencast_start 会重新配置同一个屏幕广播，因此客户端可以在流中看到格式变化。在繁忙的页面上，1280×720 质量 80 大约每帧 54 KB，质量 20 大约 25 KB，质量 20 在 640×360 下大约 9 KB。
# 为受限链接节省帧数据
AGENT_BROWSER_STREAM_QUALITY=20 \
AGENT_BROWSER_STREAM_MAX_WIDTH=640 \
AGENT_BROWSER_STREAM_MAX_HEIGHT=360 \
agent-browser open example.com
你也可以在运行时使用 stream enable 、 stream disable 和 stream status 管理流式传输：
agent-browser stream enable –port 9223 # 在特定端口上重新启用
agent-browser stream disable # 停止会话的流式传输
WebSocket 服务器流式传输浏览器视口并接受输入事件。
WebSocket 协议
连接到 ws://localhost:9223 以接收帧并发送输入：
接收帧：
{
"type": "frame",
"seq": 41,
"data": "<base64-encoded-jpeg>",
"metadata": {
"deviceWidth": 1280,
"deviceHeight": 720,
"pageScaleFactor": 1,
"offsetTop": 0,
"scrollOffsetX": 0,
"scrollOffsetY": 0,
"timestamp": 1785038682238
}
}
seq 是单调递增的帧 ID，在 ack 节奏下会通过 ack 消息回显。 metadata.timestamp 是捕获时间的纪元毫秒数，因此客户端可以判断帧在绘制时有多旧。
发送鼠标事件：
{
"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 }]
}
限制帧率（按客户端）：
{
"type": "config",
"maxFps": 10
}
帧以最新优先的方式传递：服务器在发送时选择最新帧，因此当一个较早的帧仍在写入时产生的帧会被跳过而不是排队。 maxFps （1 到 120， 0 = 无限制）仅为该客户端限制传递。发送 {"type":"config","pacing":"ack"} 的客户端一次接收一帧，并使用 {"type":"ack","seq":N} 确认，因此即使该客户端暂停，也不会有过时的帧到达套接字；在默认的推送节奏下，已经交给传输层的帧仍会按顺序传递。这两个设置也可以在 URL 上声明（ ws://127.0.0.1:<port>/?pacing=ack&maxFps=10 ），这是覆盖连接初始帧的唯一方式。输入事件在每个连接上由专用任务读取，因此即使帧正在写入慢速客户端，点击和按键也会立即分发。它们被发送到浏览器而无需等待其回复，因此点击在鼠标移动爆发时保持响应，并且顺序得以保留。
架构
agent-browser 使用客户端-守护进程架构：
Rust CLI – 解析命令，与守护进程通信
Rust 守护进程 – 纯 Rust 守护进程，使用直接 CDP，无需 Node.js
守护进程在第一个命令时自动启动，并在命令之间保持运行，以便后续操作快速执行。在没有命令或仪表盘输入 1 小时 后，它会保存配置的恢复状态、关闭浏览器并退出，因此一个未调用 close 就崩溃的集成不会无限期泄漏守护进程及其浏览器；下一个命令会启动一个新的守护进程，配置的状态恢复正常工作。没有 –restore 或其他恢复键的会话不会保存浏览器状态，因此其临时状态和打开的标签页会在关闭时丢弃。设置 –idle-timeout 为持续时间，如 30s 、 5m 或 1h ，或设置 AGENT_BROWSER_IDLE_TIMEOUT_MS 为毫秒值。使用 0 完全禁用空闲关闭。默认情况下，不会关闭有头浏览器，包括 Safari 和 iOS WebDriver 会话，或用户附加的浏览器，因为这些可能正在被人类直接使用。提供商拥有的云浏览器仍可被清理。显式设置的超时适用于所有浏览器。
浏览器引擎： 默认使用 Chrome（来自 Chrome for Testing）。 –engine 标志在 chrome 和 lightpanda 之间选择。支持的浏览器：Chromium/Chrome（通过 CDP）和 Safari（通过 iOS 的 WebDriver）。
平台
平台
二进制
macOS ARM64
原生 Rust
macOS x64
原生 Rust
Linux ARM64
原生 Rust
Linux x64
原生 Rust
Windows x64
原生 Rust
与 AI 智能体配合使用
直接告诉智能体
最简单的方法是告诉你的智能体使用它：
Use agent-browser to test the login flow. Run agent-browser –help to see available commands.
–help 输出内容全面，大多数智能体都能据此操作。
AGENTS.md / CLAUDE.md
为了获得更一致的结果，请添加到你的项目或全局指令文件中：
## Browser Automation
Use `agent-browser` for web automation. Run `agent-browser –help` for all commands.
Core workflow:
- `agent-browser open <url>` – Navigate to page
- `agent-browser snapshot -i` – Get interactive elements with refs (@e1, @e2)
- `agent-browser click @e1` / `fill @e2 "text"` – Interact using refs
- Re-snapshot after page changes
集成
iOS 模拟器
在 iOS 模拟器中控制真实的 Mobile Safari，进行真实的移动端 Web 测试。需要 macOS 和 Xcode。
设置：
# 安装 Appium 和 XCUITest 驱动
npm install -g appium
appium driver install xcuitest
用法：
# 列出可用的 iOS 模拟器
agent-browser device list
# 在特定设备上启动 Safari
agent-browser -p ios –device "iPhone 16 Pro" open https://example.com
# 与桌面端相同的命令
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1
agent-browser -p ios fill @e2 "text"
agent-browser -p ios screenshot mobile.png
# 移动端特定命令
agent-browser -p ios swipe up
agent-browser -p ios swipe down 500
# 关闭会话
agent-browser -p ios close
或者使用环境变量：
export AGENT_BROWSER_PROVIDER=ios
export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"
agent-browser open https://example.com
变量
描述
AGENT_BROWSER_PROVIDER
设置为 ios 以启用 iOS 模式
AGENT_BROWSER_IOS_DEVICE
设备名称（例如 "iPhone 16 Pro"、"iPad Pro"）
AGENT_BROWSER_IOS_UDID
设备 UDID（替代设备名称）
支持的设备： Xcode 中可用的所有 iOS 模拟器（iPhone、iPad），以及真实 iOS 设备。
注意： iOS 提供商会启动模拟器、启动 Appium 并控制 Safari。首次启动约需 30-60 秒；后续命令快速执行。
真实设备支持
Appium 也支持通过 USB 连接的真实 iOS 设备。这需要额外的一次性设置：
1. 获取设备 UDID：
xcrun xctrace list devices
# 或
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"
2. 签署 WebDriverAgent（一次性）：
# 打开 WebDriverAgent Xcode 项目
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
open WebDriverAgent.xcodeproj
在 Xcode 中：
选择 WebDriverAgentRunner 目标
转到 Signing & Capabilities
选择你的团队（需要 Apple Developer 账户，免费账户可用）
让 Xcode 自动管理签名
3. 与 agent-browser 配合使用：
# 通过 USB 连接设备，然后：
agent-browser -p ios –device "<DEVICE_UDID>" open https://example.com
# 或者使用设备名称（如果唯一）
agent-browser -p ios –device "John's iPhone" open https://example.com
真实设备说明：
首次运行会将 WebDriverAgent 安装到设备（可能需要信任提示）
设备必须解锁并通过 USB 连接
初始连接比模拟器稍慢
测试真实 Safari 性能和行为
Browserless
Browserless 提供具有 Sessions API 的云浏览器基础设施。在本地浏览器不可用的环境中运行 agent-browser 时使用。
要启用 Browserless，请使用 -p 标志：
export BROWSERLESS_API_KEY="your-api-token"
agent-browser -p browserless open https://example.com
或者为 CI/脚本使用环境变量：
export AGENT_BROWSER_PROVIDER=browserless
export BROWSERLESS_API_KEY="your-api-token"
agent-browser open https://example.com
可通过环境变量进行可选配置：
变量
描述
默认值
BROWSERLESS_API_URL
基础 API 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 提供远程浏览器基础设施，使智能体浏览代理的部署变得简单。在运行 agent-browser CLI 的环境不适合本地浏览器时使用。
要启用 Browserbase，请使用 -p 标志：
export BROWSERBASE_API_KEY="your-api-key"
agent-browser -p browserbase open https://example.com
或者为 CI/脚本使用环境变量：
export AGENT_BROWSER_PROVIDER=browserbase
export BROWSERBASE_API_KEY="your-api-key"
agent-browser open https://example.com
启用后，agent-browser 会连接到 Browserbase 会话，而不是启动本地浏览器。所有命令的工作方式相同。
从 Browserbase Dashboard 获取 API 密钥。
Browser Use
Browser Use 为 AI 智能体提供云浏览器基础设施。在本地浏览器不可用的环境（无服务器、CI/CD 等）中运行 agent-browser 时使用。
要启用 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 智能体提供云浏览器基础设施，具有隐身模式和持久配置文件等功能。
要启用 Kernel，请使用 -p 标志：
export KERNEL_API_KEY="your-api-key"
agent-browser -p kernel open https://example.com
或者为 CI/脚本使用环境变量：
export AGENT_BROWSER_PROVIDER=kernel
export KERNEL_API_KEY="your-api-key"
agent-browser open https://example.com
可通过环境变量进行可选配置：
变量
描述
默认值
KERNEL_HEADLESS
以无头模式运行浏览器（ true / false ）
true
KERNEL_STEALTH
启用隐身模式以避免机器人检测（ true / false ）
false
KERNEL_TIMEOUT_SECONDS
会话超时时间（秒）
300
KERNEL_PROFILE_NAME
浏览器配置文件名称，用于持久化 cookie/登录（如果不存在则创建）
（无）
启用后，agent-browser 会连接到 Kernel 云会话，而不是启动本地浏览器。所有命令的工作方式相同。
配置文件持久化： 当设置了 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
用于持久化状态的浏览器配置文件（cookie、localStorage）
（无）
AGENTCORE_SESSION_TIMEOUT
会话超时时间（秒）
3600
AWS_PROFILE
用于凭据解析的 AWS CLI 配置文件
default
浏览器配置文件： 当设置了 AGENTCORE_PROFILE_ID 时，浏览器状态（cookie、localStorage）会在会话之间自动持久化。
启用后，agent-browser 会连接到 AgentCore 云浏览器会话，而不是启动本地浏览器。所有命令的工作方式相同。
要求
Chrome – 运行 agent-browser install 从 Chrome for Testing （Google 官方自动化渠道）下载 Chrome。会自动检测已有的 Chrome、Brave、Playwright 和 Puppeteer 安装。守护进程不需要 Playwright 或 Node.js。
限制与说明
当另一个元素覆盖了目标的点击点时，点击会提前失败。请先关闭覆盖元素，然后重新拍摄快照，再重试。
无头 Chromium 截图默认隐藏原生滚动条。使用 –hide-scrollbars false 保留它们。
注释截图在基于 CDP 的浏览器路径（Chrome/Lightpanda）上受支持，Safari/WebDriver 不支持。
无障碍审计（ a11y ）需要 CDP 浏览器，Safari 或 iOS WebDriver 会话中不可用。
React 命令需要在启动时传递 –enable react-devtools 。
WebGPU 截图在 Windows 和 Linux 上有限制（无头模式下捕获为黑色）。在这些平台上使用 –headed 。
–allowed-domains 不能与预先存在的 CDP 会话、自动连接、Chrome 配置文件、恢复/状态重放、直接页面提供程序插件或 iOS/Safari 一起使用。
状态文件以明文形式包含会话令牌，除非使用 AGENT_BROWSER_ENCRYPTION_KEY 加密。
操作默认超时时间为 25 秒。设置为 30 秒以上可能会导致 EAGAIN 错误。
守护进程默认在 1 小时无活动后关闭（可通过 –idle-timeout 配置）。有头浏览器和用户附加的浏览器不会受到空闲关闭的影响，除非显式设置。
在 Linux 上，没有显示器的 –headed 需要 Xvfb。
–auto-connect 通过读取 DevToolsActivePort 文件或探测常用端口来发现 Chrome。
–allow-file-access 仅适用于 Chromium。
iOS 提供程序需要 macOS、Xcode 和 Appium。
云提供商（Browserless、Browserbase、Browser Use、Kernel、AgentCore）需要 API 密钥或凭据。
不带 URL 的 read 命令的 –llms 和 –require-md 使用活动标签页 URL。
批量执行使用 –json 通过 stdin 接受 JSON 数组形式的命令。
标签页 id 是稳定的字符串，以 t 开头（例如 t1 ）。不接受位置整数。
标签页的标签由用户分配，并在导航后保持不变。
仪表盘默认运行在端口 4848 上。
AI 聊天需要 Vercel AI Gateway 配置。
MCP 服务器默认使用 core 工具配置。
插件系统使用 stdio JSON 协议。
agent-browser install 命令从 Chrome for Testing 下载 Chrome。
agent-browser upgrade 命令检测安装方法并相应更新。
agent-browser doctor 命令诊断并可以修复安装问题。
agent-browser skills 命令列出和检索捆绑的技能内容。
agent-browser mcp 命令启动 MCP stdio 服务器。
agent-browser chat 命令需要模型配置（环境变量或 –model ）。
agent-browser dashboard 命令启动后台 Web 服务器。
agent-browser connect 命令连接到现有的 CDP 端点。
agent-browser stream 命令启用/禁用 WebSocket 流式传输。
agent-browser diff 命令比较快照、截图或 URL。
agent-browser eval 命令在页面上下文中运行 JavaScript。
agent-browser set 命令在运行时更改浏览器设置。
agent-browser tab 命令管理标签页和窗口。
agent-browser frame 命令切换到 iframe。
agent-browser dialog 命令处理 JavaScript 对话框。
agent-browser network 命令拦截和检查网络请求。
agent-browser cookies 和 agent-browser storage 命令管理 cookie 和存储。
agent-browser keyboard 和 agent-browser mouse 命令模拟输入。
agent-browser clipboard 命令读写剪贴板。
agent-browser batch 命令在一次调用中执行多个命令。
agent-browser press 命令按下按键。
agent-browser type 和 agent-browser fill 命令输入文本。
agent-browser upload 命令上传文件。
agent-browser drag 命令执行拖放。
agent-browser scroll 和 agent-browser scrollintoview 命令滚动。
agent-browser select 命令选择下拉选项。
agent-browser check 和 agent-browser uncheck 命令处理复选框。
agent-browser hover 命令悬停元素。
agent-browser find 命令通过语义条件定位元素。
agent-browser is visible 、 is enabled 、 is checked 命令检查元素状态。
agent-browser wait 命令等待条件。
agent-browser screenshot 命令截图。
agent-browser pdf 命令将页面保存为 PDF。
agent-browser snapshot 命令输出无障碍树。
agent-browser read 命令获取智能体友好的文本。
agent-browser open 命令启动浏览器并导航。
agent-browser close 命令关闭浏览器。
agent-browser back 、 forward 、 reload 命令导航。
agent-browser pushstate 命令处理 SPA 导航。
agent-browser get 命令检索页面信息。
许可证
Apache-2.0
试试这样做
- 使用 agent-browser 打开 https://example.com，获取页面快照并点击其中的登录按钮。
- 如何使用 agent-browser 截取网页的全屏截图并保存到指定目录？
- 利用 agent-browser 的 chat 模式，通过自然语言指令自动填写并提交网页表单。
作者：vercel-labs 开发者 / 职场人 ｜ GitHub Stars 39K ｜ 标签：自动化 编程开发 已认证 开源许可: Apache
来源：colaos.ai ｜ Skill ID：agent-browser
留言 0
还没有留言，快来抢沙发