browser

浏览器自动化

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

环境检查

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

which browse || npm install -g browse

环境选择（本地 vs 远程）

CLI 支持每个命令显式指定环境标志。如果不指定，当设置了 BROWSERBASE_API_KEY 时，下一个会话默认使用 Browserbase，否则使用本地模式。

本地模式

• browse open <url> --local 启动一个干净的隔离本地浏览器
• browse open <url> --auto-connect 附加到已运行的可调试 Chrome；当没有可调试 Chrome 时使用 --local
• browse open <url> --cdp <port|url> 附加到特定的 CDP 目标
• 最佳用途：开发、localhost、受信任的站点和可重现的运行

远程模式（Browserbase）

• browse open <url> --remote 启动一个 Browserbase 会话
• 如果没有本地标志，当设置了 BROWSERBASE_API_KEY 时，Browserbase 也是默认选项
• 提供：Browserbase Identity、验证浏览器、自动 CAPTCHA 解决、住宅代理、会话持久化
• 在以下情况下使用远程模式： 目标站点有机器人检测、CAPTCHA、IP 速率限制、Cloudflare 保护，或需要特定地理位置访问
• 在 https://browserbase.com/settings 获取凭据

何时选择哪种模式

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

命令

大多数驱动命令在本地、远程和 CDP 会话中均可工作，守护进程启动后即可使用。

导航

browse open <url>                        # 打开 URL
browse open <url> --local                # 在干净的本地浏览器中打开 URL
browse open <url> --remote               # 在 Browserbase 会话中打开 URL
browse reload                            # 重新加载当前页面
browse back                              # 返回历史记录
browse forward                           # 前进历史记录

页面状态（优先使用 snapshot 而非 screenshot）

browse snapshot                          # 获取带有元素引用的无障碍树（快速、结构化）
browse screenshot --path <path>          # 截取视觉截图（慢，消耗视觉 token）
browse get url                           # 获取当前 URL
browse get title                         # 获取页面标题
browse get text <selector>               # 获取文本内容（使用 "body" 获取所有文本）
browse get html <selector>               # 获取元素的 HTML 内容
browse get markdown [selector]           # 获取页面内容为 markdown（默认为 body）
browse get value <selector>              # 获取表单字段值

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

交互

browse click <ref>                       # 点击 snapshot 中的元素引用（例如 @0-5）
browse type <text>                       # 在聚焦元素中输入文本
browse fill <selector> <value>           # 填充输入；如果需要按 Enter，添加 --press-enter
browse select <selector> <values...>     # 选择下拉选项
browse upload <selector> <files...>      # 上传文件到 <input type="file">
browse press <key>                       # 按键（Enter、Tab、Escape、Cmd+A 等）
browse mouse drag <fromX> <fromY> <toX> <toY>  # 从一点拖到另一点
browse mouse scroll <x> <y> <deltaX> <deltaY>  # 在坐标处滚动
browse highlight <selector>              # 在页面上高亮元素
browse is visible <selector>             # 检查元素是否可见
browse is checked <selector>             # 检查元素是否被选中
browse wait <type> [arg]                 # 等待：加载、选择器、超时

CDP 事件跟踪

browse cdp <url|port>                    # 从任何目标流式传输 CDP 事件为 NDJSON
browse cdp 9222                          # 附加到本地 Chrome 的端口 9222
browse cdp ws://localhost:9222/devtools/browser/...  # 完整的 WebSocket URL
browse cdp <url> --domain Network        # 仅 Network 事件
browse cdp <url> --domain Network --domain Console  # 多个域
browse cdp <url> --pretty                # 人类可读输出
browse cdp <url> > events.jsonl          # 管道到文件
browse cdp <url> | jq '.method'          # 使用 jq 过滤

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

会话管理

browse stop                              # 停止浏览器守护进程
browse status                            # 检查守护进程状态和解析的模式
browse tab list                          # 列出所有打开的标签页
browse tab switch <index-or-target-id>   # 按索引或目标 ID 切换标签页
browse tab close [index-or-target-id]    # 关闭标签页

典型工作流程

如果环境重要，请在第一个浏览器命令中放置 --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> — 使用 snapshot 中的引用进行交互
4. browse snapshot — 确认操作成功
5. 根据需要重复步骤 3-4
6. browse stop — 完成后关闭浏览器

快速示例

browse open https://example.com
browse snapshot                          # 查看页面结构 + 元素引用
browse click @0-5                        # 点击引用为 0-5 的元素
browse get title
browse stop

模式比较

特性	本地	Browserbase
速度	更快	稍慢
设置	需要 Chrome	需要 API 密钥
重用现有本地 cookie	使用 browse open <url> --auto-connect	不适用
验证浏览器	否	是（通过 Identity 的 Browserbase 验证浏览器）
CAPTCHA 解决	否	是（自动 reCAPTCHA/hCaptcha）
住宅代理	否	是（201 个国家，地理定位）
会话持久化	否	是（通过上下文持久化 cookie/认证）
最佳用途	开发/简单页面	受保护站点、Browserbase Identity + 验证访问、生产爬取

最佳实践

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          # 干净的隔离本地浏览器
browse open <url> --auto-connect   # 附加到现有可调试 Chrome
browse open <url> --remote         # Browserbase 会话

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

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