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	❌	结构化输出不兼容

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

browser-use

Browser-Use 浏览器自动化

何时用 Browser-Use vs 内置 browser tool

执行流程

1. 检查环境