Browser Use 是一个 Python 库,用于 AI 浏览器自动化。可连接任意 LLM,在本地或自托管环境中运行,支持复杂多步骤浏览器任务。
四步启动你的第一个 AI 浏览器 Agent,新用户可获得 5 次免费任务。
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
# .env
BROWSER_USE_API_KEY=your-key # 推荐
# GOOGLE_API_KEY=your-key
# OPENAI_API_KEY=your-key
# ANTHROPIC_API_KEY=your-key
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())
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())
# 1. 复制全部内容
# docs.browser-use.com/open-source/coding-agent-quickstart
# 2. 粘贴到你的项目中
# 3. 提示编码 Agent:
"Help me get started with Browser Use"
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 使用多会话守护进程架构,浏览器在命令之间保持运行,延迟约 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
| 命令 | 说明 |
|---|---|
| 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> | 右键点击 |
| 命令 | 说明 |
|---|---|
| cookies get | 获取所有 Cookie |
| cookies set <name> <value> | 设置 Cookie |
| cookies clear | 清除所有 Cookie |
| cookies export <file> | 导出为 JSON |
| cookies import <file> | 从 JSON 导入 |
| 命令 | 说明 |
|---|---|
| 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 配置参考,精细控制自动化行为。
| 参数 | 类型 | 说明 |
|---|---|---|
| tools | ToolRegistry | Agent 可调用的工具注册表 |
| skills / skill_ids | list[str] | 要加载的技能 ID 列表,需要 BROWSER_USE_API_KEY |
| browser | Browser | 浏览器对象,可指定浏览器设置 |
| output_model_schema | type[BaseModel] | 用于结构化输出验证的 Pydantic 模型类 |
| 参数 | 默认值 | 说明 |
|---|---|---|
| use_vision | "auto" | "auto" 仅在请求时使用视觉;True 始终包含截图;False 禁用截图 |
| vision_detail_level | 'auto' | 截图细节级别:'low' / 'high' / 'auto' |
| page_extraction_llm | 主 LLM | 用于页面内容提取的独立 LLM |
| fallback_llm | None | 主 LLM 失败时的备用 LLM,触发条件:429/401/402/500-504 错误 |
| 参数 | 默认值 | 说明 |
|---|---|---|
| initial_actions | None | 在主任务前运行的初始动作列表(不使用 LLM) |
| max_actions_per_step | 4 | 每步最大动作数 |
| max_failures | 3 | 出错步骤的最大重试次数 |
| use_thinking | True | 是否使用内部思考字段进行推理 |
| flash_mode | False | 快速模式,跳过评估和思考过程 |
| 参数 | 类型 | 说明 |
|---|---|---|
| override_system_message | str | 完全替换默认系统提示 |
| extend_system_message | str | 在默认系统提示基础上添加自定义指令 |
| 参数 | 类型 | 说明 |
|---|---|---|
| save_conversation_path | str | 保存完整对话历史的路径 |
| available_file_paths | list[str] | Agent 可访问的文件路径列表 |
| sensitive_data | dict | 需谨慎处理的敏感数据字典 |
| 参数 | 默认值 | 说明 |
|---|---|---|
| max_history_items | None | LLM 内存中保留的最大步骤数,None 保留全部 |
| llm_timeout | 90 | LLM 调用超时(秒) |
| step_timeout | 120 | 每步超时(秒) |
| directly_open_url | True | 检测到 URL 时直接打开 |
| generate_gif | False | 生成操作过程 GIF 动画 |
| include_attributes | — | 页面分析中包含的 HTML 属性列表 |
完整的浏览器配置参考,从显示模式到网络代理、视频录制全覆盖。
| 参数 | 默认值 | 说明 |
|---|---|---|
| cdp_url | None | 连接现有浏览器的 CDP URL,如 http://localhost:9222 |
| headless | None | 无头模式,自动检测显示可用性(True/False/None) |
| window_size | — | 有头模式窗口大小,如 {'width': 1920, 'height': 1080} |
| viewport | — | 内容区域大小,如 {'width': 1280, 'height': 720} |
| device_scale_factor | 1.0 | 设备缩放比例(DPI),高分辨率截图设为 2.0 或 3.0 |
| 参数 | 默认值 | 说明 |
|---|---|---|
| keep_alive | None | Agent 完成后保持浏览器运行 |
| allowed_domains | — | 限制导航到特定域名,支持通配符 *.example.com |
| prohibited_domains | — | 阻止导航到特定域名 |
| enable_default_extensions | True | 加载自动化扩展(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_time | 0.25 | 捕获页面状态前的最短等待时间(秒) |
| wait_for_network_idle_page_load_time | 0.5 | 等待网络空闲的时间(秒) |
| wait_between_actions | 0.5 | Agent 动作之间的等待时间(秒) |
| 参数 | 默认值 | 说明 |
|---|---|---|
| accept_downloads | True | 自动接受所有下载 |
| downloads_path | — | 下载文件目录 |
| auto_download_pdfs | True | 自动下载 PDF 而非在浏览器中查看 |
| record_video_dir | — | 视频录制目录(.mp4 格式),需 pip install "browser-use[video]" |
| record_video_framerate | 30 | 视频帧率 |
| 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']}")
克隆仓库、配置开发环境并运行示例。
# 克隆仓库
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