browser-use

Browser-Use Browser Automation

When to use Browser-Use vs the built-in browser tool

Scenario	Built-in tool	Browser-Use
Screenshot/view page/click one button	✅ Free and fast	❌ Overkill
Flows of 5+ steps (login→navigate→fill form→submit)	❌ Easily breaks	✅
Needs anti-detection (real Chrome)	❌	✅
Batch repetitive operations	❌	✅

Cost: Browser-Use calls an external LLM at every step (costs money + slow), use the built-in tool for simple operations.

Execution Flow

1. Check Environment

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

2. First-time install (only once)

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

3. Decide the mode

• Simple scenarios / don't mind being detected: use the built-in Chromium (Mode A), run directly
• Need anti-detection / user already has a login session: connect to real Chrome (Mode B), requires user cooperation

Mode B prerequisite step—prompt the user:

Please fully quit Chrome first (Mac: Cmd+Q), then tell me "closed"

After the user confirms, execute:

/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 &

Verify:curl -s http://127.0.0.1:9222/json/version

4. Write the script and run it

Write the script to the user's workspace, then:

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

5. Report the result

After running, send the result to the user; if it fails, handle it according to the troubleshooting decision tree.

Script Template

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 Writing Guide (key!)

✅ Good writing: specific and step-by-step

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. 点击发布按钮
"""

❌ Bad writing: vague and general

task = "去Reddit发个帖子"

Advanced Techniques

• Keyboard navigation fallback: add to the task "if the button can't be clicked, use Tab+Enter keyboard navigation"
• Error recovery: add "if the page fails to load, refresh and retry"
• Sensitive data: use placeholders + sensitive_data parameters, passwords are not exposed to the LLM

Sensitive Data Handling

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

Key Parameters Quick Reference

Parameter	Description	Recommended
use_vision	AI sees screenshots	Generally True, False when there are passwords
max_steps	Max steps	20-30
max_failures	Max retries	3 (default)
flash_mode	Fast mode (skip thinking)	True for simple tasks
extend_system_message	Append system prompt	Add specific instructions
allowed_domains	Restrict accessible domains	Use for security scenarios
fallback_llm	Fallback LLM	Set when the main LLM is unstable

Troubleshooting Decision Tree

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

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

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

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

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

LLM Compatibility

LLM	Compatible	Notes
GPT-4o / 4o-mini	✅	Best, recommended
Claude	✅	Works well
Gemini	❌	Structured output not compatible