尧图网站建设 
agent-browser 命令参考全解AI 浏览器自动化 CLI 的完整命令体系与实战指南【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browseragent-browser 是一个专为 AI Agent 设计的浏览器自动化 CLI通过 Chrome/Chromium 的 CDP 协议直接驱动浏览器不依赖 Playwright 或 Puppeteer。本文以仓库 skill-data/core/references/commands.md 为骨架系统梳理其全部命令、子命令、标志与环境变量并结合 cli/src/commands.rs、cli/src/native/actions.rs 等源码讲清每条命令背后的行为与适用场景。读完本文你将掌握从导航、快照、交互、等待到网络拦截、标签页管理、视频录制、MCP 集成的完整命令使用能力可以直接用于编写稳定的浏览器自动化脚本。导航Navigation基础导航命令agent-browser open # 启动浏览器不导航停留在 about:blank # 可搭配 network route、cookies set --curl 或 # addinitscript 在首次导航前预置状态 agent-browser open url # 启动 导航别名goto, navigate # 支持https://、http://、file://、about:、data:// # 未给出协议时自动补全 https:// agent-browser read [url] # 获取 agent 可读文本或读取活动标签页渲染后的 DOM # 显式 URL 发送 Accept: text/markdown必要时尝试 .md # 沿祖先路径查找 llms.txt再回退到 HTML # --llms 与 --require-md 无 URL 时使用活动标签页 URL # --filter 将页面内容收窄到匹配的标题小节 # 遵守 --allowed-domains、--content-boundaries、--max-output # 选项--raw、--require-md、--outline、--llms index|full、--filter、--timeout ms agent-browser back # 后退 agent-browser forward # 前进 agent-browser reload # 刷新页面 agent-browser pushstate url # SPA 客户端导航。自动检测 # window.next.router.push在 Next.js 上触发 RSC 请求 # 回退到 history.pushState popstate/navigate 事件 agent-browser close # 关闭浏览器别名quit, exit agent-browser connect 9222 # 通过 CDP 端口连接浏览器URL 的协议归一化在源码中由normalize_navigation_url完成见 cli/src/commands.rs凡以http://、https://、about:、data:、file:、chrome-extension://、chrome://开头的输入原样保留其余一律自动补全为https://前缀。这意味着agent-browser open example.com等价于打开https://example.com。open不带 URL 时提供一次干净的启动你注册的任何拦截规则、Cookie 或 init 脚本都会在第一次真实导航时生效。典型用法包括 SSR-only 调试--resource-type script、受保护域名的认证以及在无历史页面噪声的情况下抓取新鲜的react suspense/vitals状态。预导航设置单轮批量 batchagent-browser batch \ [open] \ [network,route,*,--abort,--resource-type,script] \ [cookies,set,--curl,cookies.curl,--domain,localhost] \ [navigate,http://localhost:3000/target]batch将启动 → 注册拦截 → 导入 Cookie → 首次导航压缩成一次往返避免每条命令单独与 daemon 通信。Snapshot页面分析agent-browser snapshot # 完整可访问性树 agent-browser snapshot -i # 仅交互元素推荐 agent-browser snapshot -c # 紧凑输出 agent-browser snapshot -d 3 # 深度限制为 3 agent-browser snapshot -s #main # 作用域限定到 CSS 选择器 agent-browser snapshot --delta # 首次全量状态之后输出有界的结构增量 agent-browser snapshot --delta --full # 强制全量状态并刷新基线--delta的增量历史按标签页 选项组合隔离。响应类型为full、unchanged或deltaURL 变化或增量过大时返回全量状态。对于 delta 响应将changesadd、remove、replace应用到 ref 元数据先把上一棵树按换行拆开在零基startLine位置拼接treeChange.lines替换deleteCount行再按换行合并。两个部分都要应用到baseRevision之后再前进到revision若基线不可用用--full重建。源码层面delta逻辑位于 cli/src/native/actions.rs当未开启delta或强制--full时返回{kind:full,revision:...,tree:...,refs:...}与基线完全一致时返回{kind:unchanged,baseRevision:...,revision:...}否则计算treeChange补丁返回{kind:delta,baseRevision:...,treeChange:...,revision:...}。对应的测试用例cli/src/native/actions.rs验证了 delta 补丁应用、baseRevision递增与 unchanged 判定等行为。交互Interactions使用 snapshot 产生的 refsagent-browser click e1 # 点击 agent-browser click e1 --new-tab # 点击并在新标签页打开 agent-browser dblclick e1 # 双击 agent-browser focus e1 # 聚焦 agent-browser fill e2 text # 清空并输入 agent-browser type e2 text # 不清空直接输入 agent-browser press Enter # 按键别名key agent-browser press Controla # 组合键 agent-browser keydown Shift # 按住键 agent-browser keyup Shift # 松开键 agent-browser hover e1 # 悬停 agent-browser check e1 # 勾选复选框 agent-browser uncheck e1 # 取消勾选 agent-browser select e1 value # 按值或可见标签选择 agent-browser select e1 a b # 多选 agent-browser scroll down 500 # 滚动页面默认向下 300px agent-browser scrollintoview e1 # 滚动元素到视野内别名scrollinto agent-browser drag e1 e2 # 拖放 agent-browser upload e1 file.pdf # 上传文件可见标签匹配将不换行空格与普通空格视为等价。当目标点击点被其他元素覆盖时点击在派发前即失败错误信息会指明覆盖元素例如covered by div#consent-banner。处理方式是先关闭或处理该覆盖元素、重新执行 snapshot再重试原动作——这是处理 Cookie 横幅、弹窗遮罩的标准姿势。获取信息Get Informationagent-browser get text e1 # 获取元素文本 agent-browser get html e1 # 获取 innerHTML agent-browser get value e1 # 获取输入值 agent-browser get attr e1 href # 获取属性 agent-browser get title # 获取页面标题 agent-browser get url # 获取当前 URL agent-browser get cdp-url # 获取 CDP WebSocket URL agent-browser get count .item # 统计匹配元素数量 agent-browser get box e1 # 获取包围盒 agent-browser get styles e1 # 获取计算样式字体、颜色、背景等状态检查Check Stateagent-browser is visible e1 # 检查是否可见 agent-browser is enabled e1 # 检查是否可用 agent-browser is checked e1 # 检查是否已勾选截图与 PDFScreenshots and PDFagent-browser screenshot # 保存到临时目录 agent-browser screenshot path.png # 保存到指定路径 agent-browser screenshot --full # 整页截图 agent-browser screenshot --if-changed # 推荐跳过未变化的图片以节省 token agent-browser screenshot --threshold 0.01 # 忽略最多影响 1% 像素的变化 agent-browser pdf output.pdf # 保存为 PDF--threshold 0-1隐含--if-changed。条件历史按标签页和截图作用域隔离。JSON 响应包含changed、revision、pixelChangeRatio和threshold仅当变化超过阈值时path才出现。每个作用域的首次捕获始终判定为 changed。无头 Chromium 截图默认隐藏原生滚动条以保证图片输出一致如需保留原生滚动条启动时传--hide-scrollbars false。截图模块的标注覆盖层实现见 cli/src/native/screenshot.rs。视频录制Video Recordingagent-browser open https://example.com # 先启动一个浏览器会话 agent-browser record start ./demo.webm # 以 30 fps 录制当前页面 agent-browser click e1 # 执行操作 agent-browser record stop # 停止并保存视频 agent-browser record restart ./take2.webm # 停止当前录制并开始新录制 agent-browser record start ./scroll.webm --fps 60 # 动效密集场景用 60 fps agent-browser record start ./soak.webm --fps 10 # 长时间会话用低帧率 agent-browser tab new https://example.com # 如需在新标签页录制先开标签页 agent-browser record start ./demo.webm --cursor # 添加动画鼠标指针 agent-browser record start ./demo.webm --contact-sheet # 保存带时间戳的 PNG 摘要录制需要 PATH 中有ffmpeg路径需带扩展名。--fps接受 1 到 60默认 30。--contact-sheet-threshold 0-1调整关键帧灵敏度并隐含--contact-sheet。等待Waitagent-browser wait e1 # 等待元素出现 agent-browser wait 2000 # 等待毫秒数 agent-browser wait --text Success # 等待文本出现或 -t agent-browser wait --url **/dashboard # 等待 URL 匹配模式或 -u agent-browser wait --load domcontentloaded # 等待 DOMContentLoaded或 -l agent-browser wait --load load # 等待 load 事件 agent-browser wait --load networkidle # 仅在已知会安静下来的页面上等待网络空闲 agent-browser wait --fn window.ready # 等待 JS 条件成立或 -f在页面变更动作之后优先选择代表你所需结果的选择器、文本、URL 或 JS 条件作为等待目标当生命周期事件本身就是里程碑时使用生命周期等待。networkidle也受支持但仅适用于已知会安静下来的页面——SSE、WebSocket、轮询和长轮询可能让它永远无法完成。鼠标控制Mouse Controlagent-browser mouse move 100 200 # 立即移动鼠标 agent-browser mouse move 600 400 --duration 250 --steps 24 agent-browser mouse move 600 400 --human --seed 42 agent-browser mouse down left # 按下按钮 agent-browser mouse up left # 松开按钮 agent-browser mouse wheel 100 # 滚动滚轮当指针路径事件重要时在click或drag上使用--human。移动从当前光标位置开始、到目标位置结束mouse move --seed让路径可复现。语义定位器Semantic Locatorsrefs 之外的替代方案agent-browser find role button click --name Submit agent-browser find role heading text --name Skills # 隐式角色可用h2heading, ullist, 顶层 headerbanner agent-browser find text Sign In click agent-browser find text Sign In click --exact # 仅精确匹配 agent-browser find label Email fill usertest.com agent-browser find placeholder Search fill query agent-browser find alt Logo click agent-browser find title Close click agent-browser find testid submit-btn click agent-browser find first .item click agent-browser find last .item click agent-browser find nth 2 a hover浏览器设置Browser Settingsagent-browser set viewport 1920 1080 # 设置视口尺寸 agent-browser set viewport 1920 1080 2 # 2x 视网膜CSS 尺寸相同截图分辨率更高 agent-browser set device iPhone 14 # 模拟设备 agent-browser set geo 37.7749 -122.4194 # 设置地理位置别名geolocation agent-browser set offline on # 切换离线模式 agent-browser set headers {X-Key:v} # 附加 HTTP 头 agent-browser set credentials user pass # 为当前与未来标签页设置 HTTP 基本认证别名auth agent-browser set media dark # 模拟色彩方案 agent-browser set media light reduced-motion # 浅色模式 减弱动态效果Cookies 与存储Cookies and Storageagent-browser cookies # 获取所有 Cookie agent-browser cookies set name value # 设置 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 # 全部清除网络Networkagent-browser network route url # 拦截请求 agent-browser network route url --abort # 屏蔽请求 agent-browser network route url --body {} # 伪造响应 agent-browser network unroute [url] # 移除路由 agent-browser network requests # 查看被追踪的请求 agent-browser network requests --filter api # 过滤请求 agent-browser network request requestId # 查看完整请求/响应详情含 body agent-browser network har start # 记录流量内嵌文本响应体 agent-browser network har start --content all # 内嵌全部 body二进制转 base64 agent-browser network har start --content none # 仅记录尺寸与头部 agent-browser network har stop [output.har] # 停止并保存 HARroute的处理入口位于 cli/src/native/actions.rs 的handle_route与命令解析层cli/src/commands.rs 中的network分支协同完成从拦截、伪造到取消的完整生命周期。HAR 默认内嵌文本响应体JSON/HTML/JS单凭录制文件即可离线研究站点 API需要二进制内容时用--content all。标签页与窗口Tabs and Windowsagent-browser tab # 列出标签页含 tabId 与 label agent-browser tab new [url] # 新建标签页 agent-browser tab new --label docs [url] # 新建并带易记标签 agent-browser tab t2 # 按 id 切换标签页 agent-browser tab docs # 按标签切换 agent-browser tab close # 关闭当前标签页 agent-browser tab close t2 # 按 id 关闭 agent-browser tab close docs # 按标签关闭 agent-browser window new # 新建窗口标签页 id 是形如t1、t2、t3的稳定字符串会话内从不复用因此同一个 id 在跨命令间始终指向同一个标签页。不接受位置整数——tab 2会报错并附带教学提示请用t2。用户分配的标签docs、app、admin在任意接受标签页引用的地方都与 id 互换使用。标签是 Agent 编写多标签工作流的友好方式agent-browser tab new --label docs https://docs.example.com agent-browser tab new --label app https://app.example.com agent-browser tab docs # 切换到 docs agent-browser snapshot # 为 docs 填充 refs agent-browser click e1 # 在 docs 上按 ref 点击 agent-browser tab app # 切换到 app agent-browser tab close docs # 按标签关闭标签从不自动生成、导航后从不重写、且会话内必须唯一。要与另一个标签页交互必须先切换过去daemon 只维护一个活动标签页eNrefs 归属于执行 snapshot 时活动的标签页。通过tab new或click --new-tab打开的标签页在其首个文档加载前继承会话设置user agent、set headers、set credentials、按源作用域的--headers、init 脚本、route规则以及模拟覆盖色彩方案、时区、locale、地理位置、离线。关闭离线模式或将 headers 设为{}会为未来标签页恢复默认设置。tab list --json还会报告每个标签页的 CDPtargetId在任意接受标签页引用的地方均可使用tab targetId、tab close targetId。与tN这类按 daemon 计数的 id 不同targetId 在 daemon 重启后保持稳定。配合--pin-tab时会话被钉在其绑定的标签页上该标签页被关闭后命令会以tab_gone错误失败而不是回退到其他标签页可用tab new或tab list恢复JSON 错误包含code: tab_gone与恢复对象data.targetId及可选的脱敏data.lastUrlbatch 用result承载同一对象。切换到一个被浏览器回收discard以省内存的标签页会将其重新激活——被回收的标签页没有渲染进程可驱动。重新激活会重载页面并重置其未保存状态切换结果附加revived: true让重载不再静默。被 JS 对话框暂停的标签页是存活而非被回收切换不会触碰它但会附加dialogBlocked: true。用dialog accept/dialog dismiss处理对话框后其状态得以保留。关闭活动标签页落到一个被回收的后继标签页上时会以相同方式复活并报告activeTabRevived: true。框架Framesagent-browser frame #iframe # 按 CSS 选择器切换到 iframe agent-browser frame e3 # 按元素 ref 切换到 iframe agent-browser frame main # 回到主框架iframe 支持iframe 在 snapshot 期间自动检测。主框架 snapshot 运行时Iframe节点会被解析其内容内联在 iframe 元素下方输出一层嵌套iframe 中的 iframe 不展开agent-browser snapshot -i # e3 [Iframe] payment-frame # e4 [input] Card number # e5 [button] Pay # 直接交互——iframe 内的 refs 已经可用 agent-browser fill e4 4111111111111111 agent-browser click e5 # 或切换 frame 上下文做作用域 snapshot agent-browser frame e3 # 用元素 ref 切换 agent-browser snapshot -i # 限定到该 iframe 的 snapshot agent-browser frame main # 返回主框架frame命令接受三种定位方式元素 refs——frame e3将 ref 解析为 iframe 元素CSS 选择器——frame #payment-iframe按选择器查找 iframeframe 名称/URL—— 与浏览器的 frame 树匹配对话框Dialogs默认情况下alert与beforeunload对话框会被自动接受绝不阻塞 Agentconfirm与prompt仍需显式处理。可用--no-auto-dialog关闭此行为。agent-browser dialog accept [text] # 接受对话框 agent-browser dialog dismiss # 取消对话框 agent-browser dialog status # 检查当前是否有对话框打开JavaScriptagent-browser eval document.title # 仅限简单表达式 agent-browser eval -b base64 # 任意 JavaScriptbase64 编码 agent-browser eval --stdin # 从 stdin 读取脚本推荐使用-b/--base64或--stdin保证可靠执行。内联脚本中嵌套引号与特殊字符的 shell 转义极易出错# 先 base64 编码你的脚本然后 agent-browser eval -b ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ # 或用 heredoc 从 stdin 执行多行脚本 cat EOF | agent-browser eval --stdin const links document.querySelectorAll(a); Array.from(links).map(a a.href); EOF认证与插件Authentication and Pluginsagent-browser auth save name --url url --username user --password-stdin agent-browser auth login name # 使用已保存凭据登录 agent-browser auth login name --no-navigate # 同源校验后使用当前活动页面 agent-browser auth login name --credential-provider plugin [--item ref] [--url url] agent-browser auth login name --username-selector s --password-selector s [--submit-selector s] agent-browser auth list # 列出已保存的认证配置 agent-browser auth show name # 显示配置元数据不含密码 agent-browser auth delete name # 删除已保存的配置 agent-browser plugin add ref # 从 npm 或 GitHub 添加插件 agent-browser plugin list # 列出已配置插件 agent-browser plugin show name # 查看单个插件 agent-browser plugin run name type --payload json # 运行任意插件请求auth login默认导航到有效凭据 URL。--no-navigate要求存在一个活动的顶层 HTTP(S) 页面校验其 scheme、host 与有效端口与有效凭据 URL 匹配然后在不替换文档的前提下执行常规的选择器等待、填写与提交点击。路径、查询串与片段可以不同且由提交触发的导航保持开启。命令级--url优先于存储或 provider 元数据并在此模式下成为期望源约束。凭据提供者插件通过进程外的agent-browser.plugin.v1stdio JSON 协议运行且必须声明credential.read能力。使用--confirm-actions plugin:name:credential.read可在插件解析机密前要求显式批准。其他能力使用同一协议browser.provideragent-browser --provider name open urllaunch.mutate追加本地启动参数、扩展或 init 脚本command.runagent-browser plugin run name type --payload jsonplugin run面向command.run与自定义能力核心能力与协议请求类型使用各自的专用命令路径。状态管理State Managementagent-browser state save auth.json # 保存 Cookie、存储、认证状态 agent-browser state load auth.json # 恢复已保存状态实时流Live Streamingagent-browser stream status --json # 启用状态、端口、客户端数量 agent-browser stream enable # 启动 WebSocket 流服务器 agent-browser stream enable --port 9223 # 实验性 WebMCP 页面工具 # 浏览器结果仅在目录变化时公布简要摘要。 # 选择相关工具、获取其 schema然后在用户任务内调用。 agent-browser webmcp list tool --frame frame-id --json agent-browser webmcp list --json # 完整目录或上下文恢复 agent-browser webmcp invoke tool --params {key:value} agent-browser webmcp invoke tool --params input.json --detach agent-browser webmcp result invocation-id agent-browser webmcp cancel invocation-id agent-browser stream disable # 停止流服务器客户端连接ws://127.0.0.1:port接收frame、status、tabs、url与console消息发送input_mouse、input_keyboard、input_touch驱动页面{type:config,maxFps:N}1 到 1200为不设上限限制自身帧率{type:config,pacing:ack}则每次只接收一帧并用{type:ack,seq:N}确认。两种设置也可写在 URL 上ws://127.0.0.1:port/?pacingackmaxFps10。详见 skill-data/core/references/streaming.md。可观测性仪表盘Observability Dashboardagent-browser dashboard start agent-browser dashboard start --port 8080 agent-browser dashboard start --allowed-origins https://dashboard.example.com agent-browser dashboard stop回环源默认在 IPv4 与 IPv6 上免 token 放行。设置--allowed-origins或AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS为精确 HTTPS 反向代理源的逗号分隔列表。每个源都必须合法自定义端口必须是 1 到 65535 的整数。未知选项、缺失值、非法端口与格式错误的源都会导致服务器不启动。命令只为外部源打印私密的 token 化访问 URL打开一次匹配的 URL 以建立浏览器会话切勿分享。本地访问直接打开http://localhost:port。仅当端口与允许源都匹配时重复启动才会复用已运行的仪表盘更改任一设置前先dashboard stop。MCP 服务器agent-browser mcp agent-browser mcp --tools all agent-browser mcp --tools core,network,react启动一个 stdio Model Context Protocol 服务器。MCP 客户端应将服务器命令配置为agent-browser、参数为[mcp]。服务器默认使用 MCP 协议 2025-11-25并在初始化期间接受旧版受支持的客户端协议版本。默认工具集为core保持日常浏览器自动化的 MCP 上下文精简。--tools all提供完整类型化 CLI 对等面或按逗号组合多个 profile如--tools core,network,react。各 profile 的能力划分core—— 默认。导航、快照、交互、等待、读取、截图、JavaScript eval、关闭、基础标签页与 profile 发现network—— 网络路由、请求检查、HAR、头部、凭据、离线state—— Cookie、存储、认证、已保存状态、会话、profiles、skillsdebug—— Console/errors、tracing、profiling、录制、a11y 审计、剪贴板、插件、doctor、仪表盘、install、upgrade、chat、diff、batch、confirm/denytabs—— 后退/前进/刷新、标签页、窗口、frames、对话框react—— React tree/inspect/renders/suspense、vitals、pushstatemobile—— 视口/设备/地理位置/媒体、触摸、滑动、鼠标、键盘all—— 全部 MCP 工具含完整类型化 CLI 对等面常用工具包括agent_browser_tools_profilesagent_browser_openagent_browser_snapshotagent_browser_clickagent_browser_fillagent_browser_typeagent_browser_pressagent_browser_wait_for_selectoragent_browser_screenshotagent_browser_get_urlagent_browser_evalagent_browser_close工具调用使用与 CLI 相同的配置文件与环境变量。每个工具接受类型化参数外加extraArgs用于高级 CLI 标志与精确的 CLI 对等。公共的allowedDomains数组映射到--allowed-domains并激活相同的 WebRTC 遏制与启动模式限制。工具发现是分页的并带只读/开放世界注解现代 MCP 客户端可以增量加载庞大的类型化面。用工具session参数或AGENT_BROWSER_SESSION隔离浏览器状态。全局选项Global Optionsagent-browser --session name ... # 隔离浏览器会话 agent-browser --json ... # 为解析输出 JSON agent-browser --headed ... # 显示浏览器窗口非无头无显示器的 Linux 上自动启动 Xvfb agent-browser --webgpu ... # 启用 WebGPULinux 上为 SwiftShader 软件 Vulkan无需 GPU agent-browser --no-webmcp ... # 禁用默认的实验性 WebMCP Chrome 特性或 AGENT_BROWSER_NO_WEBMCP 环境变量 agent-browser --cdp port|url ... # 通过 CDP 连接根查询斜杠可选 agent-browser --pin-tab ... # 将会话钉在其绑定的标签页严格标签页绑定 agent-browser --no-pin-tab ... # 禁用此前用 --pin-tab 启用的粘性钉 agent-browser -p provider ... # 浏览器 provider 或已配置的 provider 插件 agent-browser --proxy url ... # 使用代理服务器 agent-browser --proxy-bypass hosts # 绕过代理的主机 agent-browser --headers json ... # 按 URL 源作用域的 HTTP 头 agent-browser --executable-path p # 自定义浏览器可执行文件 agent-browser --extension path ... # 加载浏览器扩展可重复 agent-browser --ignore-https-errors # 忽略 SSL 证书错误 agent-browser --ca-cert path # 在 Linux 本地 Chromium 中信任 CAinstall --with-deps 提供 certutil agent-browser --no-ca-cert # 清除运行中会话保留的 CA 信任 agent-browser --hide-scrollbars false # 在无头 Chromium 截图中保留原生滚动条 agent-browser --help # 显示帮助-h agent-browser --version # 显示版本-V agent-browser command --help # 显示某命令的详细帮助调试Debugging在 Windows 上受控的无头 Chrome 运行在私有桌面隐藏窗口不会在用户桌面画出杂散矩形。这适用于自定义 Chrome 可执行文件以及之后通过 CDP 创建的窗口。有头与扩展会话使用交互式桌面。受控的 Chrome 进程树会在其 daemon 退出时被终止包括强制终止附加到外部浏览器不取得其所有权。agent-browser --headed open example.com # 显示浏览器窗口 agent-browser --cdp 9222 snapshot # 通过 CDP 端口连接 agent-browser connect 9222 # 备选connect 命令 agent-browser console # 查看 console 消息 agent-browser console --clear # 清空 console agent-browser errors # 查看页面错误 agent-browser errors --clear # 清空错误 agent-browser highlight e1 # 高亮元素 agent-browser inspect # 为本会话打开 Chrome DevTools agent-browser trace start # 开始记录 trace agent-browser trace stop trace.json # 停止并保存 trace agent-browser profiler start # 开始 Chrome DevTools 性能分析 agent-browser profiler stop trace.json # 停止并保存 profileReact / Web Vitalsreact ...系列命令要求在启动时启用--enable react-devtoolsvitals与pushstate与框架无关。agent-browser open --enable react-devtools url # 安装 React 钩子后启动 agent-browser react tree # 完整组件树 agent-browser react inspect fiberId # props、hooks、state、源码 agent-browser react renders start # 开始记录重渲染 agent-browser react renders stop [--json] # 停止并打印渲染 profile agent-browser react suspense [--only-dynamic] [--json] # Suspense 边界 分类器 # --only-dynamic 隐藏 static 列表 agent-browser vitals [url] [--json] # LCP/CLS/TTFB/FCP/INP 水合 agent-browser pushstate url # SPA 客户端导航自动检测 Next routervitals默认打印摘要字段与结构化--json响应一致。可访问性审计Accessibility Audit运行内嵌的 axe-core 审计无需 CDN 拉取。内置引擎通过 CDP 跨页面 frame 树执行私有部分审计并合并序列化结果全程不通过页面消息传递因此页面 CSP 不会阻断它、页面提供的window.axe值保持原样、iframe 违规保留其 frame 选择器路径。可访问性审计需要 CDP 浏览器Safari 与 iOS WebDriver 会话不可用。报告 WCAG 违规并附影响等级、规则 id、修复指引 URL 与失败节点选择器。agent-browser a11y # 审计当前页面 agent-browser a11y url # 导航后再审计 agent-browser a11y --tags wcag2a,wcag2aa # 仅限这些 axe 标签的规则 agent-browser a11y --selector #main # 将审计限定到子树 agent-browser a11y url --json # 面向自动化的结构化结果--json返回counts加violations/incomplete数组每个条目含id、impact、help、helpUrl、tags、nodeCount与最多 10 个nodestarget选择器路径数组、html片段、failureSummary。嵌套的target数组保留 shadow DOM 边界。incomplete列出 axe 无法自动评估的规则——需人工复核。Init 脚本Init Scriptsagent-browser open --init-script path # 在首次导航前注册可重复 agent-browser addinitscript js # 运行时注册返回标识符 agent-browser removeinitscript identifier # 从会话的每个标签页移除运行时 init 脚本标识符是会话级的。移除一个会将其从已注册的所有打开标签页以及将重放到未来标签页的设置中清除。cURL Cookie 导入agent-browser cookies set --curl file # 自动检测 JSON/cURL/Cookie-header agent-browser cookies set --curl file --domain example.com # 限定到某域名支持的格式{name, value}的 JSON 数组、DevTools - Network - Copy as cURL 的 cURL 转储或裸 Cookie 头。错误信息绝不回显 Cookie 值。按资源类型路由Network Route by Resource Typeagent-browser network route * --abort --resource-type script # 仅屏蔽脚本SSR-lock 模式 agent-browser network route * --resource-type image,font --body # 桩替图片与字体环境变量Environment VariablesAGENT_BROWSER_SESSIONmysession # 默认会话名 AGENT_BROWSER_EXECUTABLE_PATH/path/chrome # 自定义浏览器路径 AGENT_BROWSER_EXTENSIONS/ext1,/ext2 # 逗号分隔的扩展路径 AGENT_BROWSER_INIT_SCRIPTS/a.js,/b.js # 逗号分隔的 init 脚本路径 AGENT_BROWSER_ENABLEreact-devtools # 逗号分隔的内置 init 脚本特性 AGENT_BROWSER_HIDE_SCROLLBARSfalse # 在无头 Chromium 截图中保留原生滚动条 AGENT_BROWSER_WEBGPU1 # 启用 WebGPU 启动预设见 [skill-data/core/references/webgpu.md](https://link.gitcode.com/i/a83f9a05c711d8784c0c6b38125fd912) AGENT_BROWSER_NO_XVFB1 # 在无显示器的 Linux 上禁用有头模式的自动 Xvfb AGENT_BROWSER_PROVIDERbrowserbase # 浏览器 provider 或已配置的 provider 插件 AGENT_BROWSER_STREAM_PORT9223 # 覆盖 WebSocket 流端口默认OS 分配 AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINShttps://dashboard.example.com # 受信任的 HTTPS 反向代理仪表盘源 AGENT_BROWSER_CONFIG./agent-browser.json # 自定义配置文件 AGENT_BROWSER_CDP9222 # 将 daemon 连接到 CDP 端口或 WebSocket URL AGENT_BROWSER_ALLOWED_DOMAINSexample.com # 限制网络域名需要全新可控浏览器上下文不带 profile/会话启动参数、restore/state 重放或直接页面 provider 插件 AGENT_BROWSER_PLUGINS[{name:vault,command:agent-browser-plugin-vault,capabilities:[credential.read]},{name:stealth,command:agent-browser-plugin-stealth,capabilities:[launch.mutate]}]源码视角命令系统如何运转整个 CLI 的解析与分发在 cli/src/commands.rs约 6700 行完成入口在 cli/src/main.rs。is_top_level_commandcli/src/commands.rs枚举了全部顶层命令名及别名goto/navigate/open、quit/exit/close、key/press、scrollinto/scrollintoview等解析失败时产生带上下文的ParseErrorcli/src/commands.rs区分未知命令未知子命令附合法选项列表缺参附 usage非法取值与非法会话名并给出可执行的修复提示。执行侧命令被翻译成 JSON 请求发往常驻 daemon再由 cli/src/native/actions.rs 等模块经 CDP 驱动浏览器。以click为例解析层会校验 ref 语法并生成{action:click,selector:...}指令cli/src/commands.rs交互层在执行前进行命中测试目标被覆盖时返回covered by ...错误这正是先处理遮罩元素再重试这一最佳实践的源码依据。最佳实践小结快照驱动交互snapshot -i产生eNrefs每次页面变更后重新快照refs 的解析与失效处理让 Agent 以极小 token 成本获得稳定定位。等待优先于固定延时优先使用选择器、文本、URL 模式与 JS 条件等待networkidle只用于确定会安静下来的页面裸wait 2000仅作调试手段。敏感信息走专用通道认证凭据用auth save --password-stdinCookie 用cookies set --curl file错误信息不回显 Cookie 值凭据插件通过credential.read能力经进程外协议解析机密。会话隔离用--session name或AGENT_BROWSER_SESSION隔离多任务/多 Agent 的浏览器状态--pin-tab防止共享 CDP 连接时串标签页。截图省 token--if-changed及--threshold跳过未变化的截图是最省 token 的重复捕获方式。完整参考自助获取运行agent-browser skills get core --full可拉取完整命令清单本命令参考即 skill-data/core/references/commands.md配合agent-browser command --help获取单命令详细帮助。【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agent-browser 命令参考全解：AI 浏览器自动化 CLI 的完整命令体系与实战指南
agent-browser 命令参考全解AI 浏览器自动化 CLI 的完整命令体系与实战指南【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browseragent-browser 是一个专为 AI Agent 设计的浏览器自动化 CLI通过 Chrome/Chromium 的 CDP 协议直接驱动浏览器不依赖 Playwright 或 Puppeteer。本文以仓库 skill-data/core/references/commands.md 为骨架系统梳理其全部命令、子命令、标志与环境变量并结合 cli/src/commands.rs、cli/src/native/actions.rs 等源码讲清每条命令背后的行为与适用场景。读完本文你将掌握从导航、快照、交互、等待到网络拦截、标签页管理、视频录制、MCP 集成的完整命令使用能力可以直接用于编写稳定的浏览器自动化脚本。导航Navigation基础导航命令agent-browser open # 启动浏览器不导航停留在 about:blank # 可搭配 network route、cookies set --curl 或 # addinitscript 在首次导航前预置状态 agent-browser open url # 启动 导航别名goto, navigate # 支持https://、http://、file://、about:、data:// # 未给出协议时自动补全 https:// agent-browser read [url] # 获取 agent 可读文本或读取活动标签页渲染后的 DOM # 显式 URL 发送 Accept: text/markdown必要时尝试 .md # 沿祖先路径查找 llms.txt再回退到 HTML # --llms 与 --require-md 无 URL 时使用活动标签页 URL # --filter 将页面内容收窄到匹配的标题小节 # 遵守 --allowed-domains、--content-boundaries、--max-output # 选项--raw、--require-md、--outline、--llms index|full、--filter、--timeout ms agent-browser back # 后退 agent-browser forward # 前进 agent-browser reload # 刷新页面 agent-browser pushstate url # SPA 客户端导航。自动检测 # window.next.router.push在 Next.js 上触发 RSC 请求 # 回退到 history.pushState popstate/navigate 事件 agent-browser close # 关闭浏览器别名quit, exit agent-browser connect 9222 # 通过 CDP 端口连接浏览器URL 的协议归一化在源码中由normalize_navigation_url完成见 cli/src/commands.rs凡以http://、https://、about:、data:、file:、chrome-extension://、chrome://开头的输入原样保留其余一律自动补全为https://前缀。这意味着agent-browser open example.com等价于打开https://example.com。open不带 URL 时提供一次干净的启动你注册的任何拦截规则、Cookie 或 init 脚本都会在第一次真实导航时生效。典型用法包括 SSR-only 调试--resource-type script、受保护域名的认证以及在无历史页面噪声的情况下抓取新鲜的react suspense/vitals状态。预导航设置单轮批量 batchagent-browser batch \ [open] \ [network,route,*,--abort,--resource-type,script] \ [cookies,set,--curl,cookies.curl,--domain,localhost] \ [navigate,http://localhost:3000/target]batch将启动 → 注册拦截 → 导入 Cookie → 首次导航压缩成一次往返避免每条命令单独与 daemon 通信。Snapshot页面分析agent-browser snapshot # 完整可访问性树 agent-browser snapshot -i # 仅交互元素推荐 agent-browser snapshot -c # 紧凑输出 agent-browser snapshot -d 3 # 深度限制为 3 agent-browser snapshot -s #main # 作用域限定到 CSS 选择器 agent-browser snapshot --delta # 首次全量状态之后输出有界的结构增量 agent-browser snapshot --delta --full # 强制全量状态并刷新基线--delta的增量历史按标签页 选项组合隔离。响应类型为full、unchanged或deltaURL 变化或增量过大时返回全量状态。对于 delta 响应将changesadd、remove、replace应用到 ref 元数据先把上一棵树按换行拆开在零基startLine位置拼接treeChange.lines替换deleteCount行再按换行合并。两个部分都要应用到baseRevision之后再前进到revision若基线不可用用--full重建。源码层面delta逻辑位于 cli/src/native/actions.rs当未开启delta或强制--full时返回{kind:full,revision:...,tree:...,refs:...}与基线完全一致时返回{kind:unchanged,baseRevision:...,revision:...}否则计算treeChange补丁返回{kind:delta,baseRevision:...,treeChange:...,revision:...}。对应的测试用例cli/src/native/actions.rs验证了 delta 补丁应用、baseRevision递增与 unchanged 判定等行为。交互Interactions使用 snapshot 产生的 refsagent-browser click e1 # 点击 agent-browser click e1 --new-tab # 点击并在新标签页打开 agent-browser dblclick e1 # 双击 agent-browser focus e1 # 聚焦 agent-browser fill e2 text # 清空并输入 agent-browser type e2 text # 不清空直接输入 agent-browser press Enter # 按键别名key agent-browser press Controla # 组合键 agent-browser keydown Shift # 按住键 agent-browser keyup Shift # 松开键 agent-browser hover e1 # 悬停 agent-browser check e1 # 勾选复选框 agent-browser uncheck e1 # 取消勾选 agent-browser select e1 value # 按值或可见标签选择 agent-browser select e1 a b # 多选 agent-browser scroll down 500 # 滚动页面默认向下 300px agent-browser scrollintoview e1 # 滚动元素到视野内别名scrollinto agent-browser drag e1 e2 # 拖放 agent-browser upload e1 file.pdf # 上传文件可见标签匹配将不换行空格与普通空格视为等价。当目标点击点被其他元素覆盖时点击在派发前即失败错误信息会指明覆盖元素例如covered by div#consent-banner。处理方式是先关闭或处理该覆盖元素、重新执行 snapshot再重试原动作——这是处理 Cookie 横幅、弹窗遮罩的标准姿势。获取信息Get Informationagent-browser get text e1 # 获取元素文本 agent-browser get html e1 # 获取 innerHTML agent-browser get value e1 # 获取输入值 agent-browser get attr e1 href # 获取属性 agent-browser get title # 获取页面标题 agent-browser get url # 获取当前 URL agent-browser get cdp-url # 获取 CDP WebSocket URL agent-browser get count .item # 统计匹配元素数量 agent-browser get box e1 # 获取包围盒 agent-browser get styles e1 # 获取计算样式字体、颜色、背景等状态检查Check Stateagent-browser is visible e1 # 检查是否可见 agent-browser is enabled e1 # 检查是否可用 agent-browser is checked e1 # 检查是否已勾选截图与 PDFScreenshots and PDFagent-browser screenshot # 保存到临时目录 agent-browser screenshot path.png # 保存到指定路径 agent-browser screenshot --full # 整页截图 agent-browser screenshot --if-changed # 推荐跳过未变化的图片以节省 token agent-browser screenshot --threshold 0.01 # 忽略最多影响 1% 像素的变化 agent-browser pdf output.pdf # 保存为 PDF--threshold 0-1隐含--if-changed。条件历史按标签页和截图作用域隔离。JSON 响应包含changed、revision、pixelChangeRatio和threshold仅当变化超过阈值时path才出现。每个作用域的首次捕获始终判定为 changed。无头 Chromium 截图默认隐藏原生滚动条以保证图片输出一致如需保留原生滚动条启动时传--hide-scrollbars false。截图模块的标注覆盖层实现见 cli/src/native/screenshot.rs。视频录制Video Recordingagent-browser open https://example.com # 先启动一个浏览器会话 agent-browser record start ./demo.webm # 以 30 fps 录制当前页面 agent-browser click e1 # 执行操作 agent-browser record stop # 停止并保存视频 agent-browser record restart ./take2.webm # 停止当前录制并开始新录制 agent-browser record start ./scroll.webm --fps 60 # 动效密集场景用 60 fps agent-browser record start ./soak.webm --fps 10 # 长时间会话用低帧率 agent-browser tab new https://example.com # 如需在新标签页录制先开标签页 agent-browser record start ./demo.webm --cursor # 添加动画鼠标指针 agent-browser record start ./demo.webm --contact-sheet # 保存带时间戳的 PNG 摘要录制需要 PATH 中有ffmpeg路径需带扩展名。--fps接受 1 到 60默认 30。--contact-sheet-threshold 0-1调整关键帧灵敏度并隐含--contact-sheet。等待Waitagent-browser wait e1 # 等待元素出现 agent-browser wait 2000 # 等待毫秒数 agent-browser wait --text Success # 等待文本出现或 -t agent-browser wait --url **/dashboard # 等待 URL 匹配模式或 -u agent-browser wait --load domcontentloaded # 等待 DOMContentLoaded或 -l agent-browser wait --load load # 等待 load 事件 agent-browser wait --load networkidle # 仅在已知会安静下来的页面上等待网络空闲 agent-browser wait --fn window.ready # 等待 JS 条件成立或 -f在页面变更动作之后优先选择代表你所需结果的选择器、文本、URL 或 JS 条件作为等待目标当生命周期事件本身就是里程碑时使用生命周期等待。networkidle也受支持但仅适用于已知会安静下来的页面——SSE、WebSocket、轮询和长轮询可能让它永远无法完成。鼠标控制Mouse Controlagent-browser mouse move 100 200 # 立即移动鼠标 agent-browser mouse move 600 400 --duration 250 --steps 24 agent-browser mouse move 600 400 --human --seed 42 agent-browser mouse down left # 按下按钮 agent-browser mouse up left # 松开按钮 agent-browser mouse wheel 100 # 滚动滚轮当指针路径事件重要时在click或drag上使用--human。移动从当前光标位置开始、到目标位置结束mouse move --seed让路径可复现。语义定位器Semantic Locatorsrefs 之外的替代方案agent-browser find role button click --name Submit agent-browser find role heading text --name Skills # 隐式角色可用h2heading, ullist, 顶层 headerbanner agent-browser find text Sign In click agent-browser find text Sign In click --exact # 仅精确匹配 agent-browser find label Email fill usertest.com agent-browser find placeholder Search fill query agent-browser find alt Logo click agent-browser find title Close click agent-browser find testid submit-btn click agent-browser find first .item click agent-browser find last .item click agent-browser find nth 2 a hover浏览器设置Browser Settingsagent-browser set viewport 1920 1080 # 设置视口尺寸 agent-browser set viewport 1920 1080 2 # 2x 视网膜CSS 尺寸相同截图分辨率更高 agent-browser set device iPhone 14 # 模拟设备 agent-browser set geo 37.7749 -122.4194 # 设置地理位置别名geolocation agent-browser set offline on # 切换离线模式 agent-browser set headers {X-Key:v} # 附加 HTTP 头 agent-browser set credentials user pass # 为当前与未来标签页设置 HTTP 基本认证别名auth agent-browser set media dark # 模拟色彩方案 agent-browser set media light reduced-motion # 浅色模式 减弱动态效果Cookies 与存储Cookies and Storageagent-browser cookies # 获取所有 Cookie agent-browser cookies set name value # 设置 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 # 全部清除网络Networkagent-browser network route url # 拦截请求 agent-browser network route url --abort # 屏蔽请求 agent-browser network route url --body {} # 伪造响应 agent-browser network unroute [url] # 移除路由 agent-browser network requests # 查看被追踪的请求 agent-browser network requests --filter api # 过滤请求 agent-browser network request requestId # 查看完整请求/响应详情含 body agent-browser network har start # 记录流量内嵌文本响应体 agent-browser network har start --content all # 内嵌全部 body二进制转 base64 agent-browser network har start --content none # 仅记录尺寸与头部 agent-browser network har stop [output.har] # 停止并保存 HARroute的处理入口位于 cli/src/native/actions.rs 的handle_route与命令解析层cli/src/commands.rs 中的network分支协同完成从拦截、伪造到取消的完整生命周期。HAR 默认内嵌文本响应体JSON/HTML/JS单凭录制文件即可离线研究站点 API需要二进制内容时用--content all。标签页与窗口Tabs and Windowsagent-browser tab # 列出标签页含 tabId 与 label agent-browser tab new [url] # 新建标签页 agent-browser tab new --label docs [url] # 新建并带易记标签 agent-browser tab t2 # 按 id 切换标签页 agent-browser tab docs # 按标签切换 agent-browser tab close # 关闭当前标签页 agent-browser tab close t2 # 按 id 关闭 agent-browser tab close docs # 按标签关闭 agent-browser window new # 新建窗口标签页 id 是形如t1、t2、t3的稳定字符串会话内从不复用因此同一个 id 在跨命令间始终指向同一个标签页。不接受位置整数——tab 2会报错并附带教学提示请用t2。用户分配的标签docs、app、admin在任意接受标签页引用的地方都与 id 互换使用。标签是 Agent 编写多标签工作流的友好方式agent-browser tab new --label docs https://docs.example.com agent-browser tab new --label app https://app.example.com agent-browser tab docs # 切换到 docs agent-browser snapshot # 为 docs 填充 refs agent-browser click e1 # 在 docs 上按 ref 点击 agent-browser tab app # 切换到 app agent-browser tab close docs # 按标签关闭标签从不自动生成、导航后从不重写、且会话内必须唯一。要与另一个标签页交互必须先切换过去daemon 只维护一个活动标签页eNrefs 归属于执行 snapshot 时活动的标签页。通过tab new或click --new-tab打开的标签页在其首个文档加载前继承会话设置user agent、set headers、set credentials、按源作用域的--headers、init 脚本、route规则以及模拟覆盖色彩方案、时区、locale、地理位置、离线。关闭离线模式或将 headers 设为{}会为未来标签页恢复默认设置。tab list --json还会报告每个标签页的 CDPtargetId在任意接受标签页引用的地方均可使用tab targetId、tab close targetId。与tN这类按 daemon 计数的 id 不同targetId 在 daemon 重启后保持稳定。配合--pin-tab时会话被钉在其绑定的标签页上该标签页被关闭后命令会以tab_gone错误失败而不是回退到其他标签页可用tab new或tab list恢复JSON 错误包含code: tab_gone与恢复对象data.targetId及可选的脱敏data.lastUrlbatch 用result承载同一对象。切换到一个被浏览器回收discard以省内存的标签页会将其重新激活——被回收的标签页没有渲染进程可驱动。重新激活会重载页面并重置其未保存状态切换结果附加revived: true让重载不再静默。被 JS 对话框暂停的标签页是存活而非被回收切换不会触碰它但会附加dialogBlocked: true。用dialog accept/dialog dismiss处理对话框后其状态得以保留。关闭活动标签页落到一个被回收的后继标签页上时会以相同方式复活并报告activeTabRevived: true。框架Framesagent-browser frame #iframe # 按 CSS 选择器切换到 iframe agent-browser frame e3 # 按元素 ref 切换到 iframe agent-browser frame main # 回到主框架iframe 支持iframe 在 snapshot 期间自动检测。主框架 snapshot 运行时Iframe节点会被解析其内容内联在 iframe 元素下方输出一层嵌套iframe 中的 iframe 不展开agent-browser snapshot -i # e3 [Iframe] payment-frame # e4 [input] Card number # e5 [button] Pay # 直接交互——iframe 内的 refs 已经可用 agent-browser fill e4 4111111111111111 agent-browser click e5 # 或切换 frame 上下文做作用域 snapshot agent-browser frame e3 # 用元素 ref 切换 agent-browser snapshot -i # 限定到该 iframe 的 snapshot agent-browser frame main # 返回主框架frame命令接受三种定位方式元素 refs——frame e3将 ref 解析为 iframe 元素CSS 选择器——frame #payment-iframe按选择器查找 iframeframe 名称/URL—— 与浏览器的 frame 树匹配对话框Dialogs默认情况下alert与beforeunload对话框会被自动接受绝不阻塞 Agentconfirm与prompt仍需显式处理。可用--no-auto-dialog关闭此行为。agent-browser dialog accept [text] # 接受对话框 agent-browser dialog dismiss # 取消对话框 agent-browser dialog status # 检查当前是否有对话框打开JavaScriptagent-browser eval document.title # 仅限简单表达式 agent-browser eval -b base64 # 任意 JavaScriptbase64 编码 agent-browser eval --stdin # 从 stdin 读取脚本推荐使用-b/--base64或--stdin保证可靠执行。内联脚本中嵌套引号与特殊字符的 shell 转义极易出错# 先 base64 编码你的脚本然后 agent-browser eval -b ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ # 或用 heredoc 从 stdin 执行多行脚本 cat EOF | agent-browser eval --stdin const links document.querySelectorAll(a); Array.from(links).map(a a.href); EOF认证与插件Authentication and Pluginsagent-browser auth save name --url url --username user --password-stdin agent-browser auth login name # 使用已保存凭据登录 agent-browser auth login name --no-navigate # 同源校验后使用当前活动页面 agent-browser auth login name --credential-provider plugin [--item ref] [--url url] agent-browser auth login name --username-selector s --password-selector s [--submit-selector s] agent-browser auth list # 列出已保存的认证配置 agent-browser auth show name # 显示配置元数据不含密码 agent-browser auth delete name # 删除已保存的配置 agent-browser plugin add ref # 从 npm 或 GitHub 添加插件 agent-browser plugin list # 列出已配置插件 agent-browser plugin show name # 查看单个插件 agent-browser plugin run name type --payload json # 运行任意插件请求auth login默认导航到有效凭据 URL。--no-navigate要求存在一个活动的顶层 HTTP(S) 页面校验其 scheme、host 与有效端口与有效凭据 URL 匹配然后在不替换文档的前提下执行常规的选择器等待、填写与提交点击。路径、查询串与片段可以不同且由提交触发的导航保持开启。命令级--url优先于存储或 provider 元数据并在此模式下成为期望源约束。凭据提供者插件通过进程外的agent-browser.plugin.v1stdio JSON 协议运行且必须声明credential.read能力。使用--confirm-actions plugin:name:credential.read可在插件解析机密前要求显式批准。其他能力使用同一协议browser.provideragent-browser --provider name open urllaunch.mutate追加本地启动参数、扩展或 init 脚本command.runagent-browser plugin run name type --payload jsonplugin run面向command.run与自定义能力核心能力与协议请求类型使用各自的专用命令路径。状态管理State Managementagent-browser state save auth.json # 保存 Cookie、存储、认证状态 agent-browser state load auth.json # 恢复已保存状态实时流Live Streamingagent-browser stream status --json # 启用状态、端口、客户端数量 agent-browser stream enable # 启动 WebSocket 流服务器 agent-browser stream enable --port 9223 # 实验性 WebMCP 页面工具 # 浏览器结果仅在目录变化时公布简要摘要。 # 选择相关工具、获取其 schema然后在用户任务内调用。 agent-browser webmcp list tool --frame frame-id --json agent-browser webmcp list --json # 完整目录或上下文恢复 agent-browser webmcp invoke tool --params {key:value} agent-browser webmcp invoke tool --params input.json --detach agent-browser webmcp result invocation-id agent-browser webmcp cancel invocation-id agent-browser stream disable # 停止流服务器客户端连接ws://127.0.0.1:port接收frame、status、tabs、url与console消息发送input_mouse、input_keyboard、input_touch驱动页面{type:config,maxFps:N}1 到 1200为不设上限限制自身帧率{type:config,pacing:ack}则每次只接收一帧并用{type:ack,seq:N}确认。两种设置也可写在 URL 上ws://127.0.0.1:port/?pacingackmaxFps10。详见 skill-data/core/references/streaming.md。可观测性仪表盘Observability Dashboardagent-browser dashboard start agent-browser dashboard start --port 8080 agent-browser dashboard start --allowed-origins https://dashboard.example.com agent-browser dashboard stop回环源默认在 IPv4 与 IPv6 上免 token 放行。设置--allowed-origins或AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINS为精确 HTTPS 反向代理源的逗号分隔列表。每个源都必须合法自定义端口必须是 1 到 65535 的整数。未知选项、缺失值、非法端口与格式错误的源都会导致服务器不启动。命令只为外部源打印私密的 token 化访问 URL打开一次匹配的 URL 以建立浏览器会话切勿分享。本地访问直接打开http://localhost:port。仅当端口与允许源都匹配时重复启动才会复用已运行的仪表盘更改任一设置前先dashboard stop。MCP 服务器agent-browser mcp agent-browser mcp --tools all agent-browser mcp --tools core,network,react启动一个 stdio Model Context Protocol 服务器。MCP 客户端应将服务器命令配置为agent-browser、参数为[mcp]。服务器默认使用 MCP 协议 2025-11-25并在初始化期间接受旧版受支持的客户端协议版本。默认工具集为core保持日常浏览器自动化的 MCP 上下文精简。--tools all提供完整类型化 CLI 对等面或按逗号组合多个 profile如--tools core,network,react。各 profile 的能力划分core—— 默认。导航、快照、交互、等待、读取、截图、JavaScript eval、关闭、基础标签页与 profile 发现network—— 网络路由、请求检查、HAR、头部、凭据、离线state—— Cookie、存储、认证、已保存状态、会话、profiles、skillsdebug—— Console/errors、tracing、profiling、录制、a11y 审计、剪贴板、插件、doctor、仪表盘、install、upgrade、chat、diff、batch、confirm/denytabs—— 后退/前进/刷新、标签页、窗口、frames、对话框react—— React tree/inspect/renders/suspense、vitals、pushstatemobile—— 视口/设备/地理位置/媒体、触摸、滑动、鼠标、键盘all—— 全部 MCP 工具含完整类型化 CLI 对等面常用工具包括agent_browser_tools_profilesagent_browser_openagent_browser_snapshotagent_browser_clickagent_browser_fillagent_browser_typeagent_browser_pressagent_browser_wait_for_selectoragent_browser_screenshotagent_browser_get_urlagent_browser_evalagent_browser_close工具调用使用与 CLI 相同的配置文件与环境变量。每个工具接受类型化参数外加extraArgs用于高级 CLI 标志与精确的 CLI 对等。公共的allowedDomains数组映射到--allowed-domains并激活相同的 WebRTC 遏制与启动模式限制。工具发现是分页的并带只读/开放世界注解现代 MCP 客户端可以增量加载庞大的类型化面。用工具session参数或AGENT_BROWSER_SESSION隔离浏览器状态。全局选项Global Optionsagent-browser --session name ... # 隔离浏览器会话 agent-browser --json ... # 为解析输出 JSON agent-browser --headed ... # 显示浏览器窗口非无头无显示器的 Linux 上自动启动 Xvfb agent-browser --webgpu ... # 启用 WebGPULinux 上为 SwiftShader 软件 Vulkan无需 GPU agent-browser --no-webmcp ... # 禁用默认的实验性 WebMCP Chrome 特性或 AGENT_BROWSER_NO_WEBMCP 环境变量 agent-browser --cdp port|url ... # 通过 CDP 连接根查询斜杠可选 agent-browser --pin-tab ... # 将会话钉在其绑定的标签页严格标签页绑定 agent-browser --no-pin-tab ... # 禁用此前用 --pin-tab 启用的粘性钉 agent-browser -p provider ... # 浏览器 provider 或已配置的 provider 插件 agent-browser --proxy url ... # 使用代理服务器 agent-browser --proxy-bypass hosts # 绕过代理的主机 agent-browser --headers json ... # 按 URL 源作用域的 HTTP 头 agent-browser --executable-path p # 自定义浏览器可执行文件 agent-browser --extension path ... # 加载浏览器扩展可重复 agent-browser --ignore-https-errors # 忽略 SSL 证书错误 agent-browser --ca-cert path # 在 Linux 本地 Chromium 中信任 CAinstall --with-deps 提供 certutil agent-browser --no-ca-cert # 清除运行中会话保留的 CA 信任 agent-browser --hide-scrollbars false # 在无头 Chromium 截图中保留原生滚动条 agent-browser --help # 显示帮助-h agent-browser --version # 显示版本-V agent-browser command --help # 显示某命令的详细帮助调试Debugging在 Windows 上受控的无头 Chrome 运行在私有桌面隐藏窗口不会在用户桌面画出杂散矩形。这适用于自定义 Chrome 可执行文件以及之后通过 CDP 创建的窗口。有头与扩展会话使用交互式桌面。受控的 Chrome 进程树会在其 daemon 退出时被终止包括强制终止附加到外部浏览器不取得其所有权。agent-browser --headed open example.com # 显示浏览器窗口 agent-browser --cdp 9222 snapshot # 通过 CDP 端口连接 agent-browser connect 9222 # 备选connect 命令 agent-browser console # 查看 console 消息 agent-browser console --clear # 清空 console agent-browser errors # 查看页面错误 agent-browser errors --clear # 清空错误 agent-browser highlight e1 # 高亮元素 agent-browser inspect # 为本会话打开 Chrome DevTools agent-browser trace start # 开始记录 trace agent-browser trace stop trace.json # 停止并保存 trace agent-browser profiler start # 开始 Chrome DevTools 性能分析 agent-browser profiler stop trace.json # 停止并保存 profileReact / Web Vitalsreact ...系列命令要求在启动时启用--enable react-devtoolsvitals与pushstate与框架无关。agent-browser open --enable react-devtools url # 安装 React 钩子后启动 agent-browser react tree # 完整组件树 agent-browser react inspect fiberId # props、hooks、state、源码 agent-browser react renders start # 开始记录重渲染 agent-browser react renders stop [--json] # 停止并打印渲染 profile agent-browser react suspense [--only-dynamic] [--json] # Suspense 边界 分类器 # --only-dynamic 隐藏 static 列表 agent-browser vitals [url] [--json] # LCP/CLS/TTFB/FCP/INP 水合 agent-browser pushstate url # SPA 客户端导航自动检测 Next routervitals默认打印摘要字段与结构化--json响应一致。可访问性审计Accessibility Audit运行内嵌的 axe-core 审计无需 CDN 拉取。内置引擎通过 CDP 跨页面 frame 树执行私有部分审计并合并序列化结果全程不通过页面消息传递因此页面 CSP 不会阻断它、页面提供的window.axe值保持原样、iframe 违规保留其 frame 选择器路径。可访问性审计需要 CDP 浏览器Safari 与 iOS WebDriver 会话不可用。报告 WCAG 违规并附影响等级、规则 id、修复指引 URL 与失败节点选择器。agent-browser a11y # 审计当前页面 agent-browser a11y url # 导航后再审计 agent-browser a11y --tags wcag2a,wcag2aa # 仅限这些 axe 标签的规则 agent-browser a11y --selector #main # 将审计限定到子树 agent-browser a11y url --json # 面向自动化的结构化结果--json返回counts加violations/incomplete数组每个条目含id、impact、help、helpUrl、tags、nodeCount与最多 10 个nodestarget选择器路径数组、html片段、failureSummary。嵌套的target数组保留 shadow DOM 边界。incomplete列出 axe 无法自动评估的规则——需人工复核。Init 脚本Init Scriptsagent-browser open --init-script path # 在首次导航前注册可重复 agent-browser addinitscript js # 运行时注册返回标识符 agent-browser removeinitscript identifier # 从会话的每个标签页移除运行时 init 脚本标识符是会话级的。移除一个会将其从已注册的所有打开标签页以及将重放到未来标签页的设置中清除。cURL Cookie 导入agent-browser cookies set --curl file # 自动检测 JSON/cURL/Cookie-header agent-browser cookies set --curl file --domain example.com # 限定到某域名支持的格式{name, value}的 JSON 数组、DevTools - Network - Copy as cURL 的 cURL 转储或裸 Cookie 头。错误信息绝不回显 Cookie 值。按资源类型路由Network Route by Resource Typeagent-browser network route * --abort --resource-type script # 仅屏蔽脚本SSR-lock 模式 agent-browser network route * --resource-type image,font --body # 桩替图片与字体环境变量Environment VariablesAGENT_BROWSER_SESSIONmysession # 默认会话名 AGENT_BROWSER_EXECUTABLE_PATH/path/chrome # 自定义浏览器路径 AGENT_BROWSER_EXTENSIONS/ext1,/ext2 # 逗号分隔的扩展路径 AGENT_BROWSER_INIT_SCRIPTS/a.js,/b.js # 逗号分隔的 init 脚本路径 AGENT_BROWSER_ENABLEreact-devtools # 逗号分隔的内置 init 脚本特性 AGENT_BROWSER_HIDE_SCROLLBARSfalse # 在无头 Chromium 截图中保留原生滚动条 AGENT_BROWSER_WEBGPU1 # 启用 WebGPU 启动预设见 [skill-data/core/references/webgpu.md](https://link.gitcode.com/i/a83f9a05c711d8784c0c6b38125fd912) AGENT_BROWSER_NO_XVFB1 # 在无显示器的 Linux 上禁用有头模式的自动 Xvfb AGENT_BROWSER_PROVIDERbrowserbase # 浏览器 provider 或已配置的 provider 插件 AGENT_BROWSER_STREAM_PORT9223 # 覆盖 WebSocket 流端口默认OS 分配 AGENT_BROWSER_DASHBOARD_ALLOWED_ORIGINShttps://dashboard.example.com # 受信任的 HTTPS 反向代理仪表盘源 AGENT_BROWSER_CONFIG./agent-browser.json # 自定义配置文件 AGENT_BROWSER_CDP9222 # 将 daemon 连接到 CDP 端口或 WebSocket URL AGENT_BROWSER_ALLOWED_DOMAINSexample.com # 限制网络域名需要全新可控浏览器上下文不带 profile/会话启动参数、restore/state 重放或直接页面 provider 插件 AGENT_BROWSER_PLUGINS[{name:vault,command:agent-browser-plugin-vault,capabilities:[credential.read]},{name:stealth,command:agent-browser-plugin-stealth,capabilities:[launch.mutate]}]源码视角命令系统如何运转整个 CLI 的解析与分发在 cli/src/commands.rs约 6700 行完成入口在 cli/src/main.rs。is_top_level_commandcli/src/commands.rs枚举了全部顶层命令名及别名goto/navigate/open、quit/exit/close、key/press、scrollinto/scrollintoview等解析失败时产生带上下文的ParseErrorcli/src/commands.rs区分未知命令未知子命令附合法选项列表缺参附 usage非法取值与非法会话名并给出可执行的修复提示。执行侧命令被翻译成 JSON 请求发往常驻 daemon再由 cli/src/native/actions.rs 等模块经 CDP 驱动浏览器。以click为例解析层会校验 ref 语法并生成{action:click,selector:...}指令cli/src/commands.rs交互层在执行前进行命中测试目标被覆盖时返回covered by ...错误这正是先处理遮罩元素再重试这一最佳实践的源码依据。最佳实践小结快照驱动交互snapshot -i产生eNrefs每次页面变更后重新快照refs 的解析与失效处理让 Agent 以极小 token 成本获得稳定定位。等待优先于固定延时优先使用选择器、文本、URL 模式与 JS 条件等待networkidle只用于确定会安静下来的页面裸wait 2000仅作调试手段。敏感信息走专用通道认证凭据用auth save --password-stdinCookie 用cookies set --curl file错误信息不回显 Cookie 值凭据插件通过credential.read能力经进程外协议解析机密。会话隔离用--session name或AGENT_BROWSER_SESSION隔离多任务/多 Agent 的浏览器状态--pin-tab防止共享 CDP 连接时串标签页。截图省 token--if-changed及--threshold跳过未变化的截图是最省 token 的重复捕获方式。完整参考自助获取运行agent-browser skills get core --full可拉取完整命令清单本命令参考即 skill-data/core/references/commands.md配合agent-browser command --help获取单命令详细帮助。【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考