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

browser-use 命令提供快速、持久的浏览器自动化能力。后台守护进程（daemon）使浏览器在多次命令调用间保持运行，单次调用延迟约 50ms。

前提条件

browser-use doctor    # 验证安装状态

详细安装说明请参阅：https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

核心工作流

1. 导航：browser-use open — 启动无头浏览器并打开页面
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 open                          # 默认：无头 Chromium（无需配置）
browser-use --headed open                 # 可见窗口模式（适用于调试）
browser-use connect                            # 连接至用户本地 Chrome（保留登录态与 Cookie）
browser-use cloud connect                      # 使用云浏览器（零配置，需 API key）
browser-use --profile "Default" open      # 使用指定 profile 的真实 Chrome

执行 connect 或 cloud connect 后，所有后续命令将自动路由至该浏览器，无需添加额外标志。

命令列表

# 导航
browser-use open                     # 跳转至指定 URL
browser-use back                          # 浏览器历史后退
browser-use scroll down                   # 向下滚动（--amount N 指定像素数）
browser-use scroll up                     # 向上滚动
browser-use tab list                      # 列出全部标签页
browser-use tab new [url]                 # 新建标签页（空白页或带 URL）
browser-use tab switch             # 切换至指定索引的标签页
browser-use tab close  [index...]  # 关闭一个或多个标签页

# 页面状态 — 执行任何交互前，请务必先运行 state 获取元素索引
browser-use state                         # 返回当前 URL、标题及带索引号的可点击元素列表
browser-use screenshot [path.png]         # 截图（未指定路径时返回 base64；--full 表示整页截图）

# 交互操作 — 使用 state 输出中的索引号
browser-use click                  # 按索引号点击元素
browser-use click                   # 在指定像素坐标处点击
browser-use type "text"                   # 向当前聚焦元素输入文本
browser-use input  "text"          # 先点击元素，再输入文本
browser-use keys "Enter"                  # 发送键盘按键（支持 "Control+a" 等组合键）
browser-use select  "option"       # 选择下拉框选项
browser-use upload           # 向文件输入框上传文件
browser-use hover                  # 鼠标悬停于元素上方
browser-use dblclick               # 双击元素
browser-use rightclick             # 右键点击元素

# 数据提取
browser-use eval "js code"                # 执行 JavaScript 并返回结果
browser-use get title                     # 获取页面标题
browser-use get html [--selector "h1"]    # 获取页面 HTML（可选 CSS 选择器限定范围）
browser-use get text               # 获取指定索引元素的文本内容
browser-use get value              # 获取 input/textarea 元素的当前值
browser-use get attributes         # 获取元素全部属性
browser-use get bbox               # 获取元素边界框（x, y, width, height）

# 等待
browser-use wait selector "css"           # 等待元素出现（--state 支持 visible|hidden|attached|detached；--timeout 指定毫秒超时）
browser-use wait text "text"              # 等待指定文本出现

# Cookie 管理
browser-use cookies get [--url ]     # 获取 Cookie（可选 URL 过滤）
browser-use cookies set      # 设置 Cookie（支持 --domain、--secure、--http-only、--same-site、--expires）
browser-use cookies clear [--url ]   # 清除 Cookie
browser-use cookies export          # 导出为 JSON 文件
browser-use cookies import          # 从 JSON 文件导入

# 会话管理
browser-use close                         # 关闭浏览器并停止守护进程
browser-use sessions                      # 列出当前活跃会话
browser-use close --all                   # 关闭全部会话

如需高级浏览器控制能力（CDP 调试协议、设备模拟、标签页激活等），请参阅 references/cdp-python.md。

云 API

browser-use cloud connect                 # 创建并连接云浏览器（零配置）
browser-use cloud login          # 保存 API key（或设置环境变量 BROWSER_USE_API_KEY）
browser-use cloud logout                  # 移除 API key
browser-use cloud v2 GET /browsers        # REST 请求透传（v2 或 v3 版本）
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll        # 轮询任务直至完成
browser-use cloud v2 --help               # 显示所有 API 端点

cloud connect 将创建一个带持久化 profile 的云浏览器（首次使用时自动创建），通过 CDP 连接，并打印一个实时可访问的 URL。browser-use close 不仅断开连接，还会终止该云浏览器实例。如需自定义浏览器设置（如代理、超时、特定 profile），请直接调用 cloud v2 POST /browsers 并传入所需参数。

Agent 自注册

仅当您尚未拥有 API key 时才需执行此流程（可通过 browser-use doctor 检查 api_key 是否已配置）。如已登录，请跳过本节。

1. browser-use cloud signup — 获取挑战题
2. 解答挑战题
3. browser-use cloud signup --verify — 提交答案完成验证并保存 API key
4. browser-use cloud signup --claim — 生成供人工确认账户的 URL

隧道（Tunnels）

browser-use tunnel                  # 启动 Cloudflare 隧道（幂等操作）
browser-use tunnel list                   # 查看当前活跃隧道
browser-use tunnel stop             # 停止指定端口的隧道
browser-use tunnel stop --all             # 停止全部隧道

Profile 管理

browser-use profile list                  # 列出检测到的浏览器及其 profiles
browser-use profile sync --all            # 将本地 profiles 同步至云端
browser-use profile update                # 下载/更新 profile-use 二进制文件

命令链式调用

命令可通过 && 进行链式调用。由于浏览器由守护进程维持，链式调用安全且高效。

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

若无需中间输出，推荐链式调用；若需先解析 state 输出以动态获取元素索引，则建议分步执行。

常见工作流

认证后浏览（Authenticated Browsing）

当任务需访问已登录站点（如 Gmail、GitHub 或内部系统）时，推荐使用 Chrome profiles：

browser-use profile list                           # 查看可用 profiles
# 向用户询问需使用的 profile，然后执行：
browser-use --profile "Default" open https://github.com  # 已预登录状态

暴露本地开发服务

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # 通过隧道访问本地服务

多浏览器支持

对于子 Agent 工作流或需并行运行多个浏览器的场景，请使用 --session NAME 参数。每个 session 将独占一个浏览器实例。详情参见 references/multi-session.md。

配置管理

browser-use config list                            # 显示全部配置项
browser-use config set cloud_connect_proxy jp      # 设置配置项值
browser-use config get cloud_connect_proxy         # 获取配置项值
browser-use config unset cloud_connect_timeout     # 删除配置项
browser-use doctor                                 # 显示配置与诊断信息
browser-use setup                                  # 交互式安装后配置向导

配置文件存储于 ~/.browser-use/config.json。

全局选项

使用技巧

1. 始终优先运行 state，以便查看当前页面可交互元素及其索引号
2. 调试时启用 --headed，直观观察浏览器行为
3. 会话持久化 — 浏览器在命令间保持开启状态
4. CLI 别名支持：bu、browser 和 browseruse 均可作为命令前缀使用
5. 命令执行失败时，请先运行 browser-use close 再重试

故障排查

• 浏览器无法启动？ 执行 browser-use close 后，再尝试 browser-use --headed open
• 找不到目标元素？ 先执行 browser-use scroll down，再运行 browser-use state
• 运行诊断工具： browser-use doctor

清理操作

browser-use close                         # 关闭浏览器会话
browser-use tunnel stop --all             # 停止全部隧道（如有）