browser-use
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBrowser Automation with browser-use CLI
借助browser-use CLI实现浏览器自动化
The command provides fast, persistent browser automation. It maintains browser sessions across commands, enabling complex multi-step workflows.
browser-usebrowser-useInstallation
安装
bash
undefinedbash
undefinedRun without installing (recommended for one-off use)
无需安装即可运行(推荐用于一次性使用)
uvx "browser-use[cli]" open https://example.com
uvx "browser-use[cli]" open https://example.com
Or install permanently
或永久安装
uv pip install "browser-use[cli]"
uv pip install "browser-use[cli]"
Install browser dependencies (Chromium)
安装浏览器依赖(Chromium)
browser-use install
undefinedbrowser-use install
undefinedQuick Start
快速开始
bash
browser-use open https://example.com # Navigate to URL
browser-use state # Get page elements with indices
browser-use click 5 # Click element by index
browser-use type "Hello World" # Type text
browser-use screenshot # Take screenshot
browser-use close # Close browserbash
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 # 关闭浏览器Core Workflow
核心工作流
- Navigate: - Opens URL (starts browser if needed)
browser-use open <url> - Inspect: - Returns clickable elements with indices
browser-use state - Interact: Use indices from state to interact (,
browser-use click 5)browser-use input 3 "text" - Verify: or
browser-use stateto confirm actionsbrowser-use screenshot - Repeat: Browser stays open between commands
- 导航:- 打开指定URL(如需则启动浏览器)
browser-use open <url> - 检查:- 返回带索引的可点击元素
browser-use state - 交互:使用返回的索引进行交互(如
browser-use state、browser-use click 5)browser-use input 3 "text" - 验证:通过或
browser-use state确认操作结果browser-use screenshot - 重复操作:浏览器在多个命令之间保持开启状态
Browser Modes
浏览器模式
bash
browser-use --browser chromium open <url> # Default: headless Chromium
browser-use --browser chromium --headed open <url> # Visible Chromium window
browser-use --browser real open <url> # User's Chrome with login sessions
browser-use --browser remote open <url> # Cloud browser (requires API key)- chromium: Fast, isolated, headless by default
- real: Uses your Chrome with cookies, extensions, logged-in sessions
- remote: Cloud-hosted browser with proxy support (requires BROWSER_USE_API_KEY)
bash
browser-use --browser chromium open <url> # 默认模式:无头Chromium
browser-use --browser chromium --headed open <url> # 可见Chromium窗口
browser-use --browser real open <url> # 用户的Chrome浏览器(包含登录会话)
browser-use --browser remote open <url> # 云端浏览器(需要API密钥)- chromium:快速、隔离,默认无头模式
- real:使用你的Chrome浏览器,包含Cookie、扩展程序和已登录会话
- remote:云端托管浏览器,支持代理(需要BROWSER_USE_API_KEY)
Commands
命令列表
Navigation
导航命令
bash
browser-use open <url> # Navigate to URL
browser-use back # Go back in history
browser-use scroll down # Scroll down
browser-use scroll up # Scroll upbash
browser-use open <url> # 导航至指定URL
browser-use back # 返回上一页
browser-use scroll down # 向下滚动
browser-use scroll up # 向上滚动Page State
页面状态命令
bash
browser-use state # Get URL, title, and clickable elements
browser-use screenshot # Take screenshot (outputs base64)
browser-use screenshot path.png # Save screenshot to file
browser-use screenshot --full path.png # Full page screenshotbash
browser-use state # 获取URL、标题和可点击元素
browser-use screenshot # 截取屏幕(输出base64格式内容)
browser-use screenshot path.png # 将截图保存至指定文件
browser-use screenshot --full path.png # 截取整页屏幕Interactions (use indices from browser-use state
)
browser-use state交互命令(使用browser-use state
返回的索引)
browser-use statebash
browser-use click <index> # Click element
browser-use type "text" # Type text into focused element
browser-use input <index> "text" # Click element, then type text
browser-use keys "Enter" # Send keyboard keys
browser-use keys "Control+a" # Send key combination
browser-use select <index> "option" # Select dropdown optionbash
browser-use click <index> # 点击元素
browser-use type "text" # 向当前聚焦元素输入文本
browser-use input <index> "text" # 点击元素后输入文本
browser-use keys "Enter" # 发送键盘按键
browser-use keys "Control+a" # 发送组合按键
browser-use select <index> "option" # 选择下拉菜单选项Tab Management
标签页管理
bash
browser-use switch <tab> # Switch to tab by index
browser-use close-tab # Close current tab
browser-use close-tab <tab> # Close specific tabbash
browser-use switch <tab> # 通过索引切换标签页
browser-use close-tab # 关闭当前标签页
browser-use close-tab <tab> # 关闭指定标签页JavaScript & Data
JavaScript与数据处理
bash
browser-use eval "document.title" # Execute JavaScript, return result
browser-use extract "all product prices" # Extract data using LLM (requires API key)bash
browser-use eval "document.title" # 执行JavaScript并返回结果
browser-use extract "all product prices" # 使用大语言模型提取数据(需要API密钥)Cookies
Cookie管理
bash
browser-use cookies get # Get all cookies
browser-use cookies get --url <url> # Get cookies for specific URL
browser-use cookies set <name> <value> # Set a cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies clear # Clear all cookies
browser-use cookies clear --url <url> # Clear cookies for specific URL
browser-use cookies export <file> # Export all cookies to JSON file
browser-use cookies export <file> --url <url> # Export cookies for specific URL
browser-use cookies import <file> # Import cookies from JSON filebash
browser-use cookies get # 获取所有Cookie
browser-use cookies get --url <url> # 获取指定URL的Cookie
browser-use cookies set <name> <value> # 设置Cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies clear # 清除所有Cookie
browser-use cookies clear --url <url> # 清除指定URL的Cookie
browser-use cookies export <file> # 将所有Cookie导出至JSON文件
browser-use cookies export <file> --url <url> # 导出指定URL的Cookie至JSON文件
browser-use cookies import <file> # 从JSON文件导入CookieWait Conditions
等待条件
bash
browser-use wait selector "h1" # Wait for element to be visible
browser-use wait selector ".loading" --state hidden # Wait for element to disappear
browser-use wait selector "#btn" --state attached # Wait for element in DOM
browser-use wait text "Success" # Wait for text to appear
browser-use wait selector "h1" --timeout 5000 # Custom timeout in msbash
browser-use wait selector "h1" # 等待元素可见
browser-use wait selector ".loading" --state hidden # 等待元素消失
browser-use wait selector "#btn" --state attached # 等待元素加载至DOM
browser-use wait text "Success" # 等待文本出现
browser-use wait selector "h1" --timeout 5000 # 自定义超时时间(毫秒)Additional Interactions
额外交互命令
bash
browser-use hover <index> # Hover over element (triggers CSS :hover)
browser-use dblclick <index> # Double-click element
browser-use rightclick <index> # Right-click element (context menu)bash
browser-use hover <index> # 悬停在元素上(触发CSS :hover效果)
browser-use dblclick <index> # 双击元素
browser-use rightclick <index> # 右键点击元素(打开上下文菜单)Information Retrieval
信息获取
bash
browser-use get title # Get page title
browser-use get html # Get full page HTML
browser-use get html --selector "h1" # Get HTML of specific element
browser-use get text <index> # Get text content of element
browser-use get value <index> # Get value of input/textarea
browser-use get attributes <index> # Get all attributes of element
browser-use get bbox <index> # Get bounding box (x, y, width, height)bash
browser-use get title # 获取页面标题
browser-use get html # 获取完整页面HTML
browser-use get html --selector "h1" # 获取指定元素的HTML
browser-use get text <index> # 获取元素的文本内容
browser-use get value <index> # 获取输入框/文本域的值
browser-use get attributes <index> # 获取元素的所有属性
browser-use get bbox <index> # 获取元素的边界框(x, y, 宽度, 高度)Python Execution (Persistent Session)
Python执行(持久会话)
bash
browser-use python "x = 42" # Set variable
browser-use python "print(x)" # Access variable (outputs: 42)
browser-use python "print(browser.url)" # Access browser object
browser-use python --vars # Show defined variables
browser-use python --reset # Clear Python namespace
browser-use python --file script.py # Execute Python fileThe Python session maintains state across commands. The object provides:
browser- - Current page URL
browser.url - - Page title
browser.title - - Navigate
browser.goto(url) - - Click element
browser.click(index) - - Type text
browser.type(text) - - Take screenshot
browser.screenshot(path) - - Scroll page
browser.scroll() - - Get page HTML
browser.html
bash
browser-use python "x = 42" # 设置变量
browser-use python "print(x)" # 访问变量(输出:42)
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- - 当前页面URL
browser.url - - 页面标题
browser.title - - 导航至指定URL
browser.goto(url) - - 点击元素
browser.click(index) - - 输入文本
browser.type(text) - - 截取屏幕并保存至指定路径
browser.screenshot(path) - - 滚动页面
browser.scroll() - - 获取页面HTML
browser.html
Agent Tasks (Requires API Key)
智能代理任务(需要API密钥)
bash
browser-use run "Fill the contact form with test data" # Run AI agent
browser-use run "Extract all product prices" --max-steps 50Agent tasks use an LLM to autonomously complete complex browser tasks. Requires or configured LLM API key (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc).
BROWSER_USE_API_KEYbash
browser-use run "Fill the contact form with test data" # 运行AI代理任务
browser-use run "Extract all product prices" --max-steps 50智能代理任务使用大语言模型自主完成复杂的浏览器任务。需要BROWSER_USE_API_KEY或已配置的大语言模型API密钥(如OPENAI_API_KEY、ANTHROPIC_API_KEY等)。
Session Management
会话管理
bash
browser-use sessions # List active sessions
browser-use close # Close current session
browser-use close --all # Close all sessionsbash
browser-use sessions # 列出活跃会话
browser-use close # 关闭当前会话
browser-use close --all # 关闭所有会话Profile Management
配置文件管理
bash
browser-use profile list-local # List local Chrome profilesBefore opening a real browser (), always ask the user if they want to use a specific Chrome profile or no profile. Use to show available profiles:
--browser realprofile list-localbash
browser-use profile list-localbash
browser-use profile list-local # 列出本地Chrome配置文件在打开真实浏览器()之前,务必询问用户是否要使用特定的Chrome配置文件或不使用配置文件。使用查看可用配置文件:
--browser realprofile list-localbash
browser-use profile list-localOutput: Default: Person 1 (user@gmail.com)
输出:Default: Person 1 (user@gmail.com)
Profile 1: Work (work@company.com)
Profile 1: Work (work@company.com)
With a specific profile (has that profile's cookies/logins)
使用特定配置文件(包含该配置文件的Cookie/登录信息)
browser-use --browser real --profile "Profile 1" open https://gmail.com
browser-use --browser real --profile "Profile 1" open https://gmail.com
Without a profile (fresh browser, no existing logins)
不使用配置文件(全新浏览器,无现有登录信息)
browser-use --browser real open https://gmail.com
browser-use --browser real open https://gmail.com
Headless mode (no visible window) - useful for cookie export
无头模式(无可见窗口)- 适用于Cookie导出
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
Each Chrome profile has its own cookies, history, and logged-in sessions. Choosing the right profile determines whether sites will be pre-authenticated.browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
每个Chrome配置文件都有独立的Cookie、历史记录和已登录会话。选择正确的配置文件决定了网站是否会自动登录。Cloud Profiles
云端配置文件
Cloud profiles store browser state (cookies) in Browser-Use Cloud, persisting across sessions. Requires .
BROWSER_USE_API_KEYbash
browser-use profile list # List cloud profiles
browser-use profile get <id> # Get profile details
browser-use profile update <id> --name "New" # Rename profile
browser-use profile delete <id> # Delete profileUse a cloud profile with :
--browser remote --profile <id>bash
browser-use --browser remote --profile abc-123 open https://example.com云端配置文件将浏览器状态(如Cookie)存储在Browser-Use云端,可跨会话持久保存。需要BROWSER_USE_API_KEY。
bash
browser-use profile list # 列出云端配置文件
browser-use profile get <id> # 获取配置文件详情
browser-use profile update <id> --name "New" # 重命名配置文件
browser-use profile delete <id> # 删除配置文件结合使用云端配置文件:
--browser remote --profile <id>bash
browser-use --browser remote --profile abc-123 open https://example.comSyncing Cookies to Cloud
Cookie同步至云端
⚠️ IMPORTANT: Before syncing cookies from a local browser to the cloud, the agent MUST:
- Ask the user which local Chrome profile to use ()
browser-use profile list-local - Ask which domain(s) to sync - do NOT default to syncing the full profile
- Confirm before proceeding
Default behavior: Create a NEW cloud profile for each domain sync. This ensures clear separation of concerns for cookies. Users can add cookies to existing profiles if needed.
Step 1: List available profiles and cookies
bash
undefined⚠️ 重要提示:在将本地浏览器的Cookie同步至云端之前,代理必须:
- 询问用户要使用哪个本地Chrome配置文件()
browser-use profile list-local - 询问要同步哪些域名 - 请勿默认同步整个配置文件
- 确认后再执行
默认行为: 为每个域名同步创建新的云端配置文件。这确保了Cookie的关注点分离。用户可根据需要将Cookie添加至现有配置文件。
步骤1:列出可用配置文件和Cookie
bash
undefinedList local Chrome profiles
列出本地Chrome配置文件
browser-use profile list-local
browser-use profile list-local
→ Default: Person 1 (user@gmail.com)
→ Default: Person 1 (user@gmail.com)
→ Profile 1: Work (work@company.com)
→ Profile 1: Work (work@company.com)
See what cookies are in a profile
查看配置文件中的Cookie
browser-use profile cookies "Default"
browser-use profile cookies "Default"
→ youtube.com: 23
→ youtube.com: 23
→ google.com: 18
→ google.com: 18
→ github.com: 2
→ github.com: 2
**Step 2: Sync cookies (three levels of control)**
**1. Domain-specific sync (recommended default)**
```bash
browser-use profile sync --from "Default" --domain youtube.com
**步骤2:同步Cookie(三种控制级别)**
**1. 按域名同步(推荐默认方式)**
```bash
browser-use profile sync --from "Default" --domain youtube.comCreates new cloud profile: "Chrome - Default (youtube.com)"
创建新的云端配置文件:"Chrome - Default (youtube.com)"
Only syncs youtube.com cookies
仅同步youtube.com的Cookie
This is the recommended approach - sync only the cookies you need.
**2. Full profile sync (use with caution)**
```bash
browser-use profile sync --from "Default"这是推荐的方式 - 仅同步需要的Cookie。
**2. 同步完整配置文件(谨慎使用)**
```bash
browser-use profile sync --from "Default"Syncs ALL cookies from the profile
同步配置文件中的所有Cookie
⚠️ **Warning:** This syncs ALL cookies including sensitive data, tracking cookies, session tokens for every site, etc. Only use when the user explicitly needs their entire browser state.
**3. Fine-grained control (advanced)**
```bash⚠️ **警告:** 这会同步所有Cookie,包括敏感数据、跟踪Cookie和所有网站的会话令牌等。仅当用户明确需要完整浏览器状态时使用。
**3. 细粒度控制(高级)**
```bashExport cookies to file
将Cookie导出至文件
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
Manually edit the JSON to keep only specific cookies
手动编辑JSON文件,仅保留特定Cookie
Import to cloud profile
导入至云端配置文件
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json
For users who need individual cookie-level control.
**Step 3: Use the synced profile**
```bash
browser-use --browser remote --profile <id> open https://youtube.comAdding cookies to existing profiles:
bash
undefinedbrowser-use --browser remote --profile <id> cookies import /tmp/cookies.json
适用于需要单个Cookie级别控制的用户。
**步骤3:使用已同步的配置文件**
```bash
browser-use --browser remote --profile <id> open https://youtube.com向现有配置文件添加Cookie:
bash
undefinedSync additional domain to existing profile
将额外域名的Cookie同步至现有配置文件
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <existing-id> cookies import /tmp/cookies.json
**Managing profiles:**
```bash
browser-use profile update <id> --name "New Name" # Rename
browser-use profile delete <id> # Deletebrowser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <existing-id> cookies import /tmp/cookies.json
**管理配置文件:**
```bash
browser-use profile update <id> --name "New Name" # 重命名
browser-use profile delete <id> # 删除Server Control
服务器控制
bash
browser-use server status # Check if server is running
browser-use server stop # Stop server
browser-use server logs # View server logsbash
browser-use server status # 检查服务器是否运行
browser-use server stop # 停止服务器
browser-use server logs # 查看服务器日志Setup
环境搭建
bash
browser-use install # Install Chromium and system dependenciesbash
browser-use install # 安装Chromium和系统依赖Global Options
全局选项
| Option | Description |
|---|---|
| Use named session (default: "default") |
| Browser mode: chromium, real, remote |
| Show browser window (chromium mode) |
| Chrome profile (real mode only) |
| Output as JSON |
| Override API key |
Session behavior: All commands without use the same "default" session. The browser stays open and is reused across commands. Use to run multiple browsers in parallel.
--session--session NAME| 选项 | 描述 |
|---|---|
| 使用命名会话(默认:"default") |
| 浏览器模式:chromium、real、remote |
| 显示浏览器窗口(仅chromium模式) |
| Chrome配置文件(仅real模式) |
| 以JSON格式输出 |
| 覆盖API密钥 |
会话行为: 所有未指定的命令都使用同一个"default"会话。浏览器保持开启状态,并在多个命令之间复用。使用可并行运行多个浏览器。
--session--session NAMEAPI Key Configuration
API密钥配置
Some features (, , ) require an API key. The CLI checks these locations in order:
runextract--browser remote- command line flag
--api-key - environment variable
BROWSER_USE_API_KEY - file
~/.config/browser-use/config.json
To configure permanently:
bash
mkdir -p ~/.config/browser-use
echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.json部分功能(、、)需要API密钥。CLI会按以下顺序检查密钥位置:
runextract--browser remote- 命令行参数
--api-key - 环境变量
BROWSER_USE_API_KEY - 文件
~/.config/browser-use/config.json
如需永久配置:
bash
mkdir -p ~/.config/browser-use
echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.jsonExamples
示例
Form Submission
表单提交
bash
browser-use open https://example.com/contact
browser-use statebash
browser-use open https://example.com/contact
browser-use stateShows: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"
显示:[0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use input 2 "Hello, this is a test message."
browser-use click 3
browser-use state # Verify success
undefinedbrowser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use input 2 "Hello, this is a test message."
browser-use click 3
browser-use state # 验证提交是否成功
undefinedMulti-Session Workflows
多会话工作流
bash
browser-use --session work open https://work.example.com
browser-use --session personal open https://personal.example.com
browser-use --session work state # Check work session
browser-use --session personal state # Check personal session
browser-use close --all # Close both sessionsbash
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 --session personal state # 检查个人会话
browser-use close --all # 关闭两个会话Data Extraction with Python
使用Python进行数据提取
bash
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')"bash
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')"Using Real Browser (Logged-In Sessions)
使用真实浏览器(已登录会话)
bash
browser-use --browser real open https://gmail.combash
browser-use --browser real open https://gmail.comUses your actual Chrome with existing login sessions
使用你的真实Chrome浏览器,包含现有登录会话
browser-use state # Already logged in!
undefinedbrowser-use state # 已自动登录!
undefinedTips
技巧
- Always run first to see available elements and their indices
browser-use state - Use for debugging to see what the browser is doing
--headed - Sessions persist - the browser stays open between commands
- Use for parsing output programmatically
--json - Python variables persist across commands within a session
browser-use python - Real browser mode preserves your login sessions and extensions
- CLI aliases: ,
bu, andbrowserall work identically tobrowserusebrowser-use
- 始终先运行,查看可用元素及其索引
browser-use state - 使用进行调试,查看浏览器的操作过程
--headed - 会话会持久保存 - 浏览器在多个命令之间保持开启
- 使用以编程方式解析输出内容
--json - Python变量在会话内的命令之间持久保存
browser-use python - 真实浏览器模式保留你的登录会话和扩展程序
- CLI别名:、
bu和browser与browseruse功能完全相同browser-use
Troubleshooting
故障排除
Browser won't start?
bash
browser-use install # Install/reinstall Chromium
browser-use server stop # Stop any stuck server
browser-use --headed open <url> # Try with visible windowElement not found?
bash
browser-use state # Check current elements
browser-use scroll down # Element might be below fold
browser-use state # Check againSession issues?
bash
browser-use sessions # Check active sessions
browser-use close --all # Clean slate
browser-use open <url> # Fresh start浏览器无法启动?
bash
browser-use install # 安装/重新安装Chromium
browser-use server stop # 停止所有卡住的服务器
browser-use --headed open <url> # 尝试使用可见窗口模式找不到元素?
bash
browser-use state # 检查当前元素
browser-use scroll down # 元素可能在页面下方
browser-use state # 再次检查会话出现问题?
bash
browser-use sessions # 检查活跃会话
browser-use close --all # 清理所有会话
browser-use open <url> # 重新开始Cleanup
清理
Always close the browser when done. Run this after completing browser automation:
bash
browser-use close完成浏览器自动化后请务必关闭浏览器,执行以下命令:
bash
browser-use close