browser-use CLI 技能

本技能涵盖范围

当您需要通过命令行使用 browser-use 自动化浏览器操作时，均可使用本技能。涵盖的操作包括：页面导航、点击/输入/填写表单、截图、执行 JavaScript、管理标签页、处理 Cookie、驱动云浏览器，以及通过隧道暴露本地服务器。

安装

前提条件

一键安装（推荐）

# macOS / Linux
curl -fsSL https://browser-use.com/cli/install.sh | bash

# Windows（PowerShell）
& "C:Program FilesGitbinbash.exe" -c 'curl -fsSL https://browser-use.com/cli/install.sh | bash'

手动安装

uv pip install browser-use
browser-use install   # 下载 Chromium
browser-use doctor    # 验证环境配置

安装后健康检查

browser-use doctor   # 输出诊断信息与配置
browser-use setup    # 可选的交互式向导

核心心智模型

标准工作流始终为：

1. 打开 页面 → browser-use open
2. 检查 页面 → browser-use state（返回带编号的可交互元素索引）
3. 交互（基于上述索引）→ browser-use click 3、browser-use input 1 "text"
4. 重复 — 后台守护进程在各命令间保持浏览器活跃（延迟约 50ms）

首次执行命令时将自动启动后台守护进程，并持续运行，直至您执行 browser-use close。

浏览器模式

# 默认：无头 Chromium（不可见）
browser-use open https://example.com

# 可见窗口
browser-use --headed open https://example.com

# 使用本地 Chrome（保留登录态、Cookie 和扩展程序）
browser-use connect

# 使用指定 Chrome 用户资料
browser-use --profile "Default" open https://gmail.com

# 零配置云浏览器（需 API 密钥）
browser-use cloud connect

# 通过 CDP 连接已运行的浏览器
browser-use --cdp-url http://localhost:9222 open https://example.com
browser-use --cdp-url ws://localhost:9222/devtools/browser/... state

执行 connect 或 cloud connect 后，后续所有命令将自动作用于该浏览器，无需额外参数。

全部命令

导航

browser-use open                # 导航至指定 URL
browser-use back                     # 返回上一页
browser-use scroll down              # 向下滚动
browser-use scroll up                # 向上滚动
browser-use scroll down --amount 1000  # 按像素值滚动

检查

browser-use state                    # 获取当前 URL、标题及带编号的可点击元素列表
browser-use screenshot output.png    # 截图并保存为文件
browser-use screenshot               # 截图为 base64 编码（输出至 stdout）
browser-use screenshot --full page.png  # 全页截图

交互

browser-use click             # 按索引点击元素（索引来自 state 命令）
browser-use click             # 在指定像素坐标处点击
browser-use type "text"              # 向当前聚焦元素输入文本
browser-use input  "text"     # 先点击元素再输入（表单操作最常用）
browser-use keys "Enter"             # 发送键盘按键
browser-use keys "Control+a"         # 发送组合键
browser-use select  "value"   # 选择下拉框选项
browser-use upload  /path/to/file  # 向文件输入框上传文件
browser-use hover             # 鼠标悬停于元素上方
browser-use dblclick          # 双击元素
browser-use rightclick        # 右键点击元素

标签页

browser-use tab list                 # 列出所有已打开标签页
browser-use tab new                  # 打开空白标签页
browser-use tab new https://url.com  # 以指定 URL 打开新标签页
browser-use tab switch        # 切换至指定索引的标签页
browser-use tab close                # 关闭当前标签页
browser-use tab close         # 关闭指定索引的标签页

Cookie

browser-use cookies get                        # 获取全部 Cookie
browser-use cookies get --url https://site.com # 获取指定 URL 的 Cookie
browser-use cookies set name value             # 设置 Cookie
browser-use cookies set name val --domain .example.com --secure
browser-use cookies set name val --same-site Strict   # Strict | Lax | None
browser-use cookies set name val --expires 1735689600 # Unix 时间戳
browser-use cookies clear                      # 清空全部 Cookie
browser-use cookies clear --url https://site.com
browser-use cookies export cookies.json        # 导出为 JSON 文件
browser-use cookies import cookies.json        # 从 JSON 文件导入

等待

browser-use wait selector ".btn"               # 等待元素可见
browser-use wait selector ".loading" --state hidden  # 等待元素隐藏
browser-use wait text "Success"                # 等待页面出现指定文本
browser-use wait selector "h1" --timeout 5000 # 自定义超时时间（毫秒）

获取（信息提取）

browser-use get title                  # 获取页面标题
browser-use get html                   # 获取完整页面 HTML
browser-use get html --selector "main" # 获取指定元素的 HTML
browser-use get text            # 获取元素的文本内容
browser-use get value           # 获取 input/textarea 的值
browser-use get attributes      # 获取元素全部属性
browser-use get bbox            # 获取元素边界框（x, y, width, height）

JavaScript

browser-use eval "document.title"
browser-use eval "Array.from(document.querySelectorAll('a')).map(a => a.href)"
browser-use eval "window.scrollTo(0, document.body.scrollHeight)"

Python（持久会话）

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               # 清空命名空间
browser-use python --file script.py      # 运行 Python 脚本文件

会话管理

每个 --session 均拥有独立的守护进程、套接字和浏览器实例。

# 默认会话（隐式）
browser-use open https://example.com
browser-use state

# 命名会话
browser-use --session work open https://example.com
browser-use --session personal open https://gmail.com
browser-use --session work state    # 作用于 work 浏览器

# 列出所有活跃会话
browser-use sessions

# 关闭指定会话
browser-use --session work close

# 关闭所有会话
browser-use close --all

# 通过环境变量指定会话
BROWSER_USE_SESSION=work browser-use state

云 API

认证

browser-use cloud login sk-abc123...    # 保存 API 密钥
browser-use cloud logout                # 删除 API 密钥
# 或：export BROWSER_USE_API_KEY=sk-abc123...

云浏览器

browser-use cloud connect              # 创建并连接云浏览器
browser-use state                      # 连接成功后可正常执行命令
browser-use close                      # 断开连接并停止云浏览器
browser-use cloud close                # 同样会停止云浏览器

REST 透传

browser-use cloud v2 GET /browsers
browser-use cloud v2 POST /tasks '{"task":"Search for AI news","url":"https://google.com"}'
browser-use cloud v2 poll     # 轮询直至任务完成
browser-use cloud v3 POST /path '{"key":"value"}'
browser-use cloud v2 --help            # 显示全部 v2 API 接口
browser-use cloud v3 --help            # 显示全部 v3 API 接口

隧道（将本地服务器暴露给云浏览器）

browser-use tunnel 3000                # 将 localhost:3000 暴露为公开 HTTPS 地址
browser-use tunnel list                # 列出所有活跃隧道
browser-use tunnel stop 3000           # 停止指定端口的隧道
browser-use tunnel stop --all          # 停止全部隧道

# 使用云浏览器测试本地应用的典型流程：
npm run dev &
browser-use tunnel 3000                # → https://abc.trycloudflare.com
browser-use cloud connect
browser-use open https://abc.trycloudflare.com

用户资料管理（同步 Chrome Cookie 至云端）

browser-use profile                    # 启动交互式同步向导
browser-use profile list               # 列出检测到的浏览器及其用户资料
browser-use profile sync --all         # 同步全部用户资料至云端
browser-use profile sync --browser "Google Chrome" --profile "Default"
browser-use profile auth --apikey 
browser-use profile inspect --browser "Google Chrome" --profile "Default"
browser-use profile update             # 更新 profile-use 二进制文件

全局选项

配置

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/config.json

模板生成

browser-use init                          # 启动交互式模板选择器
browser-use init --list                   # 列出全部可用模板
browser-use init --template basic         # 生成指定模板
browser-use init --output my_script.py    # 指定输出文件名
browser-use init --force                  # 覆盖已有文件

目录结构

~/.browser-use/
├── config.json          # API 密钥与设置
├── bin/
│   └── profile-use      # 托管的 Go 二进制文件（自动下载）
├── tunnels/
│   ├── {port}.json      # 隧道元数据
│   └── {port}.log       # 隧道日志
├── default.state.json   # 守护进程生命周期状态
├── default.sock         # 守护进程套接字（临时）
├── default.pid          # 守护进程 PID（临时）
└── cli.log              # 守护进程日志

可通过 BROWSER_USE_HOME 环境变量覆盖基础目录。

常用示例

填写并提交表单

browser-use open https://example.com/contact
browser-use state
# 输出：[0] input "Name", [1] input "Email", [2] button "Submit"
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use click 2
browser-use wait text "Thank you"

使用 JavaScript 抓取数据

browser-use open https://news.ycombinator.com
browser-use eval "Array.from(document.querySelectorAll('.titleline a')).slice(0,5).map(a => a.textContent)"

多步骤 Python 自动化

browser-use open https://example.com
browser-use python "
for i in range(5):
    browser.scroll('down')
    browser.wait(0.5)
browser.screenshot('scrolled.png')
"

使用已保存的 Chrome 用户资料登录

browser-use --profile "Default" open https://gmail.com
browser-use state
# Gmail 收件箱已自动完成登录

并行运行两个浏览器

browser-use --session a open https://site-a.com
browser-use --session b open https://site-b.com
browser-use --session a state
browser-use --session b state
browser-use close --all

通过云浏览器测试本地应用

npm run dev &
browser-use tunnel 3000
# 复制控制台输出的公网 URL，例如 https://xyz.trycloudflare.com
browser-use cloud connect
browser-use open https://xyz.trycloudflare.com
browser-use screenshot check.png

Windows 故障排查

ARM64 Windows — 安装 x64 版 Python 以启用模拟：

winget install Python.Python.3.11 --architecture x64

存在多个 Python 版本 — 固定 Python 版本：

$env:PY_PYTHON=3.11

PATH 未更新 — 重启终端，或改用 Git Bash 运行：

& "C:Program FilesGitbinbash.exe" -c 'browser-use --help'

守护进程无法启动 — 终止残留进程：

wmic process where "name='python.exe' and commandline like '%browser%use%'" get processid
taskkill /PID  /F

残留虚拟环境 — 彻底清理并重装：

wmic process where "name='python.exe' and commandline like '%browser%use%'" call terminate
Remove-Item -Recurse -Force "$env:USERPROFILE.browser-use-env"
# 重新运行安装脚本

速查卡片