浏览器自动化

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

设置检查

在运行任何浏览器命令之前，请验证 CLI 是否可用：

which browse || npm install -g @browserbasehq/browse-cli

环境选择（本地与远程）

CLI 会根据可用配置自动选择本地或远程浏览器环境：

本地模式（默认）

• 使用本地 Chrome —— 无需 API 密钥
• 最佳适用场景：开发、简单页面、无机器人防护的可信站点

远程模式（Browserbase）

• 在以下情况激活：设置了 BROWSERBASE_API_KEY和设置了 BROWSERBASE_PROJECT_ID时激活
• 提供功能：反机器人隐身、自动验证码解决、住宅代理、会话持久化
• 在以下情况使用远程模式：目标站点有机器人检测、验证码、IP 速率限制、Cloudflare 防护或需要特定地理区域访问权限时
• 在以下网址获取凭据：https://browserbase.com/settings

何时选择哪种模式

• 简单浏览（文档、维基、公共 API）：本地模式即可
• 受保护站点（登录墙、验证码、反爬虫）：使用远程模式
• 如果本地模式失败（出现机器人检测或访问被拒绝）：切换到远程模式

命令

所有命令在两种模式下工作方式相同。守护进程会在首次执行命令时自动启动。

导航

browse open <url>                        # 访问 URL（别名：goto）
browse reload                            # 重新加载当前页面
browse back                              # 后退
browse forward                           # 前进

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

浏览快照                          # 获取带元素引用符的无障碍树（快速、结构化）
浏览截图 [路径]                 # 拍摄视觉截图（慢，消耗视觉令牌）
浏览 获取 网址                           # 获取当前网址
浏览 获取 标题                         # 获取页面标题
浏览 获取 文本 <选择器>               # 获取文本内容（使用"body"获取所有文本）
浏览 获取 html <选择器>               # 获取元素的HTML内容
浏览 获取 值 <选择器>              # 获取表单字段的值

请将浏览快照作为理解页面状态的默认方式——它返回带有元素引用符的无障碍树，你可以使用这些引用符进行交互。仅在需要视觉上下文（布局、图像、调试）时使用浏览截图。

交互

浏览 点击 <引用符>                       # 通过快照中的引用符点击元素（例如，@0-5）
浏览 输入 <文本>                       # 在焦点元素中输入文本
浏览 填充 <选择器> <值>           # 填充输入框并按回车键
浏览 选择 <选择器> <值...>     # 选择下拉选项
浏览 按下 <按键>                       # 按下按键（回车、Tab、Esc、Cmd+A等）
浏览 拖拽 <起始X> <起始Y> <目标X> <目标Y>  # 从一点拖拽到另一点
浏览 滚动 <x> <y> <deltaX> <deltaY> # 在坐标处滚动
浏览 高亮 <选择器>              # 在页面上高亮元素
浏览 是否可见 <选择器>             # 检查元素是否可见
浏览 是否选中 <选择器>             # 检查元素是否被选中
浏览 等待 <类型> [参数]                 # 等待：加载、选择器、超时

会话管理

浏览 停止                              # 停止浏览器守护进程
浏览 状态                            # 检查守护进程状态（包含环境信息）
浏览 环境                               # 显示当前环境（本地或远程）
浏览 环境 本地                         # 切换到本地Chrome
浏览 环境 远程                        # 切换到Browserbase（需要API密钥）
浏览 页面                             # 列出所有打开的标签页
浏览 标签切换 <索引>                # 按索引切换到标签页
浏览 标签关闭 [索引]                 # 关闭标签页

典型工作流程

1. 浏览 打开 <网址>— 导航到页面
2. 浏览 快照— 阅读无障碍树以理解页面结构并获取元素引用符
3. 浏览 点击 <引用符>/浏览 输入 <文本>/浏览 填充 <选择器> <值>— 使用快照中的引用符进行交互
4. 浏览 快照— 确认操作已生效
5. 根据需要重复步骤3-4
6. 浏览 停止— 完成后关闭浏览器

快速示例

浏览 打开 https://example.com
浏览 快照                          # 查看页面结构 + 元素引用符
浏览 点击 @0-5                        # 点击引用符为0-5的元素
浏览 获取 标题
浏览 停止

模式对比

最佳实践

1. 始终先浏览打开在交互前使用
2. 浏览快照来检查页面状态——它速度快且提供元素引用仅在需要视觉上下文时截图
3. （布局检查、图像、调试）使用快照中的引用
4. 进行点击/交互——例如：浏览点击 @0-5browse click @0-5
5. 浏览停止完成后清理浏览器会话

故障排除

• "无活动页面"：运行浏览停止，然后检查浏览状态。如果仍显示运行中，使用pkill -f "browse.*daemon"终止僵尸守护进程，然后重试浏览打开
• 未找到Chrome：安装Chrome或使用浏览环境远程
• 操作失败：运行浏览快照查看可用元素及其引用
• Browserbase失败：验证API密钥和项目ID是否已设置

切换到远程模式

当检测到以下情况时切换到远程模式：验证码（reCAPTCHA、hCaptcha、Turnstile）、机器人检测页面（"正在检查您的浏览器..."）、HTTP 403/429错误、本应有内容的网站显示空白页面，或用户要求切换。

对于简单网站（文档、维基、公共API、本地主机）无需切换。

浏览环境远程            # 切换到Browserbase
浏览环境本地             # 切换回本地Chrome

切换将保持生效，直到您运行浏览停止或再次切换。

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