browser-use 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

（browser-use）是一个以 Python 编写的开源浏览器自动化项目，目标是让人工智能代理能够像用户一样访问和操作网站。它通过浏览器打开页面、点击按钮、输入文字和填写表单，把自然语言任务交给代理执行。

仓库元信息显示：项目拥有 109086 个 Star 和 11977 个 Fork，默认分支为 main，许可证为 MIT，项目描述为“Make websites accessible for AI agents”。资料中的 Python 包版本为 0.13.7，要求 Python >=3.11,<4.0。

• 主要形态：Python 库、命令行工具（Command-Line Interface，CLI）以及 Docker 镜像构建文件。
• 任务输入：自然语言任务字符串，例如填写职位申请、提取关注者数据或测试本地网站。
• 执行结果：代理运行历史由 agent.run() 返回；具体结果结构需以当前文档和代码为准。
• 模型接入：资料列出了 Browser Use、OpenAI、Anthropic、Google、Groq、Ollama 等相关依赖或示例配置。
• 部署方式：可以安装到 Python 环境，也可以基于仓库中的 Dockerfile 构建容器。

定位与目标用户

本项目解决的是“让模型能够使用真实网页界面”的工程问题，而不是只处理静态 HTML 或只调用网站后端接口。代理接收任务描述后，通过浏览器交互完成页面级操作，因此适用于网页结构随用户操作变化的任务。

根据 README，项目面向两类使用者：一类是已经在使用 Claude Code、Codex、Cursor、Hermes 或 OpenClaw 等代理工具，希望让现有代理控制浏览器的用户；另一类是需要在软件中批量、定时或并行执行网页自动化任务的开发者。

• 需要将网页表单填写、公开数据整理或回归测试嵌入 Python 程序的团队。
• 希望通过自然语言描述操作流程，而不是为每个页面编写固定点击脚本的开发者。
• 需要在自有机器运行代理，并自行选择模型提供商和代理行为的工程团队。
• 需要使用命令行方式，把浏览器能力交给已有编码代理的个人开发者。

项目并不等于通用网站访问权限系统。它仍然需要浏览器环境、模型凭据、目标网站的授权以及对任务结果的人工或程序化校验。

核心功能

核心能力可以概括为“自然语言任务驱动的浏览器代理”。README 中列举的操作包括打开页面、点击控件、输入文本和填写表单；这些动作由代理根据页面状态逐步决定，而不是由示例代码硬编码成一组固定的鼠标坐标。

网页表单填写

用户可以把职位申请等流程描述为任务，并提供简历或个人信息作为输入。代理需要读取当前页面可交互元素，判断字段含义，再将信息写入表单；输出通常体现为页面状态变化或任务运行历史，资料没有规定统一的业务结果对象。

README 给出的示例文件为 examples/use-cases/apply_to_job.py。该能力依赖浏览器交互、页面内容提取和所选大语言模型（Large Language Model，LLM）的决策能力，实际字段映射仍受目标网站布局、验证规则和登录状态影响。

网页数据提取

数据提取场景把页面内容交给代理理解，再要求输出结构化数据，例如将关注者信息导出为 CSV。资料明确展示了“Extract structured data”用例，但没有提供该输出的完整字段定义、分页策略或 CSV schema，因此这些内容不能从仓库资料中推断。

pyproject.toml 注释说明，markdownify 用于提取页面文本并传递给 LLM；这说明页面文本转换是依赖链中的一个环节。需要稳定数据结构时，应在调用侧定义字段校验、空值处理和重复记录处理规则。

质量保证（Quality Assurance，QA）自动化

README 将“测试本地网站并报告缺陷、可用性问题和视觉不一致”列为 QA 自动化场景。触发方式是给代理一项测试任务，由代理访问目标页面并根据观察结果生成运行记录或报告；资料没有提供固定的报告格式，也没有声明测试覆盖率。

该功能适合测试环境中的探索式检查。对于发布阻断条件、精确像素差异或严格回归断言，仍应在调用方增加明确的断言和结果存档，不能仅依据自然语言总结判断构建是否通过。

命令行代理控制

项目在 pyproject.toml 中注册了 browser-use、browseruse、bu 和 browser 四个命令入口，它们都指向 browser_use.cli:main。README 还说明，CLI 适合已有编码代理执行“上传视频”“比较商品”“填写职位申请”等浏览器任务。

CLI 与 Python 库的差异在于调用边界：CLI 作为已有代理的技能或工具入口，Python 库则将代理对象嵌入应用程序。资料中另有 browser-use-tui 入口，但已标记为弃用别名，不应作为新集成的首选命令。

系统架构与关键模块

仓库资料能够确认的架构由代理层、浏览器控制层、模型适配层、配置与观测层组成。具体类之间的完整调用图、内部状态机和每个动作的重试策略，官方仓库资料未提供，建议以 开源库文档 和当前源代码为准。

代理与任务层

README 示例通过 Agent(task=..., llm=...) 创建代理，再以异步方法 await agent.run() 执行任务。任务字符串是高层输入，Agent 负责将它转化为浏览器操作流程；运行结果赋值给 history，但资料没有给出其具体类型和字段。

浏览器与页面交互层

pyproject.toml 将 cdp-use 列为依赖，并在构建配置中包含 browser_use/dom/**/*.js。据此可以确认项目包含基于 Chrome DevTools Protocol（CDP）的浏览器控制相关组件，以及 DOM（Document Object Model）处理代码；浏览器可执行文件路径、用户数据目录和无头模式通过环境变量提供配置入口。

模型适配层

示例使用 ChatBrowserUse，并注释列出了 ChatOpenAI 与 ChatAnthropic 的替代写法。依赖清单还包括 google-genai、openai、anthropic、groq 和 ollama，表明仓库为多种模型接入保留了依赖支持。

模型选择会影响代理对页面内容的判断，但资料没有给出所有模型的兼容矩阵、上下文限制、费用、延迟或成功率保证。README 提到的评测结果只代表其公开 benchmark 描述，不能直接当作任意任务的性能承诺。

命令行与技能层

pyproject.toml 将 CLI 入口统一映射到 browser_use.cli:main，并将 browser_use/skills/**/*.md 纳入构建包。README 的 Quickstart 还建议通过 browser-use skill install 注册技能，使外部编码代理能够调用浏览器能力。

云端接口与本地库边界

README 同时提供本地开源代理和托管云代理两条路径。仓库内的 Python 库强调自有机器、模型选择和代码级定制；云端路径则通过 https://api.browser-use.com/api/v4/runs 提交任务。云端接口的完整认证、请求字段、响应结构和服务限制不在本资料范围内，应查阅官方云文档。

依赖与运行环境

运行环境的最低 Python 要求来自 pyproject.toml：Python >=3.11,<4.0。仓库 Dockerfile 使用 python:3.12-slim 作为基础镜像，并安装 Chromium、字体和 Python 依赖；这为容器化运行提供了仓库内的可核查依据。

依赖清单还包含 mcp、pypdf、reportlab、pillow、python-docx 和 browser-use-sdk 等组件。可选依赖组包括 aws、oci、video、examples、eval 与 all；使用这些能力时应按仓库声明的 extras 安装，不能将可选依赖视为所有部署都必需。

快速开始：安装、运行与验证

最小闭环是安装 Python 包、准备模型 API 密钥、运行一个异步代理任务，再用版本命令验证 CLI 已安装。下面的命令来自 README 和 Dockerfile 中的真实用法，任务示例访问公开 GitHub 仓库并执行只读查询。

安装

uv add browser-use
# 或
pip install browser-use

项目要求 Python >=3.11。README 的 Quickstart 还给出了使用 uv、Python 3.12 和 browser-use skill install 的代理安装提示；如果通过已有编码代理安装，应让该代理按官方安装说明处理连接失败。

运行最小示例

import asyncio

from browser_use import Agent, ChatBrowserUse


async def main():
    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=ChatBrowserUse(model='openai/gpt-5.5'),
    )
    history = await agent.run()
    print(history)


if __name__ == "__main__":
    asyncio.run(main())

运行前，在当前项目目录创建 .env 并设置 BROWSER_USE_API_KEY=<你的-API-KEY>，或者按照 README 配置所选模型提供商的密钥。占位符不是有效凭据，不应提交到版本库；API 密钥应通过环境变量或受控密钥管理方式注入。

验证

browser-use --version

Dockerfile 的注释还给出了本地构建和运行方式：

git clone https://github.com/browser-use/browser-use.git
cd browser-use
docker build . -t browseruse --no-cache
docker run -v "$PWD/data":/data browseruse --version

以上容器命令只验证镜像和 CLI 运行，不代表已经完成模型配置或目标网站任务。Dockerfile 创建了非特权用户 browseruse，并将数据目录设置为 /data；容器中的浏览器访问、持久化数据和权限仍需结合实际部署进行检查。

配置说明

配置主要通过环境变量完成，示例来源于仓库的 .env.example。下表只列出资料中明确出现的字段；“未提供”表示示例没有给出默认值，而不是该字段一定没有内部默认行为。

代理与模型提供商的密钥字段还包括 OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY、DEEPSEEK_API_KEY、GROK_API_KEY 和 NOVITA_API_KEY。这些字段在示例中被注释，具体启用方式取决于所选模型实现；资料没有给出它们的默认模型映射。

代理配置还包括 BROWSER_USE_PROXY_SERVER、BROWSER_USE_NO_PROXY、BROWSER_USE_PROXY_USERNAME 和 BROWSER_USE_PROXY_PASSWORD。这些配置涉及网络边界和凭据，不能在日志、任务文本或公开代码中输出。

进阶用法

进阶使用的关键是将任务拆成可验证的业务步骤，并明确模型、浏览器配置和结果保存策略。README 展示了自有代码嵌入、CLI、云端代理和自定义工具等方向，但每个方向的完整 API 说明应以官方文档为准。

切换模型提供商

README 示例通过注释展示了 ChatBrowserUse、ChatOpenAI 和 ChatAnthropic 的使用位置。切换提供商时，需要同步替换 Python 导入、模型实例和对应的环境变量；只设置密钥而不替换 LLM 实例，不足以改变示例中的模型对象。

重复、调度与并行任务

README 将“按计划或并行运行许多任务”列为使用 Python 库的场景，示例包括抓取、监控和 QA。资料没有提供调度器、并发参数、队列实现或资源上限，因此应由应用侧负责任务排队、并发控制、超时、重试和幂等设计。

本地浏览器与远程浏览器

开源代理可以运行在自己的机器上；README 建议将其与 Browser Use 的云浏览器结合，用于隐身、代理轮换和扩展规模。涉及远程浏览器时，网络流量、登录会话和页面数据的处理位置会发生变化，必须在部署前确认组织的数据处理要求。

云端任务提交

README 给出了向 /api/v4/runs 发送任务的 curl 示例。该方式的输入是 JSON 中的 task 字段，认证头为 X-Browser-Use-API-Key；资料没有列出返回 JSON、轮询方式或失败状态，因此不应据此编写未经验证的生产客户端。

可观测性与运维

仓库提供了日志级别、日志文件、CDP 日志级别、版本检查和匿名遥测配置，足以构成基础运行观测入口。生产运维所需的指标名称、追踪协议、告警阈值、SLA 和容量数据，官方仓库资料未提供。

• 通过 BROWSER_USE_LOGGING_LEVEL 控制日志详细程度。
• 通过 BROWSER_USE_DEBUG_LOG_FILE 和 BROWSER_USE_INFO_LOG_FILE 将不同级别日志写入文件。
• 通过 CDP_LOGGING_LEVEL 控制浏览器协议相关日志。
• 通过 ANONYMIZED_TELEMETRY 选择是否启用匿名遥测。
• 通过 BROWSER_USE_VERSION_CHECK 控制启动时的版本检查行为。

运行记录应至少关联任务标识、执行时间、所用模型、浏览器配置和最终状态。根据本文作者的经验判断，网页自动化排错还应保留失败页面、关键操作和模型输入输出的最小必要证据，但这些字段不是资料中声明的内置格式，实施时应避免记录密码、令牌和个人信息。

安全与合规边界

浏览器代理能够填写表单、处理登录后页面并访问网络资源，因此必须限定在获得授权的环境中使用。本节只讨论授权测试、内部自动化和合规数据处理，不提供绕过检测、规避验证码、入侵网站或操作未授权账号的教程。

授权范围

• 只对组织拥有或明确获准测试的站点执行自动化。
• 对本地 QA 页面、测试账号和沙箱数据设置独立浏览器配置。
• 对涉及职位申请、邮件、社交账户或其他个人资料的任务，先取得数据主体和业务方授权。
• 对写入、提交、删除、购买或发布等不可逆动作增加人工确认或明确的测试开关。

凭据与隐私

API 密钥、浏览器用户数据目录、代理用户名和代理密码都属于敏感配置。应使用环境变量或受控密钥系统注入，避免把 .env、浏览器配置目录和运行日志提交到仓库；资料没有提供专门的密钥托管机制或隐私合规认证声明。

启用云端代理或远程浏览器时，任务内容和页面数据可能离开本机。数据驻留、保留期限、处理者身份和服务合同信息不在本次仓库资料中，需查阅官方条款、隐私政策及组织内部合规要求后再决定。

许可证与商用条款

仓库 LICENSE 文件声明项目采用 MIT License，版权标注为 Copyright (c) 2024 Gregor Zunic。MIT 授权文本允许获得软件的人员使用、复制、修改、合并、发布、分发、再许可和销售软件副本，因此从许可证授权范围看，可以将该开源软件用于商业场景。

分发软件或其重要部分时，必须在所有副本或实质性部分中保留版权声明和许可声明。许可证同时以“按现状”提供软件，不提供适销性、特定用途适用性和不侵权保证，也不承担因使用软件产生的责任；具体权利义务以仓库 LICENSE 为准。

开源许可证不等于云端服务条款、第三方网站条款或数据处理协议。使用 Browser Use Cloud、模型提供商、代理服务或目标网站时，应分别遵守对应服务的条款和隐私要求，仓库的 MIT License 不能替代这些约束。

局限性与已知限制

网页自动化依赖页面结构、浏览器状态和模型判断，任务成功不应被解释为对所有网站或所有流程的保证。README 给出了具体演示和 benchmark 说明，但没有提供统一的稳定性承诺、错误分类、并发上限或长期兼容性矩阵。

• 模型输出存在不确定性，资料未声明固定成功率或确定性执行保证。
• 登录、二次验证、动态渲染、文件上传和复杂表单可能要求额外的浏览器配置或人工介入；资料未提供完整覆盖清单。
• 浏览器用户数据目录包含会话状态，复制、共享或持久化时会扩大敏感数据暴露面。
• 模型供应商的 API、配额、价格和可用性不由本仓库的 MIT License 保证。
• Dockerfile 的多架构注释提到 linux/amd64 和 linux/arm64 构建示例，但不同宿主机上的 Chromium、字体和系统依赖仍需实际验证。
• 资料没有给出完整目录说明、端口配置、健康检查、数据库方案或 Kubernetes 部署清单。

README 提到 Browser Use 在 100 个真实浏览器任务上进行 benchmark，并称在 Odysseys leaderboard 上有 87.4% 平均成绩。该信息属于 README 的项目方陈述，未附带本资料中的实验环境、复现实验命令和统计细节，不能据此推导本地部署的性能。

适合谁

以下信号表明项目与需求较匹配，判断依据来自仓库提供的 Python 库、CLI、浏览器任务和云端接口能力。

• 团队已有 Python 3.11 或更高版本环境，并能维护异步任务代码。
• 需求是操作真实网页，例如填写表单、提取公开页面数据或执行本地网站 QA，而不是单纯调用稳定的后端 API。
• 需要选择不同 LLM 提供商，或需要在代理层进行代码级定制。
• 已有 Claude Code、Codex、Cursor、Hermes 或 OpenClaw 等代理工具，并希望通过 CLI 赋予其浏览器操作能力。
• 能够为浏览器会话、API 密钥、日志脱敏和任务授权建立明确的工程边界。

不适合谁

以下信号表示应谨慎采用，或先选择更确定的自动化方式；其中“替代方式”的具体产品或工具不在资料中，本文不作未声明的产品对比。

• 任务要求每一步都具有严格确定性，且无法接受模型对页面元素作出错误判断。
• 组织禁止将页面内容、账号会话或任务文本发送到外部模型或云端浏览器，而团队又没有本地模型和本地浏览器隔离方案。
• 需求只是调用已有稳定 API，且不需要浏览器呈现、登录态或页面交互；此时应在场景 A 选用直接 API 集成，在场景 B 需要网页交互时再评估本项目。
• 团队没有能力管理 Python 依赖、Chromium、浏览器用户数据、模型密钥和失败重试。
• 业务要求仓库已经提供 SLA、合规认证、固定响应 schema 或官方容量保证，但资料没有这些声明。

常见问题与排查（FAQ / Troubleshooting）

排查顺序应从运行时、凭据、浏览器和任务本身逐层缩小范围。以下回答只覆盖资料中能核实的命令和配置，未提供的信息明确保留为空。

安装时应使用 pip 还是 uv

README 同时给出 uv add browser-use 和 pip install browser-use。项目声明的 Python 约束是 >=3.11,<4.0；如果环境版本不满足该范围，应先切换到符合要求的 Python 解释器。

为什么示例无法调用模型

检查 .env 是否包含 BROWSER_USE_API_KEY，或是否设置了所选模型供应商对应的 API 密钥。占位值 your-key 和 <你的-API-KEY> 都不是可用凭据；仓库资料没有提供密钥有效性检测命令。

如何确认 CLI 已安装

执行 browser-use --version。如果命令不存在，应检查当前虚拟环境是否已激活、安装命令是否作用于同一个 Python 环境，以及包安装是否完成；仓库为该 CLI 另外提供了 browseruse、bu 和 browser 别名。

浏览器无法启动时检查什么

优先检查 Chromium 或 Chrome 可执行文件，以及 BROWSER_USE_EXECUTABLE_PATH 是否指向有效路径。Dockerfile 使用系统包安装 Chromium，但仓库资料没有给出各操作系统的手动安装命令，因此其他系统的安装步骤应以官方文档为准。

如何降低排错成本

将 BROWSER_USE_LOGGING_LEVEL 设置为 debug，并根据需要配置 BROWSER_USE_DEBUG_LOG_FILE；同时查看 CDP_LOGGING_LEVEL 对应的浏览器协议日志。日志收集前应移除 API 密钥、Cookie、表单个人信息和页面敏感内容。

官方仓库未提供哪些排查信息

官方仓库未提供统一端口、健康检查接口、完整错误码表、并发限制、SLA 和所有模型的兼容矩阵，建议以最新 README 和官方文档为准。遇到版本行为差异时，应同时核对当前分支、发布版本和依赖锁定状态。

项目地址与资源

以下链接均来自仓库元信息、README 或项目配置文件，可用于获取源代码、文档、云端入口和项目公告。

• browser-use GitHub 仓库
• Browser Use 官网
• Browser Use 开源文档
• 开源库介绍文档
• Browser Use CLI 文档
• Browser Use Cloud 快速开始文档
• Browser Use Cloud 文档
• Browser Use Cloud
• Browser Use Benchmark 仓库
• Odysseys Leaderboard
• Browser Use 博客
• Browser Use Discord 社区
• Browser Use Merch 页面
• 服务条款
• 隐私政策

“Browser Use lets an AI agent use a web browser the same way you do — it opens pages, clicks buttons, types, and fills in forms.”

来源：README