browser-use

使用 browser-use CLI 进行浏览器自动化

browser-use 命令可实现快速、持久的浏览器自动化。后台守护进程会让浏览器在多条命令间保持打开状态，每次调用的延迟约为 50 ms。

前提条件

browser-use doctor    # Verify installation

设置详情请参阅 https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

核心工作流

1. 导航：browser-use open <url> — 启动无头浏览器并打开页面
2. 检查：browser-use state — 返回带有索引的可点击元素
3. 交互：使用 state 中的索引（browser-use click 5、browser-use input 3 "text"）
4. 验证：使用 browser-use state 或 browser-use screenshot 确认
5. 重复操作：浏览器会在多条命令间保持打开状态

如果命令失败，请先运行 browser-use close 清除异常会话，然后重试。

要使用用户现有的 Chrome（保留登录状态和 Cookie）：请先运行 browser-use connect。 要使用云浏览器：请先运行 browser-use cloud connect。 完成其中任一连接后，命令的用法相同。

如果 browser-use connect 失败

如果 browser-use connect 无法找到正在运行且启用了远程调试的 Chrome，请向用户提供两个选项：

1. 使用他们的真实 Chrome 浏览器 — 需要先启用远程调试：
   • 在 Chrome 中打开 chrome://inspect/#remote-debugging，或使用 --remote-debugging-port=9222 重新启动 Chrome
   • 然后重试 browser-use connect
2. 使用带有其 Chrome 配置文件的托管 Chromium — 无需设置 Chrome：
   • 运行 browser-use profile list 查看可用配置文件
   • 询问用户想使用哪个配置文件，然后运行 browser-use --profile "ProfileName" open <url>
   • 这会启动一个单独的 Chromium 实例，并加载其配置文件数据（Cookie、登录状态、扩展程序）

让用户自行选择，不要替他们做决定。

浏览器模式

browser-use open <url>                         # Default: headless Chromium (no setup needed)
browser-use --headed open <url>                # Visible window (for debugging)
browser-use connect                            # Connect to user's Chrome (preserves logins/cookies)
browser-use cloud connect                      # Cloud browser (zero-config, requires API key)
browser-use --profile "Default" open <url>     # Real Chrome with specific profile

运行 connect 或 cloud connect 后，后续所有命令都会发送到该浏览器，无需额外标志。

命令

# Navigation
browser-use open <url>                    # Navigate to URL
browser-use back                          # Go back in history
browser-use scroll down                   # Scroll down (--amount N for pixels)
browser-use scroll up                     # Scroll up
browser-use tab list                      # List all tabs
browser-use tab new [url]                 # Open a new tab (blank or with URL)
browser-use tab switch <index>            # Switch to tab by index
browser-use tab close <index> [index...]  # Close one or more tabs

# Page State — always run state first to get element indices
browser-use state                         # URL, title, clickable elements with indices
browser-use screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
browser-use click <index>                 # Click element by index
browser-use click <x> <y>                 # Click at pixel coordinates
browser-use type "text"                   # Type into focused element
browser-use input <index> "text"          # Click element, clear existing text, then type
browser-use input <index> ""              # Clear a field without typing new text
browser-use keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
browser-use select <index> "option"       # Select dropdown option
browser-use upload <index> <path>         # Upload file to file input
browser-use hover <index>                 # Hover over element
browser-use dblclick <index>              # Double-click element
browser-use rightclick <index>            # Right-click element

# Data Extraction
browser-use eval "js code"                # Execute JavaScript, return result
browser-use get title                     # Page title
browser-use get html [--selector "h1"]    # Page HTML (or scoped to selector)
browser-use get text <index>              # Element text content
browser-use get value <index>             # Input/textarea value
browser-use get attributes <index>        # Element attributes
browser-use get bbox <index>              # Bounding box (x, y, width, height)

# Wait
browser-use wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Wait for text to appear

# Cookies
browser-use cookies get [--url <url>]     # Get cookies (optionally filtered)
browser-use cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Clear cookies
browser-use cookies export <file>         # Export to JSON
browser-use cookies import <file>         # Import from JSON

# Session
browser-use close                         # Close browser and stop daemon
browser-use sessions                      # List active sessions
browser-use close --all                   # Close all sessions

有关高级浏览器控制（CDP、设备模拟、标签页激活），请参阅 references/cdp-python.md。

云 API

browser-use cloud connect                 # Provision cloud browser and connect (zero-config)
browser-use cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
browser-use cloud logout                  # Remove API key
browser-use cloud v2 GET /browsers        # REST passthrough (v2 or v3)
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>       # Poll task until done
browser-use cloud v2 --help               # Show API endpoints

cloud connect 会创建一个带有持久化配置文件（首次使用时自动创建）的云浏览器，通过 CDP 连接，并打印一个实时 URL。browser-use close 会断开连接并停止云浏览器。若要自定义浏览器设置（代理、超时、指定配置文件），请直接使用 cloud v2 POST /browsers 并传入所需参数。

Agent 自助注册

仅当你还没有 API 密钥时才使用此功能（运行 browser-use doctor 检查是否已设置 api_key）。如果已经登录，请完全跳过此步骤。

1. browser-use cloud signup — 获取验证挑战
2. 解决验证挑战
3. browser-use cloud signup --verify <challenge-id> <answer> — 验证并保存 API 密钥
4. browser-use cloud signup --claim — 生成供他人认领账户的 URL

隧道

browser-use tunnel <port>                 # Start Cloudflare tunnel (idempotent)
browser-use tunnel list                   # Show active tunnels
browser-use tunnel stop <port>            # Stop tunnel
browser-use tunnel stop --all             # Stop all tunnels

配置文件管理

browser-use profile list                  # List detected browsers and profiles
browser-use profile sync --all            # Sync profiles to cloud
browser-use profile update                # Download/update profile-use binary

命令串联

可以使用 && 串联命令。浏览器通过守护进程保持运行，因此串联命令安全且高效。

browser-use open https://example.com && browser-use state
browser-use input 5 "[email protected]" && browser-use input 6 "password" && browser-use click 7

如果不需要中间输出，可以串联命令。如果需要先解析 state 以获取索引，请分开运行命令。

常见工作流

已验证身份的浏览

任务需要访问已验证身份的网站（Gmail、GitHub、内部工具）时，请使用 Chrome 配置文件：

browser-use profile list                           # Check available profiles
# Ask the user which profile to use, then:
browser-use --profile "Default" open https://github.com  # Already logged in

暴露本地开发服务器

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Browse the tunnel

多个浏览器

对于子 Agent 工作流，或需要并行运行多个浏览器的场景，请使用 --session NAME。每个会话都有自己的浏览器。请参阅 references/multi-session.md。

配置

browser-use config list                            # Show all config values
browser-use config set cloud_connect_proxy jp      # Set a value
browser-use config get cloud_connect_proxy         # Get a value
browser-use config unset cloud_connect_timeout     # Remove a value
browser-use doctor                                 # Shows config + diagnostics
browser-use setup                                  # Interactive post-install setup

配置存储在 ~/.browser-use/config.json 中。

全局选项

选项	说明
--headed	显示浏览器窗口
--profile [NAME]	使用真实的 Chrome（单独使用 --profile 时使用 "Default"）
--cdp-url <url>	通过 CDP URL（http:// 或 ws://）连接
--session NAME	指定命名会话（默认值："default"）
--json	以 JSON 格式输出
--mcp	通过 stdin/stdout 作为 MCP 服务运行

提示

1. 始终先运行 state，查看可用元素及其索引
2. 使用 --headed 进行调试，查看浏览器正在执行的操作
3. 会话会持续保留 — 浏览器会在命令之间保持打开
4. CLI 别名：bu、browser 和 browseruse 均可使用
5. 如果命令失败，先运行 browser-use close，然后重试

故障排除

• 浏览器无法启动？ 运行 browser-use close，然后运行 browser-use --headed open <url>
• 找不到元素？ 运行 browser-use scroll down，然后运行 browser-use state
• 运行诊断： browser-use doctor

清理

browser-use close                         # Close browser session
browser-use tunnel stop --all             # Stop tunnels (if any)