browser-use：让 AI 自主操控浏览器的开源 Web 自动化 Agent｜部署与使用全指南

本文基于 browser-use 官方 GitHub 仓库与官方文档（docs.browser-use.com）的当前真实状态撰写，并交叉核实了项目在 2025–2026 年的持续活跃维护情况。所有链接、命令与参数均来自官方资料，可放心照做。

一、项目简介与适用场景

browser-use 是一个开源的 Python 库与浏览器自动化 Agent 框架，定位是"让 LLM（大语言模型）像人一样操控真实浏览器"。它把 Playwright 封装了一层对模型友好的 DOM 抽取与动作循环：模型看到页面的"可交互元素 + 可见文本"的结构化表示，决定下一步动作（点击、填写、滚动、导航），browser-use 通过 Playwright 执行后回传新的页面状态，如此循环直到任务完成。

项目自 2024 年 10 月开源，到 2026 年已成为浏览器 Agent 生态的事实标准底座：GitHub Stars 超过 10 万，月下载量达百万级，贡献者数百人，提交与发版节奏持续活跃（近期仍有几乎每天的提交与文档更新），属于典型的"高活跃、强维护"开源项目。

browser-use 提供三种使用路径，对应不同人群：

• Path 1 · 全托管云（Fully Hosted Cloud）：通过 API 把任务交给 Browser Use 官方，由它跑 Agent + 浏览器 + 基础设施（含 stealth 浏览器、代理、CAPTCHA 处理）。适合不想管环境的团队。

• Path 2 · CLI：把浏览器能力接入你已有的 Agent（Claude Code、Codex、Cursor 等）。适合开发者在脚本/IDE 中调用。

• Path 3 · Python 库（本文重点）：在你自己的代码里跑开源 Agent，自由选择模型与本地/云浏览器。适合自建应用、自定义工具、结构化输出。

适用场景

二、核心功能逐条拆解

1. LLM 友好的 DOM 抽取：不把整页原始 HTML（动辄数万 token）丢给模型，而是抽取"可交互元素 + 可见文本 + 元素关系"的精简表示，显著降低 token 成本、提升决策准确率。这是 browser-use 作为"库"而非"薄封装"的核心价值。

2. 多模型支持：内置 ChatOpenAI、ChatAnthropic、ChatGoogle，以及官方优化的 ChatBrowserUse（模型 bu-2-0）。切换模型是配置级改动，无需改业务代码。也支持本地模型（Ollama）。

3. 动作循环（Agent Loop）：模型读取页面状态 → 决策动作 → Playwright 执行 → 回传新状态，直到 is_done 或命中错误/步数上限。

4. 自定义工具（Tools）：通过 Tools 注册函数，让 Agent 调用你自己的能力（如获取当前时间、查数据库）。

5. 系统提示自动注入：Agent(...) 自动附带 browser-use 系统提示，无需手写；可用 extend_system_message 追加或 override_system_message 覆盖。

6. 本地 / 云浏览器双模式：默认本地 Chromium；也可 Browser(use_cloud=True) 用官方云浏览器（免装 Chrome，含 stealth、住宅代理、CAPTCHA 解算、实时预览 URL）。

7. 复用真实登录态：Browser.from_system_chrome() 复用本机 Chrome 用户数据，免重复登录。

8. Claude 工具集集成：官方提供与 Anthropic SDK 对接的 toolsets_for_claude，实现 31 个浏览器动作 + Bash，浏览器可为本地/云/远程 CDP。

9. 生产级沙箱（Sandbox）：@sandbox 装饰器把 Agent 跑在靠近浏览器的沙箱里，自动处理持久化、认证、Cookie、LLM，是最快的生产部署方式。

10. 性能与基准：官方在 BU Bench V2（高难度浏览器任务）基准上对比主流模型的速度、成本与准确率；下图为各模型平均得分与单任务成本对照（官方公开基准图）：

三、全套官方链接

在线 Demo：官方提供托管版 https://cloud.browser-use.com —— 注册后可直接在网页里提交任务，由云端 Agent + stealth 浏览器执行，无需本地安装。新用户通过 Google / GitHub / Microsoft 注册可获 $1 云额度，并有按浏览器小时计费的 stealth 浏览器（约 $0.02/浏览器小时）。

四、硬件与环境前置要求

五、多平台部署实战

下面以 Path 3（Python 库）本地自部署为主线，覆盖 Windows / Linux / macOS / Docker / 源码五种方式。所有方式都涉及两步关键动作：装包 与 装浏览器（Playwright Chromium）。

5.1 通用：安装 browser-use 与 Playwright 浏览器

使用 uv（推荐）：

# 新建并激活虚拟环境（Python 3.12）
uv venv --python 3.12
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 安装 browser-use
uv pip install browser-use

# 安装 Playwright 浏览器（Chromium 及系统依赖）
uvx browser-use install          # 官方一键安装命令
# 等价命令：playwright install chromium --with-deps

使用 pip：

python -m venv .venv && source .venv/bin/activate
pip install browser-use
playwright install chromium --with-deps

提示：uvx browser-use install 会安装 browser-use 自带的浏览器启动器所需内核；若你用纯 pip，则直接用 playwright install chromium --with-deps。--with-deps 在 Linux 上会一并装系统库（需 sudo/root）。

5.2 Windows

# 1) 安装 uv（如未装）：winget install --id=astral-sh.uv 或直接用 pip install uv
uv venv --python 3.12
.venv\Scripts\activate
uv pip install browser-use
uvx browser-use install

# 2) 创建 .env（PowerShell）
echo. > .env
# 用记事本编辑 .env 填入 API Key（见第六章）

# 3) 运行示例（见第八章）
uv run agent.py

注意：若要用 Browser.from_system_chrome() 复用登录态，请先完全关闭所有 Chrome 窗口，否则会被占用。

5.3 Linux

# 系统依赖（Debian/Ubuntu，首次需要）
sudo apt-get update && sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 \
  libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
  libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2

uv venv --python 3.12 && source .venv/bin/activate
uv pip install browser-use
uvx browser-use install

无界面服务器建议用 headless=True（默认）运行；需要可视化调试时设 headless=False 并安装 Xvfb（xvfb-run python agent.py）。

5.4 macOS

# Apple Silicon / Intel 均可，建议用 brew 装 uv 或官方安装脚本
uv venv --python 3.12 && source .venv/bin/activate
uv pip install browser-use
uvx browser-use install

macOS 上 Playwright 会自动下载适配的 Chromium，无需额外系统库。若提示"无法验证开发者"，到"系统设置 → 隐私与安全性"允许一次即可。

5.5 Docker（推荐生产 / 干净隔离）

仓库根目录自带 Dockerfile 与 Dockerfile.fast，可直接从源码构建：

git clone https://github.com/browser-use/browser-use.git
cd browser-use
docker build -t browser-use .            # 或用 Dockerfile.fast 加速构建

运行（把代码与数据挂载进容器，设置 API Key 环境变量）：

docker run -it --rm \
  -e OPENAI_API_KEY=your-key \
  -v "$(pwd)/examples:/app/examples" \
  browser-use \
  python examples/your_agent.py

说明：社区与部分文档也提到发布镜像 browseruse/browser-use:latest。若你信任该官方镜像，可直接 docker pull browseruse/browser-use:latest 后运行；否则以"从源码构建"最稳妥、可审计。容器内已是 headless 环境，无需额外 X 服务。

5.6 源码安装（开发 / 想看最新未发版代码）

git clone https://github.com/browser-use/browser-use.git
cd browser-use
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e .            # 可编辑安装
uvx browser-use install

源码安装便于调试、贡献代码或试用 main 分支的新特性。

六、配置文件参数全解

browser-use 的运行配置主要来自两块：LLM 配置（在 Python 代码里用 LangChain 风格对象）与 Browser 配置（同样在代码里），敏感信息放在 .env 环境变量。

6.1 LLM 配置

6.2 Browser 配置

Browser(...) 构造参数（部分常用）：

示例：

from browser_use import Browser

browser = Browser(
    headless=False,                       # 显示浏览器窗口
    window_size={'width': 1000, 'height': 700},
)
# 或复用本机登录态：
# browser = Browser.from_system_chrome()

6.3 环境变量（.env）

6.4 .env 示例

# === LLM 提供商（至少填一个你用的）===
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-key
GOOGLE_API_KEY=your-google-key

# Browser Use 官方网关 / 云浏览器（可选，用于 BU2 模型或云浏览器）
BROWSER_USE_API_KEY=your-browser-use-key

# 如需代理（可选）
# BROWSER_PROXY=http://127.0.0.1:7890

在 Python 脚本开头用 from dotenv import load_dotenv; load_dotenv() 加载。切勿把 .env 提交到公开仓库。

七、启动 / 后台常驻 / 开机自启 / 改端口 教程

7.1 直接运行（CLI / 脚本）

# 用 uv 运行脚本
uv run agent.py

# 或用激活后的 venv
python agent.py

browser-use 也提供 CLI 相关子命令，例如为 Claude 等 Agent 安装技能并连接浏览器：

uvx browser-use install          # 安装浏览器内核
browser-use skill install        # 注册 browser-use skill（用于接入 Claude Code 等）

7.2 改端口（Web UI）

browser-use 仓库自带官方 Gradio 演示界面：

python examples/ui/gradio_demo.py
# 默认监听 http://127.0.0.1:7860

如需改端口，直接编辑 examples/ui/gradio_demo.py 末尾的 demo.launch(...) 增加 server_port=xxxx（或 server_name 改监听地址）。社区维护的 browser-use/web-ui 项目则默认端口 7788，可用 --port 修改：

python webui.py --ip 127.0.0.1 --port 7788

7.3 后台常驻运行

• nohup（最简单）：

nohup uv run agent.py > agent.log 2>&1 &

• tmux（推荐，可随时附着查看）：

tmux new -s bu
uv run agent.py
# Ctrl+B 再按 D 脱离；tmux attach -t bu 重新进入

• systemd（Linux 服务，稳定常驻）：

# /etc/systemd/system/browser-use.service
[Unit]
Description=Browser Use Agent
After=network.target

[Service]
WorkingDirectory=/opt/browser-use
ExecStart=/opt/browser-use/.venv/bin/python agent.py
Environment=OPENAI_API_KEY=your-key
Restart=on-failure

[Install]
WantedBy=multi-user.target

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

7.4 开机自启

• Linux：用上面的 systemd enable 即可开机自启。

• macOS：把启动命令写进 launchd plist，或用 brew services 包装。

• Windows：把 .bat 启动脚本放入"启动"文件夹（shell:startup），或用任务计划程序设置"登录时触发"。

八、功能实操教程

8.1 首次运行：连接 LLM + 跑第一个任务

步骤 1 — 准备环境与密钥

uv venv --python 3.12 && source .venv/bin/activate
uv pip install browser-use
uvx browser-use install
echo. > .env          # Windows；macOS/Linux: touch .env

在 .env 中至少填入一个模型 Key，例如 OpenAI：

OPENAI_API_KEY=sk-your-key

步骤 2 — 写第一个 Agent 脚本 agent.py

import asyncio
from browser_use import Agent, ChatBrowserUse
from dotenv import load_dotenv

load_dotenv()

async def main():
    llm = ChatBrowserUse()                      # 或 ChatOpenAI(model='gpt-5.6-luna')
    agent = Agent(
        task="Find the number 1 post on Show HN",
        llm=llm,
    )
    history = await agent.run()
    print(history.final_result())

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

步骤 3 — 运行

uv run agent.py

Agent 会自动打开浏览器、访问目标网站、逐步执行并打印最终结果。首次运行会下载 Chromium（若之前没装），请耐心等待。

使用云端浏览器（免装 Chrome）：在 .env 设 BROWSER_USE_API_KEY 后，把 Agent 改为：

from browser_use import Agent, Browser, ChatBrowserUse
agent = Agent(task="...", llm=ChatBrowserUse(), browser=Browser(use_cloud=True))

8.2 进阶：自定义工具与系统提示

注册自定义工具（让 Agent 调用你的函数）：

from browser_use import ActionResult, Agent, ChatBrowserUse, Tools

tools = Tools()

@tools.action(description='Get the current UTC time.')
def get_current_time() -> ActionResult:
    from datetime import datetime, timezone
    return ActionResult(extracted_content=datetime.now(timezone.utc).isoformat())

agent = Agent(task="What is the current UTC time?", llm=ChatBrowserUse(), tools=tools)

8.3 Gradio Web UI 使用

browser-use 自带官方可视化界面，适合不想写代码、想用网页提交任务的人：

# 在仓库目录下
python examples/ui/gradio_demo.py

打开浏览器访问 http://127.0.0.1:7860，界面包含：

• API Key 输入：填入 LLM 提供商的 Key（OpenAI / Google / Anthropic 等）

• 任务描述：用自然语言描述要做的网页任务

• 模型选择：如 gpt-5、gemini-3-pro、claude-sonnet-4-6 等

• 无头模式：勾选则在后台运行，不弹窗

点击 Run Task 后，系统会：启动浏览器 → 调模型分析 → 自动点击/输入/导航 → 在输出框返回结果。

若想要功能更全（多模型切换、复用本地 Chrome 登录态、VNC 实时观看、Docker 一键部署），可使用社区项目 browser-use/web-ui（默认端口 7788，Docker 下 VNC 在 6080）。它属于社区生态，非核心库自带。

九、全套报错故障排查

下面列出使用 browser-use 时最常见的 10 类问题与对策。

1. Playwright 浏览器未安装（报错：Executable doesn't exist / chromium not found） - 现象：首次运行直接崩溃，提示找不到 Chromium 可执行文件。 - 解决：uvx browser-use install 或 playwright install chromium --with-deps。Linux 上务必加 --with-deps 并具备 sudo。

2. API Key 未设置 / 401 未授权 - 现象：AuthenticationError、401，或 BROWSER_USE_API_KEY 相关报错。 - 解决：确认 .env 已填对应 Key 且脚本调用了 load_dotenv()；或在运行 shell 中 export OPENAI_API_KEY=...。新 shell 需重新 export。

3. 网站登录态丢失 / 需要重复登录 - 现象：每次任务都要重新登录目标网站。 - 解决：用 Browser.from_system_chrome() 复用本机 Chrome 用户数据（运行前先彻底关闭 Chrome）；或使用云浏览器的持久化 Profile（@sandbox(cloud_profile_id=...)）。

4. 反爬 / CAPTCHA 拦截 - 现象：页面弹出验证码，或返回"疑似机器人"的拦截页，任务失败。 - 解决：对云浏览器模式，Browser Use Cloud 提供 stealth、住宅代理与 CAPTCHA 解算；本地模式可配置 proxy、降低请求频率、拆分任务。注意合规边界（见第十一章），不要对明确禁止自动化的站点强行突破。

5. 任务超时 / 步数过多 - 现象：Agent 跑了很久还没完成，或中途中止。 - 解决：合理设置 max_steps 与超时；把复杂任务拆成更小、更明确的子任务；选择更快/更便宜的模型（如 BU2）。

6. 元素定位失败 / 页面结构变化 - 现象：Agent 找不到按钮、填错输入框，或目标网站改版后失效。 - 解决：在 task 里给出更精确的描述与上下文；必要时用 extend_system_message 增加领域说明；对高度动态的页面，可让模型结合截图理解（确保 headless=False 时窗口尺寸足够）。

7. 无头模式下的截图 / 下载异常 - 现象：headless 下某些下载、弹窗或渲染异常。 - 解决：调试阶段设 headless=False 并设 window_size；服务器无界面环境用 xvfb-run 包裹；检查目标站是否需要用户手势才能触发下载。

8. 代理配置错误 - 现象：连不上目标站、请求卡住或返回代理错误。 - 解决：确认 proxy={'server':'http://host:port'} 格式正确；带认证的代理写成 http://user:pass@host:port；云浏览器可在创建会话时指定 proxy_country_code。

9. Python 版本 / 依赖不匹配 - 现象：pip/uv 报找不到满足条件的版本，或导入错误。 - 解决：确认 Python ≥ 3.11（推荐 3.12）；删除旧 venv 重建；优先用 uv 避免依赖冲突。

10. 速率限制 / 费用激增 - 现象：API 返回 429，或账单异常上涨。 - 解决：为所用 provider 配置限速/重试；优先选用 BU2 等低成本模型；本地模型走 Ollama 可零 API 费用（需本地算力）；监控 max_steps 防止死循环。

十、升级 / 回滚 / 卸载 教程

10.1 升级

# uv
uv pip install --upgrade browser-use
# pip
pip install --upgrade browser-use
# 验证版本
python -c "import browser_use, importlib.metadata as m; print(m.version('browser-use'))"

如用源码可编辑安装：cd browser-use && git pull && uv pip install -e . --upgrade。

10.2 回滚到指定版本

# 固定（降级）到某版本，例如 0.13.7
uv pip install "browser-use==0.13.7"
# 或 pip
pip install "browser-use==0.13.7"

建议把版本写进 pyproject.toml / requirements.txt 锁定，避免意外升级破坏脚本。回滚后如行为异常，可删除 .venv 重建并重新 uvx browser-use install。

10.3 卸载

pip uninstall browser-use        # 或 uv pip uninstall browser-use
# 如不再需要 Playwright 浏览器内核：
playwright uninstall chromium
# 清理项目目录（按需）：
# rm -rf .venv

Docker 方式停止并删除容器/镜像即可：

docker rm -f browser-use && docker rmi browser-use

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

11.1 许可证：MIT，可商用

browser-use 核心库以 MIT License 发布（见仓库 LICENSE 文件）。MIT 是非常宽松的开源许可证，允许你：

• 免费用于商业产品与内部系统；

• 修改、再分发、私有化部署；

• 无需开源你的衍生代码（MIT 不要求 copyleft）。

唯一义务：在分发软件时保留原始版权声明与 MIT 许可文本。官方库本身"免费"，但你仍需为模型推理（LLM API）与云浏览器（如启用）按各自服务商付费；用本地模型（Ollama）则可免去模型 API 费用。

11.2 合规与反爬风险提示（务必重视）

把 AI Agent 放到真实网站上自动操作，涉及法律与平台规则的边界，请务必留意：

1. 遵守网站服务条款（ToS）与 robots.txt：部分网站明确禁止自动化访问/抓取，强行突破可能违反其 ToS，严重时涉及违约或相关法律风险。商用前请阅读目标站点的使用条款。

2. 反爬 / CAPTCHA 的边界：browser-use Cloud 提供 stealth、住宅代理与 CAPTCHA 解算等能力。请仅用于你有权操作的站点或已获授权的场景；不要用其规避付费墙、登录限制或从事批量滥用。

3. 数据与隐私：Agent 会读取页面内容，若处理包含个人隐私或敏感信息的页面，需符合《个人信息保护法》等适用法规，避免未经授权收集/存储他人数据。

4. 频率与资源占用：合理设置步数与间隔，避免对目标站造成过大流量压力（相当于 DoS 风险）。

5. 账号安全：复用登录态（本地 Chrome / 云 Profile）意味着 Agent 拥有你的账号操作权限，请仅在可信环境使用，并妥善保管 .env 与 API Key，切勿提交到公开仓库。

6. 责任归属：自动化操作产生的下单、发文、转账等动作由操作者负责，上线前务必在低风险任务上充分验证。

总结：用 browser-use 做网页抓取、自动填表、RPA 在技术上完全可行且合规友好（MIT 可商用），但自动化访问网站的行为本身需遵守目标站点规则与当地法律，切勿用于规避反爬、突破授权或滥用。

本教程整理自 browser-use 官方 GitHub 与官方文档的当前真实状态（核实于 2025–2026 持续活跃维护期）。命令与参数请以官方仓库最新说明为准。