browser-use 是一款命令行浏览器自动化工具，通过 browser-use 命令提供快速、持久的浏览器自动化能力。浏览器会话在命令之间保持开启，从而支持复杂的多步骤工作流。其 CLI 别名 bu、browser、browseruse 与 browser-use 等效。
安装
推荐一次性使用可不安装直接运行： uvx "browser-use[cli]" open https://example.com
永久安装： uv pip install "browser-use[cli]"
还需安装浏览器依赖（Chromium）： browser-use install
快速开始与核心工作流
browser-use open https://example.com # 导航到 URL browser-use state # 获取带索引的页面元素 browser-use click 5 # 按索引点击元素 browser-use type "Hello World" # 输入文本 browser-use screenshot # 截图 browser-use close # 关闭浏览器
典型流程为：导航（open）→ 检查（state）→ 交互（click / input）→ 验证（state 或 screenshot）→ 重复，浏览器在命令之间保持开启。
浏览器模式
- chromium：默认无头 Chromium，快速、隔离，可通过 --headed 显示窗口。
- real：使用用户本机 Chrome，带 Cookie、扩展和已登录会话。
- remote：云端托管浏览器，支持代理（需要 BROWSER_USE_API_KEY）。
对应命令示例： browser-use --browser chromium open <url> browser-use --browser chromium --headed open <url> browser-use --browser real open <url> browser-use --browser remote open <url>
命令分类
导航：open <url>、back、scroll down、scroll up。
页面状态：state（返回 URL、标题和可点击元素）、screenshot（输出 base64，可存为文件，--full 为整页截图）。
交互（使用 state 返回的索引）：click <index>、type "text"、input <index> "text"、keys "Enter"、keys "Control+a"、select <index> "option"。
标签页管理：switch <tab>、close-tab、close-tab <tab>。
JavaScript 与数据：eval "document.title" 执行 JS 并返回结果；extract "all product prices" 使用 LLM 提取数据（需要 API Key）。
Cookie：cookies get、cookies get --url、cookies set、cookies clear、cookies export <file>、cookies import <file> 等。
等待条件：wait selector "h1"、wait selector ".loading" --state hidden、wait selector "#btn" --state attached、wait text "Success"、--timeout 毫秒。
其他交互：hover <index>、dblclick <index>、rightclick <index>。
信息获取：get title、get html、get html --selector、get text <index>、get value <index>、get attributes <index>、get bbox <index>。
Python 执行（持久会话）
browser-use python "x = 42" # 设置变量 browser-use python "print(x)" # 访问变量 browser-use python "print(browser.url)" # 访问 browser 对象 browser-use python --vars # 显示已定义变量 browser-use python --reset # 清空 Python 命名空间 browser-use python --file script.py # 执行 Python 文件
Python 会话在命令间保持状态。browser 对象提供：browser.url、browser.title、browser.goto(url)、browser.click(index)、browser.type(text)、browser.screenshot(path)、browser.scroll()、browser.html。
代理任务（需要 API Key）
browser-use run "Fill the contact form with test data" browser-use run "Extract all product prices" --max-steps 50
代理任务使用 LLM 自主完成复杂浏览器任务，需要 BROWSER_USE_API_KEY 或已配置的 LLM API Key（如 OPENAI_API_KEY、ANTHROPIC_API_KEY 等）。
会话与配置
会话：sessions（列出活动会话）、close（关闭当前）、close --all（关闭全部）。所有不带 --session 的命令共用 "default" 会话；用 --session NAME 可并行运行多个浏览器。
全局选项：--session NAME、--browser MODE、--headed、--profile NAME（仅 real 模式）、--json、--api-key KEY。
API Key 配置：CLI 依次检查 --api-key 命令行参数、BROWSER_USE_API_KEY 环境变量、~/.config/browser-use/config.json 文件。永久配置： mkdir -p ~/.config/browser-use echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.json
服务器控制：server status、server stop、server logs。
本地 Chrome 配置文件
browser-use profile list-local 可列出本地 Chrome 配置文件（默认配置、Profile 1 等）。使用 --browser real 前应先询问用户使用哪个配置文件或无配置文件。不同配置文件有各自的 Cookie、历史与登录会话。
browser-use --browser real --profile "Profile 1" open https://gmail.com browser-use --browser real open https://gmail.com browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
云端配置文件与 Cookie 同步
云端配置文件将浏览器状态（Cookie）存储于 Browser-Use Cloud，跨会话持久（需要 BROWSER_USE_API_KEY）。命令：profile list、profile get <id>、profile update <id> --name "New"、profile delete <id>。配合 --browser remote --profile <id> 使用。
从本地同步 Cookie 到云端前，代理必须先询问使用哪个本地 Chrome 配置文件、同步哪些域名（不得默认同步完整配置文件）并确认。默认行为是为每个域名同步创建新的云端配置文件。
同步方式分三级：
- 按域名同步（推荐）：browser-use profile sync --from "Default" --domain youtube.com，只同步该域名 Cookie。
- 完整配置文件同步（谨慎）：browser-use profile sync --from "Default"，会同步所有 Cookie 包括敏感数据，仅在用户明确需要完整浏览器状态时使用。
- 细粒度控制：cookies export 导出并手动编辑 JSON，再 cookies import 导入云端配置文件。
查看某配置文件 Cookie：browser-use profile cookies "Default"。
示例
表单提交：open 页面后 state 查看元素索引，依次 input 0、input 1、input 2、click 3，再 state 验证成功。
多会话： browser-use --session work open https://work.example.com browser-use --session personal open https://personal.example.com browser-use --session work state browser-use close --all
使用 Python 提取数据： browser-use open https://example.com/products browser-use python " products = [] for i in range(20): browser.scroll('down') browser.screenshot('products.png') " browser-use python "print(f'Captured {len(products)} products')"
使用真实浏览器（已登录会话）： browser-use --browser real open https://gmail.com
提示与故障排查
提示：始终先运行 browser-use state 查看元素及索引；调试时用 --headed；会话持久，浏览器在命令间保持开启；--json 便于程序化解析；Python 变量在会话内的 python 命令间保持；真实浏览器模式保留登录会话与扩展。
浏览器无法启动：browser-use install 重装 Chromium；browser-use server stop 停止卡住的服务器；browser-use --headed open <url> 用可见窗口尝试。
找不到元素：browser-use state 检查当前元素；browser-use scroll down 元素可能在折叠下方，再检查。
会话问题：browser-use sessions 检查活动会话；browser-use close --all 清理；browser-use open <url> 重新开始。
完成后应关闭浏览器：browser-use close。