跳到主要内容

Agent Browser 快速上手指南

简介​

Agent Browser 是 Vercel 开发的浏览器自动化 CLI 工具，用于 AI 代理与网站交互。

安装​

npm install -g @vercel/agent-browser

或直接使用 npx：

npx @vercel/agent-browser <command>

核心概念：元素引用 (@e1, @e2, ...)​

这是 Agent Browser 最核心的概念！每次执行 snapshot -i 后，页面上的可交互元素会获得引用编号如 @e1、@e2、@e3 等。

示例输出：

@e1 [input type="email"] placeholder="邮箱"
@e2 [input type="password"] placeholder="密码"
@e3 [button] "登录"
@e4 [a] "忘记密码?"
@e5 [checkbox] "记住我"

核心命令速查​

导航与控制​

命令说明
agent-browser open <url>打开网页
agent-browser close关闭浏览器
agent-browser snapshot -i获取页面元素快照（最重要！）

交互操作（必须先 snapshot 获取 @e1 引用）​

命令说明
agent-browser click @e1点击元素
agent-browser click @e1 --new-tab点击并在新标签页打开
agent-browser fill @e1 "text"清除并输入文本
agent-browser type @e1 "text"输入文本（不清除）
agent-browser select @e1 "option"选择下拉选项
agent-browser check @e1勾选复选框
agent-browser uncheck @e1取消勾选
agent-browser hover @e1悬停元素
agent-browser drag @e1 @e2拖拽元素
agent-browser upload @e1 file.pdf上传文件
agent-browser scroll down 500向下滚动
agent-browser press Enter按键

获取信息​

命令说明
agent-browser get text @e1获取元素文本
agent-browser get value @e1获取输入框值
agent-browser get html @e1获取元素 HTML
agent-browser get attr @e1 href获取元素属性
agent-browser get url获取当前 URL
agent-browser get title获取页面标题

等待​

命令说明
agent-browser wait @e1等待元素出现
agent-browser wait --load networkidle等待网络空闲（最常用！）
agent-browser wait --url "**/dashboard"等待 URL 匹配
agent-browser wait 2000等待毫秒数

捕获与状态​

命令说明
agent-browser screenshot截图
agent-browser screenshot --full整页截图
agent-browser screenshot --annotate带编号标注的截图
agent-browser pdf output.pdf保存为 PDF
agent-browser state save login.json保存登录状态
agent-browser state load login.json加载登录状态

语义定位器（替代 @e1 引用）​

当元素引用不可靠时，可以使用语义定位器：

agent-browser find text "登录" click
agent-browser find label "邮箱" fill "user@test.com"
agent-browser find placeholder "搜索" type "查询内容"
agent-browser find role button click --name "提交"
agent-browser find testid "submit-btn" click

标准工作流（必须牢记！）​

1. agent-browser open <url>
2. agent-browser snapshot -i         # 获取 @e1, @e2, @e3... 引用
3. agent-browser click/fill @e1     # 使用引用进行操作
4. agent-browser snapshot -i        # 页面变化后重新获取引用！
5. agent-browser click/fill @e1     # 继续操作

常用工作流​

打开网站并截图​

agent-browser open https://www.baidu.com && agent-browser screenshot

登录网站并保存状态​

# 1. 打开登录页
agent-browser open https://example.com/login

# 2. 获取元素（必须！）
agent-browser snapshot -i
# 输出: @e1 [input], @e2 [input], @e3 [button]

# 3. 填写表单（使用引用）
agent-browser fill @e1 "username"
agent-browser fill @e2 "password"
agent-browser click @e3

# 4. 等待导航完成
agent-browser wait --url "**/dashboard"

# 5. 保存状态
agent-browser state save login.json

复用登录状态​

# 加载之前保存的状态
agent-browser state load login.json
agent-browser open https://example.com/dashboard

推荐：使用 Auth Vault（更安全）​

# 保存凭据（加密）
echo "password" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 使用保存的凭据登录
agent-browser auth login github

⚠️ 重要坑点汇总​

⚠️ 坑1：元素引用失效（最常见！）​

问题: 执行 click @e1 后，再执行 click @e2 失败

原因: 每次页面变化（点击、导航、表单提交）后，原来的 @e1、@e2 引用都会失效！

解决: 每次操作后重新执行 snapshot -i 获取新引用！

# ❌ 错误：连续使用旧引用
agent-browser click @e1
agent-browser fill @e2 "text"  # 会失败！

# ✅ 正确：每次页面变化后重新 snapshot
agent-browser click @e1
agent-browser snapshot -i        # 重新获取引用！
agent-browser fill @e2 "text"   # 使用新引用

⚠️ 坑2：权限问题​

问题: 执行命令时报错 Bash command permission check failed

解决: 在 .claude/settings.local.json 配置权限

{
  "permissions": {
    "allow": [
      "Skill(agent-browser)",
      "Bash(npx agent-browser:*)",
      "Bash(agent-browser:*)"
    ]
  }
}

或者：直接在终端输入命令，不使用 Skill 调用

agent-browser open https://www.baidu.com

⚠️ 坑3：Skill 调用失败​

问题: 使用 Skill 调用时仍然报权限错误

解决: 重启 Claude Code 会话让权限生效

⚠️ 坑4：状态保存路径​

问题: 保存的状态找不到

解决: 状态默认保存在 ~/.agent-browser/sessions/ 目录

agent-browser state list    # 列出所有状态
agent-browser state show xxx # 查看状态详情

⚠️ 坑5：会话冲突​

问题: 再次运行时浏览器冲突

解决: 使用 --session-name 命名隔离

agent-browser --session-name myapp open https://example.com
agent-browser close  # 关闭会话

⚠️ 坑6：慢速页面加载​

问题: 页面还没加载完就执行操作导致失败

解决: 使用 wait --load networkidle 等待加载

agent-browser open https://example.com
agent-browser wait --load networkidle  # 等待页面完全加载
agent-browser snapshot -i

⚠️ 坑7：命令中的特殊字符​

问题: 命令中包含 !、反引号等导致权限报错

解决: 使用 --stdin 或 base64 编码

快捷命令模板​

# 基础：打开网站
agent-browser open <url>

# 完整工作流
agent-browser open <url> && agent-browser wait --load networkidle && agent-browser snapshot -i

# 打开 + 截图
agent-browser open <url> && agent-browser wait --load networkidle && agent-browser screenshot

# 登录流程
agent-browser open <url>/login && agent-browser wait --load networkidle && agent-browser snapshot -i

相关资源​