browser-use

name	browser-use
description	自动化浏览器交互，用于网页测试、表单填写、截图与页面数据提取。当用户需要访问网站、操作网页、填写表单、截图或抓取网页内容时，应使用本技能。
allowed-tools	Bash(browser-use:*)

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

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. 执行交互：基于索引点击、输入、选择或上传
4. 再次验证：再次运行 state 或 screenshot，确认结果正确
5. 重复操作：浏览器会在命令之间保持打开

如果某条命令失败，先执行：

browser-use close

再重新开始，避免残留异常会话影响后续操作。

如果希望直接复用用户本机 Chrome 的登录态和 Cookie，先执行：

browser-use connect

如果希望用云浏览器，则先执行：

browser-use cloud connect

无论连的是本地 Chrome 还是云浏览器，后续命令的调用方式都一样。

浏览器模式

browser-use open <url>                         # 默认：无头 Chromium
browser-use --headed open <url>                # 可见窗口，适合调试
browser-use connect                            # 连接用户自己的 Chrome
browser-use cloud connect                      # 连接云浏览器
browser-use --profile "Default" open <url>     # 指定本地 Chrome profile

执行 connect 或 cloud connect 后，后续命令都会作用于该浏览器，不需要再重复加额外模式参数。

常用命令

# 导航
browser-use open <url>                    # 打开 URL
browser-use back                          # 后退
browser-use scroll down                   # 向下滚动
browser-use scroll up                     # 向上滚动
browser-use tab list                      # 查看标签页
browser-use tab new [url]                 # 新建标签页
browser-use tab switch <index>            # 切换标签页
browser-use tab close <index> [index...]  # 关闭一个或多个标签页

# 页面状态
browser-use state                         # 查看当前 URL、标题、元素索引
browser-use screenshot [path.png]         # 截图

# 交互
browser-use click <index>                 # 点击元素
browser-use click <x> <y>                 # 点击坐标
browser-use type "text"                   # 向当前焦点输入
browser-use input <index> "text"          # 点击后输入
browser-use keys "Enter"                  # 发送按键
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>              # 取元素位置尺寸

# 等待
browser-use wait selector "css"           # 等待选择器出现或消失
browser-use wait text "text"              # 等待文本出现

# Cookie
browser-use cookies get [--url <url>]     # 读取 Cookie
browser-use cookies set <name> <value>    # 设置 Cookie
browser-use cookies clear [--url <url>]   # 清理 Cookie
browser-use cookies export <file>         # 导出 Cookie
browser-use cookies import <file>         # 导入 Cookie

# 会话
browser-use close                         # 关闭浏览器
browser-use sessions                      # 查看活动会话
browser-use close --all                   # 关闭所有会话

使用原则

1. 先看 state，再操作

大多数页面操作都依赖元素索引，因此在点击、输入之前，先跑一次：

browser-use state

2. 需要肉眼调试时用 --headed

如果页面元素不稳定、交互异常或索引判断不清楚，优先切到可见模式：

browser-use --headed open <url>

3. 需要登录态时优先连本地 Chrome

例如 Gmail、GitHub、企业后台等场景，优先使用现有 profile：

browser-use profile list
browser-use --profile "Default" open https://github.com

4. 需要并行浏览器时使用多会话

如果要同时跑多个浏览器实例，请使用 --session NAME。每个 session 都是一套独立浏览器。详见：

• references/multi-session.md

5. 需要更底层控制时查看 CDP 参考

如果任务需要直接操作 CDP、切激活标签页、做设备模拟等，查看：

• references/cdp-python.md

云浏览器 API

browser-use cloud connect
browser-use cloud login <api-key>
browser-use cloud logout
browser-use cloud v2 GET /browsers
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>
browser-use cloud v2 --help

cloud connect 会创建并连接一个云浏览器实例；browser-use close 会断开并关闭该实例。

隧道

browser-use tunnel <port>
browser-use tunnel list
browser-use tunnel stop <port>
browser-use tunnel stop --all

这适合把本地开发服务暴露到公网做远程访问或云浏览器联调。

配置

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
--cdp-url <url>	通过 CDP 地址连接已有浏览器
--session NAME	使用命名会话
--json	输出 JSON
--mcp	作为 MCP 服务运行

常见问题

• 浏览器起不来：先执行 browser-use close，再重新打开
• 找不到元素：先滚动，再运行 browser-use state
• 不确定环境状态：运行 browser-use doctor

清理

browser-use close
browser-use tunnel stop --all