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

browser-use 命令提供快速、持久的浏览器自动化。后台守护进程会保持浏览器常开，每次调用延迟约为 50ms。

前置条件

browser-use doctor    # 验证安装状态

设置详情请参阅：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 浏览器（保留登录状态/Cookies）：请先运行 browser-use connect。

如需使用云端浏览器：请先运行 browser-use cloud connect。

完成任一操作后，后续命令使用方式相同。

浏览器模式

browser-use open <url>                         # 默认：无头 Chromium（无需额外配置）
browser-use --headed open <url>                # 可视化窗口（用于调试）
browser-use connect                            # 连接用户本地 Chrome（保留登录状态/Cookies）
browser-use cloud connect                      # 使用云端浏览器（零配置，需 API 密钥）
browser-use --profile "Default" open <url>     # 使用真实 Chrome 并指定用户配置文件

在执行 connect 或 cloud connect 后，所有后续命令都将作用于该浏览器实例——无需额外参数。

命令列表

导航类命令

browser-use open <url>                    # 跳转至指定 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 <index>            # 切换到指定索引的标签页
browser-use tab close <index> [index...]  # 关闭一个或多个标签页

页面状态查询 —— 始终先运行 state 获取元素索引

browser-use state                         # 显示当前页面的 URL、标题及可点击元素（含索引）
browser-use screenshot [path.png]         # 截图（未指定路径时返回 base64 编码；--full 可截取完整页面）

交互类命令 —— 使用 state 输出的索引编号

browser-use click <index>                 # 通过索引点击元素
browser-use click <x> <y>                 # 在指定坐标位置点击
browser-use type "text"                   # 在聚焦元素中输入文本
browser-use input <index> "text"          # 点击元素后输入文本
browser-use keys "Enter"                  # 发送键盘按键（支持 "Control+a" 等组合键）
browser-use select <index> "option"       # 选择下拉框选项
browser-use upload <index> <path>         # 向文件输入框上传文件
browser-use hover <index>                 # 鼠标悬停于元素上
browser-use dblclick <index>              # 双击元素
browser-use rightclick <index>            # 右键点击元素

数据提取类命令

browser-use eval "js code"                # 执行 JavaScript 代码并返回结果
browser-use get title                     # 获取页面标题
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, width, height）

等待类命令

browser-use wait selector "css"           # 等待元素出现（可选 --state visible|hidden|attached|detached，--timeout 指定超时时间）
browser-use wait text "text"              # 等待指定文本出现

Cookie 管理

browser-use cookies get [--url <url>]     # 获取 Cookie（可选按 URL 进行过滤）
browser-use cookies set <name> <value>    # 设置 Cookie（支持 --domain、--secure、--http-only、--same-site、--expires 参数）
browser-use cookies clear [--url <url>]   # 清除 Cookie
browser-use cookies export <file>         # 导出 Cookie 至 JSON 文件
browser-use cookies import <file>         # 从 JSON 文件导入 Cookie

会话管理

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>         # 保存 API 密钥（也可通过设置 BROWSER_USE_API_KEY 环境变量）
browser-use cloud logout                  # 移除已保存的 API 密钥
browser-use cloud v2 GET /browsers        # REST 透传接口（v2 或 v3 版本）
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>       # 轮询任务直至完成
browser-use cloud v2 --help               # 查看可用 API 接口列表

cloud connect 将自动创建一个带有持久化配置文件的云端浏览器，通过 CDP 协议连接，并输出实时访问地址。运行 browser-use close 不仅断开连接，还会关闭云端浏览器实例。如需自定义浏览器设置（如代理、超时时间、特定配置文件），建议直接使用 cloud v2 POST /browsers 并传入所需参数。

自动注册代理账户

仅在尚未拥有 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 — 生成人工领取账户的链接

隧道服务

bash

browser-use tunnel <port> # 启动 Cloudflare 隧道（幂等操作）

browser-use tunnel list # 显示当前活动的隧道

browser-use tunnel stop <port> # 停止指定端口的隧道

browser-use tunnel stop --all # 停止所有隧道

## 配置文件管理

browser-use profile list # 列出检测到的浏览器及配置文件

browser-use profile sync --all # 将配置文件同步至云端

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` 来获取元素索引，则应分步执行。

## 常见工作流

### 已登录浏览

当任务需要访问已登录的网站（如 Gmail、GitHub、内部系统）时，建议使用 Chrome 配置文件：

browser-use profile list # 检查可用的配置文件

询问用户选择配置文件后：

browser-use --profile "Default" open https://github.com # 已登录状态访问

### 暴露本地开发服务器

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

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

## 多浏览器支持

在子代理工作流或多浏览器并行场景中，使用 `--session NAME`。每个会话将拥有独立的浏览器实例。详见 `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`。

## 全局选项

| 选项 | 描述 |
|------|------|
| `--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 # 关闭浏览器会话

browser-use tunnel stop --all # 停止所有隧道（如有）