// open-source Python library

连接任意 LLM
自动化浏览器操作

Browser Use 是一个 Python 库,用于 AI 浏览器自动化。可连接任意 LLM,在本地或自托管环境中运行,支持复杂多步骤浏览器任务。

79k+
GitHub Stars
MIT
开源协议
3.11+
Python 版本
9+
支持 LLM 提供商
quickstart

快速开始

四步启动你的第一个 AI 浏览器 Agent,新用户可获得 5 次免费任务。

01
安装 Browser-Use
使用 uv 创建虚拟环境(需要 Python ≥ 3.11),安装库并下载 Chromium。
pip install uv
uv venv --python 3.12
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

uv pip install browser-use
uvx browser-use install   # 安装 Chromium
02
配置 LLM 密钥
推荐使用 ChatBrowserUse,新用户可在 cloud.browser-use.com/new-api-key 获取 5 次免费任务。
# .env
BROWSER_USE_API_KEY=your-key   # 推荐
# GOOGLE_API_KEY=your-key
# OPENAI_API_KEY=your-key
# ANTHROPIC_API_KEY=your-key
03
运行第一个 Agent
创建 Agent,用自然语言描述任务,等待 Agent 自动完成。
from browser_use import Agent, ChatBrowserUse
from dotenv import load_dotenv
import asyncio

load_dotenv()

async def main():
    llm = ChatBrowserUse()
    agent = Agent(
        task="Find the number 1 post on Show HN",
        llm=llm
    )
    await agent.run()

asyncio.run(main())
04
生产环境部署
使用 @sandbox 装饰器,处理 Agent、浏览器、持久化、认证与 Cookie。
from browser_use import Browser, sandbox, ChatBrowserUse
from browser_use.agent.service import Agent

@sandbox(cloud_profile_id='your-profile-id')
async def production_task(browser: Browser):
    agent = Agent(
        task="Your authenticated task",
        browser=browser,
        llm=ChatBrowserUse(),
    )
    await agent.run()

asyncio.run(production_task())
// features
  • 连接任意 LLM(OpenAI、Anthropic、Gemini、Ollama 等)
  • 本地运行或自托管,完全掌控
  • MIT 开源,完全可定制
  • 支持复杂多步骤浏览器任务
  • 支持视觉模式(截图分析)
  • 支持结构化输出(Pydantic)
  • 生成操作过程 GIF
  • 视频录制与网络追踪调试
// coding agent quickstart
将以下内容粘贴到 Claude Code、Cursor 或 Copilot 中,获取完整 SDK 参考(约 9k tokens):
# 1. 复制全部内容
# docs.browser-use.com/open-source/coding-agent-quickstart
# 2. 粘贴到你的项目中
# 3. 提示编码 Agent:
"Help me get started with Browser Use"
supported models

支持的 LLM 模型

Browser Use 支持所有主流 LLM 提供商,推荐使用 ChatBrowserUse 获得最佳性能。

# 推荐:针对浏览器自动化优化,精度最高、速度快 3-5 倍
from browser_use import Agent, ChatBrowserUse

# 默认模型 bu-latest
llm = ChatBrowserUse()

# 高级模型 bu-2-0(能力更强)
llm = ChatBrowserUse(model='bu-2-0')

agent = Agent(task="...", llm=llm)

# 所需环境变量:BROWSER_USE_API_KEY
# 可用模型:bu-latest / bu-1-0(默认)| bu-2-0(高级)

# bu-1-0 定价:输入 $0.20 / 缓存 $0.02 / 输出 $2.00(每 1M tokens)
# bu-2-0 定价:输入 $0.60 / 缓存 $0.06 / 输出 $3.50(每 1M tokens)
from browser_use import Agent, ChatGoogle
from dotenv import load_dotenv

load_dotenv()  # 读取 GOOGLE_API_KEY

llm = ChatGoogle(model='gemini-flash-latest')
agent = Agent(task="Your task here", llm=llm)

# 所需环境变量:GOOGLE_API_KEY
# 注意:GEMINI_API_KEY 已于 2025-05 弃用
from browser_use import Agent, ChatOpenAI

# 推荐使用 O3 模型以获得最佳精度
llm = ChatOpenAI(model="o3")
agent = Agent(task="...", llm=llm)

# 所需环境变量:OPENAI_API_KEY
from browser_use import Agent, ChatAnthropic

llm = ChatAnthropic(model="claude-sonnet-4-0")
agent = Agent(task="...", llm=llm)

# 所需环境变量:ANTHROPIC_API_KEY
from browser_use import Agent, ChatAzureOpenAI

llm = ChatAzureOpenAI(model="o4-mini")
agent = Agent(task="...", llm=llm)

# 所需环境变量:
# AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
# AZURE_OPENAI_API_KEY=your-key

# GPT-5.1 Codex 模型(自动使用 Responses API):
llm = ChatAzureOpenAI(
    model="gpt-5.1-codex-mini",
    api_version="2025-03-01-preview",
)
from browser_use import Agent
from browser_use.llm import ChatAWSBedrock

llm = ChatAWSBedrock(
    model="anthropic.claude-3-5-sonnet-20240620-v1:0",
    aws_region="us-east-1",
)
agent = Agent(task="Your task here", llm=llm)

# 所需环境变量:
# AWS_ACCESS_KEY_ID  AWS_SECRET_ACCESS_KEY  AWS_DEFAULT_REGION
from browser_use import Agent, ChatGroq

llm = ChatGroq(model="meta-llama/llama-4-maverick-17b-128e-instruct")
agent = Agent(task="Your task here", llm=llm)

# 所需环境变量:GROQ_API_KEY
# 1. 安装 Ollama:https://github.com/ollama/ollama
# 2. 启动服务
ollama serve
# 3. 拉取模型
ollama pull llama3.1:8b

# Python 代码:
from browser_use import Agent, ChatOllama

llm = ChatOllama(model="llama3.1:8b")
agent = Agent(task="...", llm=llm)
# 仅推荐使用 qwen-vl-max
from browser_use import Agent, ChatOpenAI
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('ALIBABA_CLOUD')
base_url = 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1'

llm = ChatOpenAI(model='qwen-vl-max', api_key=api_key, base_url=base_url)
agent = Agent(task="Your task here", llm=llm, use_vision=True)
cli

Browser Use CLI

快速、持久的命令行浏览器自动化工具。CLI 使用多会话守护进程架构,浏览器在命令之间保持运行,延迟约 50ms。

安装
一行安装(推荐)
# macOS / Linux
curl -fsSL https://browser-use.com/cli/install.sh | bash

# Windows(PowerShell)
& "C:\Program Files\Git\bin\bash.exe" -c \
  'curl -fsSL https://browser-use.com/cli/install.sh | bash'

# 安装技能插件(推荐)
npx skills add https://github.com/browser-use/browser-use \
  --skill browser-use

# 验证安装
browser-use doctor
browser-use setup    # 运行设置向导(可选)
浏览器模式
启动选项
# 默认:无头 Chromium
browser-use open https://example.com

# 显示浏览器窗口
browser-use --headed open https://example.com

# 使用真实 Chrome(含已有登录/Cookie)
browser-use --profile "Default" open https://gmail.com

# 自动发现并连接正在运行的 Chrome
browser-use --connect open https://example.com

# 通过 CDP URL 连接现有浏览器
browser-use --cdp-url http://localhost:9222 open https://example.com
命令说明
open <url>导航到 URL
back后退
scroll down向下滚动
scroll up向上滚动
scroll down --amount 1000按像素滚动
命令说明
state获取 URL、标题和可点击元素
screenshot [path]截图
screenshot --full path.png全页截图
命令说明
click <index>按索引点击元素
click <x> <y>按坐标点击
type "text"向聚焦元素输入
input <index> "text"点击元素后输入
keys "Enter"发送键盘按键
keys "Control+a"发送组合键
select <index> "value"选择下拉选项
upload <index> <path>上传文件
hover <index>鼠标悬停
dblclick <index>双击
rightclick <index>右键点击
命令说明
wait selector "css"等待元素可见
wait text "Success"等待文本出现
wait selector ".loading" --state hidden等待元素消失
命令说明
get title获取页面标题
get html获取完整 HTML
get html --selector "h1"获取指定元素 HTML
get text <index>获取元素文本
get value <index>获取输入框值
eval "js code"执行 JavaScript
# 保存 API Key
browser-use cloud login sk-abc123...

# 创建云端浏览器并连接
browser-use cloud connect

# 创建任务
browser-use cloud v2 POST /tasks \
  '{"task":"Search for AI news","url":"https://google.com"}'

# 轮询任务完成
browser-use cloud v2 poll <task-id>

# Tunnel:将本地开发服务器暴露给云端浏览器
npm run dev &                       # localhost:3000
browser-use tunnel 3000             # → https://abc.trycloudflare.com
agent configuration

Agent 配置参数

完整的 Agent 配置参考,精细控制自动化行为。

参数类型说明
toolsToolRegistryAgent 可调用的工具注册表
skills / skill_idslist[str]要加载的技能 ID 列表,需要 BROWSER_USE_API_KEY
browserBrowser浏览器对象,可指定浏览器设置
output_model_schematype[BaseModel]用于结构化输出验证的 Pydantic 模型类
参数默认值说明
use_vision"auto""auto" 仅在请求时使用视觉;True 始终包含截图;False 禁用截图
vision_detail_level'auto'截图细节级别:'low' / 'high' / 'auto'
page_extraction_llm主 LLM用于页面内容提取的独立 LLM
fallback_llmNone主 LLM 失败时的备用 LLM,触发条件:429/401/402/500-504 错误
参数默认值说明
initial_actionsNone在主任务前运行的初始动作列表(不使用 LLM)
max_actions_per_step4每步最大动作数
max_failures3出错步骤的最大重试次数
use_thinkingTrue是否使用内部思考字段进行推理
flash_modeFalse快速模式,跳过评估和思考过程
参数类型说明
override_system_messagestr完全替换默认系统提示
extend_system_messagestr在默认系统提示基础上添加自定义指令
参数类型说明
save_conversation_pathstr保存完整对话历史的路径
available_file_pathslist[str]Agent 可访问的文件路径列表
sensitive_datadict需谨慎处理的敏感数据字典
参数默认值说明
max_history_itemsNoneLLM 内存中保留的最大步骤数,None 保留全部
llm_timeout90LLM 调用超时(秒)
step_timeout120每步超时(秒)
directly_open_urlTrue检测到 URL 时直接打开
generate_gifFalse生成操作过程 GIF 动画
include_attributes页面分析中包含的 HTML 属性列表
browser configuration

浏览器配置参数

完整的浏览器配置参考,从显示模式到网络代理、视频录制全覆盖。

参数默认值说明
cdp_urlNone连接现有浏览器的 CDP URL,如 http://localhost:9222
headlessNone无头模式,自动检测显示可用性(True/False/None)
window_size有头模式窗口大小,如 {'width': 1920, 'height': 1080}
viewport内容区域大小,如 {'width': 1280, 'height': 720}
device_scale_factor1.0设备缩放比例(DPI),高分辨率截图设为 2.0 或 3.0
参数默认值说明
keep_aliveNoneAgent 完成后保持浏览器运行
allowed_domains限制导航到特定域名,支持通配符 *.example.com
prohibited_domains阻止导航到特定域名
enable_default_extensionsTrue加载自动化扩展(uBlock Origin、Cookie 处理器等)
参数默认值说明
user_data_dir自动临时目录浏览器配置文件数据目录;None 为隐身模式
profile_directory'Default'Chrome 配置文件子目录名
storage_state浏览器存储状态(Cookie、localStorage),可为文件路径或字典
参数说明
proxy代理配置,使用 ProxySettings(server='http://host:8080', username='user', password='pass')
permissions授予浏览器的权限,默认 ['clipboardReadWrite', 'notifications']
参数说明
executable_path自定义浏览器可执行文件路径(macOS/Windows/Linux 各有不同路径)
channel浏览器渠道:'chromium' / 'chrome' / 'chrome-beta' / 'msedge' 等
args额外命令行参数,如 ['--disable-gpu']
参数默认值说明
minimum_wait_page_load_time0.25捕获页面状态前的最短等待时间(秒)
wait_for_network_idle_page_load_time0.5等待网络空闲的时间(秒)
wait_between_actions0.5Agent 动作之间的等待时间(秒)
参数默认值说明
accept_downloadsTrue自动接受所有下载
downloads_path下载文件目录
auto_download_pdfsTrue自动下载 PDF 而非在浏览器中查看
record_video_dir视频录制目录(.mp4 格式),需 pip install "browser-use[video]"
record_video_framerate30视频帧率
record_har_path保存网络追踪文件路径(.har 格式)
traces_dir调试用完整 trace 文件目录
from browser_use import Browser

# 自动选择第一个可用配置文件
browser = Browser.from_system_chrome()

# 或指定配置文件
browser = Browser.from_system_chrome(profile_directory='Profile 1')

# 列出所有 Chrome 配置文件
profiles = Browser.list_chrome_profiles()
for p in profiles:
    print(f"{p['directory']}: {p['name']}")
local development

本地开发

克隆仓库、配置开发环境并运行示例。

环境搭建
# 克隆仓库
git clone https://github.com/browser-use/browser-use
cd browser-use

# 使用 uv 安装(推荐)
uv sync --all-extras --dev

# 或使用 pip 直接安装最新版
pip install -U \
  git+https://github.com/browser-use/browser-use.git@main
配置
cp .env.example .env
# 设置日志级别
BROWSER_USE_LOGGING_LEVEL=debug
辅助脚本
# 完整安装脚本
./bin/setup.sh

# 运行所有预提交钩子(格式化、lint、类型检查)
./bin/lint.sh

# 运行 CI 核心测试套件
./bin/test.sh

# 运行示例
uv run examples/simple.py
开始你的第一个 Agent
开源 MIT 协议,连接任意 LLM,本地或自托管运行。
★ Star on GitHub 获取免费 API Key → 查看开源文档 ↗