Browser Use 项目部署

项目定位：开源的 Python AI 浏览器智能体库（Browser Use），可搭配任意 LLM 在本地运行，也可对接官方云端的隐身浏览器与托管 Agent API。
开源协议：MIT
文档依据：项目仓库 README（2026 年 11 月版本），具体参数以官方文档为准。

一、部署方案选择

Browser Use 官方提供三条使用路径，先选定再往下看：

本文重点讲解路径三（Python 库自托管），并补充 Docker 部署、云浏览器接入与生产建议。

二、环境要求

• 操作系统：Linux / macOS / Windows（Windows 下部分扩展功能建议使用 WSL）
• Python：3.11 及以上（官方示例使用 3.12）
• 包管理器：uv（推荐）
• 浏览器：本地 Chrome / Chromium（使用云浏览器则无需安装）
• 模型密钥：至少准备一种
  • OpenAI、Anthropic、Google 等厂商的 API Key
  • 或 Browser Use 官方的 API Key（使用其专用模型 BU2 或云浏览器时需要）
  • 或本地 Ollama 模型（受硬件限制）
• 网络：服务器需能访问所选模型厂商的 API

三、本地 / 服务器部署（Python 库）

3.1 安装 uv

已安装 uv 可跳过。没有的话可以通过 pip 安装：

pip install uv
uv --version

3.2 创建项目并安装 browser-use

mkdir my-browser-agent && cd my-browser-agent
uv init --python 3.12
uv add browser-use

3.3 安装浏览器内核（Linux 服务器建议执行）

如果机器上没有 Chrome / Chromium，可通过 Playwright 安装 Chromium 及系统依赖：

uvx playwright install chromium --with-deps

使用云浏览器（见第五章）时，这一步可以省略。

3.4 配置环境变量

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

# .env
OPENAI_API_KEY=your-key

# 可选：使用 BU2 模型或云浏览器时需要
# BROWSER_USE_API_KEY=your-key

注意：.env 含有密钥，务必加入 .gitignore，不要提交到代码仓库。

3.5 编写并运行第一个 Agent

新建 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')  # 改用 BU2，需要 BROWSER_USE_API_KEY
    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=llm,
        # browser=Browser(use_cloud=True),  # 使用云浏览器，需要 BROWSER_USE_API_KEY
    )
    history = await agent.run()
    print(history.final_result())

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

运行：

uv run agent.py

正常情况下，程序会打开浏览器、查询仓库并输出结果。模型名称请替换为你账号实际可用的模型。

四、Docker 部署

仓库根目录已提供 Dockerfile 与 Dockerfile.fast，以及 docker 目录，适合在服务器或 CI 中使用。

4.1 获取源码

gh repo clone browser-use/browser-use
cd browser-use
# 没有 gh 命令行工具时，可在 GitHub 搜索 browser-use/browser-use，下载源码压缩包后解压

4.2 准备环境变量

cp .env.example .env
# 编辑 .env，填入模型厂商的 API Key

4.3 构建镜像

docker build -t browser-use .
# 追求构建速度可改用精简版
# docker build -f Dockerfile.fast -t browser-use:fast .

4.4 运行容器

docker run --rm --env-file .env browser-use

4.5 在容器中运行自己的脚本

容器内以 root 或受限环境运行 Chrome 时，通常需要关闭 Chromium 沙箱并使用无头模式，示例：

from browser_use import Agent, Browser

browser = Browser(
    headless=True,
    chromium_sandbox=False,  # 容器环境常用；不同版本参数名请对照官方文档
)
agent = Agent(task="your task", llm=llm, browser=browser)

提示：容器内跑浏览器建议配置足够的共享内存，例如给 docker run 增加 --shm-size=2g，否则页面容易崩溃。

五、接入 Browser Use Cloud（可选）

不想在服务器上维护 Chrome，或需要隐身、验证码、住宅代理能力，可直接使用云浏览器。

1. 在官方云平台注册并创建 API Key（新用户通过 Google、GitHub 或 Microsoft 注册有 1 美元体验额度）。
2. 写入 .env：

BROWSER_USE_API_KEY=your-key

3. 代码中开启云浏览器，其余代码不用改：

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

计费参考：云浏览器按小时加网络流量计费，官方标注起价为每浏览器小时 0.02 美元；同时提供实时查看地址、隐身、住宅代理与验证码处理能力。具体价格以官方价格页为准。

登录态处理

• 本地浏览器：可用 Browser.from_system_chrome() 复用本机 Chrome 配置文件。
• 云浏览器：先同步配置文件，再使用 Browser(use_cloud=True, cloud_profile_id='your-profile-id')。
• 注意：配置同步只会搬运 Cookie，不包含 LocalStorage、IndexedDB 和扩展，部分网站需要重新登录。

六、模型选择与配置

使用建议：浏览器任务对模型的视觉理解与长流程规划要求较高，简单任务可用较小模型，复杂任务再升级模型，并结合成本与延迟评估。

七、进阶功能配置

7.1 自定义工具

import asyncio
from datetime import datetime, timezone

from browser_use import ActionResult, Agent, ChatBrowserUse, Tools
from dotenv import load_dotenv

load_dotenv()
tools = Tools()

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

async def main():
    agent = Agent(
        task="What is the current UTC time?",
        llm=ChatBrowserUse(model='bu-2-0'),
        tools=tools,
    )
    history = await agent.run()
    print(history.final_result())

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

7.2 自定义系统提示词

Agent 已内置官方系统提示词，一般无需手写。需要定制时：

• extend_system_message：在默认提示词后追加规则
• override_system_message：完全替换默认提示词（谨慎使用）

7.3 录制与回放（降低模型调用成本）

成功跑通一次后保存历史，之后用新参数回放，每一步不再调用模型：

from browser_use import Agent, ChatBrowserUse

llm = ChatBrowserUse()
agent = Agent(task='your task', llm=llm)
await agent.run()
agent.save_history('run.json')
print(agent.detect_variables())

results = await Agent(task='', llm=llm).load_and_rerun(
    'run.json', variables={'name': 'Grace Hopper'}, skip_failures=False
)

注意事项：

• 变量名以 detect_variables() 的输出为准，未知变量会被跳过并给出警告。
• 页面结构变化后，回放会在第一个无法匹配的步骤抛出 RuntimeError，之前的步骤已执行，重跑前先确认表单是否已提交。
• 保存的历史文件请妥善保管，页面快照与结果可能含有敏感信息。
• 使用 sensitive_data 时，回放的 Agent 也要传入相同的 sensitive_data，否则会直接输入占位符文本。

7.4 Claude 工具集集成

项目提供面向 Claude 的浏览器工具集，让 Claude 以 Browser Use 作为浏览器驱动，支持本地浏览器、云浏览器或通过 CDP 连接的远程浏览器，并附带 Bash 工具。依赖包含 anthropic.tools.browser 的 Anthropic SDK 版本，Bash 需要 Linux 或 macOS 环境（Windows 请用 WSL）。

八、生产环境建议

1. 密钥管理：使用环境变量或密钥管理服务，不要把密钥写进代码和镜像。
2. 进程管理：长期运行的服务可用 systemd、supervisor 或容器编排工具托管，并配置自动重启。
3. 资源规划：每个浏览器实例约占用数百 MB 内存，并发量较高时建议拆分实例或改用云浏览器。
4. 超时与重试：为任务设置最大步数与整体超时，避免异常页面造成无限循环。
5. 日志与录制：保留运行日志，需要排查时配合云端录制或实时查看功能。
6. 安全隔离：让 Agent 访问不可信网页存在提示词注入风险，建议使用独立账号、最小权限，并避免在同一浏览器配置中保存高权限登录态。
7. 合规使用：自动化访问网站前，确认目标站点条款允许，验证码与反爬策略的处理效果因站点而异，没有任何配置可以保证全部通过。

九、常见问题排查

十、快速命令速查

# 新建项目并安装
uv init --python 3.12 && uv add browser-use

# 安装浏览器内核
uvx playwright install chromium --with-deps

# 运行脚本
uv run agent.py

# Docker 构建与运行
docker build -t browser-use .
docker run --rm --env-file .env browser-use

附：项目关键信息

• 项目名称：Browser Use
• 仓库组织：browser-use
• 主要语言：Python（另有 TypeScript 版本）
• 协议：MIT
• 关注度：约 12 万 Star
• 相关仓库：Browser Harness（CLI）、Browser Harness JS、Browser Use Pi、Cloud SDK、Video Use、macOS Harness、Benchmark