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

browser-use 命令提供快速、持久的浏览器自动化能力。它能够在命令之间保持浏览器会话，支持复杂的多步骤工作流。

先决条件

使用本技能前，需先安装并配置 browser-use。运行诊断命令以验证环境：

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 --browser chromium open <url>      # 默认：无头 Chromium
browser-use --browser chromium --headed open <url>  # 可视化 Chromium 窗口
browser-use --browser real open <url>          # 使用真实 Chrome 浏览器（不指定配置文件则为全新会话）
browser-use --browser real --profile "Default" open <url>  # 使用真实 Chrome 并加载你的登录信息等数据
browser-use --browser remote open <url>        # 使用云端浏览器（支持代理）

• chromium：速度快，环境隔离，默认无头运行
• real：使用真实的 Chrome 可执行文件。未指定 --profile 时，会在 ~/.config/browseruse/profiles/cli/ 创建一个持久但空的 CLI 配置文件；若指定 --profile "ProfileName"，将复制你实际的 Chrome 配置（包括 Cookie、登录状态、扩展等）
• remote：云托管浏览器，支持代理连接

必备命令

# 导航相关
browser-use open <url>                    # 访问指定网址
browser-use back                          # 返回上一页
browser-use scroll down                   # 向下滚动页面（可选参数 --amount N 指定像素数）

# 页面状态查询（建议每次操作前先运行 state 获取元素索引）
browser-use state                         # 显示当前 URL、标题及可点击元素列表
browser-use screenshot                    # 截图并输出 base64 编码内容
browser-use screenshot path.png           # 将截图保存为本地文件

# 交互操作（使用 state 返回的索引编号）
browser-use click <index>                 # 点击指定元素
browser-use type "text"                   # 在聚焦元素中输入文本
browser-use input <index> "text"          # 点击元素后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use select <index> "option"       # 选择下拉框选项

# 数据提取
browser-use eval "document.title"         # 执行 JavaScript 脚本并返回结果
browser-use get text <index>              # 获取指定元素的文本内容
browser-use get html --selector "h1"      # 提取特定选择器的 HTML 内容

# 等待操作
browser-use wait selector "h1"            # 等待指定选择器的元素出现
browser-use wait text "Success"           # 等待页面中出现指定文本

# 会话管理
browser-use sessions                      # 列出所有活跃会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

# AI 代理任务
browser-use -b remote run "task"          # 在云端运行代理任务（默认异步）
browser-use task status <id>              # 查询云端任务执行状态

命令分类

导航与标签页操作

browser-use open <url>                    # 访问指定网址
browser-use back                          # 返回历史记录中的上一页
browser-use scroll down                   # 向下滚动页面
browser-use scroll up                     # 向上滚动页面
browser-use scroll down --amount 1000     # 按指定像素数滚动（默认 500）
browser-use switch <tab>                  # 切换到指定索引的标签页
browser-use close-tab                     # 关闭当前标签页
browser-use close-tab <tab>              # 关闭指定索引的标签页

页面状态查询

browser-use state                         # 获取当前页面的 URL、标题和可点击元素
browser-use screenshot                    # 截图并输出 base64 编码
browser-use screenshot path.png           # 将截图保存为本地文件
browser-use screenshot --full path.png    # 生成完整页面截图

交互操作

browser-use click <index>                 # 点击指定元素
browser-use type "text"                   # 在焦点元素中输入文本
browser-use input <index> "text"          # 点击元素后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use keys "Control+a"              # 发送组合键（如 Ctrl+A）
browser-use select <index> "option"       # 从下拉菜单中选择选项
browser-use hover <index>                 # 鼠标悬停于元素上（触发 CSS :hover 效果）
browser-use dblclick <index>              # 双击元素
browser-use rightclick <index>            # 右键点击元素（触发上下文菜单）

请根据 browser-use state 输出的索引编号进行操作。

JavaScript 执行与数据提取

browser-use eval "document.title"         # 执行 JavaScript 表达式并返回结果
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, width, height）

Cookies

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 set name val --same-site Strict  # SameSite: Strict、Lax 或 None
browser-use cookies set name val --expires 1735689600  # 过期时间戳
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
browser-use cookies import <file>         # 从 JSON 文件导入 Cookie

等待条件

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  # 自定义超时时间（毫秒）

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

Python 会话在命令之间保持状态。browser 对象提供以下功能：

• browser.url、browser.title、browser.html —— 页面信息
• browser.goto(url)、browser.back() —— 浏览器导航
• browser.click(index)、browser.type(text)、browser.input(index, text)、browser.keys(keys) —— 交互操作
• browser.screenshot(path)、browser.scroll(direction, amount) —— 可视化操作
• browser.wait(seconds)、browser.extract(query) —— 工具函数

代理任务

远程模式选项

使用 --browser remote 时，可选以下额外参数：

# 指定 LLM 模型
browser-use -b remote run "task" --llm gpt-4o
browser-use -b remote run "task" --llm claude-sonnet-4-20250514

# 代理配置（默认：us）
browser-use -b remote run "task" --proxy-country uk

# 会话复用
browser-use -b remote run "task 1" --keep-alive        # 任务结束后保持会话
browser-use -b remote run "task 2" --session-id abc-123 # 复用已有会话

# 执行模式
browser-use -b remote run "task" --flash       # 快速执行模式
browser-use -b remote run "task" --wait        # 等待完成（默认为异步）

# 高级选项
browser-use -b remote run "task" --thinking    # 启用扩展推理模式
browser-use -b remote run "task" --no-vision   # 禁用视觉功能（默认启用）

# 使用云配置文件（需先创建会话，再通过 --session-id 使用）
browser-use session create --profile <cloud-profile-id> --keep-alive
# → 返回 session_id
browser-use -b remote run "task" --session-id <session-id>

# 任务配置
browser-use -b remote run "task" --start-url https://example.com  # 从指定 URL 开始
browser-use -b remote run "task" --allowed-domain example.com     # 限制导航范围（可重复）
browser-use -b remote run "task" --metadata key=value             # 任务元数据（可重复）
browser-use -b remote run "task" --skill-id skill-123             # 启用技能（可重复）
browser-use -b remote run "task" --secret key=value               # 秘密元数据（可重复）

# 结构化输出与评估
browser-use -b remote run "task" --structured-output '{"type":"object"}'  # 输出的 JSON Schema
browser-use -b remote run "task" --judge                 # 启用判断模式
browser-use -b remote run "task" --judge-ground-truth "expected answer"

任务管理

browser-use task list                     # 列出最近的任务
browser-use task list --limit 20          # 显示更多任务
browser-use task list --status finished   # 按状态过滤（finished、stopped）
browser-use task list --session <id>      # 按会话 ID 过滤
browser-use task list --json              # JSON 格式输出

browser-use task status <task-id>         # 获取任务状态（仅最新步骤）
browser-use task status <task-id> -c      # 显示所有步骤及推理过程
browser-use task status <task-id> -v      # 显示所有步骤及 URL + 操作
browser-use task status <task-id> --last 5  # 仅显示最后 N 步
browser-use task status <task-id> --step 3  # 查看特定步骤
browser-use task status <task-id> --reverse # 最新在前

browser-use task stop <task-id>           # 停止正在运行的任务
browser-use task logs <task-id>           # 获取任务执行日志

云会话管理

browser-use session list                  # 列出云会话
browser-use session list --limit 20       # 显示更多会话
browser-use session list --status active  # 按状态过滤
browser-use session list --json           # JSON 格式输出

browser-use session get <session-id>      # 获取会话详情及实时访问链接
browser-use session get <session-id> --json

browser-use session stop <session-id>     # 停止某个会话
browser-use session stop --all            # 停止所有活跃会话

browser-use session create                          # 使用默认配置创建
browser-use session create --profile <id>           # 使用云配置文件
browser-use session create --proxy-country uk       # 使用地理代理
browser-use session create --start-url https://example.com
browser-use session create --screen-size 1920x1080
browser-use session create --keep-alive
browser-use session create --persist-memory

browser-use session share <session-id>              # 创建公开分享链接
browser-use session share <session-id> --delete     # 删除公开分享链接

隧道功能

browser-use tunnel <port>           # 启动隧道（返回访问地址）
browser-use tunnel <port>           # 幂等操作 — 返回已有地址
browser-use tunnel list             # 显示当前活跃的隧道
browser-use tunnel stop <port>      # 停止指定端口的隧道
browser-use tunnel stop --all       # 停止所有隧道

会话管理

browser-use sessions                      # 列出当前活跃会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

配置文件管理

本地 Chrome 配置文件（--browser real）

browser-use -b real profile list          # 列出本地 Chrome 配置文件
browser-use -b real profile cookies "Default"  # 查看指定配置文件中的 Cookie 域名

云配置文件（--browser remote）

browser-use -b remote profile list            # 列出云配置文件
browser-use -b remote profile list --page 2 --page-size 50
browser-use -b remote profile get <id>        # 获取配置文件详情
browser-use -b remote profile create          # 创建新的云配置文件
browser-use -b remote profile create --name "我的配置文件"
browser-use -b remote profile update <id> --name "新名称"
browser-use -b remote profile delete <id>

同步功能

browser-use profile sync --from "Default" --domain github.com  # 指定域名同步
browser-use profile sync --from "Default"                      # 整体配置文件同步
browser-use profile sync --from "Default" --name "自定义名称"   # 使用自定义名称同步

服务器控制

browser-use server logs                   # 查看服务器日志

常用工作流程

暴露本地开发服务器

适用于拥有本地开发服务，需要通过云浏览器访问的情况。

核心流程： 启动本地开发服务 → 创建隧道 → 远程访问隧道地址。

# 1. 启动你的开发服务
npm run dev &  # 本地地址：localhost:3000

# 2. 通过 Cloudflare 隧道暴露服务
browser-use tunnel 3000
# → url: https://abc.trycloudflare.com

# 3. 现在云浏览器可以访问你的本地服务
browser-use --browser remote open https://abc.trycloudflare.com
browser-use state
browser-use screenshot

注意： 隧道与浏览器会话无关。隧道独立于 browser-use close 操作，可单独管理。需提前安装 cloudflared — 可运行 browser-use doctor 检查。

使用配置文件进行已登录浏览

适用于任务需要访问用户已登录的网站（如 Gmail、GitHub、内部系统）的情况。

核心流程： 检查现有配置文件 → 询问用户选择使用本地浏览器还是云浏览器 → 使用对应配置文件浏览。若无合适配置文件，则提供同步选项。

在访问已登录网站前，代理必须：

1. 询问用户是否使用 真实（本地 Chrome）或 远程（云）浏览器
2. 列出该模式下的可用配置文件
3. 询问使用哪个配置文件
4. 若无包含所需 Cookie 的配置文件，提供同步选项（见下文）

步骤一：检查现有配置文件

# 选项 A：本地 Chrome 配置文件（--browser real）
browser-use -b real profile list
# → Default: 个人账户 (user@gmail.com)
# → Profile 1: 工作账号 (work@company.com)

# 选项 B：云配置文件（--browser remote）
browser-use -b remote profile list
# → abc-123: "Chrome - 默认配置 (github.com)"
# → def-456: "工作配置"

步骤二：使用选定配置文件浏览

# 真实浏览器 — 使用本地 Chrome 并保留已有的登录状态
browser-use --browser real --profile "Default" open https://github.com

# 云浏览器 — 使用已同步 Cookie 的云配置文件
browser-use --browser remote --profile abc-123 open https://github.com

用户已处于登录状态 — 无需重新登录。

注意： 云配置文件的 Cookie 可能随时间过期。若认证失败，应从本地 Chrome 配置文件重新同步 Cookie。

步骤三：同步 Cookie（仅在必要时）

若用户希望使用云浏览器但没有合适的云配置文件包含所需 Cookie，可从本地 Chrome 配置文件同步。

同步前，代理必须：

1. 询问使用哪个本地 Chrome 配置文件
2. 询问要同步的域名 — 不应默认同步整个配置文件
3. 在执行前确认

查看本地配置文件中包含哪些 Cookie：

browser-use -b real profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2

按域名同步（推荐）：

browser-use profile sync --from "Default" --domain github.com
# 创建新云配置文件："Chrome - 默认配置 (github.com)"
# 仅同步 github.com 的 Cookie

完整配置文件同步（谨慎使用）：

browser-use profile sync --from "Default"
# 同步全部 Cookie — 包括敏感数据、追踪 Cookie、所有会话令牌

仅当用户明确需要完整浏览器状态时才使用。

细粒度控制（高级功能）：

# 导出 cookies 到文件，手动编辑后导入
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json

使用同步的配置文件：

browser-use --browser remote --profile <id> open https://github.com

运行子代理

使用云会话在并行环境中运行自主浏览器代理。

核心工作流程： 使用 run 启动任务 → 用 task status 轮询状态 → 收集结果 → 清理会话。

• 会话 = 代理：每个云会话都是一个具有独立状态的浏览器代理
• 任务 = 工作：分配给代理的任务；一个代理可按顺序执行多个任务
• 会话生命周期：一旦停止，会话无法恢复 —— 必须创建新会话

启动任务

# 单个任务（默认异步 —— 立即返回）
browser-use -b remote run "搜索 AI 新闻并总结前 3 篇文章"
# → task_id: task-abc, session_id: sess-123

# 并行任务 —— 每个任务获得独立会话
browser-use -b remote run "研究竞争对手 A 的定价策略"
# → task_id: task-1, session_id: sess-a
browser-use -b remote run "研究竞争对手 B 的定价策略"
# → task_id: task-2, session_id: sess-b
browser-use -b remote run "研究竞争对手 C 的定价策略"
# → task_id: task-3, session_id: sess-c

# 在同一会话中顺序执行任务（复用 cookies、登录状态等）
browser-use -b remote run "登录 example.com" --keep-alive
# → task_id: task-1, session_id: sess-123
browser-use task status task-1  # 等待完成
browser-use -b remote run "导出设置" --session-id sess-123
# → task_id: task-2, session_id: sess-123（相同会话）

管理与停止

browser-use task list --status finished      # 查看已完成的任务
browser-use task stop task-abc               # 停止任务（若使用 --keep-alive，会话可能继续运行）
browser-use session stop sess-123            # 停止整个会话（终止其所有任务）
browser-use session stop --all               # 停止所有会话

监控

任务状态设计注重令牌效率。 默认输出最小化 —— 仅在需要时扩展：

# 对于长任务（50+ 步骤）
browser-use task status <id> -c --last 5   # 仅显示最后 5 步
browser-use task status <id> -v --step 10  # 检查特定步骤

实时查看：browser-use session get <session-id> 返回一个实时访问链接，可观看代理执行过程。

检测卡住的任务：如果 task status 中的成本或持续时间不再增加，说明任务已卡住 —— 应停止并启动新的代理。

日志：browser-use task logs <task-id> —— 仅在任务完成后可用。

全局选项

会话行为：所有未指定 --session 的命令均使用相同的“default”会话。浏览器保持开启，并在命令间重复使用。使用 --session NAME 可并行运行多个浏览器实例。

使用建议

1. **始终先运行 browser-use state** 以查看当前可用元素及其索引
2. **调试时使用 --headed** 以便观察浏览器实际行为
3. 会话持久化 —— 浏览器在命令间保持开启
4. **使用 --json** 便于程序解析
5. **在同一会话内，Python 变量在 browser-use python 命令间保持持久**
6. CLI 别名：bu、browser 和 browseruse 与 browser-use 功能完全相同

故障排查

首先运行诊断：

browser-use doctor

浏览器无法启动？

browser-use close --all               # 关闭所有会话
browser-use --headed open <url>       # 尝试以可见窗口模式打开

元素未找到？

browser-use state                     # 检查当前页面元素
browser-use scroll down               # 元素可能在视窗下方
browser-use state                     # 再次检查

会话问题？

browser-use sessions                  # 查看当前活跃会话
browser-use close --all               # 清理所有会话
browser-use open <url>                # 重新开始

任务停止后会话重用失败：

若停止任务后尝试复用原会话，新任务可能卡在“created”状态。应创建新会话：

browser-use session create --profile <profile-id> --keep-alive
browser-use -b remote run "新任务" --session-id <new-session-id>

任务卡在“started”状态：使用 task status 检查成本 —— 若无增长，说明任务已卡住。通过 session get 查看实时链接，然后停止并重新启动代理。

任务完成后会话仍持续存在：任务结束不会自动停止会话。请运行 browser-use session stop --all 手动清理。

清理

完成操作后，请关闭浏览器：

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