Browser-Use CLI 命令行工具完整文档

概述

browser-use 是一个快速、持久化的浏览器自动化命令行工具。它在命令之间保持浏览器会话，支持复杂的多步骤工作流程。

快速开始

browser-use open https://example.com           # 导航到 URL
browser-use state                              # 获取页面元素及其索引
browser-use click 5                            # 通过索引点击元素
browser-use type "Hello World"                 # 输入文本
browser-use screenshot                         # 截图
browser-use close                              # 关闭浏览器

安装

# 安装 browser-use 包
uv add browser-use
uv sync

# 安装 Chromium 浏览器
uvx browser-use install

核心工作流程

导航: browser-use open <url> - 打开 URL（如需要会自动启动浏览器）
检查: browser-use state - 返回可点击元素及其索引
交互: 使用 state 返回的索引进行交互（browser-use click 5, browser-use input 3 "text"）
验证: 使用 browser-use state 或 browser-use screenshot 确认操作结果
重复: 浏览器在命令之间保持打开状态

浏览器模式

# 默认：无头 Chromium
browser-use --browser chromium open <url>

# 可见的 Chromium 窗口
browser-use --browser chromium --headed open <url>

# 使用真实的 Chrome（带登录会话）
browser-use --browser real open <url>

# 云端浏览器（需要 API key）
browser-use --browser remote open <url>

模式说明:

chromium: 快速、隔离、默认无头模式
real: 使用你的 Chrome，包含 cookies、扩展、已登录会话
remote: 云端托管浏览器，支持代理（需要 BROWSER_USE_API_KEY）

命令参考

1. 导航命令

命令	描述	示例
`browser-use open <url>`	导航到指定 URL	`browser-use open https://example.com`
`browser-use back`	返回上一页	`browser-use back`
`browser-use scroll down`	向下滚动	`browser-use scroll down`
`browser-use scroll up`	向上滚动	`browser-use scroll up`
`browser-use scroll down --amount 1000`	向下滚动指定像素	`browser-use scroll down --amount 1000`

2. 页面状态检查

命令	描述	示例
`browser-use state`	获取 URL、标题和可点击元素	`browser-use state`
`browser-use screenshot`	截图（输出 base64）	`browser-use screenshot`
`browser-use screenshot <path>`	保存截图到文件	`browser-use screenshot page.png`
`browser-use screenshot --full <path>`	全页面截图	`browser-use screenshot --full page.png`

3. 交互命令

注意: 使用 browser-use state 获取的索引来进行交互

命令	描述	示例
`browser-use click <index>`	点击指定索引的元素	`browser-use click 5`
`browser-use type "text"`	在当前焦点元素中输入文本	`browser-use type "Hello World"`
`browser-use input <index> "text"`	点击元素后输入文本	`browser-use input 3 "john@example.com"`
`browser-use keys "Enter"`	发送键盘按键	`browser-use keys "Enter"`
`browser-use keys "Control+a"`	发送组合键	`browser-use keys "Control+a"`
`browser-use select <index> "option"`	选择下拉选项	`browser-use select 2 "Option 1"`

4. 标签页管理

命令	描述	示例
`browser-use switch <tab>`	切换到指定索引的标签页	`browser-use switch 1`
`browser-use close-tab`	关闭当前标签页	`browser-use close-tab`
`browser-use close-tab <tab>`	关闭指定索引的标签页	`browser-use close-tab 2`

5. JavaScript 和数据提取

命令	描述	示例
`browser-use eval "js code"`	执行 JavaScript 代码并返回结果	`browser-use eval "document.title"`
`browser-use extract "query"`	使用 LLM 提取数据（需要 API key）	`browser-use extract "all product prices"`

6. Python 执行（持久化会话）

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

# 设置变量
browser-use python "x = 42"

# 访问变量
browser-use python "print(x)"  # 输出: 42

# 访问浏览器对象
browser-use python "print(browser.url)"

# 显示已定义的变量
browser-use python --vars

# 清除 Python 命名空间
browser-use python --reset

# 执行 Python 文件
browser-use python --file script.py

browser 对象 API:

browser.url - 当前页面 URL
browser.title - 页面标题
browser.goto(url) - 导航到 URL
browser.click(index) - 点击元素
browser.type(text) - 输入文本
browser.screenshot(path) - 截图
browser.scroll() - 滚动页面
browser.html - 获取页面 HTML

7. AI 代理任务（需要 API Key）

# 运行 AI 代理完成任务
browser-use run "Fill the contact form with test data"

# 指定最大步数
browser-use run "Extract all product prices" --max-steps 50

代理任务使用 LLM 自主完成复杂的浏览器任务。需要配置以下任一 API key：

BROWSER_USE_API_KEY（推荐）
OPENAI_API_KEY
ANTHROPIC_API_KEY
GOOGLE_API_KEY

8. 会话管理

命令	描述	示例
`browser-use sessions`	列出所有活动会话	`browser-use sessions`
`browser-use close`	关闭当前会话	`browser-use close`
`browser-use close --all`	关闭所有会话	`browser-use close --all`

9. 服务器控制

命令	描述	示例
`browser-use server status`	检查服务器是否运行	`browser-use server status`
`browser-use server stop`	停止服务器	`browser-use server stop`
`browser-use server logs`	查看服务器日志	`browser-use server logs`

全局选项

选项	描述	默认值
`--session NAME`	使用命名会话	"default"
`--browser MODE`	浏览器模式：chromium, real, remote	chromium
`--headed`	显示浏览器窗口（chromium 模式）	false
`--profile NAME`	Chrome 配置文件（仅 real 模式）	-
`--json`	以 JSON 格式输出	false
`--api-key KEY`	覆盖 API key	-

会话行为: 所有不带 --session 的命令使用同一个 "default" 会话。浏览器在命令之间保持打开并被重用。使用 --session NAME 可以并行运行多个浏览器。

实用示例

示例 1: 表单提交

# 打开表单页面
browser-use open https://example.com/contact

# 查看页面元素
browser-use state
# 输出: [0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"

# 填写表单
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use input 2 "Hello, this is a test message."

# 提交表单
browser-use click 3

# 验证结果
browser-use state

示例 2: 数据提取（使用 JavaScript）

# 打开页面
browser-use open https://news.ycombinator.com

# 使用 JavaScript 提取数据
browser-use eval "Array.from(document.querySelectorAll('.titleline a')).slice(0,5).map(a => a.textContent)"

示例 3: 多会话工作流

# 启动工作会话
browser-use --session work open https://work.example.com

# 启动个人会话
browser-use --session personal open https://personal.example.com

# 检查工作会话
browser-use --session work state

# 检查个人会话
browser-use --session personal state

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

示例 4: Python 自动化

# 打开页面
browser-use open https://example.com/products

# 使用 Python 进行复杂操作
browser-use python "
products = []
for i in range(20):
    browser.scroll('down')
    browser.wait(0.5)
browser.screenshot('products.png')
"

# 输出结果
browser-use python "print(f'Captured {len(products)} products')"

示例 5: 使用真实浏览器（已登录会话）

# 使用你的 Chrome 浏览器（保留登录状态）
browser-use --browser real open https://gmail.com

# 已经登录！
browser-use state

示例 6: 可见浏览器调试

# 使用可见窗口进行调试
browser-use --headed open https://example.com

# 查看浏览器操作
browser-use click 5
browser-use type "test"

最佳实践

始终先运行 browser-use state 查看可用元素及其索引
使用 --headed 进行调试 可以看到浏览器的实际操作
会话持久化 - 浏览器在命令之间保持打开状态
使用 --json 进行程序化解析 输出结果
Python 变量持久化 - 在同一会话中，browser-use python 命令之间变量保持
真实浏览器模式 保留你的登录会话和扩展

故障排除

浏览器无法启动？

# 停止卡住的服务器
browser-use server stop

# 尝试使用可见窗口
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>

工作原理

CLI 使用会话服务器架构：

第一个命令启动后台服务器（浏览器保持打开）
后续命令通过 Unix socket 通信（Windows 使用 TCP）
浏览器在命令之间持久化，实现快速交互
服务器按需自动启动，使用 browser-use server stop 停止

这使得命令延迟约为 50ms，而不是每次都等待浏览器启动。

清理

完成后始终关闭浏览器。完成浏览器自动化后运行：

browser-use close

命令别名

以下命令是等效的：

browser-use <command>
browseruse <command>
bu <command>
browser <command>

API Key 配置

在 .env 文件中配置 API key：

# Browser-Use Cloud API（推荐）
BROWSER_USE_API_KEY=your-key

# 或使用其他 LLM 提供商
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key

新用户注册 Browser Use Cloud 可获得 $10 免费额度。

高级功能

使用代理（云端浏览器）

# 使用云端浏览器（自动支持代理和隐身模式）
browser-use --browser remote open https://example.com

自定义 Chrome 配置文件

# 使用特定的 Chrome 配置文件
browser-use --browser real --profile "Profile 1" open https://example.com

JSON 输出用于脚本

# 获取 JSON 格式的输出
browser-use --json state

# 在脚本中解析
STATE=$(browser-use --json state)
echo $STATE | jq '.data.url'

测试验证

基本任务验证清单

导航到 URL
获取页面状态
点击元素
输入文本
提交表单
截图
滚动页面
执行 JavaScript
管理标签页
使用 Python 会话
关闭浏览器

测试脚本示例

#!/bin/bash

# 测试基本功能
echo "测试 1: 打开页面"
browser-use open https://example.com

echo "测试 2: 获取状态"
browser-use state

echo "测试 3: 截图"
browser-use screenshot test.png

echo "测试 4: 执行 JavaScript"
browser-use eval "document.title"

echo "测试 5: Python 会话"
browser-use python "print('Hello from Python')"

echo "测试 6: 关闭浏览器"
browser-use close

echo "所有测试完成！"

参考资源

文档版本: 基于 browser-use v0.11.5 最后更新: 2026-01-29

SKILL.md 12 KB Permalink Histórico Raw