name: browser-cash
description: 通过 Browser.cash 启动无阻的浏览器会话，用于网页自动化。这些会话可绕过常见的反机器人防护（如 Cloudflare、DataDome 等），非常适合在常规自动化任务受阻时进行数据抓取和自动化操作。
homepage: https://browser.cash
metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["curl","jq"]}}}

browser-cash

通过 Browser.cash 启动无阻的浏览器会话，用于网页自动化。这些会话可绕过常见的反机器人防护（如 Cloudflare、DataDome 等），非常适合数据抓取、测试以及其他容易被拦截的自动化任务。

适用场景： 任何浏览器自动化任务——数据抓取、表单填写、测试、截图等。Browser.cash 的会话表现为真实浏览器，并能自动处理机器人检测。

设置

API 密钥 存储在 clawdbot 配置的 skills.entries.browser-cash.apiKey 路径下。

如果尚未配置，请提示用户：

从 https://dash.browser.cash 获取您的 API 密钥，然后运行：
bash clawdbot config set skills.entries.browser-cash.apiKey "your_key_here"

读取密钥：

BROWSER_CASH_KEY=$(clawdbot config get skills.entries.browser-cash.apiKey)

首次使用前，检查并按需安装 Playwright：

if [ ! -d ~/clawd/node_modules/playwright ]; then
  cd ~/clawd && npm install playwright puppeteer-core
fi

API 基础

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

创建浏览器会话

基础会话：

curl -X POST "https://api.browser.cash/v1/browser/session" \
  -H "Authorization: Bearer $BROWSER_CASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应示例：

{
  "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"
}

带选项的会话：

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
    }
  }'

会话选项

在 Clawdbot 中使用 Browser.cash

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

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

重要： 运行 Playwright/Puppeteer 脚本前，请确保依赖已安装：

[ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core)

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

# 1. 创建会话
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. 通过 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. 完成后停止会话
curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \
  -H "Authorization: Bearer $BROWSER_CASH_KEY"

选项 2：基于 Curl 的自动化

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

# 使用 CDP URL 导航并提取内容
# （可用的方法请参阅 CDP 协议文档）

关于 Clawdbot 浏览器工具的说明

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

获取会话状态

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

状态包括：starting、active、completed、error

停止会话

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

列出会话

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

浏览器配置文件

配置文件可在会话间持久保存 Cookie、localStorage 和会话数据，对于保持登录状态或维持状态非常有用。

列出配置文件：

curl "https://api.browser.cash/v1/browser/profiles" \
  -H "Authorization: Bearer $BROWSER_CASH_KEY"

删除配置文件：

curl -X DELETE "https://api.browser.cash/v1/browser/profile?profileName=my-profile" \
  -H "Authorization: Bearer $BROWSER_CASH_KEY"

通过 CDP 连接

cdpUrl 是一个用于 Chrome DevTools 协议的 WebSocket 端点。可与任何兼容 CDP 的库一起使用。

Playwright：

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：

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');

完整工作流程示例

# 0. 确保已安装 Playwright
[ -d ~/clawd/node_modules/playwright ] || (cd ~/clawd && npm install playwright puppeteer-core)

# 1. 创建会话
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. 使用 $CDP_URL 连接 Playwright/Puppeteer...

# 3. 完成后停止会话
curl -X DELETE "https://api.browser.cash/v1/browser/session?sessionId=$SESSION_ID" \
  -H "Authorization: Bearer $BROWSER_CASH_KEY"

数据抓取技巧

从具有懒加载或无限滚动功能的页面提取数据时：

// 滚动以加载所有产品
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); // 等待内容加载
  }
}

// 等待特定元素
await page.waitForSelector('.product-card', { timeout: 10000 });

// 处理“加载更多”按钮
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： 提供直接的 WebSocket 连接，支持 Playwright、Puppeteer 或原始 CDP
• 地理定位： 可在特定国家/地区启动会话
• 持久化配置文件： 在会话间保持登录状态

注意事项

• 长时间无活动后，会话会自动终止
• 完成后请务必停止会话，以避免不必要的使用量
• 需要保持登录状态时，请使用配置文件
• 仅支持 SOCKS5 代理类型
• Clawdbot 从 ~/clawd/ 目录运行脚本，请在该目录下安装 npm 依赖
• 进行全页抓取时，务必滚动以触发懒加载内容