Browser Cash

# browser-cash

通过 Browser.cash 启动不受阻的浏览器会话，以进行 Web 自动化。这些会话可以绕过常见的反机器人保护（如 Cloudflare、DataDome 等），非常适合抓取、测试和那些通常会被阻止的自动化任务。

**何时使用：** 任何浏览器自动化任务——抓取、表单填写、测试、截图。Browser.cash 会话看起来像真实浏览器，并自动处理机器人检测。

## 设置

**API Key** 存储在 clawdbot 配置中的 `skills.entries.browser-cash.apiKey`。

如果未配置，提示用户： > 从 https://dash.browser.cash 获取您的 API key 并运行： > ```bash > clawdbot config set skills.entries.browser-cash.apiKey "your_key_here" > ```

**读取 key：** ```bash BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) ```

**首次使用前**，检查并按需安装 Playwright： ```bash if [ ! -d ~/clawd/node_modules/playwright ]; then cd ~/clawd && npm install playwright puppeteer-core fi ```

## API 基础

```bash curl -X POST "https://api.browser.cash/v1/..." \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" ```

## 创建浏览器会话

**基本会话：** ```bash curl -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{}' ```

**响应：** ```json { "sessionId": "abc123...", "status": "active", "servedBy": "node-id", "createdAt": "2025-01-20T01:51:25.000Z", "stoppedAt": null, "cdpUrl": "wss://gcp-usc1-1.browser.cash/v1/consumer/abc123.../devtools/browser/uuid" } ```

**带选项：** ```bash curl -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{ "country": "US", "windowSize": "1920x1080", "profile": { "name": "my-profile", "persist": true } }' ```

### 会话选项

| 选项 | 类型 | 描述 | |--------|------|-------------| | `country` | string | 2字母 ISO 代码（例如 "US", "DE", "GB"） | | `windowSize` | string | 浏览器尺寸，例如 "1920x1080" | | `proxyUrl` | string | SOCKS5 代理 URL（可选） | | `profile.name` | string | 用于会话持久化的命名浏览器配置文件 | | `profile.persist` | boolean | 会话结束后保存 cookies/storage |

## 在 Clawdbot 中使用 Browser.cash

Browser.cash 返回一个 WebSocket CDP URL (`wss://...`)。使用以下方法之一：

### 选项 1：通过 exec 直接连接 CDP（推荐）

**重要：** 在运行 Playwright/Puppeteer 脚本之前，请确保已安装依赖项： ```bash [ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core) ```

在 exec 块中使用 Playwright 或 Puppeteer 直接连接到 CDP URL：

```bash # 1. Create session BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) SESSION=$(curl -s -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{"country": "US", "windowSize": "1920x1080"}')

SESSION_ID=$(echo $SESSION | jq -r '.sessionId') CDP_URL=$(echo $SESSION | jq -r '.cdpUrl')

# 2. Use via Node.js exec (Playwright) node -e " const { chromium } = require('playwright'); (async () => { const browser = await chromium.connectOverCDP('$CDP_URL'); const context = browser.contexts()[0]; const page = context.pages()[0] || await context.newPage(); await page.goto('https://example.com'); console.log('Title:', await page.title()); await browser.close(); })(); "

# 3. Stop session when done curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

### 选项 2：基于 Curl 的自动化

对于简单任务，使用 curl 通过 CDP 命令与页面交互：

```bash # Navigate and extract content using the CDP URL # (See CDP protocol docs for available methods) ```

### 关于 Clawdbot 浏览器工具的说明

Clawdbot 原生的 `browser` 工具期望 HTTP 控制服务器 URL，而不是原始的 WebSocket CDP。当 Clawdbot 的浏览器控制服务器代理连接时，`gateway config.patch` 方法有效。对于直接的 Browser.cash CDP，请使用上面的 exec 方法。

## 获取会话状态

```bash curl "https://api.browser.cash/v1/browser/session?sessionId=YOUR_SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

状态：`starting`（启动中）、`active`（活跃）、`completed`（完成）、`error`（错误）

## 停止会话

```bash curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=YOUR_SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

## 列出会话

```bash curl "https://api.browser.cash/v1/browser/sessions?page=1&pageSize=20" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

## 浏览器配置文件

配置文件可以在会话之间持久化 cookies、localStorage 和会话数据——这对于保持登录状态或维持状态非常有用。

**列出配置文件：** ```bash curl "https://api.browser.cash/v1/browser/profiles" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

**删除配置文件：** ```bash curl -X DELETE "https://api.browser.cash/v1/browser/profile?profileName=my-profile" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

## 通过 CDP 连接

`cdpUrl` 是 Chrome DevTools Protocol 的 WebSocket 端点。可以将其与任何兼容 CDP 的库一起使用。

**Playwright：** ```javascript const { chromium } = require('playwright'); const browser = await chromium.connectOverCDP(cdpUrl); const context = browser.contexts()[0]; const page = context.pages()[0] || await context.newPage(); await page.goto('https://example.com'); ```

**Puppeteer：** ```javascript const puppeteer = require('puppeteer-core'); const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl }); const pages = await browser.pages(); const page = pages[0] || await browser.newPage(); await page.goto('https://example.com'); ```

## 完整工作流示例

```bash # 0. Ensure Playwright is installed [ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core)

# 1. Create session BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey) SESSION=$(curl -s -X POST "https://api.browser.cash/v1/browser/session" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" \ -H "Content-Type: application/json" \ -d '{"country": "US", "windowSize": "1920x1080"}')

SESSION_ID=$(echo $SESSION | jq -r '.sessionId') CDP_URL=$(echo $SESSION | jq -r '.cdpUrl')

# 2. Connect with Playwright/Puppeteer using $CDP_URL...

# 3. Stop session when done curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \ -H "Authorization: Bearer $BROWSER_CASH_KEY" ```

## 抓取技巧

当从具有延迟加载或无限滚动的页面中提取数据时：

```javascript // Scroll to load all products async function scrollToBottom(page) { let previousHeight = 0; while (true) { const currentHeight = await page.evaluate(() => document.body.scrollHeight); if (currentHeight === previousHeight) break; previousHeight = currentHeight; await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight)); await page.waitForTimeout(1500); // Wait for content to load } }

// Wait for specific elements await page.waitForSelector('.product-card', { timeout: 10000 });

// Handle "Load More" buttons const loadMore = await page.$('button.load-more'); if (loadMore) { await loadMore.click(); await page.waitForTimeout(2000); } ```

**常见模式：** - 始终滚动以触发延迟加载的内容 - 等待网络空闲：`await page.waitForLoadState('networkidle')` - 在提取元素之前使用 `page.waitForSelector()` - 在操作之间添加延迟以避免速率限制

## 为什么选择 Browser.cash 进行自动化

- **不受阻：** 会话绕过 Cloudflare、DataDome、PerimeterX 和其他机器人保护 - **真实浏览器指纹：** 显示为真正的 Chrome 浏览器，而非无头模式 - **CDP 原生：** 为 Playwright、Puppeteer 或原始 CDP 提供直接的 WebSocket 连接 - **地理定位：** 在特定国家启动会话 - **持久化配置文件：** 在会话之间保持登录状态

## 注意事项

- 会话在长时间不活动后会自动终止 - 完成后务必停止会话以避免不必要的消耗 - 当需要保持登录状态时使用配置文件 - 仅支持 SOCKS5 类型的代理 - Clawdbot 从 `~/clawd/` 运行脚本——请在该处安装 npm 依赖 - 对于全页抓取，请务必滚动以触发延迟加载的内容