browser

浏览器自动化

使用 browse CLI 配合 Claude 自动化浏览器交互。

设置检查

运行任何浏览器命令之前，请先确认 CLI 可用：

which browse || npm install -g browse

环境选择（本地与远程）

CLI 支持为每条命令明确指定环境标志。如果不指定，且设置了 BROWSERBASE_API_KEY，下一次会话将默认使用 Browserbase；否则默认使用本地环境。

本地模式

• browse open <url> --local 启动一个干净、隔离的本地浏览器
• browse open <url> --auto-connect 连接到已运行且可调试的 Chrome；如果没有可调试的 Chrome，请使用 --local
• browse open <url> --cdp <port|url> 连接到指定的 CDP 目标
• 适用场景：开发、本地主机、可信网站和可复现的运行

远程模式（Browserbase）

• browse open <url> --remote 启动 Browserbase 会话
• 如果设置了 BROWSERBASE_API_KEY，不指定本地标志时也会默认使用 Browserbase
• 提供：Browserbase Identity、Verified 浏览器、自动解决 CAPTCHA、住宅代理、会话持久化
• 适用场景： 目标网站启用了机器人检测、CAPTCHA、IP 速率限制、Cloudflare 保护，或需要特定地理位置才能访问时
• 前往 https://browserbase.com/settings 获取凭据

如何选择

• 可重复的本地测试／干净状态：browse open <url> --local
• 复用本地登录状态／Cookie：browse open <url> --auto-connect
• 简单浏览（文档、维基、公共 API）：本地模式即可
• 受保护的网站（登录墙、CAPTCHA、反爬虫）：使用远程模式
• 本地模式因机器人检测或访问被拒而失败时：切换到远程模式

命令

守护进程启动后，大多数驱动程序命令都适用于本地、远程和 CDP 会话。

导航

browse open <url>                        # Go to URL
browse open <url> --local                # Go to URL in a clean local browser
browse open <url> --remote               # Go to URL in a Browserbase session
browse reload                            # Reload current page
browse back                              # Go back in history
browse forward                           # Go forward in history

页面状态（优先使用快照，而非截图）

browse snapshot                          # Get accessibility tree with element refs (fast, structured)
browse screenshot --path <path>          # Take visual screenshot (slow, uses vision tokens)
browse get url                           # Get current URL
browse get title                         # Get page title
browse get text <selector>               # Get text content (use "body" for all text)
browse get html <selector>               # Get HTML content of element
browse get markdown [selector]           # Get page content as markdown (defaults to body)
browse get value <selector>              # Get form field value

默认使用 browse snapshot 了解页面状态——它会返回无障碍树，其中包含可用于交互的元素引用。只有在需要视觉上下文（布局、图像、调试）时才使用 browse screenshot。

交互

browse click <ref>                       # Click element by ref from snapshot (e.g., @0-5)
browse type <text>                       # Type text into focused element
browse fill <selector> <value>           # Fill input; add --press-enter if Enter is needed
browse select <selector> <values...>     # Select dropdown option(s)
browse upload <selector> <files...>      # Upload file(s) to <input type="file">
browse press <key>                       # Press key (Enter, Tab, Escape, Cmd+A, etc.)
browse mouse drag <fromX> <fromY> <toX> <toY>  # Drag from one point to another
browse mouse scroll <x> <y> <deltaX> <deltaY>  # Scroll at coordinates
browse highlight <selector>              # Highlight element on page
browse is visible <selector>             # Check if element is visible
browse is checked <selector>             # Check if element is checked
browse wait <type> [arg]                 # Wait for: load, selector, timeout

CDP 事件跟踪

browse cdp <url|port>                    # Stream CDP events as NDJSON from any target
browse cdp 9222                          # Attach to local Chrome on port 9222
browse cdp ws://localhost:9222/devtools/browser/...  # Full WebSocket URL
browse cdp <url> --domain Network        # Only Network events
browse cdp <url> --domain Network --domain Console  # Multiple domains
browse cdp <url> --pretty                # Human-readable output
browse cdp <url> > events.jsonl          # Pipe to file
browse cdp <url> | jq '.method'          # Filter with jq

cdp 命令可直接连接到任何 Chrome DevTools Protocol 目标并流式传输事件。它不使用守护进程，而是一个独立的长时间运行进程。按 Ctrl+C 停止。默认域：Network、Console、Runtime、Log、Page。

会话管理

browse stop                              # Stop the browser daemon
browse status                            # Check daemon status and resolved mode
browse tab list                          # List all open tabs
browse tab switch <index-or-target-id>   # Switch to tab by index or target ID
browse tab close [index-or-target-id]    # Close tab

典型工作流

如果环境很重要，请在第一条浏览器命令中添加 --local、--remote、--auto-connect 或 --cdp <port|url>。

1. browse open <url> --local 或 browse open <url> --remote — 导航到页面
2. browse snapshot — 查看无障碍树，了解页面结构并获取元素引用
3. browse click <ref> / browse type <text> / browse fill <selector> <value> — 使用快照中的引用进行交互
4. browse snapshot — 确认操作成功
5. 根据需要重复步骤 3-4
6. browse stop — 完成后关闭浏览器

快速示例

browse open https://example.com
browse snapshot                          # see page structure + element refs
browse click @0-5                        # click element with ref 0-5
browse get title
browse stop

模式对比

特性	本地	Browserbase
速度	更快	稍慢
设置要求	需要 Chrome	需要 API 密钥
复用现有的本地 Cookie	使用 browse open <url> --auto-connect	不适用
Verified 浏览器	否	是（通过 Identity 使用 Browserbase Verified 浏览器）
CAPTCHA 解决	否	是（自动解决 reCAPTCHA/hCaptcha）
住宅代理	否	是（201 个国家／地区，可定向地理位置）
会话持久化	否	是（通过上下文持久保存 Cookie／身份验证）
适用场景	开发／简单页面	受保护的网站、Browserbase Identity + Verified 访问、生产环境抓取

最佳实践

1. 有意识地选择本地策略：使用 browse open <url> --local 获取干净的状态，使用 browse open <url> --auto-connect 使用现有的本地凭据，使用 browse open <url> --remote 访问受保护的网站
2. 交互前始终先运行 browse open
3. 使用 browse snapshot 检查页面状态——速度快，还能提供元素引用
4. 仅在需要视觉上下文时截图（检查布局、查看图像、调试）
5. 使用 snapshot 中的引用进行点击和交互——例如，browse click @0-5
6. 完成后运行 browse stop，以清理浏览器会话并清除环境变量覆盖

故障排查

• “No active page”：运行 browse stop，然后检查 browse status。如果仍显示正在运行，使用 pkill -f "browse.*daemon" 结束僵尸守护进程，然后重试 browse open
• 找不到 Chrome：安装 Chrome；如果已有可调试的 Chrome 在运行，则使用 browse open <url> --auto-connect；或者切换到 browse open <url> --remote
• 操作失败：运行 browse snapshot 查看可用元素及其引用
• Browserbase 失败：确认已设置 API 密钥

切换到远程模式

检测到以下情况时切换到远程模式：CAPTCHA（reCAPTCHA、hCaptcha、Turnstile）、机器人检测页面（“Checking your browser...”）、HTTP 403/429、应该有内容的网站显示空白页面，或用户提出要求。

对于简单的网站（文档、维基、公共 API、localhost），不要切换。

browse open <url> --local          # clean isolated local browser
browse open <url> --auto-connect   # attach to existing debuggable Chrome
browse open <url> --remote         # Browserbase session

模式标志会在会话启动时应用。运行 browse stop 后，下次启动时会回退到基于环境变量的自动检测。守护进程运行期间，使用 browse status 查看解析出的模式和目标。

详细示例请参阅 EXAMPLES.md。 API 参考请参阅 REFERENCE.md。