browser-use

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

所有命令都使用独立的封装脚本 bu.sh，它会：

• 自动初始化本地 .venv（首次运行时通过 uv 下载依赖，大约需要 60 秒）
• 自动设置 PYTHONUTF8=1（在 Windows 上处理表情符号和 Unicode）
• 保持浏览器守护进程运行，每次调用延迟约为 50 毫秒

简写——在所有示例中，bu 表示：

bash ~/.claude/skills/browser-use/bu.sh

前置条件

• 必须安装 uv（uv --version）
• 首次运行会从 GitHub 将 browser-use 安装到 ~/.claude/skills/browser-use/.venv

核心工作流

1. 导航：bu open <url> — 按需启动浏览器和守护进程
2. 检查：bu state — 返回带索引的可点击元素
3. 交互：使用 state 中的索引（bu click 5、bu input 3 "text"）
4. 验证：使用 bu state 或 bu screenshot 确认
5. 重复操作：浏览器会在命令之间保持打开
6. 清理：完成后运行 bu close

浏览器模式

bu open <url>                         # Default: headless Chromium
bu --headed open <url>                # Visible window
bu --profile "Default" open <url>     # Real Chrome with Default profile (existing logins/cookies)
bu --profile "Profile 1" open <url>   # Real Chrome with named profile
bu --connect open <url>               # Auto-discover running Chrome via CDP
bu --cdp-url ws://localhost:9222/... open <url>  # Connect via specific CDP URL

--connect、--cdp-url 和 --profile 不能同时使用。

命令

# Navigation
bu open <url>                    # Navigate to URL
bu back                          # Go back in history
bu scroll down                   # Scroll down (--amount N for pixels)
bu scroll up                     # Scroll up
bu switch <tab>                  # Switch to tab by index
bu close-tab [tab]               # Close tab (current if no index)

# Page State — always run state first to get element indices
bu state                         # URL, title, clickable elements with indices
bu screenshot [path.png]         # Screenshot (base64 if no path, --full for full page)

# Interactions — use indices from state
bu click <index>                 # Click element by index
bu click <x> <y>                 # Click at pixel coordinates
bu type "text"                   # Type into focused element
bu input <index> "text"          # Click element, then type
bu keys "Enter"                  # Send keyboard keys (also "Control+a", etc.)
bu select <index> "option"       # Select dropdown option
bu upload <index> <path>         # Upload file to file input
bu hover <index>                 # Hover over element
bu dblclick <index>              # Double-click element
bu rightclick <index>            # Right-click element

# Data Extraction
bu eval "js code"                # Execute JavaScript, return result
bu get title                     # Page title
bu get html [--selector "h1"]    # Page HTML (or scoped to selector)
bu get text <index>              # Element text content
bu get value <index>             # Input/textarea value
bu get attributes <index>        # Element attributes
bu get bbox <index>              # Bounding box (x, y, width, height)

# Wait
bu wait selector "css"           # Wait for element (--state visible|hidden|attached|detached, --timeout ms)
bu wait text "text"              # Wait for text to appear

# Cookies
bu cookies get [--url <url>]     # Get cookies (optionally filtered)
bu cookies set <name> <value>    # Set cookie (--domain, --secure, --http-only, --same-site, --expires)
bu cookies clear [--url <url>]   # Clear cookies
bu cookies export <file>         # Export to JSON
bu cookies import <file>         # Import from JSON

# Python — persistent session with browser access
bu python "code"                 # Execute Python (variables persist across calls)
bu python --file script.py       # Run file
bu python --vars                 # Show defined variables
bu python --reset                # Clear namespace

# Session
bu close                         # Close browser and stop daemon
bu sessions                      # List active sessions
bu close --all                   # Close all sessions

# Recipes — store and replay DOM access patterns (no screenshot on repeat runs)
bu recipe list                   # Show all installed recipes + run history
bu recipe run <name>             # Execute a recipe directly against the DOM
bu recipe run <name> --connect   # Override auth: use CDP connect mode
bu recipe run <name> --headed    # Override: show browser window (debug)
bu recipe show <name>            # Print recipe JSON
bu recipe save <name> --file <path>  # Install a recipe JSON file
bu recipe delete <name>          # Remove a recipe

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)。

云 API

bu cloud connect                 # Provision cloud browser and connect
bu cloud connect --timeout 120 --proxy-country US  # With options
bu cloud login <api-key>         # Save API key (or set BROWSER_USE_API_KEY)
bu cloud logout                  # Remove API key
bu cloud v2 GET /browsers        # REST passthrough (v2 or v3)
bu cloud v2 POST /tasks '{"task":"...","url":"..."}'
bu cloud v2 poll <task-id>       # Poll task until done

常见工作流

身份验证浏览（现有 Chrome 会话）

bu --connect open https://gmail.com   # Reuse logged-in Chrome via CDP
bu --connect state
bu --connect eval "document.title"

需要使用 --remote-debugging-port=9222 启动 Chrome。

身份验证浏览（Chrome 配置文件）

bu profile list                                # Check available profiles
bu --profile "Default" open https://github.com # Already logged in

通过 JavaScript 提取数据

bu --connect open https://x.com/notifications
bu --connect eval "Array.from(document.querySelectorAll('[data-testid=\"notification\"]')).slice(0,10).map(n => n.innerText).join('\n---\n')"

暴露本地开发服务

bu tunnel 3000                             # → https://abc.trycloudflare.com
bu open https://abc.trycloudflare.com

命令串联

bu open https://example.com && bu state
bu input 5 "[email protected]" && bu input 6 "password" && bu click 7

如果不需要中间输出，可以串联命令。若需要先解析 state 以查找索引，则应分别运行命令。

全局选项

选项	描述
--headed	显示浏览器窗口
--profile [NAME]	使用真实的 Chrome（单独使用 --profile 时采用 "Default"）
--connect	通过 CDP 自动发现正在运行的 Chrome
--cdp-url <url>	通过 CDP URL 连接（http:// 或 ws://）
--session NAME	指定命名会话（默认为 "default"）
--json	以 JSON 格式输出
--mcp	通过 stdin/stdout 作为 MCP 服务运行

提示

1. 始终先运行 state，查看可用元素及其索引
2. 调试时使用 --headed，查看浏览器正在执行的操作
3. 会话会持续保留——浏览器会在命令之间保持打开
4. 对于复杂页面，使用 JS 的 eval 是最强大的提取方法

故障排除

• 首次运行很慢？ 这是正常的——正在将约 200MB 的依赖下载到 .venv。后续运行会立即完成。
• 浏览器无法启动？ 先运行 bu close，然后运行 bu --headed open <url>
• 找不到元素？ 运行 bu scroll down，然后运行 bu state
• Unicode 错误？ 已自动处理——bu.sh 会自动设置 PYTHONUTF8=1

清理

bu close           # Close browser session
bu tunnel stop --all  # Stop tunnels (if any)

配方系统

配方会保存 DOM 访问模式，让重复任务无需再进行视觉发现。

首次运行：手动查找选择器 → 编写配方 JSON
重复运行：bu recipe run <name> 直接执行 JS——无需截图，也无需扫描元素

配方 JSON 格式

{
  "name": "my_recipe",
  "version": 1,
  "description": "What this recipe does",
  "url": "https://example.com/page",

  "auth": {
    "mode": "connect",      // "connect" | "profile" | "headless"
    "profile": null,        // Chrome profile name (mode=profile only)
    "headed": false,
    "session": "default"
  },

  "steps": [
    {
      "id": "nav",
      "type": "navigate",
      "url": "https://example.com/page",
      "wait_for": ".main-content",
      "wait_timeout_ms": 10000
    },
    {
      "id": "extract",
      "type": "eval",
      "js": "document.querySelector('.result')?.innerText",
      "output_var": "result",
      "fallback_selectors": [".alt-result", "[data-result]"]
    }
  ],

  "output": { "format": "text", "var": "result" },
  "metadata": { "created": "2026-01-01", "last_run": null, "run_count": 0, "broken_step": null }
}

步骤类型

类型	必填字段	功能
navigate	url	打开 URL；也可等待 CSS 选择器出现
eval	js	运行 JavaScript；将结果存入 output_var
click	index	根据 bu state 中的索引点击元素
input	index、text	点击元素，然后输入文本
wait	selector 或 text	等待元素或文本出现
scroll	direction	向上或向下滚动

自愈回退

当 eval 步骤失败时：

1. 依次尝试每个 fallback_selectors 条目，作为 document.querySelector('SEL')?.innerText 执行
2. 首个匹配项优先——记录到 stderr，配方继续执行
3. 如果所有回退项都失败：截图保存到 recipes/.broken_<name>_<step>.png，在元数据中设置 broken_step，退出码为 1

配方示例

参见 recipes/x_notifications.json——通过 CDP 连接获取 X.com 通知。

平台支持

支持 Linux、macOS 和 Windows（Windows 上需要 Git Bash 或 WSL）。 bash 必须在 PATH 中可用——所有标准配置都已满足此条件。