Browser Use 保姆级部署教程：让 AI 像人一样操控你的浏览器

Browser Use（仓库 browser-use/browser-use，MIT 协议，GitHub 星数约 6.5 万，最近提交 2026-10-30）是目前最火的开源浏览器智能体：你给它一句话"查一下这个仓库有多少 star"，它就真的打开浏览器、导航、点链接、读页面，最后把结果告诉你。它在 Stealth Bench V2 上拿到 90.5% 的高分，能处理预订考驾照、抢票、填表单这类"人才能干的网页操作"。

本文严格对照官方 README 给出本地 Python 库的完整部署与运行方式。

一、项目介绍与适用场景

官方把 Browser Use 分成三条路径：

全托管 Cloud：直接调 API，连浏览器都托管在云端（$0.02/浏览器·小时）；
CLI：给 Claude Code、Codex 等编程智能体装上"控制浏览器"的能力；
Python 库：在你自己的代码里跑开源 Agent，可接本地浏览器或云浏览器。

本文重点是第三条路径——完全本地、自托管。

适用场景：

自动化运营：每天定时登录后台导数据、截图、对账。
爬虫增强：遇到需要点击、翻页、过 JS 渲染的页面，用 LLM 直接理解页面而不是写死 XPath。
智能测试：用自然语言描述"帮我走完下单流程"，AI 自己操作浏览器。
私人助手：抢券、挂号、查快递、填表，全部一句话交给 AI。

二、核心功能逐条拆解

本地浏览器驱动：通过 Agent(task=..., llm=...) 自动开浏览器、看截图、决定点哪。
云端浏览器可选：Browser(use_cloud=True) 切到云端隐身浏览器，自带住宅代理与验证码处理。
自带 BU2 模型：官方专门优化的 bu-2-0 模型，专为浏览器操作调优。
多模型兼容：通过 ChatOpenAI / ChatAnthropic / ChatGoogle / Ollama 接任意模型。
复用本机 Chrome 登录态：Browser.from_system_chrome() 直接用你已登录的 Cookie。
自定义工具：用 Tools() 装饰器把 Python 函数注册成 Agent 可用的工具。
历史回放：agent.save_history() + load_and_rerun() 把一次成功操作录下来，换参数重跑，无需每步都调模型。
Claude 集成：BrowserUse 驱动 + Bash 工具，直接给 Claude 当浏览器手脚。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/browser-use/browser-use
官方文档	https://docs.browser-use.com/open-source/introduction
官方 Demo	https://browser-use.com/showcase
License	MIT

四、硬件与环境前置要求

官方 README 明确要求：Python >= 3.11（推荐用 uv 初始化 3.12）。

其他：

操作系统：Windows / macOS / Linux 均可；
浏览器：本地模式需要本机装 Chrome / Chromium（首次运行会自动装 Playwright 内核）；
内存：4 GB 起步；
模型 Key：一个 OpenAI Key（或 Anthropic / Google / 本地 Ollama）；
网络：需要能访问模型 API；云浏览器模式还需访问 Browser Use Cloud。

五、多平台部署步骤

5.1 新建 Python 项目并安装 Browser Use

官方 README 原文：

uv init --python 3.12
uv add browser-use

逐条解释：

uv init --python 3.12：初始化一个全新项目并指定 Python 3.12（已有项目可跳过 init）；
uv add browser-use：把 browser-use 作为依赖加入项目，自动创建/更新虚拟环境。

预期：uv add 输出中包含 + browser-use-x.y.z，表示安装成功。

5.2 配置模型 Key

官方 README 给出的 .env 文件内容：

# .env
OPENAI_API_KEY=your-key
# BROWSER_USE_API_KEY=your-key  # Optional: BU2 model or cloud browser

如果你想用官方 BU2 模型或云浏览器，去 https://cloud.browser-use.com/new-api-key 申请一个 Key，把第二行取消注释并填进去。

5.3 编写第一个 Agent 脚本

官方 README 给出的 agent.py 原文：

import asyncio

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

load_dotenv()

async def main():
    llm = ChatOpenAI(model='gpt-5.6-luna', reasoning_effort='xhigh')
    # llm = ChatBrowserUse(model='bu-2-0')  # Use BU2 instead; requires BROWSER_USE_API_KEY
    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=llm,
        # browser=Browser(use_cloud=True),  # Use a cloud browser; requires BROWSER_USE_API_KEY
    )
    history = await agent.run()
    print(history.final_result())

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

逐段解释：

load_dotenv()：从 .env 读模型 Key；
ChatOpenAI(...)：用 OpenAI 模型做决策；注释行展示如何换成官方 BU2；
Agent(task=..., llm=...)：把"任务"和"大脑"交给 Agent；
await agent.run()：真正开浏览器执行；
history.final_result()：把最终答案打印出来。

5.4 运行

官方 README 命令：

uv run agent.py

预期：弹出一个浏览器窗口，自动打开 GitHub 的 browser-use 仓库页面，几秒后终端打印出 star 数。

5.5 切到云浏览器（无 Chrome 也能跑）

官方 README 原文：先在 .env 里设好 BROWSER_USE_API_KEY，然后把 agent.py 里的注释取消：

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

再 uv run agent.py 即可。官方说明：云浏览器按 $0.02/浏览器·小时计费，自带隐身、住宅代理、验证码处理和实时查看 URL，同一段代码无需其他改动。

5.6 复用本机已登录的 Chrome

官方 README 提示：用 Browser.from_system_chrome() 复用你日常 Chrome 的 Profile（含已登录网站 Cookie），详见 examples/browser/real_browser.py。官方未提供 Windows 专属安装脚本，本文不展开。

5.7 Docker / Windows 部署

官方 README 未提供官方 Docker 镜像，也未提供 Windows 安装包；Python 库本身跨平台，Windows 上直接按 5.1–5.4 用 PowerShell 跑即可。

六、配置文件全部参数解释

参数名	作用	可选值	默认值	配置示例	改错后果
`OPENAI_API_KEY`	OpenAI 模型 Key	有效 sk-xxx	无	`sk-...`	不传则模型调用 401
`BROWSER_USE_API_KEY`	BU2 / 云浏览器 Key	云端申请	无	取消注释填入	不填则不能用 BU2 与云浏览器
`task`	Agent 任务描述	自然语言	无	`"Find ..."`	任务不清则 Agent 乱点
`llm`	决策模型	`ChatOpenAI`/`ChatBrowserUse`/`ChatAnthropic` 等	无	`ChatOpenAI(model='gpt-5.6-luna')`	模型名错则调用失败
`browser=Browser(use_cloud=True)`	是否用云浏览器	`True`/`False`	本地浏览器	见 5.5	没配云 Key 却开云端会报错
`reasoning_effort`	推理强度	`xhigh` 等	模型默认	`'xhigh'`	强度越高越慢越贵
`extend_system_message`	追加系统提示	字符串	无	官方示例	覆盖默认行为

七、启动、后台常驻与开机自启

7.1 前台运行

cd ~/my-agent
uv run agent.py

7.2 后台常驻（systemd，Linux）

[Unit]
Description=Browser Use Agent
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/my-agent
ExecStart=/home/ubuntu/.venv/bin/python agent.py
Restart=on-failure

[Install]
WantedBy=multi-user.target

注意：本地浏览器模式需要图形环境；无桌面的服务器请用云浏览器模式（5.5）。

7.3 开机自启

sudo systemctl daemon-reload
sudo systemctl enable --now browser-use

7.4 端口

Browser Use 是 Python 库，本身不监听 Web 端口（官方未提供内置 Web 服务），因此"改端口"不适用。

八、功能实操教程

第 1 步：按 5.1–5.3 装好依赖、写好 agent.py、填好 OpenAI Key。第 2 步：uv run agent.py，观察浏览器自动打开 GitHub 仓库页面，Agent 滚动页面、定位 star 数字。第 3 步：终端打印类似 123456 stars 的答案——这是 AI 第一次"自主上网"。第 4 步：把 task 改成你自己的任务，例如"打开 example.com 报告页面标题"。第 5 步：用官方回放能力：跑完后加 agent.save_history('run.json')，再用 load_and_rerun('run.json', variables={...}) 把成功操作固化下来。第 6 步（可选）：按官方示例 Tools() 装饰器加一个"获取当前 UTC 时间"的工具，让 Agent 能在网页里填表时调用。

九、全套报错故障排查

报错：ModuleNotFoundError: No module named 'browser_use'。原因：没在 uv 项目环境里跑。解决：uv run agent.py，不要直接 python agent.py。
报错：401 Incorrect API key。原因：.env 里 Key 无效或没加载。解决：确认 .env 与 agent.py 同目录；load_dotenv() 在最前面；终端 grep OPENAI .env。
报错：云浏览器模式 BROWSER_USE_API_KEY is required。原因：开了 use_cloud=True 但没填 Key。解决：去 cloud.browser-use.com 申请 Key 写入 .env；或改回本地浏览器。
报错：本地浏览器打不开 / Executable doesn't exist。原因：缺 Playwright 内核。解决：按 Playwright 官方文档装内核（uv run playwright install chromium），或切云浏览器。
报错：Agent 点错地方、结果不对。原因：任务描述太模糊，或模型推理强度不够。解决：把 task 写得更具体（含网址、步骤、要输出什么）；调高 reasoning_effort。

十、升级、回滚与卸载

升级：uv add browser-use@latest（uv 会自动升级到最新版）。
回滚：uv add browser-use==<旧版本> 锁版本。
卸载：删除项目目录即可；全局无残留。

十二、进阶：多步骤任务、自定义工具与费用控制

让 Agent 处理复杂任务：把 task 描述写成"目标 + 步骤提示 + 验收标准"，例如"打开某电商网站，找到销量第一的商品，把标题、价格、评论数写成 JSON 输出"。任务越具体，成功率越高。

加自定义工具：官方 README 给出的 Tools() 装饰器模式非常实用——你可以把"查公司内网 API""读本地数据库""发企业微信通知"封装成 Python 函数，Agent 在需要时自动调用，不必每次都让它自己点浏览器。

费用控制：浏览器 Agent 每一步都要让模型"看截图→决定下一步"，token 消耗远大于普通聊天。建议：① 简单任务用小模型（官方 BU2 或 GPT-5.6-mini）；② 用 save_history + load_and_rerun 把跑通的流程固化，下次重跑时只在最后汇总时调一次模型；③ 监控 history 里的 token 统计。

反爬与登录态：遇到验证码、滑块、Cloudflare 拦截，本地浏览器很难绕；官方推荐切云浏览器（Browser(use_cloud=True)），自带住宅代理与隐身指纹。需要保持登录的网站，用 Browser.from_system_chrome() 复用你日常 Chrome 的 Profile，但注意这等于把所有网站 Cookie 交给 AI。

十一、商用许可与合规风险提示

Browser Use 开源库采用 MIT License（README FAQ 明确："This open-source library is licensed under the MIT License"）。

注意：

模型与云浏览器另计费：MIT 只覆盖代码，OpenAI/Claude/BU2 推理与 Browser Use Cloud 浏览器按各自价格收费。
合规爬取：自动化操作他人网站时注意目标站 robots 协议、服务条款与当地法律；不要用于绕过验证码、批量薅羊毛。
本机 Chrome 登录态：from_system_chrome() 会让 Agent 拿到你所有已登录网站的会话，等于把账号交给 AI，生产环境建议用独立 Profile 或云浏览器。

参考链接

官方 README：https://github.com/browser-use/browser-use
开源库文档：https://docs.browser-use.com/open-source/introduction
支持模型列表：https://docs.browser-use.com/open-source/supported-models
真实浏览器示例：https://github.com/browser-use/browser-use/blob/main/examples/browser/real_browser.py