browser-use 本地部署指南：用自然语言指挥 AI 自动操作浏览器

一、项目介绍

如果说传统的爬虫是"写死规则去抓数据"，那么新一代的浏览器代理（Browser Agent）则是"告诉 AI 你要干什么，让它自己看页面、点按钮、填表单"。browser-use 正是这一方向上最活跃的开源项目之一。

按照官方 README 的说法，browser-use 是一个开源浏览器代理：你可以在本地搭配任意大模型运行，也可以使用它的云端浏览器服务（隐身浏览器每小时约 0.02 美元）。它的目标是让 AI "像人一样浏览网页"——找到可用的预约时段、选好日期时间、处理验证码，然后完成一次驾驶考试预约这样的完整任务。

项目同时提供 Python 与 TypeScript 两种语言的库，并区分三种使用路径：完全托管的云端 Agent、命令行工具，以及可嵌入自己代码的开源 Python 库。本文聚焦于最通用的"本地 Python 库"路径。

传统爬虫靠的是"分析页面结构、写死选择器"，页面一改版就失效；浏览器代理靠的是"让模型像人一样看屏幕、做决策"，对页面改版的容忍度高得多。这种范式转移意味着，你描述的是"任务目标"而不是"操作步骤"——例如"帮我查一下明天北京的天气"，代理自己决定点哪里、输什么。代价是每次操作都要调用大模型，成本与延迟都比传统爬虫高，因此它更适合低频、复杂、需要判断的任务，而不是大规模数据采集。

二、官方信息

本文聚焦最通用的本地 Python 库路径，带你装好依赖、配置密钥，并让 AI 真正打开浏览器完成一次任务。

三、项目结构与核心特性

browser-use 的核心抽象是 Agent：你给它一个自然语言任务（task）和一个大模型（llm），它会自动循环地"观察页面 → 决定下一步动作 → 执行 → 再观察"，直到任务完成。

核心特性包括：

• 任意大模型可插拔：通过 ChatOpenAI、ChatBrowserUse 等适配器接入 OpenAI 兼容接口，也支持其他厂商模型。
• 本地或云端浏览器：默认驱动本机 Chrome；加上 browser=Browser(use_cloud=True) 即可切换到云端隐身浏览器，无需在服务器装 Chrome，适合 Docker、CI、Serverless 环境。
• 完整的浏览器动作集：官方称实现了 31 种浏览器动作，还可与 Claude 等模型的浏览器工具集集成。
• CDP 远程控制：可以连接已有的远程浏览器（通过 Chrome DevTools Protocol）。
• 内置演示与基准：在 Stealth Bench 等反检测基准上取得高分，云端版自带验证码求解、住宅代理与实时预览。

适用场景

browser-use 适合"需要人判断、但流程重复"的网页任务。例如：定时登录内部系统导出报表、在预约网站上抢可用时段、批量在后台录入数据、把网页上的动态内容抓下来存档。它不适合大规模结构化采集——那种任务用传统爬虫更快更便宜；但在需要登录、需要点选、页面经常改版、规则难以写死的场景，让 AI 自己看页面自己操作，反而更省事。配合云端隐身浏览器，还能在服务器无界面环境下稳定运行。

与同类工具对比

和 Selenium、Playwright 这类传统自动化框架相比，browser-use 不需要你写选择器、不需要维护元素定位，它让模型自己"看"页面决策；代价是每次操作都要调用大模型，成本与延迟更高。和 RPA 工具相比，它更灵活、能处理没见过的页面，但稳定性不如写死的脚本。适合"低频、多变、需要判断"的任务；高频结构化抓取，传统爬虫仍是更经济的选择。

四、环境与版本要求

• Python ≥ 3.11（官方 Quickstart 明确要求，推荐用 3.12）。
• 推荐使用 uv 管理项目依赖。
• 一个 OpenAI API Key（或其他兼容 Chat Completions 的模型 Key）。
• 本地浏览器模式需要本机安装 Chrome/Chromium；云端模式则不需要。
• 可选：BROWSER_USE_API_KEY，用于使用官方云端模型（BU2）或云端隐身浏览器。

提示：这是一个会真实操作浏览器、访问真实网站的代理，建议先在测试账号与非生产数据上试运行，注意遵守目标网站的服务条款。

五、本地部署步骤

1. 安装

官方推荐用 uv：

# 新建项目时（已有项目可跳过）
uv init --python 3.12
cd my-agent

# 添加依赖
uv add browser-use

如果你更习惯 pip，也可以在虚拟环境中执行 pip install browser-use，但官方文档主推 uv。

2. 配置 API Key

在项目根目录新建 .env 文件：

# .env
OPENAI_API_KEY=你的OpenAI密钥
# BROWSER_USE_API_KEY=你的密钥   # 可选：使用 BU2 模型或云端浏览器

OPENAI_API_KEY 可从 OpenAI 平台 获取；BROWSER_USE_API_KEY 则在官方云控制台申请。

3. 编写代理脚本

新建 agent.py：

import asyncio

from browser_use import Agent, Browser, ChatBrowserUse, ChatOpenAI
from dotenv import load_dotenv

load_dotenv()

async def main():
    # 使用 OpenAI 模型
    llm = ChatOpenAI(model="gpt-5.6-luna", reasoning_effort="xhigh")
    # 如需使用官方 BU2 模型，改用下面这行（需要 BROWSER_USE_API_KEY）：
    # llm = ChatBrowserUse(model="bu-2-0")

    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=llm,
        # browser=Browser(use_cloud=True),  # 启用云端浏览器
    )

    history = await agent.run()
    print(history.final_result())

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

逐行说明：

• load_dotenv()：从 .env 加载环境变量；
• ChatOpenAI(...)：构造一个大模型适配器；
• Agent(task=..., llm=...)：把自然语言任务与模型绑定；
• await agent.run()：异步运行整个观察-决策-执行循环；
• history.final_result()：取最终结论并打印。

4. 运行验证

uv run agent.py

代理会自动打开浏览器、访问 GitHub、找到 browser-use 仓库的 Star 数，并在终端打印答案。看到这个数值输出，就说明部署成功。

5. 切换到云端浏览器（可选）

如果不想在服务器上装 Chrome，设置好 BROWSER_USE_API_KEY 后，把脚本里注释掉的 browser=Browser(use_cloud=True) 启用即可：

agent = Agent(
    task="Find the number of stars of the browser-use repo",
    llm=llm,
    browser=Browser(use_cloud=True),
)

同一份代码，无需其他改动，即可在 Docker、CI 或 Serverless 环境中运行云端隐身浏览器。

排错思路

代理打开浏览器就报错，多半是本机没有可用的 Chrome，或 Python 版本低于 3.11——用云端浏览器 Browser(use_cloud=True) 可以绕开本地浏览器依赖。模型鉴权失败则检查 .env 里的 Key 是否正确、是否有余额；用 BU2 时记得切换到 ChatBrowserUse 并配 BROWSER_USE_API_KEY。

代理走错路时，先把 history 打印出来看它每一步看到了什么、点了什么。任务描述太笼统是最常见的原因——把"帮我预约"改成"打开某站、点击预约按钮、选择明天上午"，成功率会明显提升。在生产环境，建议给任务加上明确的成功判定条件，让代理知道何时算完成。

六、API 用法与示例

换一个任务，只要改 task 字符串即可：

agent = Agent(
    task="Go to example.com and tell me the main heading on the page",
    llm=llm,
)
result = await agent.run()
print(result.final_result())

多步信息收集：

agent = Agent(
    task="Search the web for the weather in Beijing tomorrow, then summarize it in one sentence",
    llm=llm,
)

browser-use 还提供了与 Claude 浏览器工具集集成的方式：当环境中安装了带 anthropic.tools.browser 的 Anthropic SDK 后，可以让 Claude 发出浏览器动作，由 browser-use 在本地或云端浏览器上执行。完整的 Python 库 API 见官方文档。

让代理更稳：提示词、录制与反检测

浏览器代理的效果很大程度上取决于 task 的写法。经验是把任务拆成可验证的小步骤，例如"打开某网址→点击登录→输入账号→截图确认"，而不是一句笼统的"帮我搞定预约"。官方 showcase 里的优秀 prompt 都遵循"目标明确、步骤可检查"的原则，可以直接参考改写。

browser-use 还会记录每一步的执行历史（history 对象），包含它看到的页面摘要、执行的动作、最终结果。把这段历史打印出来，既能用于调试"它为什么走错了"，也能作为回归测试的素材。云端浏览器模式还提供实时预览 URL，你可以在它操作时同步观察屏幕。

在反爬较强的站点上，本地 Chrome 模式容易被识别为自动化。此时建议切换到官方云端隐身浏览器（带住宅代理与验证码求解），并在成本与稳定性之间权衡：云端按浏览器小时计费，适合生产任务；本地模式则适合开发调试与内部系统。

七、常见问题 FAQ

Q1：运行时报浏览器找不到？
A：本地模式需要本机有 Chrome/Chromium。最简单的办法是启用云端浏览器 Browser(use_cloud=True)；或者在服务器上安装 Chromium 并让 browser-use 能找到它。

Q2：提示模型鉴权失败？
A：检查 .env 里的 OPENAI_API_KEY 是否正确、是否有余额；如果使用 BU2，确认已设置 BROWSER_USE_API_KEY 并切换到 ChatBrowserUse。

Q3：代理在复杂页面上点错位置、走不下去？
A：可以通过 reasoning_effort 提高模型推理力度，或把任务拆得更具体（例如"先点击登录按钮"）。官方文档与 showcase 提供了大量经过验证的 prompt 模板，可直接参考。

Q4：能不能连接我自己已经打开的浏览器？
A：可以。browser-use 支持通过 CDP 连接远程或已有浏览器实例，具体参数见文档中关于 Browser 与 CDP 的说明。

Q5：会不会被目标网站的反爬识别出来？
A：本地浏览器模式与普通用户接近，但在强反爬站点仍可能被识别。官方云端隐身浏览器针对反检测做了优化，并在 Stealth Bench V2 上取得高分（90.5%），适合高要求场景。

小结

browser-use 代表了浏览器自动化的新范式：你描述目标，模型自己决定怎么点。它把"写选择器、维护爬虫"的负担，换成了"写清楚任务、调好模型"的新负担。对需要登录、需要判断、页面频繁变动的场景，这种方式比传统爬虫更有弹性；但也要接受它的成本——每一步都要调用大模型，且结果不如脚本确定。建议先在本地用真实任务试跑，观察它的执行历史，再决定哪些任务适合交给它、哪些仍应写死成脚本。随着使用增多，你会逐渐摸清哪些站点对它友好、哪些需要云端隐身浏览器，从而在成本与稳定性之间找到适合自己的平衡点。把它用在内部系统填报、报表导出这类高频重复操作上，往往一两周就能省下可观的手工时间。

部署后的日常使用

日常使用中，建议把"任务描述"当成一等公民来打磨：越具体、越带成功判定条件，代理越容易一次做对。把跑成功的任务 prompt 保存下来，形成自己的任务模板库。在服务器或 CI 环境里，直接用云端浏览器模式，省去装 Chrome 的麻烦；在本地开发调试时，再切回本机浏览器以便观察。随着模板库越来越丰富，你会发现大量重复性网页操作都可以放心交给它。

写在最后

browser-use 代表了浏览器自动化的未来方向：不再是写死规则，而是让模型理解目标、自己决策。它还不完美，成本与稳定性都有待打磨，但已经能在大量"需要人判断"的网页任务上省掉可观的手工时间。把它用对场景，它会成为你自动化工具箱里很有威力的一件。随着这类工具日渐成熟，未来"让人重复点网页"的工作会越来越少。对企业来说，把这类代理用在内部系统的重复性操作上，回报往往很快就能显现。关键是从一个高频、规则相对固定的小任务开始，逐步积累信任与模板。用得越久，你越能分清哪些任务交给它最划算、哪些仍该自己掌控。这种判断力会随着使用次数自然积累。从今天起，把第一个网页小任务交给它试一试。你会很快体会到"一句话搞定重复操作"的爽快。这正是 AI 浏览器代理最打动日常用户的地方。把它装进你的自动化工具箱，重复网页操作会越来越少烦你。从今天开始，把它用起来，你会感激这个决定。

任务设计建议

用好 browser-use 的关键不在框架本身，而在于你怎么描述任务。经验表明，把"帮我查一下"这类模糊请求，改写成"打开某网站、点击某个入口、填写某项内容、最后告诉我结果"这样带明确步骤与成功判定的描述，成功率会显著提升。同时建议从低频、规则相对固定的小任务开始尝试，观察它的执行历史，再逐步把更复杂的网页操作交给它；这样既能积累可复用的任务模板，也能避免一开始就在高风险操作上翻车。

相关链接

• 仓库：github.com/browser-use/browser-use
• 文档：docs.browser-use.com
• 产品地图（给 AI 看）：browser-use.com/llms.txt
• 云服务：cloud.browser-use.com
• 演示与 Prompt：browser-use.com/showcase