Agent Browser 零基础使用教程：用一行命令，让 AI 智能体自己操作浏览器

分类：开发工具｜难度：入门｜类型：实操教程｜软件：Agent Browser
标签：开源、AI 智能体、浏览器自动化、命令行、Vercel｜预计阅读：约 10 分钟

一、这是什么

Agent Browser 是 Vercel Labs 出品的一款浏览器自动化命令行工具，专为 AI 智能体设计：它让智能体（或你自己）用一条条简短的 shell 命令打开网页、读取页面内容、点击按钮、填写表单、截图存档。它在 2026 年 11 月 6 日登上 GitHub 当日热门榜单，核实时主仓库已有约 4.59 万个 star，许可证为 Apache-2.0。

它的核心想法很直接：传统浏览器自动化要写一整段脚本，而 Agent Browser 把每一步拆成一个命令。snapshot 会把页面转成一段紧凑的文字，每个可操作元素都带一个编号，例如 @e1；你（或智能体）照着编号下命令，click @e1 就点下去，再 snapshot 一次确认结果，如此循环。浏览器由后台守护进程托管，在命令之间一直保持开启，所以每一步都只是一次短调用。

它是一个原生 Rust CLI，预设使用 Chrome for Testing 浏览器，也能接上正在运行的 Chrome（--cdp）、切换 Lightpanda 或 Obscura 引擎、在 iOS 模拟器里驱动 Mobile Safari，或使用 Browserbase、Browserless 等云端浏览器。除了给智能体用，它也适合用来做网页测试、页面巡检、批量截图和自动化填表。命令覆盖导航、读取、互动、等待、截图、录影、网路状态、分页、除错、会话与认证等分组，也内建技能（skills）与 MCP 伺服器，方便接入 Claude Code 这类智能体工具。

它适合这些人：想让 AI 智能体自己上网查资料、操作网页的开发者；需要写浏览器自动化但不想维护笨重脚本的工程师；以及想快速做网页截图、表单测试、流程巡检的效率使用者。

二、开始前先确认

• 系统要求：需要一部能装 Node.js 的电脑，因为官方安装方式走 npm（npm 随 Node.js 一起提供）。原生二进位档支援 macOS（ARM64、x64）、Linux（ARM64、x64，glibc 与 musl）与 Windows（x64）。
• 首次安装会下载浏览器：执行 agent-browser install 时会下载 Chrome for Testing，需要联网并留出磁碟空间；Linux 用户可用 --with-deps 顺便装好浏览器的系统依赖库。
• 浏览器由守护进程托管：第一条命令会自动启动后台守护进程并透过 Chrome DevTools Protocol 控制浏览器；预设情况下，闲置一小时后守护进程会关闭无头浏览器并退出（设定会话持续化后会先储存状态）。
• 不要在上面登入重要账号做敏感操作：官方文件有专门的安全章节，涵盖认证保管库、网域白名单与操作政策；第一次用建议先在公开页面练习，熟悉后再处理需要登入的流程。
• 快照编号会过期：snapshot 里的 @e1 这类编号只描述当时的页面，导航或 DOM 变化后要重新快照再用编号，否则可能点到错误的元素。

三、操作步骤

步骤 1：安装 Agent Browser 与浏览器

按你的系统选一条官方安装命令。最通用的是 npm 全域安装：

npm install -g agent-browser

装好 CLI 后，第一次使用前要下载浏览器（只需做一次）：

agent-browser install

macOS 或 Linux 也可以用 Homebrew 安装，装完同样要执行 agent-browser install：

brew install agent-browser

Linux 用户如果缺系统依赖库，可以一次装齐：

agent-browser install --with-deps

不想安装也能直接试，用 npx 免安装执行：

npx agent-browser open example.com

装完后做一次自检，执行 agent-browser --help 能印出完整命令清单、agent-browser doctor 能检查环境，就说明安装成功。想升级时执行 agent-browser upgrade。

图 1：安装 Agent Browser CLI 并下载浏览器的示意。图片为 AI 生成的操作示意图，实际介面以终端输出为准。

步骤 2：打开网页并取得元素快照

打开一个网页（网址可省略 https://）：

agent-browser open example.com

接着用 snapshot -i 取得页面上可互动元素的清单，每个元素都有一个 @e 开头的编号：

agent-browser snapshot -i

以 example.com 为例，快照输出大概是这样：

- link "Learn more" [ref=e1]

这一步是整个工作流程的起点：先看快照、拿到编号，再决定下一步点哪里、填什么。编号只在当次快照有效，页面变化后要重新快照。

图 2：打开网页并以 snapshot 取得元素编号的示意。图片为 AI 生成的操作示意图。

步骤 3：按编号点击、填表并确认结果

照着快照里的编号操作，例如点一下 @e1 这个连结：

agent-browser click @e1

再用 get url 确认目前网址，看看是不是真的跳过去了：

agent-browser get url

表单也是一样的写法，用 fill 把文字填进输入框（编号以实际快照为准）：

agent-browser fill @e3 "test@example.com"

想读某段文字内容，用 get text 加上编号：

agent-browser get text @e1

除了编号，也能用 CSS 选择器或语义定位器，例如：

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

注意：如果点击失败，工具会直接报失败而不是假装成功——常见原因是目标被隐藏、被禁用、超出可视范围，或被同意横幅之类的元素盖住；先处理遮挡元素、重新快照再试一次。

图 3：按编号点击、填写表单并截图确认的示意。图片为 AI 生成的操作示意图。

步骤 4：等待、截图与串连命令

页面载入需要时间时，先等一等再快照，免得抓到半成品页面：

agent-browser wait --text "Welcome"
agent-browser wait --url "**/dashboard"
agent-browser wait --load domcontentloaded

想把结果存下来，用 screenshot（不给档名会存到暂存目录，给档名则存到指定路径）：

agent-browser screenshot
agent-browser screenshot page.png

多条命令可以用 && 串在一次 shell 调用里，浏览器靠守护进程保持开启，串连是安全的：

agent-browser open example.com && agent-browser wait --load domcontentloaded && agent-browser snapshot -i
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "pass" && agent-browser click @e3
agent-browser open example.com && agent-browser wait --load load && agent-browser screenshot page.png

只有不需要中间输出时才串连；需要先解析快照、再决定下一步时（例如先看编号再点），还是一条一条执行。

步骤 5（进阶）：有头模式、技能与关闭浏览器

想亲眼看到浏览器在做什么，除错时加上 --headed，会弹出真实浏览器视窗：

agent-browser open example.com --headed

要让 AI 智能体用它，先取得与目前 CLI 版本相符的技能说明：

agent-browser skills get core

也可以把发现技能装进智能体工具（例如 Claude Code）：

npx skills add vercel-labs/agent-browser

或在专案的 AGENTS.md 里加一句，让智能体第一次使用前先载入技能：

Use `agent-browser` for browser automation. Before the first use, run
`agent-browser skills get core` and follow it.

用 MCP 客户端的话，agent-browser mcp 会透过 stdio 启动 MCP 伺服器。用完后关闭浏览器与守护进程：

agent-browser close

四、恢复办法

Agent Browser 只在本机控制浏览器，不会动你的系统设定，遇到问题基本都能马上回到干净状态：

• 命令找不到 agent-browser：检查 npm 全域安装是否完成、终端是否需要重新载入环境；Homebrew 用户可重新执行 brew install agent-browser，或用 agent-browser upgrade 更新。
• agent-browser install 下载失败：检查网路连线与磁碟空间，Linux 用户改用 agent-browser install --with-deps 补齐系统依赖库后再试。
• 点击失败或点到错的元素：先确认目标没有被隐藏、禁用或遮挡；页面变化后编号会失效，重新执行 snapshot -i 拿到最新编号再操作。
• 页面还没载入完就快照：先用 wait --text、wait --url 或 wait --load domcontentloaded 等到想要的状态，再快照。
• 浏览器卡住或没有回应：执行 agent-browser close 关掉浏览器与守护进程，再从 open 重新开始；不同 --session 各有自己的守护进程与浏览器，互不干扰。
• 想从头再来：执行 agent-browser close 后重新 open 即可；之前的操作不会影响新会话。
• 不想用了：执行 agent-browser close，再用当初的安装方式解除安装，例如 npm 用户执行 npm uninstall -g agent-browser，Homebrew 用户执行 brew uninstall agent-browser。

五、注意事项（必读）

• 编号用一次就过期：导航或 DOM 变化后，旧快照的 @e 编号就失效了，操作前务必重新快照。
• 点击失败要当真：工具在目标被隐藏、禁用、超出可视范围或被遮挡时会明确失败，不要忽略这个失败去猜结果，先处理遮挡元素再重试。
• 敏感操作先看安全文件：处理登入、认证或付款流程前，先读官方安全文件里的认证保管库、网域白名单与操作政策，不要把真实凭证写进脚本或贴到不信任的页面。
• 守护进程会闲置退出：预设闲置一小时后无头浏览器会被关闭，需要长时间保留会话时，先设定好会话持续化。
• 它仍在快速迭代：命令与个别功能以后可能调整；遇到与本教程不一致的地方，以官方文件为准。

六、官方资源连结

• GitHub 项目：https://github.com/vercel-labs/agent-browser
• 官方网站与文件：https://agent-browser.dev
• 快速入门：https://agent-browser.dev/quick-start

七、常见问题

Agent Browser 是免费的吗？

是。项目采用 Apache-2.0 许可证，开源免费，npm 与 Homebrew 都能直接安装。

它和 Playwright、Puppeteer 有什么不同？

Playwright、Puppeteer 是给程式呼叫的函式库，要写脚本；Agent Browser 是给 shell 与 AI 智能体用的 CLI，每一步都是一条短命令，智能体可以「看快照、做决定、下命令」循环操作，不用一次写完整段脚本。

一定要装 Node.js 吗？

npm 安装路线需要 Node.js；专案本身是 Rust CLI，但官方发行走 npm 与 Homebrew，npm 随 Node.js 一起提供。

不装 CLI 也能试吗？

可以。执行 npx agent-browser open example.com 就能免安装试用，但每次都会重新下载执行环境，长期用建议正式安装。

快照里的 @e1 是什么？

它是快照当时页面元素的编号，用来让命令指名操作目标；页面变化后编号失效，要重新快照。

它能接 Claude Code 这类智能体工具吗？

可以。执行 agent-browser skills get core 取得技能说明，或用 npx skills add vercel-labs/agent-browser 安装发现技能；MCP 客户端则用 agent-browser mcp 启动 MCP 伺服器。

截图存在哪里？

不给档名时存到暂存目录；agent-browser screenshot page.png 这类写法会存到你指定的路径。

支援哪些平台？

原生二进位档支援 macOS（ARM64、x64）、Linux（ARM64、x64，glibc 与 musl）与 Windows（x64）。