agent-browser 入门与踩坑指南

在 WSL2 Ubuntu 22.04 VS Code Remote SSH 环境下使用 agent-browser 操控 Vite React FastAPI 全栈应用的完整学习记录。基础认知agent-browser 是什么agent-browser 是一个通过 Chrome DevTools Protocol (CDP) 控制浏览器的 CLI 工具。本质是AI 代替人手工操作浏览器手工操作agent-browser 命令打开浏览器 → 输入网址agent-browser open url看页面内容agent-browser snapshot -i点击按钮agent-browser click e3在输入框打字agent-browser type e7 hello等页面加载完agent-browser wait --load networkidle截图agent-browser screenshot三层架构SkillClaude Code 的说明书 来源: skills.sh/vercel-labs/agent-browser 作用: SKILL.md 文档告诉 Claude Code 正确的工作流和最佳实践 不安装任何可执行程序 agent-browser CLIRust 编译的二进制 ~11MB 安装: npm i -g agent-browser 作用: 提供 open / snapshot / click / type 等命令 通过 CDP 协议控制浏览器本身不捆绑浏览器 Chrome for Testing浏览器本体 ~177MB 安装: agent-browser install 作用: 下载完整的 Chrome 浏览器供 CLI 驱动Chrome for Testing 和日常 Google Chrome 是同一套代码构建有完整的 H.264/AAC 编解码器和 Widevine DRM。区别在于去掉了自动更新、默认浏览器设置、用户数据上报等功能专为自动化测试设计。它不是纯 Chromium纯 Chromium 缺少专利编解码器。无界面 vs 有界面 vs 远程观察agent-browser 默认 headless无界面加--headed可弹出浏览器窗口agent-browser--headedopenhttp://localhost:5173/但在 VS Code Remote SSH 到远程 Linux 的场景下--headed无效。因为 Chrome 需要 X Server 渲染窗口而远程 Linux 服务器没有显示器。WSL2 虽有基本图形支持--headed往往也只是闪一下就消失。解决方案dashboardagent-browser 自带了 Web 版实时监控面板# 1. Linux 上启动 dashboard默认端口 4848agent-browser dashboard start# 2. VS Code 中转发端口# PORTS 面板 → Add Port → 输入 4848# 或 CtrlShiftP → Forward a Port → 4848# 3. Windows 本地浏览器打开 http://localhost:4848# 可实时看到页面跳转、点击、输入等所有操作端口转发原理Windows 浏览器 SSH 隧道 Linux 服务器 localhost:4848 ──────→ VS Code 自动转发 ──────→ localhost:4848 (dashboard)三种观察方式总结方式适用场景Token 消耗snapshot -i日常自动化读结构足够~200-400 tokensscreenshot确认特定步骤的页面状态1 张图片dashboard实时观察完整交互过程无需 token坑 1WebFetch 全部失败现象✗ Unable to verify if domain www.skills.sh is safe to fetch. This may be due to network restrictions or enterprise security policies blocking claude.ai.无论目标网站是国内还是国外百度、B站、example.com全部失败。根因WebFetch 的域名安全验证服务跑在claude.ai基础设施上和模型 API如api.deepseek.com是不同的网络路径。当claude.ai被网络阻断时所有 WebFetch 调用在验证阶段就失败了跟目标网站无关。诊断# curl 走系统网络栈能正常访问curl-s-o/dev/null-wHTTP %{http_code}https://www.skills.sh/# WebFetch 走 Claude 验证层全部失败解决推荐方案安装web-fetchskill通过find-skills搜索可找到0xbigboss/claude-codeweb-fetch803 installs。它使用curl HTML→Markdown 转换器获取网页内容curl走系统网络栈完全绕过 Claude 验证层# 1. 安装 skillnpx skillsadd0xbigboss/claude-codeweb-fetch# 2. 安装 HTML→Markdown 转换器npminstall-ghtml2markdown# 3. 正常获取网页curl-sLhttps://example.com|html2markdown --include-selectorarticle,main备选方案让 Claude Code 走代理访问 Anthropic 验证服务。坑 2agent-browser 命令全部挂起现象agent-browseropenhttp://localhost:5173/# 挂起无任何输出最终超时诊断步骤 1 — 查 daemon 日志cat/run/user/$(id-u)/agent-browser/default.log输出[chrome-search] browsers_dir~/.agent-browser/browsers [chrome-search] browsers_dir does not exist [chrome] Launch attempt 1/3 failed, retrying in 500ms... [chrome] Launch attempt 2/3 failed, retrying in 500ms...步骤 2 — 查系统 Chrome 兼容性/snap/chromium/3423/usr/lib/chromium-browser/chrome--version# GLIBC_2.38 not found (required by ...)# 系统 GLIBC 2.35snap Chromium 需要 2.38根因agent-browser install从未执行过~/.agent-browser/browsers/目录不存在系统上也没有兼容的 Chrome/Chromium 可用。解决agent-browserinstall如果下载太慢见坑 3手动下载替代。坑 3Chrome for Testing 下载极慢现象从storage.googleapis.com下载 177MB 文件30 秒仅 25%随后不断重试并最终失败。解决用国内镜像手动下载# 从 npmmirror阿里云镜像下载约 30 秒完成mkdir-p~/.agent-browser/browserswget-O~/.agent-browser/browsers/chrome-linux64.zip\https://cdn.npmmirror.com/binaries/chrome-for-testing/149.0.7827.22/linux64/chrome-linux64.zipcd~/.agent-browser/browsersunzip-ochrome-linux64.zip# 验证~/.agent-browser/browsers/chrome-linux64/chrome--version# Google Chrome for Testing 149.0.7827.22版本号149.0.7827.22需和当前agent-browser版本匹配。可先执行agent-browser --version查看 CLI 版本再到 Chrome for Testing 查找对应的 Chrome 版本号。直接用 CLI 版本对应的 Chrome 即可。持久化配置不要每次都写export AGENT_BROWSER_EXECUTABLE_PATH...写入全局配置一劳永逸echo{\executablePath\:\$HOME/.agent-browser/browsers/chrome-linux64/chrome\}\~/.agent-browser/config.jsonagent-browser 配置加载优先级低 → 高~/.agent-browser/config.json— 用户级默认./agent-browser.json— 项目级覆盖可提交到 git 团队共享环境变量 — 覆盖配置文件CLI 参数 — 覆盖一切配置后直接使用agent-browseropenhttp://localhost:5173/# 自动读取 config坑 4React 表单 fill 不生效现象agent-browser fill e7Zhang Sanagent-browser fill e8zhangsanexample.comagent-browser click e10# 点 Submit输入框显示已填入但 API 返回 400 校验错误 —fill设置了 HTML 元素value属性但没有触发 React 的 onChange 事件组件状态未更新。诊断agent-browser network requests--filter/api/contact# 只有一次 POST 返回 400是之前空表单的旧请求# 说明后续点击并未触发新的 POST解决# type 产生真实键盘事件正确触发 React onChangeagent-browsertypee7Wang Wuagent-browsertypee8wangwutest.comagent-browsertypee9Hello from agent-browser!agent-browser click e10React / Vue / SPA 框架 → 用type传统 HTML 表单 → 用fill核心工作流标准循环agent-browseropenurl# 1. 打开页面agent-browser snapshot-i# 2. 快照获取 eN 引用agent-browser click e3# 3. 操作agent-browser snapshot-i# 4. 页面变化后必须重新快照每次 snapshotrefs 都会重新分配。页面只要变化导航、提交、弹窗、DOM 更新旧 ref 立即失效。永远不要跨 snapshot 复用 ref。常用命令# ── 页面 ──agent-browseropenurl# 打开agent-browser reload# 刷新agent-browser close# 关闭# ── 读取 ──agent-browser snapshot-i# 可交互元素agent-browser snapshot-i-d3# 限制深度agent-browser get value e7# input 值agent-browser get text e1# 可见文字# ── 操作 ──agent-browser click e3# 点击agent-browsertypee7text# 逐键输入SPA 用这个agent-browser fill e7text# 清空设值传统 HTMLagent-browser press Enter# 按键agent-browser check e9# 勾选# ── 等待比 sleep 可靠──agent-browserwait--textSuccess# 等文字出现agent-browserwait--url**/dashboard# 等 URL 变化agent-browserwait--loadnetworkidle# 等网络空闲# ── 语义定位不需先 snapshot──agent-browserfindrole button click--nameSubmitagent-browserfindtextSign Inclick agent-browserfindlabelEmailfillusertest.com# ── 调试 ──agent-browser network requests--filter/api/# 网络请求agent-browser console# 控制台agent-browser screenshot debug.png# 截图agent-browser dashboard start# 实时面板等待策略Agent 失败更多是因为等待不足而非选择器错误场景等待方式SPA 页面导航wait --load networkidle表单提交成功wait --text 成功提示URL 跳转wait --url **/目标路径动态元素出现wait 新元素的ref实在没办法wait 500最后手段完整实战记录以下在 Vite React (localhost:5173) FastAPI (localhost:8000) 应用上的完整操作序列。注意以下eN引用仅作示例实际值取决于当前页面的 snapshot 结果。1. 打开首页 → 快照agent-browseropenhttp://localhost:5173/ agent-browser snapshot-i输出示例- link Home [refe2] - link Todos [refe3] - link Contact [refe5] - heading Welcome to the Demo App [level1, refe6]2. 导航到 Todos → 操作列表agent-browser click e3# 点 Todos 链接agent-browserwait--loadnetworkidle agent-browser snapshot-i# 重新快照获取新 refs3. 添加 TodoReact 表单用 typeagent-browsertypee7Learn agent-browseragent-browser click e8# Add 按钮agent-browser snapshot-i# 确认新增4. Toggle 勾选 Delete 删除agent-browser click e10# 勾选新 todoagent-browser click e13# 删除某条 todoagent-browser snapshot-i# 确认变化5. Contact 表单验证# 导航agent-browser click e5 agent-browserwait--loadnetworkidle agent-browser snapshot-i# 提交空表单 → 期望出现验证错误agent-browser click e10 agent-browserwait--textName is required# 正确填写agent-browsertypee7Wang Wuagent-browsertypee8wangwutest.comagent-browsertypee9Hello from agent-browser!agent-browser click e10 agent-browserwait--textThanks环境信息项目版本/信息OSUbuntu 22.04.5 LTS (WSL2)连接方式VS Code Remote SSHGLIBC2.35agent-browser0.27.0Chrome for Testing149.0.7827.22前端Vite 8 React 19 React Router 7后端FastAPI (Python 3.10)备忘清单新环境安装npm i -g agent-browser agent-browser installChrome 下载慢 → npmmirror 镜像手动下载写入~/.agent-browser/config.json避免每次 exportRemote SSH 环境用dashboard代替--headedSPA 表单 →type不fill页面变化 → 立即snapshot -i调试先看network requests确认 API 是否被调用daemon 异常时查日志cat /run/user/$(id -u)/agent-browser/default.log清理残留 daemonrm -rf /run/user/$(id -u)/agent-browser先wait再snapshot不要反过来