Browser-Use — AI Browser Automation
Security & Privacy
- - No credential logging: Passwords are handled via Browser-Use's
sensitive_data parameter — the LLM never sees real credentials, only placeholder tokens. - User-initiated Chrome connection: CDP mode (connecting to real Chrome) is opt-in and requires the user to manually launch Chrome with debug flag. The skill never silently connects to running browsers.
- All packages are open-source: Dependencies are
browser-use (38k+ ⭐ on GitHub), playwright (by Microsoft), and langchain-openai — all widely audited open-source tools. - Local execution only: Scripts run locally on the user's machine. No data is sent to any server except the configured LLM API for step-by-step reasoning.
- Domain restriction available: Use
allowed_domains parameter to restrict which websites the agent can visit. - No telemetry: This skill does not collect, store, or transmit any usage data.
When to Use Browser-Use vs Built-in Tool
| Scenario | Built-in tool | Browser-Use |
|---|
| Screenshot / click one button | ✅ Free & fast | ❌ Overkill |
| 5+ step workflow (login→navigate→fill→submit) |
❌ Breaks easily | ✅ |
| Anti-bot sites (real Chrome needed) | ❌ | ✅ |
| Batch repetitive operations | ❌ | ✅ |
Cost: Browser-Use calls an external LLM per step (costs money + slower). Use built-in tool for simple actions.
Execution Flow
1. Check Environment
CODEBLOCK0
2. First-Time Setup (once only)
CODEBLOCK1
3. Choose Mode
- - Mode A — Built-in Chromium: For simple automation or when detection doesn't matter. Runs immediately.
- Mode B — Real Chrome CDP: For anti-bot sites or when user's login session is needed. Requires user action.
Mode B setup — prompt user:
Please quit Chrome completely (Mac: Cmd+Q), then tell me "done"
After user confirms:
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &
Verify: INLINECODE5
4. Write Script and Run
Write script to user's workspace, then:
CODEBLOCK3
5. Report Results
Return results to user. On failure, follow the troubleshooting tree below.
Script Template
CODEBLOCK4
Task Writing Guide
✅ Good: Specific steps
CODEBLOCK5
❌ Bad: Vague
CODEBLOCK6
Tips
- - Keyboard fallback: Add "If button can't be clicked, use Tab+Enter"
- Error recovery: Add "If page fails to load, refresh and retry"
- Sensitive data: Use placeholders +
sensitive_data parameter
Credential Security
CODEBLOCK7
Key Parameters
| Parameter | Purpose | Recommended |
|---|
| INLINECODE7 | AI sees screenshots | True normally, False with passwords |
| INLINECODE8 |
Max actions | 20-30 |
|
max_failures | Max retries | 3 (default) |
|
flash_mode | Skip reasoning | True for simple tasks |
|
extend_system_message | Custom instructions | Add specific guidance |
|
allowed_domains | Restrict URLs | Use for security |
|
fallback_llm | Backup LLM | When primary is unstable |
Troubleshooting
CODEBLOCK8
LLM Compatibility
| LLM | Works | Notes |
|---|
| GPT-4o / 4o-mini | ✅ | Best choice, recommended |
| Claude |
✅ | Works well |
| Gemini | ❌ | Structured output incompatible |
Browser-Use — AI浏览器自动化
安全与隐私
- - 不记录凭证：密码通过 Browser-Use 的 sensitivedata 参数处理——LLM 永远不会看到真实凭证，仅看到占位令牌。
- 用户启动的 Chrome 连接：CDP 模式（连接到真实 Chrome）为主动选择，需要用户手动以调试标志启动 Chrome。该技能不会静默连接到正在运行的浏览器。
- 所有包均为开源：依赖项包括 browser-use（GitHub 上 38k+ ⭐）、playwright（微软出品）和 langchain-openai——均为经过广泛审计的开源工具。
- 仅本地执行：脚本在用户本地机器上运行。除配置的 LLM API 用于逐步推理外，不会向任何服务器发送数据。
- 可限制域名：使用 alloweddomains 参数限制代理可访问的网站。
- 无遥测：本技能不收集、存储或传输任何使用数据。
何时使用 Browser-Use 与内置工具
| 场景 | 内置工具 | Browser-Use |
|---|
| 截图/点击一个按钮 | ✅ 免费且快速 | ❌ 大材小用 |
| 5步以上的工作流（登录→导航→填写→提交） |
❌ 容易出错 | ✅ |
| 反爬虫网站（需要真实 Chrome） | ❌ | ✅ |
| 批量重复操作 | ❌ | ✅ |
成本：Browser-Use 每一步都会调用外部 LLM（花费金钱 + 速度较慢）。简单操作请使用内置工具。
执行流程
1. 检查环境
bash
test -d ~/browser-use-env && echo 已安装 || echo 需要安装
2. 首次设置（仅一次）
bash
python3 -m venv ~/browser-use-env
source ~/browser-use-env/bin/activate
pip install browser-use playwright langchain-openai
playwright install chromium
3. 选择模式
- - 模式 A — 内置 Chromium：适用于简单自动化或无需考虑检测的情况。立即运行。
- 模式 B — 真实 Chrome CDP：适用于反爬虫网站或需要使用用户登录会话的情况。需要用户操作。
模式 B 设置——提示用户：
请完全退出 Chrome（Mac：Cmd+Q），然后告诉我完成
用户确认后：
bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 &
验证：curl -s http://127.0.0.1:9222/json/version
4. 编写脚本并运行
将脚本写入用户工作区，然后：
bash
source ~/browser-use-env/bin/activate
python3 script_path.py
5. 报告结果
将结果返回给用户。如果失败，请按照下面的故障排除树进行操作。
脚本模板
python
import asyncio
from browser_use import Agent, ChatOpenAI, Browser
async def main():
# LLM — 任何兼容 OpenAI 的 API
llm = ChatOpenAI(
model=gpt-4o-mini,
apikey=API_KEY>, # 来自环境变量或用户配置
base_url=https://api.openai.com/v1,
)
# 模式 A：内置 Chromium
browser = Browser(headless=False, userdatadir=~/.browser-use/task-profile)
# 模式 B：真实 Chrome（用户必须使用 --remote-debugging-port=9222 启动）
# browser = Browser(cdp_url=http://127.0.0.1:9222)
agent = Agent(
task=详细的逐步任务描述（参见下方指南）,
llm=llm, browser=browser,
usevision=True, maxsteps=25,
)
result = await agent.run()
print(result)
asyncio.run(main())
任务编写指南
✅ 好的：具体步骤
python
task =
- 1. 打开 https://www.reddit.com/login
- 输入用户名：xuser
- 输入密码：xpass
- 点击登录按钮
- 如果出现验证码，等待30秒让用户完成
- 导航到 https://www.reddit.com/r/xxx/submit
- 输入标题：xxx
- 输入正文：xxx
- 点击提交
❌ 不好的：模糊
python
task = 在 Reddit 上发帖
提示
- - 键盘回退：添加如果按钮无法点击，请使用 Tab+Enter
- 错误恢复：添加如果页面加载失败，请刷新并重试
- 敏感数据：使用占位符 + sensitive_data 参数
凭证安全
python
agent = Agent(
task=使用 xuser 和 xpass 登录,
sensitivedata={xuser: real@email.com, x_pass: S3cret!},
use_vision=False, # 处理密码时禁用截图
llm=llm, browser=browser,
)
关键参数
| 参数 | 用途 | 推荐值 |
|---|
| usevision | AI 查看截图 | 通常为 True，处理密码时为 False |
| maxsteps |
最大操作次数 | 20-30 |
| max_failures | 最大重试次数 | 3（默认） |
| flash_mode | 跳过推理 | 简单任务为 True |
| extend
systemmessage | 自定义指令 | 添加具体指导 |
| allowed_domains | 限制 URL | 用于安全 |
| fallback_llm | 备用 LLM | 当主 LLM 不稳定时 |
故障排除
检测为自动化？
└→ 切换到模式 B（真实 Chrome）
验证码/人工验证？
└→ 提示用户手动完成，在任务中添加等待时间
LLM 超时？
└→ 设置 fallback_llm 或使用更快的模型
操作成功但无效果（例如帖子未发布）？
└→ 1. 检查平台是否因反垃圾机制拦截（新账号常见）
2. 在任务中添加明确的确认步骤
网站 UI 变更，找不到元素？
└→ Browser-Use 会自动适应，但在任务中添加回退路径
LLM 兼容性
| LLM | 可用 | 备注 |
|---|
| GPT-4o / 4o-mini | ✅ | 最佳选择，推荐 |
| Claude |
✅ | 效果良好 |
| Gemini | ❌ | 结构化输出不兼容 |
