跳到正文

托管浏览器

只需一次 API 调用，就能在我们的服务器上启动一个 Clearcote 浏览器，并通过 Chrome DevTools Protocol 从 Playwright、Puppeteer 或任意 CDP 客户端驱动它。你无需自行安装或运行任何东西。流量默认经住宅 IP 出网，按 GB 从预付余额中扣费。

  • 住宅 IP，而非数据中心 IP。网站看到的是来自普通家用宽带运营商的真实家庭网络连接，而不是主机托管或云服务的地址。
  • 真实硬件，而非 VPS。浏览器运行在我们自有的独立物理服务器上，而不是共享的云虚拟机。
托管浏览器的更多内容：本地与云端共用一个 SDK（launch(cloud=True)）、智能体任务（输入一个任务，输出 JSON）、录像与事件时间线、Cookie 同步、密钥与 2FA，以及交给真人处理与 Webhook。

免费连接 GitHub 即可免费获得 €5 流量。无需信用卡。

一次性赠送，每个 GitHub 账号限领一次。GitHub 账号须注册满 30 天。

领取 €5

1. 获取 API 密钥

在“API keys”页面创建一个。密钥以 cc_live_ 开头，作为 bearer token 发送。请妥善保管：任何持有它的人都能花掉你的余额。

2. 启动浏览器并连接

POST /api/v1/browsers 会返回一个 connectUrl：指向该浏览器的一次性 WebSocket URL。请在两分钟内连接；它不能重复使用。浏览器会在你连接的那一刻启动，通常几秒内即可就绪；但如果设置了 country，会先查询出口 IP 的位置，最长可能需要半分钟左右。Playwright 默认 30 秒后放弃连接，因此示例中都传入了两分钟的 timeout。

javascript
// Node.js + Playwright
import { chromium } from "playwright";

const res = await fetch("https://www.clearcotelabs.com/api/v1/browsers", {
  method: "POST",
  headers: { authorization: "Bearer cc_live_...", "content-type": "application/json" },
  body: JSON.stringify({ identity: "account-1", country: "us" }),
});
const { connectUrl, id, error } = await res.json();
if (error) throw new Error(error);

const browser = await chromium.connectOverCDP(connectUrl, { timeout: 120_000 }); // the browser starts as you connect
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
await browser.close(); // ends the session
javascript
// Puppeteer: the same connectUrl
const browser = await puppeteer.connect({ browserWSEndpoint: connectUrl, defaultViewport: null });
python
# Python + Playwright
import requests
from playwright.sync_api import sync_playwright

r = requests.post("https://www.clearcotelabs.com/api/v1/browsers",
                  headers={"authorization": "Bearer cc_live_..."},
                  json={"identity": "account-1", "country": "de"}).json()
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(r["connectUrl"], timeout=120_000)
    page = browser.contexts[0].new_page()
    page.goto("https://example.com")
    browser.close()

创建调用返回 201，响应中包含你的代码连接浏览器和了解价格所需的全部信息：

json
{
  "id": "bs_…",                       // use it with GET / DELETE /api/v1/browsers/<id>
  "connectUrl": "wss://…/v1/connect/bs_…?token=…",
  "expiresAt": "2026-09-24T10:02:00.000Z", // connect before this (two minutes)
  "worker": "w_…",
  "pricing": { "eurPerGb": 1, "eurPerHour": 0 },
  "limits": { "maxSeconds": 14400, "idleSeconds": 300 } // plus maxBytes when capped
}

最佳实践

  1. 只连接，不启动。用 connectOverCDP 或 puppeteer.connect 连接 connectUrl；chromium.launch() 则会在你自己的机器上启动一个浏览器。
  2. 用现成的。使用 browser.contexts()[0] 及其第一个页面，而不是新建 context：新 context 不带 Profile 的 cookie 和存储，而且 Playwright 会给它一个模拟的 1280×720 视口，与浏览器窗口不一致。
  3. 在创建时设定身份画像，而不是在脚本里。国家、时区和语言应该放在创建调用中。在脚本里覆盖 user agent、视口或 navigator 属性，恰恰会制造出检测所要寻找的那种不一致。
  4. CDP 钩子范围要尽量小。宽泛的监听器、对每个请求的拦截以及 init 脚本，本身就是自动化的指纹。原版 Playwright 和 Puppeteer 可以直接使用，只有两个调用例外（setContent 和 exposeFunction）：引擎会让 Runtime.enable 的副作用不触及页面本身，因此像 Patchright 这样的修补版驱动是可选项，而非必需。
  5. 一个会话，多个页面。启动浏览器是最慢的环节；请在同一个浏览器内导航。用 Profile 登录一次即可，不必每次运行都登录。
  6. 务必停止。在 finally 中关闭浏览器，并根据任务设置 maxGb 和 idleTimeoutSec，这样即使代码有 bug，也不会让浏览器一直用你的余额运行下去。
  7. 先观察，再加代码。当某个站点表现异常时，先在实时画面中观察（或接管控制），再考虑添加等待和变通方案。