Browser Use 入门教程：用 AI 自动打开网页、点击按钮和提取信息

跑完 uvx browser-use install，下一步是写 task。写“打开网站看看”会失败：agent 不知道要做什么，要么循环尝试，要么提前结束。

Browser Use 是 Python 开源库，让 AI 控制 Chromium 浏览器，实现网页自动化。它可以在本地或 self-hosted 环境运行，不依赖 Cloud 服务。如果你已经理解 Browser Agent 概念，这篇教程会从安装到第一条成功任务，包括安全配置、结果读取和失败排查。

Browser Use 是什么：一句话定位

Browser Use 是 Python library for AI browser automation。它让 LLM Agent 能够像人类一样操作浏览器：导航、点击、输入、滚动、提取数据、截图。

它的定位是本地或 self-hosted 运行，不依赖 Browser Use Cloud。开源库和 Cloud Agent 的 API 不同：本篇使用开源库入门，Cloud SDK 的 structured output、human-in-the-loop、live preview 等能力不在本文范围。

如果你还在问“Browser Agent 是什么”，可以先看 Browser Agent 概念（后续发布）。如果你已经理解概念，这篇教程回答“我现在怎样跑起来”。

安装与准备：从 uv 到 API key

截至 2026-06-30，官方 README 和 quickstart 的安装步骤如下：

1. Python 版本要求

Browser Use 需要 Python ≥3.11。官方 quickstart 示例用 Python 3.12 创建 venv，你可以按自己环境选择。

2. 安装 uv（推荐）

uv 是 Astral 开发的现代 Python 包管理器。如果你的环境还没有 uv：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 初始化项目并安装 browser-use

# 创建项目目录
mkdir my-browser-use
cd my-browser-use

# 初始化项目
uv init

# 安装 browser-use（包含核心依赖）
uv add "browser-use[core]"

# 同步依赖
uv sync

如果你不用 uv，也可以用 pip：

Railway - 现代化的部署平台，告别繁琐运维，让代码分钟级上线

立即开始 →推广

pip install "browser-use[core]"

4. 安装 Chromium 浏览器运行环境

Browser Use 底层依赖 Playwright，需要先安装 Chromium：

uvx browser-use install

这个命令会下载并配置 Chromium，让 agent 能够启动浏览器实例。

5. 配置 API key

Browser Use 需要连接 LLM 才能理解任务和做出决策。官方推荐 ChatBrowserUse，它是专门为浏览器任务设计的模型。

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

# .env
BROWSER_USE_API_KEY=your_api_key_here

如果你用 OpenAI、Anthropic、Google Gemini 或本地 Ollama，需要填写对应的 API key：

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

写第一个脚本：最小模板

最小脚本只需要三个部分：导入模块、创建 Agent、运行任务。

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # 创建浏览器实例（调试时显示窗口）
    browser = Browser(headless=False)

    # 创建 LLM 实例
    llm = ChatBrowserUse()

    # 创建 Agent
    agent = Agent(
        task="打开 quotes.toscrape.com，向下滚动一屏，点击 'Next' 按钮，提取第二页所有 quotes 的文本和作者",
        llm=llm,
        browser=browser
    )

    # 运行任务（限制步数）
    history = await agent.run(max_steps=20)

    # 关闭浏览器
    await browser.close()

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

这个脚本做了几件事：

1. Browser(headless=False)：显示浏览器窗口，方便调试。调试完成后可以改成 headless=True。
2. ChatBrowserUse()：使用官方的浏览器模型。你也可以换成 ChatOpenAI(model="gpt-4o") 或其他模型。
3. task 必须具体：不要写“打开网站看看”，而是写清楚“导航到 X URL、滚动、点击 Y 按钮、提取 Z 内容”。模糊任务会导致 agent 循环尝试或提前结束。
4. max_steps=20：限制 agent 最多执行 20 步操作。第一条任务建议用 10-20 步，避免 agent 卡在某个动作循环尝试。

运行脚本：

uv run python main.py

别让 agent 无限跑：max_steps 是安全线

max_steps 参数限制 agent 的执行步数。官方默认值是 100，但第一条任务建议降到 10-20 步。

为什么需要限制：

• Agent 可能遇到点击失败、页面加载慢、弹窗遮挡等问题，导致它在一个动作上循环尝试。
• 如果没有步数限制，agent 可能一直跑下去，消耗 token 和时间。
• 第一条任务的目标是“跑通”，而不是“完美执行”。限制步数能让你更快发现问题。

建议配置：

# 第一条任务：10-20 步
await agent.run(max_steps=20)

# 复杂任务：按需要调整，但不要超过 50 步
await agent.run(max_steps=50)

给新手的安全启动配置

第一条任务不要用主账号登录态，也不要让 agent 随意跳转任意网站。安全配置包括：

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

1. headless=False 调试模式

browser = Browser(headless=False)

显示浏览器窗口，你能看到 agent 在做什么，方便判断是点击失败、页面卡住还是任务描述有误。调试完成后改成 headless=True。

2. allowed_domains 限制导航范围

browser = Browser(
    headless=False,
    allowed_domains=["quotes.toscrape.com"]
)

allowed_domains 会阻止 agent 导航到其他域名。如果你的任务只涉及一个网站，建议加上这个限制。

注意：Browser Use 支持子域通配符，例如 allowed_domains=["*.example.com"]；但不支持 TLD 通配符，allowed_domains=["example.*"] 不会被识别。如果只访问一个固定网站，直接写完整域名最稳：

allowed_domains=["quotes.toscrape.com", "github.com"]

3. 使用独立 profile，不要复用主 Chrome

browser = Browser(
    headless=False,
    user_data_dir="./browser_profile"
)

Agent 会创建独立的浏览器 profile，不会访问你的主 Chrome 登录态、Cookie 或敏感数据。第一篇教程只用公开页面，不碰登录态。

4. 不要用 disable_security

disable_security 参数会禁用浏览器安全策略，官方文档标注为不推荐。如果你看到某些教程提到这个参数，跳过它。

如何读取结果：不止是“跑完了”

agent.run() 返回 AgentHistoryList 类型。你可以用多个 helper 方法读取结果和过程：

history = await agent.run(max_steps=20)

# 最终结果
result = history.final_result()
print("最终结果:", result)

# 提取的内容
extracted = history.extracted_content()
print("提取内容:", extracted)

# 错误列表
errors = history.errors()
print("错误:", errors)

# 是否有错误
if history.has_errors():
    print("任务执行中遇到错误")

# 执行的 URL 列表
urls = history.urls()
print("访问的 URL:", urls)

# 截图路径列表
screenshots = history.screenshot_paths()
print("截图:", screenshots)

# 执行的动作名称
actions = history.action_names()
print("动作:", actions)

# 总步数
steps = history.number_of_steps()
print("执行步数:", steps)

新手常见问题：只看浏览器窗口动了，但没有用这些方法验证结果。如果 final_result() 返回空，说明 agent 可能提前结束或任务描述有误。如果 errors() 有内容，需要看具体错误再调整。

第一次任务：打开、点击、提取

使用 quotes.toscrape.com 作为第一个任务场景。这是一个专门为爬虫练习设计的公开网站，没有登录要求，结构简单。

任务 1：打开并滚动

agent = Agent(
    task="打开 quotes.toscrape.com，向下滚动一屏",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("访问的 URL:", history.urls())

任务 2：点击按钮

agent = Agent(
    task="打开 quotes.toscrape.com，点击页面底部的 'Next' 按钮",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("是否成功:", history.is_successful())

任务 3：提取内容

agent = Agent(
    task="打开 quotes.toscrape.com，提取第一页所有 quotes 的文本和作者",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("提取内容:", extracted)

任务 4：组合任务

agent = Agent(
    task="打开 quotes.toscrape.com，点击 'Next' 按钮，提取第二页所有 quotes 的文本和作者",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("最终结果:", history.final_result())
print("错误:", history.errors())

失败后看哪里：排障清单

当 agent 返回空结果、报错或卡住时，按以下清单排查：

1. 点击失败

• 检查 history.errors() 是否有 “click failed” 或 “element not found”
• 尝试在任务里加入键盘导航兜底：“如果点击失败，用键盘 Tab 找到按钮，然后按 Enter”
• 检查 history.screenshot_paths()，看截图判断元素是否可见

2. 提取内容为空

• 检查 history.urls() 确认页面是否真的打开
• 检查 history.screenshot_paths() 看页面状态
• 确认任务描述是否明确：“提取所有 quotes 的文本和作者”而不是“看看内容”

3. 页面卡住

• 检查 allowed_domains 是否阻止跳转
• 检查网络连接和页面加载时间
• 降低 max_steps 或在任务里加入超时处理：“如果页面 10 秒内没加载完，返回首页”

4. 结果不完整

• 检查 max_steps 是否过早停止
• 检查 history.number_of_steps() 看实际执行步数
• 调整任务描述，拆成多个子任务分别执行

5. 整体失败

• 检查 .env 中的 API key 是否正确
• 确认模型是否支持：ChatBrowserUse、OpenAI、Anthropic、Google Gemini 或本地 Ollama
• 检查任务描述是否过于抽象：“打开网站看看”改成具体动作

Beta Agent vs 稳定版：两套入口对照

截至 2026-06-30，官方 README 同时提供两套 Agent 导入路径：

稳定版

from browser_use import Agent, Browser

这是稳定版入口。如果你之前用过 Browser Use，可以继续用这个路径。

KiloClaw - 企业级 OpenClaw 托管服务，赋能 AI Agent 自动化编排与智能模型路由

立即开始 →推广

Beta 版（0.13）

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

这是 0.13 beta agent，由 Rust core 和 browser harness 支撑。官方 README 说明：旧用户可以继续用稳定版，新用户可以尝试 beta。

如果你不确定用哪个，按官方 README 当前版本核对。本篇教程使用稳定版示例，beta 版的 API 可能有差异。

开源 vs Cloud：边界在哪里

本篇使用 Browser Use 开源库，在本地运行。

Browser Use Cloud 提供托管服务，API 不同：

• Cloud SDK 当前是 API v3
• Cloud 提供 structured output、human-in-the-loop、live preview、persistent profiles 等能力
• Cloud 的 Python/TypeScript SDK 与开源库 API 不兼容

什么时候考虑 Cloud：

• 生产部署、托管环境
• 需要 stealth、CAPTCHA、proxy 等高级能力（本篇不展开细节）
• 多账号、持久化 profile、团队协作

本篇只做本地入门。Cloud 的使用方式和定价留在后续文章。

下一步：延伸阅读

这篇教程覆盖 Browser Use 开源库的本地入门：安装、API key、最小脚本、打开网页、点击按钮、提取信息、失败排查。

下一步可以尝试：

• 已发布：OpenClaw 浏览器自动化实战指南、Computer-Use Agent：让 AI 操作你的电脑、MCP 插件指南
• 后续主题：Playwright MCP 接入 Claude、Codex、Cursor、Stagehand 工程化、Browser Use 工具选型、登录态与认证、云基础设施、合规与安全
• 官方文档：quickstart、prompting guide、browser config

建议先用 quotes.toscrape.com 或 GitHub 公开页面跑通第一个任务，再考虑登录态和 Cloud。