🧭 核心模式选择

在开始前，请根据你的使用场景选择最合适的模式：

  • 作为 AI 代理的“技能”（CLI 方式）：适用于你已经在使用 Claude Code、Cursor、OpenClaw 等 AI 编程助手，并希望它能帮你自动完成浏览器任务（如“上传视频到 YouTube”、“填写这份工作申请”）。你只需在对话中通过一条指令让助手完成安装，即可通过自然语言驱动浏览器。
  • 作为 Python 库（开发方式）：适用于你需要编写 Python 代码来构建自动化流程的场景，例如定时抓取数据、批量执行任务或嵌入到自己的产品中。

📦 安装与配置

通用环境要求

  • 操作系统：Windows、macOS 或 Linux。
  • Python 版本：需要 Python 3.11 或更高版本。
  • 包管理工具：推荐使用 uv（更快的 Python 包管理器），也可使用 pip。

配置 LLM API 密钥

Browser-Use 本身免费，但需要一个 LLM 来驱动代理。你可以在项目根目录创建 .env 文件，并填入你的 API 密钥。支持多种 LLM：

1
2
3
4
5
6
7
# 使用 Browser-Use 云模型（推荐，自带优化）
BROWSER_USE_API_KEY=your-key

# 或使用自己的 LLM 提供商
GOOGLE_API_KEY=your-key
ANTHROPIC_API_KEY=your-key
OPENAI_API_KEY=your-key

如果没有 BROWSER_USE_API_KEY，可以到 Browser Use Cloud 免费获取。

🤖 方式一：安装为 AI 代理的“技能”（推荐新手）

这是最快上手的方式，尤其适合非开发人员或希望用自然语言控制浏览器的用户。

安装步骤：直接在 AI 编程助手（如 Cursor、Claude Code 等）的对话中输入以下指令，代理会自行完成安装和配置：

“Install or upgrade browser-use to the latest stable version with uv using Python 3.12, run browser-use skill install to register the skill, and connect it to my browser. If setup or connection fails, follow https://github.com/browser-use/browser-harness/blob/main/install.md.”

使用示例：安装成功后，你就可以用自然语言向代理下达任务了：

  • “帮我比较这三台笔记本电脑，并生成一个价格对比表格。”
  • “用我的简历信息填写这份工作申请表。”
  • “把我 GitHub 仓库的星标数量提取出来。”

🐍 方式二：作为 Python 库集成（供开发者）

如果你需要编写代码实现自动化，请按以下步骤操作。

第1步：安装 Python 库

1
2
3
4
5
# 使用 uv（推荐）
uv add browser-use

# 或使用 pip
pip install browser-use

第2步：编写第一个自动化脚本
创建一个 Python 文件（如 run_agent.py），写入以下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import asyncio
from browser_use import Agent, ChatBrowserUse

async def main():
    # 初始化代理
    agent = Agent(
        task="找出 browser-use 这个 GitHub 仓库的星标数量",  # 用自然语言描述任务
        llm=ChatBrowserUse(model='bu-2-0-mini-preview'),  # Browser-Use 优化模型
        # 也可以使用其他模型，例如：
        # llm=ChatOpenAI(model='gpt-5.5')
        # llm=ChatAnthropic(model='claude-sonnet-4')
    )
    
    # 执行任务并获取历史记录
    history = await agent.run()
    print(f"最终结果: {history.final_result()}")

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

第3步：运行脚本

1
python run_agent.py

代理会自动打开浏览器，执行你描述的任务，并返回结果。

🔧 进阶用法与推荐配置

  • 使用云代理（Cloud Agent）：若需处理复杂任务、反爬或大规模并行，推荐使用 Browser-Use 全托管云 API。它提供了更强的执行引擎、自动代理轮换和验证码解决能力。

    1
    2
    3
    4
    curl -X POST https://api.browser-use.com/api/v4/runs \
      -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"task": "你的任务描述"}'

  • 添加自定义工具：你可以扩展代理的能力，让它调用你自定义的函数。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    from browser_use import Tools

    tools = Tools()
    @tools.action(description='发送邮件')
    def send_email(recipient: str, content: str) -> str:
        # 你的邮件发送逻辑
        return f"邮件已发送至 {recipient}"

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

  • 处理认证登录：如需操作需要登录的网站，可以使用真实浏览器配置文件（复用本地 Chrome 的登录态），参考认证示例文档。

💡 常见问题解决

  • 验证码处理：基础版需依赖浏览器指纹和代理。生产环境建议使用 Browser-Use Cloud，它内置了反检测和验证码解决能力。
  • 生产环境部署：大规模运行时，Chrome 内存占用高，管理复杂。推荐直接使用 Browser-Use Cloud API，它会帮你处理基础设施、代理轮转和并行执行。
  • 模型选择建议：在代码中使用 ChatBrowserUse(model='bu-2-0-mini-preview') 是性价比最高的选择。它也支持通过前缀指定其他模型，如 anthropic/claude-sonnet-4-6。

总结

Browser-Use 的核心价值在于将复杂的浏览器自动化封装成自然语言任务。对于个人用户或快速尝试，推荐先以“技能”方式安装到你的 AI 编程助手中，通过对话来驱动浏览器。对于开发者或需要构建自动化流程的场景，推荐使用其 Python 库，并结合云 API 获得更好的稳定性与扩展性。