1. 为什么 AI Agent 操作网页总在 CSS 选择器上翻车先说一个我踩过的坑。去年帮朋友做一个自动填表的小 Agent本地跑得好好的上线第二天全挂。排查半天发现是目标网站把提交按钮的 class 从btn-primary改成了btn-main选择器直接失效。这类问题在 AI Agent 场景里特别致命因为 Agent 不像人一样能看一眼就知道按钮在哪它只能靠你给的选择器去猜。传统方案是让大模型生成 Playwright 或 Puppeteer 脚本模型输出一堆page.click(#submit-btn div:nth-child(2))这样的代码。问题有三个第一模型对 DOM 结构的理解是想象出来的它没真正看过页面第二选择器一旦写死页面结构微调就崩第三多步操作时每一步都要重新定位元素Token 消耗大且容易累积错误。Vercel 开源的 agent-browser 就是冲着这个痛点来的。它是什么一句话一个专门给 AI Agent 用的浏览器自动化 CLI 工具用 Rust 写核心、Node.js 管浏览器实例通过 refs 机制让 Agent 用指哪打哪的方式操作页面而不是猜 CSS 选择器。能做什么打开网页、点击元素、输入文本、截图、管理 Cookie、多 Tab 切换、Session 隔离大概 50 多个命令。适合谁正在做 E2E 测试自动化、网页数据采集、表单填写类 Agent 的开发者尤其是那些被选择器稳定性折磨过的人。它的核心思路是运行snapshot命令时工具给页面上每个可交互元素打一个唯一标签比如e1、e2Agent 拿到的是一份元素清单操作时直接说点击 e2就行。底层 DOM 怎么变只要元素还在ref 就能重新映射。这跟人眼看页面点按钮的逻辑是一致的。接下来我会带你从零装好这个工具配好环境变量跑通一次端到端验证最后把它接到 TaoToken 的统一 Key/API 通道上让 Agent 调用链路完整闭环。2. 安装 agent-browser 与 TaoToken 统一 Key 前置准备2.1 环境要求与安装命令agent-browser 依赖 Node.js 18 以上版本以及一个可用的 Chromium。先确认环境node -v # 期望输出 v18.x 或更高 npm -v安装 CLI 本身很简单官方推荐全局装npm install -g vercel-labs/agent-browser装完后验证agent-browser --version如果提示找不到命令检查 npm 全局 bin 目录是否在 PATH 里。macOS/Linux 一般是/usr/local/bin或~/.npm-global/binWindows 是%APPDATA%\npm。第一次运行任何命令时它会自动拉起一个 Node.js daemon 进程管理浏览器实例。这个 daemon 常驻后台后续命令响应几乎是毫秒级不用每次等浏览器冷启动。这也是它比直接写 Playwright 脚本快的原因之一。如果你在 serverless 环境比如 AWS Lambda里跑需要指定自定义 Chromium 路径export AGENT_BROWSER_CHROMIUM_PATH/opt/chromium本地开发一般不用管它会用系统自带的或自动下载的 Chromium。2.2 为什么需要 TaoToken 统一 Key装好工具只是第一步。真正让 Agent 跑起来你还得给它接一个大模型来决策——Agent 看到 snapshot 返回的元素清单后得有个模型告诉它下一步点哪个 ref、输入什么内容。这时候就会遇到多模型切换、Key 管理分散的问题。TaoToken 在这里的角色是统一 Key/API 通道。你可以把它理解成一个聚合入口不管底层用哪个模型Agent 侧只需要配一个 Base URL 和一个 Key切换模型时改 Model ID 就行不用到处改代码里的 endpoint 和密钥。官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。对 agent-browser 这种需要频繁调用模型做决策的场景统一通道的好处很直接调试时换模型不用重启 daemon生产环境做灰度也不用改 Agent 代码。2.3 获取 Key 与配置环境变量先去控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后在 API Keys 页面复制 Key然后配置到环境变量里。建议写进~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-5Model ID 按你实际要用的填具体可用列表在文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite配完执行source ~/.zshrc生效。到这里前置准备就完成了工具装好、Key 拿到、环境变量配好接下来进入实际配置环节。3. 可复制配置settings.json 与 SKILL.md 接入3.1 给 Claude Code 配置 Skill 文件agent-browser 官方提供了一个适配 Claude Code 的 Skill 文件把它放进项目里Claude Code 就能自动学会怎么调用这套工具。先建目录mkdir -p .claude/skills/agent-browser然后把官方 SKILL.md 下载进去curl -o .claude/skills/agent-browser/SKILL.md \ https://raw.githubusercontent.com/vercel-labs/agent-browser/main/skills/agent-browser/SKILL.md这个文件里定义了工具的命令用法、参数说明和调用约定Claude Code 读取后会把它作为可用工具集的一部分。你不用再手写 Prompt 教它怎么点按钮它自己就知道该用agent-browser click e2这种形式。3.2 settings.json 配置模型通道Claude Code 的模型配置在~/.claude/settings.json全局或项目级.claude/settings.json。要让请求走 TaoToken 通道配置如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意这里三个字段缺一不可Base URL 指向 TaoToken 的 API 地址API Key 用你在控制台创建的那个Model ID 填你要用的模型。如果你用的是 Cline 或 Roo Code 这类支持 MCP 的编辑器配置方式类似在 MCP 设置里填{ mcpServers: { taotoken: { url: https://taotoken.net/api, headers: { Authorization: Bearer sk-你的key } } } }如果你用的是 Codex配置写在~/.codex/auth.json{ OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_API_KEY: sk-你的key, OPENAI_MODEL: gpt-4o }三件套永远是 Base URL Key Model ID换工具不换逻辑。3.3 agent-browser 的运行时配置agent-browser 本身也支持一些环境变量来调整行为。常用的几个# 指定 Chromium 路径serverless 环境用 export AGENT_BROWSER_CHROMIUM_PATH/path/to/chromium # 设置默认超时毫秒 export AGENT_BROWSER_TIMEOUT30000 # 开启视觉降噪只返回交互元素 export AGENT_BROWSER_FILTER_INTERACTIVEtrue视觉降噪这个特别实用。有些页面元素几百个全喂给模型既费 Token 又容易让它分心。开启过滤后snapshot 只返回可点击、可输入的元素Agent 的决策准确率明显提升。配置写完后建议用一个简单的命令验证 daemon 能正常拉起agent-browser open https://example.com --json如果返回了结构化的 JSON 数据说明工具链和配置都通了。接下来进入端到端验证。4. 端到端验证从 snapshot 到点击的完整请求4.1 打开页面并获取元素快照先打开一个测试页面。用 example.com 最稳妥结构简单不会干扰验证agent-browser open https://example.com然后运行 snapshot 拿元素清单agent-browser snapshot返回结果类似这样- link More information... [refe1] - heading Example Domain [refe2]每个可交互元素都有唯一 ref。Agent 拿到的就是这份清单它不需要知道 CSS 选择器只需要说点击 e1。加--json参数可以拿到结构化输出方便程序解析agent-browser snapshot --json返回的 JSON 里包含元素类型、文本、ref、位置等信息。你的 Agent 代码可以直接解析这个 JSON把元素列表塞进 Prompt 让模型决策。4.2 执行点击与输入操作拿到 ref 后操作就是一行命令agent-browser click e1输入文本agent-browser type e3 helloexample.com等待页面加载agent-browser wait 500截图存档agent-browser screenshot ./result.png这些命令都可以组合成一个脚本让 Agent 按决策结果依次调用。比如一个登录流程agent-browser open https://example.com/login agent-browser snapshot --json elements.json # Agent 读取 elements.json决策出要填的 ref agent-browser type e2 usertest.com agent-browser type e3 password123 agent-browser click e4 agent-browser wait 1000 agent-browser screenshot ./login-result.png4.3 接入 TaoToken 完成模型调用验证上面是浏览器侧的操作。模型侧你需要让 Agent 把 snapshot 结果发给模型拿到决策后再执行命令。用 curl 验证 TaoToken 通道是否通curl https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 1024, messages: [ {role: user, content: 页面元素清单link More information [refe1]。请告诉我点击哪个 ref 能跳转到详情页只返回 ref 编号。} ] }如果返回了正常的模型响应说明 TaoToken 通道工作正常。把这段调用逻辑封装进你的 Agent 代码就形成了完整闭环snapshot 拿元素 → 发给模型决策 → 执行 agent-browser 命令 → 再 snapshot 验证结果。想直接在网页上试模型对话效果可以用https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你要做长期的编码类 Agent考虑 Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite5. 常见报错排查401、local proxy failed 与 OAuth5.1 401 Unauthorized这是最常见的。报错长这样Error: 401 Unauthorized - invalid api key原因通常是 Key 没配、配错或者环境变量没生效。排查步骤先确认echo $TAOTOKEN_API_KEY能打印出 Key再确认 settings.json 里的 Key 和你在控制台创建的一致最后检查是不是有多余空格或换行。如果用的是 Claude Code注意它读的是ANTHROPIC_API_KEY而不是TAOTOKEN_API_KEY两个变量名别搞混。还有一种情况是 Key 权限不足。去控制台确认这个 Key 有没有对应模型的调用权限。5.2 local proxy failed报错Error: local proxy failed to start这个一般出现在 agent-browser 启动 daemon 时。原因可能是端口被占用或者 Chromium 路径不对。先检查有没有残留的 daemon 进程ps aux | grep agent-browser有的话 kill 掉再重试。如果是 serverless 环境确认AGENT_BROWSER_CHROMIUM_PATH指向的 Chromium 确实存在且可执行。本地开发遇到这个试试删掉缓存目录重来rm -rf ~/.agent-browser/cache agent-browser open https://example.com5.3 reading choices 报错报错Error: reading choices: unexpected end of JSON input这是模型返回的 JSON 格式不对Agent 解析失败。常见于模型输出被截断或者 Prompt 里没明确要求返回 JSON。解决办法在 Prompt 里加一句只返回 JSON不要有其他文字同时把max_tokens调大一点。如果用的是 TaoToken 通道确认 Model ID 填对了不同模型对 JSON 输出的支持程度不一样。5.4 OAuth 相关报错报错Error: OAuth token expired如果你用的是 Claude Code 的 OAuth 登录方式token 过期后会报这个。但既然我们走的是 TaoToken 的 API Key 通道理论上不该出现 OAuth 报错。如果出现了说明 Claude Code 还在用旧的 OAuth 配置检查 settings.json 里是不是同时存在 OAuth 相关字段和 API Key 字段把 OAuth 那部分删掉只保留ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY。排查完这些基本能覆盖 90% 的接入问题。核心原则就一条Base URL、Key、Model ID 三件套必须一致且完整。6. 把 agent-browser 接进你的 Agent 工作流装好、配好、验证通过之后接下来是怎么把它用起来。我的建议是从小场景开始别一上来就搞复杂的多步流程。先拿一个固定页面练手比如每天抓一次某个公开数据页。用 agent-browser 的 snapshot 拿元素让模型决策点哪个 ref执行点击后截图存档。跑通这个最小闭环再逐步加步骤。Session 隔离这个特性值得单独说。如果你要测用户 A 和用户 B 同时在线的场景不用开两个浏览器窗口直接指定不同 Sessionagent-browser open https://example.com --session userA agent-browser open https://example.com --session userB两个 Session 的 Cookie 互不干扰切换时加--session参数就行。这对做多账号测试的 Agent 特别有用。视觉降噪也建议默认开着。页面元素越多模型决策越容易出错Token 消耗也越大。开启过滤后只返回交互元素准确率和成本都能改善。最后如果你要把这套东西部署到生产环境记得把 daemon 做成常驻服务别每次调用都冷启动。TaoToken 的 Coding Plan 适合长期跑的 Agent 场景Key 和通道都统一管理省得后面换模型时到处改配置。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI Key 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite工具装好只是开始真正省心的是把模型通道也统一掉。这样你的 Agent 代码里只有一套 Base URL 和 Key换模型、做灰度、排查问题都简单得多。