1. 为什么 browser-use 跑起来像“会点网页的模型”却总在真实页面翻车browser-use 是一个把浏览器控制、LLM 决策、DOM 解析和 CDP 底层能力放在同一工程表面的浏览器 Agent 框架。它能做什么简单说你给它一句自然语言任务它会自己观察页面、决定下一步点哪里、输入什么、什么时候提取结果。适合谁适合想把重复网页操作交给 Agent 的开发者、做自动化测试的工程师以及正在把 Claude Code、Codex、Cursor 这类宿主接上真实浏览器的团队。但我试过几次之后发现一个共性问题demo 里点得挺顺一换真实页面就开始乱点、重复点、卡在弹窗上最后还告诉你“任务完成”。这不是模型不聪明而是你根本没告诉它“什么算完成、什么必须停、什么动作根本不允许做”。browser-use 的工作方式不是一次性脚本而是一个循环观察当前页面 → 把页面状态转成模型可读结构 → LLM 决定下一步 → 执行 navigate/click/input/extract/screenshot → 记录历史 → 再进入下一轮。这个循环里真正关键的是“状态如何被看见”。DOM、截图、tab、弹窗、下载、cookie banner、hover 菜单、权限弹窗都会影响下一步。所以判断一个 browser-use 工作流能不能上手不是看它点了多少按钮而是看它能不能留下证据每一步为什么执行、当前 URL 和交互元素是什么、失败后能不能复盘上一步、结果是否经过断言、是否保存了 history 和截图。没有这些浏览器 Agent 就只是一个速度更快的远程鼠标。这篇要解决的就是这件事先给浏览器 Agent 设计一份执行契约把 LLM 的意图转成可校验的动作序列再通过 TaoToken 统一 Key/API 通道接入完成一次端到端跑通。核心检索词就是 browser-use 执行契约设计下面全部围绕它展开。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写契约之前先把模型通道准备好。browser-use 本身不绑定某一家模型它通过 LLM provider 层去调模型。你可以用 OpenAI、Anthropic、Azure也可以用兼容 OpenAI 协议的统一通道。这里我用 TaoToken 的统一 Key/API 通道好处是一个 Key 走通多家模型切换模型不用改一堆环境变量。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址https://taotoken.net/api第一步拿到 Key。进入控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole创建完在 API Keys 页面复制https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys第二步确认你要用的模型 ID。browser-use 里模型 ID 是字符串写错会直接报 provider 初始化失败。你可以在模型对话页先验证模型能不能通https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat第三步把 Base URL 和 Key 写进环境变量。browser-use 走 OpenAI 兼容协议时通常读OPENAI_API_KEY和OPENAI_BASE_URL。注意 Base URL 末尾不要多加/v1之外的路径具体以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你打算长期跑编码类或 Agent 类任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan这里有个前置判断browser-use 的失败经常不是模型不聪明而是执行环境没声明清楚。所以在接模型之前先写下这些配置事实——用哪个 provider、是否启用 judge LLM、是否启用 planning 和 loop detection、每步 timeout 多少、是否允许真实 browser profile、是否允许文件下载、失败日志存哪里。这份清单比“让它完成一个炫酷任务”重要得多。3. 可复制配置动作白名单、超时重试与状态断言模板这一节是全文核心。执行契约的本质是把“LLM 想干什么”翻译成“系统允许它干什么、干完怎么校验”。我把它拆成三块动作白名单、超时与重试、状态断言。下面给一份可直接复制的 JSON 契约模板。{ contract_version: 1.0, task_id: readonly_extract_demo, allowed_actions: [ navigate, click, input, extract, screenshot, scroll ], denied_actions: [ evaluate, download, upload, submit_payment, delete ], action_rules: { click: { require_target_description: true, require_post_check: true, max_repeat_same_target: 2 }, input: { allow_sensitive_fields: false, mask_in_log: true }, navigate: { allowed_domains: [example.com, docs.example.com], block_redirect_to_unknown: true } }, timeouts: { per_step_ms: 15000, per_task_ms: 180000, navigation_ms: 30000 }, retry: { max_attempts: 2, backoff_ms: 1500, retry_on: [navigation_timeout, element_not_found] }, assertions: [ { name: page_loaded, type: url_contains, value: example.com }, { name: title_present, type: dom_text_present, selector: h1 }, { name: no_error_banner, type: dom_text_absent, value: 500 Internal Server Error } ], stop_conditions: [ assertion_failed_twice, denied_action_requested, per_task_timeout, unknown_domain_navigation ], evidence: { save_screenshot_each_step: true, save_dom_markdown: true, save_history: true, log_dir: ./agent_logs } }这份契约里几个关键点值得展开。动作白名单不是限制能力而是限制风险面。evaluate在很多受限 profile 下会被拒绝这是安全收紧不是功能坏了。download、upload、submit_payment、delete这类动作首轮测试一律不给。click 规则里require_target_description强制 Agent 在点击前说明目标元素require_post_check强制点击后检查页面变化max_repeat_same_target防止它卡在同一个按钮上反复点。超时与重试要分层。per_step_ms管单步navigation_ms管导航per_task_ms管整个任务。重试只对可恢复错误生效比如导航超时、元素找不到。对断言失败不要盲目重试重试两次还失败就应该停把证据交给人。状态断言是“凭什么认为任务完成”的答案。url_contains确认页面到了dom_text_present确认关键内容在dom_text_absent确认没有错误横幅。断言失败两次触发assertion_failed_twice停止条件。如果你用 TOML 管理配置可以这样写[contract] version 1.0 task_id readonly_extract_demo [contract.timeouts] per_step_ms 15000 per_task_ms 180000 navigation_ms 30000 [contract.retry] max_attempts 2 backoff_ms 1500 [contract.evidence] save_screenshot_each_step true save_dom_markdown true log_dir ./agent_logs在 browser-use 里你可以把这份契约作为 Agent 的 system prompt 上下文注入也可以在工具层做拦截。更稳的做法是两层都做prompt 里告诉模型规则工具执行前再校验一次。这样即使模型“想”越界执行层也会拦住。4. 验证请求同一任务对比无契约与有契约的执行日志契约写好了得验证它真的起作用。方法很简单同一个任务跑两遍一遍不带契约一遍带契约对比执行日志。任务选一个只读的打开公开页面提取标题和主要链接。无契约版本Agent 的自由度很高。日志里你会看到它可能先点了一个 cookie banner又点了一个看起来像链接的普通文本导航到一个不在预期范围内的域名然后因为找不到目标元素开始重试最后在没有明确断言的情况下说“任务完成”。整个过程没有截图证据没有 URL 记录失败原因也说不清是网络、DOM、模型输出还是工具执行失败。有契约版本执行流会变成这样[step 1] actionnavigate targethttps://example.com assertionpage_loaded - pass (url_contains example.com) screenshotsaved step_1.png [step 2] actionextract targettitle assertiontitle_present - pass (dom_text_present h1) dom_markdownsaved step_2.md [step 3] actionclick target主要链接区域 target_description页面中部导航链接列表 post_checkurl_changed - pass screenshotsaved step_3.png [step 4] actionextract targetlinks assertionno_error_banner - pass historysaved [result] task_completedtrue evidence: 4 screenshots, 4 dom_markdown, history.json对比下来有契约的版本每一步都有动作、目标描述、断言结果和证据文件。失败时你能立刻定位到是哪一步、哪个断言没过、当时的 URL 和 DOM 是什么。这里演示一下通过 TaoToken 统一通道接入的配置。在 browser-use 的 LLM 配置里把 provider 指向 OpenAI 兼容协议import os from browser_use import Agent from browser_use.llm import ChatOpenAI os.environ[OPENAI_API_KEY] 你的 TaoToken Key os.environ[OPENAI_BASE_URL] https://taotoken.net/api llm ChatOpenAI( model你的模型ID, base_urlos.environ[OPENAI_BASE_URL], api_keyos.environ[OPENAI_API_KEY], ) agent Agent( task打开 example.com提取标题和主要链接不要点击任何提交按钮, llmllm, )跑之前先在模型对话页确认模型 ID 能通避免 provider 初始化就失败。跑起来后日志目录里应该出现截图、DOM markdown 和 history 文件。如果这些证据都在说明契约生效了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth接入和跑通过程中报错基本集中在这几类。逐个对照。401 Unauthorized。最常见的原因是 Key 没读到或 Base URL 写错。检查OPENAI_API_KEY是否真的注入到进程环境OPENAI_BASE_URL是否是https://taotoken.net/api。如果你在 Claude Code 或 Codex 里配置注意auth.json或 settings 里的字段名要和文档一致。三件套必须齐全Base URL、Key、Model ID。缺一个都可能 401 或 provider 初始化失败。local proxy failed。这个报错通常出现在本地网络层不是模型层。检查你的运行环境是否能正常访问 API 地址以及是否有本地端口冲突。browser-use 的 daemon unix socket 只允许 owner 访问如果你用多用户环境权限不对也会连不上。先确认单用户单进程能跑通再考虑 daemon 复用。reading choices 相关报错。这类错误多半是模型返回结构不符合预期比如本地模型返回空字符串触发 Pydantic JSON 校验失败。解决方向有两个换一个稳定返回 JSON 的模型或者在契约里加输出格式约束。browser-use 的 judge LLM 和 message compaction 也会影响输出结构如果开了这些功能先关掉跑最小任务确认基础链路通了再逐个打开。OAuth 相关报错。如果你在 Claude Code 或 Codex 里接入OAuth 流程和 API Key 流程是两套。用统一 Key 通道时优先走 API Key 模式避免 OAuth 回调地址和本地端口不一致。CC Switch 这类工具切换配置时确认它写入的 Base URL 和 Key 是当前生效的那一组。还有一个高频坑0.12.5 起litellm不再是 core dependency需要显式安装。如果你升级后突然报 import 错误先补装依赖。0.12.8 之后 restricted browser profile 会拒绝evaluate()这是安全收紧不要试图绕过改用 actor mouse 或受限动作。排查顺序建议先确认 Key 和 Base URL 三件套齐全再确认模型 ID 能通再看 browser-use 依赖版本最后看契约里的动作白名单是否拦掉了必要动作。每一步都留下日志别靠猜。6. 把执行契约接进你的 Agent 工作流到这里端到端已经跑通了TaoToken 统一 Key 提供模型通道browser-use 负责浏览器控制执行契约负责把 LLM 意图转成可校验的动作序列。接下来是怎么把它用起来。第一层验收只读浏览。任务就是打开公开页面、提取标题和链接。验收点不是摘要好不好看而是能不能打开页面、记录 URL、区分可点击元素和普通文本、失败时说明失败类型。第二层验收低风险交互。在测试页面填表单、切 tab、触发弹窗但不提交真实业务动作。验收点是点击前说明目标、点击后检查变化、能处理弹窗和加载延迟、避免重复点击。第三层验收有人工闸门的写操作。草稿保存、后台配置预览、发布前检查。最终提交按钮前必须停下输出提交前摘要给出截图或 DOM 证据明确哪些字段会被修改人工确认后再继续。这三层跑通之前不要让它碰真实生产账号。第一次接入只开放三个权限只读导航和截图、测试账号或临时 profile、临时目录文件读写。不要一上来就给主 Chrome profile、生产后台、真实支付权限。如果你要把 browser-use 放进 Claude Code、Codex、Cursor 这类宿主建议把契约文件放在项目根目录让宿主在动手前先读契约。你可以要求宿主先回答首轮需要哪些权限、哪些动作必须人工确认、哪些失败要立刻停、哪些能力没验证过不能宣称已跑通。这比直接把 README 丢给 Agent 更稳因为 README 解释怎么开始契约告诉你什么时候别继续。长期跑编码类或 Agent 类任务可以走 Coding Plan 通道https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan需要先验证模型输出质量去模型对话页https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat接入细节和字段说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后留一个实用判断标准浏览器 Agent 工作流值不值得继续投入看它能不能留下收据。收据要能回答三个问题——它看见了什么、它为什么这么做、它凭什么认为任务完成了。browser-use 提供了 AgentHistoryList、screenshots、judge、DOM markdown、step metadata 这些材料真正的工程工作是把这些材料接到你自己的验收标准里。先写契约再让它跑第一步。