remote-browser

沙箱代理的浏览器自动化

此技能适用于在沙箱远程机器（云虚拟机、CI、编码代理）上运行且需要控制无头浏览器的代理。

前提条件

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. 重复：浏览器在命令之间保持打开状态
6. 清理：完成后执行 browser-use close

浏览器模式

browser-use open <url>                                    # 默认：无头 Chromium
browser-use cloud connect                                 # 配置云浏览器并连接
browser-use --connect open <url>                          # 通过 CDP 自动发现正在运行的 Chrome
browser-use --cdp-url ws://localhost:9222/... open <url>  # 通过 CDP URL 连接

命令

# 导航
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（可选过滤）
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>         # 导出为 JSON
browser-use cookies import <file>         # 从 JSON 导入

# Python — 带浏览器访问的持久会话
browser-use python "code"                 # 执行 Python（变量在调用间持久化）
browser-use python --file script.py       # 运行文件
browser-use python --vars                 # 显示已定义的变量
browser-use python --reset                # 清除命名空间

# 会话
browser-use close                         # 关闭浏览器并停止守护进程
browser-use sessions                      # 列出活动会话
browser-use close --all                   # 关闭所有会话

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.upload(index, path)、browser.screenshot(path)、browser.scroll(direction, amount)、browser.wait(seconds)。

隧道

通过 Cloudflare 隧道将本地开发服务器暴露给浏览器。

browser-use tunnel <port>                 # 启动隧道（幂等）
browser-use tunnel list                   # 显示活动隧道
browser-use tunnel stop <port>            # 停止隧道
browser-use tunnel stop --all             # 停止所有隧道

命令链

命令可以用 && 链接。浏览器通过守护进程保持打开状态，因此链接安全高效。

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 以先发现索引时，请单独运行。

常见工作流

暴露本地开发服务器

python -m http.server 3000 &                      # 启动开发服务器
browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # 浏览隧道

隧道独立于浏览器会话，并在 browser-use close 后持续存在。

多代理（--connect 模式）

多个代理可以通过 --connect 共享一个浏览器。每个代理拥有自己的标签页——其他代理无法干扰。

设置：注册一次，然后在每个 --connect 命令中传递索引：

INDEX=$(browser-use register)                    # → 打印 "1"
browser-use --connect $INDEX open <url>          # 在代理自己的标签页中导航
browser-use --connect $INDEX state               # 从代理的标签页获取状态
browser-use --connect $INDEX click <element>     # 在代理的标签页中点击

• 标签页锁定：当代理修改标签页（点击、输入、导航）时，该标签页被锁定给该代理。其他代理尝试修改同一标签页时会收到错误。
• 只读访问：state、screenshot、get 和 wait 命令可对任何标签页执行，不受锁定影响。
• 代理会话在 5 分钟不活动后过期。再次运行 browser-use register 获取新索引。

全局选项

选项	描述
--headed	显示浏览器窗口
--connect	通过 CDP 自动发现正在运行的 Chrome
--cdp-url <url>	通过 CDP URL 连接（http:// 或 ws://）
--session NAME	指定目标会话（默认："default"）
--json	以 JSON 格式输出

提示

1. 始终先运行 state 以查看可用元素及其索引
2. 会话持久化 — 浏览器在命令之间保持打开状态，直到你关闭它
3. 隧道独立 — 它们在 browser-use close 后持续存在
4. tunnel 是幂等的 — 对同一端口再次调用会返回现有 URL

故障排除

• 浏览器无法启动？ 执行 browser-use close 然后重试。运行 browser-use doctor 检查。
• 找不到元素？ 执行 browser-use scroll down 然后 browser-use state
• 隧道不工作？ 执行 which cloudflared 检查，browser-use tunnel list 查看活动隧道

清理

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