用途
Browser-Use 用于处理复杂网页自动化任务，例如多步骤登录、填表、发帖、数据抓取等。当内置 browser tool（snapshot→act）搞不定时使用它——它是一个专门的浏览器 AI Agent，把一个 task 丢进去即可自主完成全流程。
触发词：browser-use、浏览器自动化、自动登录、自动填表、自动发帖、网页操控、复杂网页任务。
何时使用
- 截图、看页面、点一个按钮：使用内置 tool，免费且快；Browser-Use 属于杀鸡用牛刀。
- 5 步以上流程（登录→导航→填表→提交）：内置 tool 容易断，使用 Browser-Use。
- 需要反检测（真 Chrome）：使用 Browser-Use。
- 批量重复操作：使用 Browser-Use。
代价：Browser-Use 每步调一次外部 LLM（花钱且慢），简单操作请用内置 tool。
执行流程
- 检查环境：
test -d ~/browser-use-env && echo "已安装" || echo "需要安装"
- 首次安装（仅一次）：
python3 -m venv ~/browser-use-env
source ~/browser-use-env/bin/activate
pip install browser-use playwright langchain-openai
playwright install chromium
- 决定模式：
- 简单场景 / 不怕被检测：用内置 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
- 写脚本并运行：脚本写到用户 workspace 下，然后：
source ~/browser-use-env/bin/activate
python3 脚本路径.py
- 反馈结果：运行完把结果发给用户，失败则按故障决策树处理。
脚本模板
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 兼容性
- GPT-4o / 4o-mini：兼容，最佳，推荐。
- Claude：兼容，好用。
- Gemini：不兼容，结构化输出不兼容。
限制
Browser-Use 每步调用一次外部 LLM，成本更高、速度更慢，简单操作应使用内置 tool。模式B 需要用户先完全退出 Chrome 并配合启动远程调试端口。Gemini 因结构化输出不兼容而无法使用。