abczsl520/browser-use

Browser-Use 浏览器自动化

何时用 Browser-Use vs 内置 browser tool

| 场景 | 内置 tool | Browser-Use | |------|:-:|:-:| | 截图/看页面/点一个按钮 | ✅ 免费快 | ❌ 杀鸡用牛刀 | | 5步以上流程（登录→导航→填表→提交） | ❌ 容易断 | ✅ | | 需要反检测（真Chrome） | ❌ | ✅ | | 批量重复操作 | ❌ | ✅ |

代价：Browser-Use 每步调一次外部 LLM（花钱+慢），简单操作用内置 tool。

执行流程

1. 检查环境

test -d ~/browser-use-env && echo "已安装" || echo "需要安装"

2. 首次安装（仅一次）

python3 -m venv ~/browser-use-env
source ~/browser-use-env/bin/activate
pip install browser-use playwright langchain-openai
playwright install chromium

3. 决定模式

• 简单场景 / 不怕被检测：用内置 Chromium（模式A），直接跑
• 需要反检测 / 用户已有登录态：连真 Chrome（模式B），需用户配合

模式B前置步骤——提示用户：

请先完全退出 Chrome（Mac: Cmd+Q），然后告诉我"关了"

用户确认后执行：

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &
# Windows: "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
# Linux: google-chrome --remote-debugging-port=9222 &

验证：curl -s http://127.0.0.1:9222/json/version

4. 写脚本并运行

脚本写到用户 workspace 下，然后：

source ~/browser-use-env/bin/activate
python3 脚本路径.py

5. 反馈结果

运行完把结果发给用户，失败则按故障决策树处理。

脚本模板

import asyncio
from browser_use import Agent, ChatOpenAI, Browser

async def main():
    # LLM — 任何 OpenAI 兼容 API 均可
    llm = ChatOpenAI(
        model="gpt-4o-mini",
        api_key="<YOUR_API_KEY>",
        base_url="https://api.openai.com/v1",  # 或其他兼容端点
    )

    # 模式A: 内置 Chromium
    browser = Browser(headless=False, user_data_dir="~/.browser-use/任务名-profile")
    # 模式B: 连真 Chrome
    # browser = Browser(cdp_url="http://127.0.0.1:9222")

    agent = Agent(
        task="详细的任务描述（见下方写法指南）",
        llm=llm,
        browser=browser,
        use_vision=True,
        max_steps=25,
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

Task 写法指南（关键！）

✅ 好的写法：具体分步

task = """
1. 打开 https://www.reddit.com/login
2. 输入用户名: x_user
3. 输入密码: x_pass
4. 点击登录按钮
5. 如果遇到 CAPTCHA，等待30秒让用户手动完成
6. 登录成功后，导航到 https://www.reddit.com/r/xxx/submit
7. 在标题框输入: xxx
8. 在正文框输入: xxx
9. 点击发布按钮
"""

❌ 坏的写法：模糊笼统

task = "去Reddit发个帖子"

进阶技巧

• 键盘导航兜底：task里加 "如果按钮点不了，用 Tab+Enter 键盘导航"
• 错误恢复：加 "如果页面加载失败，刷新重试"
• 敏感数据：用占位符 + sensitive_data 参数，密码不暴露给LLM

敏感数据处理

agent = Agent(
    task="登录网站，用户名 x_user，密码 x_pass",
    sensitive_data={"x_user": "真实用户名", "x_pass": "真实密码"},
    use_vision=False,  # 关闭截图防止LLM看到密码
    llm=llm, browser=browser,
)

关键参数速查

| 参数 | 说明 | 推荐 | |------|------|------| | use_vision | AI看截图 | 一般True，有密码时False | | max_steps | 最大步数 | 20-30 | | max_failures | 最大重试 | 3（默认） | | flash_mode | 快速模式（跳过思考） | 简单任务True | | extend_system_message | 追加系统提示 | 加特定指令 | | allowed_domains | 限制访问域名 | 安全场景用 | | fallback_llm | 备用LLM | 主LLM不稳时设 |

故障决策树

被网站检测为自动化？
  └→ 换模式B连真Chrome

CAPTCHA人机验证？
  └→ 提示用户手动完成，task里写等待时间

LLM调用超时？
  └→ 设 fallback_llm 或换更快的模型

操作了但没效果（如帖子没发出）？
  └→ 1. 检查是否被平台反垃圾拦截（新账号常见）
     2. task里加更具体的确认步骤

网站UI变化导致找不到元素？
  └→ Browser-Use能自适应，但可在task里加备选路径

LLM兼容性

| LLM | 兼容 | 备注 | |-----|:---:|------| | GPT-4o / 4o-mini | ✅ | 最佳，推荐 | | Claude | ✅ | 好用 | | Gemini | ❌ | 结构化输出不兼容 |