跳到正文

安装

安装 SDK，让它自动获取经过校验的浏览器——或者自己下载并校验构建。

Clearcote 仍在积极开发中。目前提供 Windows x64 和 Linux x64 构建——SDK 会下载与你的操作系统对应的那一个。macOS 已列入路线图；在此之前，macOS 用户可以运行 Docker 镜像。在精简的 Linux 主机上，需要安装浏览器的运行时库（libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …）——clearcote info 会列出缺失的库。如果你以 root 身份自行启动二进制文件（在容器中很常见），请传入 --no-sandbox；SDK 和 clearcote serve 会替你处理这一点。

新最新构建通过 GitHub 免费使用，限一个浏览器。无需信用卡。

免费获取
bash
npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

首次调用 launch() 时，SDK 会下载适用于你操作系统的浏览器，校验其 SHA-256 并缓存下来。你不需要运行 playwright install——每个 SDK 都自带 Playwright 驱动，并自行获取浏览器。你拿到的是哪个构建，取决于是否设置了许可证密钥：

构建来源
无密钥开源版构建——Chromium 149.0.7827.114（v0.1.0-pre.22）。BSD-3 许可，可从公开源码复现。GitHub Releases，版本由 SDK 版本锁定
有密钥授权版构建——Chromium 153.0.8010.36-r28。GitHub 免费版同一时间可运行一个浏览器，或选择 Pro。clearcotelabs.com，每次启动都使用当前构建

设置许可证密钥

SDK 按以下顺序查找密钥：启动选项 licenseKey / license_key / LicenseKey，然后是环境变量 CLEARCOTE_LICENSE_KEY，最后是 ~/.clearcote/license.key——也就是 clearcote login 写入的文件。所有 SDK（包括 .NET）都会读取这个文件。免费密钥可以在控制台的“Licenses”页面获取。

bash
clearcote login cc_lic_...              # checks the key, saves it to ~/.clearcote/license.key
export CLEARCOTE_LICENSE_KEY=cc_lic_...  # or per process / per container

clearcote 命令

Python 和 Node 包会安装一个 clearcote 命令（如果是在项目本地用 npm 安装的，请用 npx clearcote … 运行）。.NET 包不包含这个命令。

bash
clearcote install              # download + verify the browser now (CI, Docker builds)
clearcote info                 # SDK, key, cached builds, seats in use, a launch test, missing libraries
clearcote info --proxy <url>   # the exit IP, timezone and language a launch through this proxy would get
clearcote update               # fetch a newer build if one exists (newest open build, or current licensed)
clearcote clear-cache          # delete cached builds — old ones are kept until you do
clearcote login [key]          # clearcote logout removes the saved key
clearcote serve                # a standing CDP endpoint — see Deployment

用 clearcote install --version 153 或 --channel preview 可以选择特定构建；参见选择构建。接下来，把它接入 Playwright 或 Puppeteer。

手动安装（开源版构建）

更想直接用二进制文件？GitHub Releases 提供的是开源版构建。授权版构建不在那里发布：它通过 SDK、clearcote serve 或 Docker 镜像运行，没有 SDK 提供的运行令牌就无法启动。

1. 下载

下载最新的 v0.1.0-pre.* 版本——目前是 v0.1.0-pre.22（Chromium 149.0.7827.114）。每个版本包含：

  • clearcote-<version>-windows-x64.zip——Windows 构建（Chromium + 运行时 + VC++ DLL）
  • clearcote-<version>-linux-x64.tar.xz——Linux 构建
  • .sha256 文件和 SHA256SUMS.txt——校验和
  • .asc 文件 + clearcote-signing-key.asc——GPG 分离签名及公钥

开源版构建的设计初衷，就是让你不必信任我们。解压之前，先确认下载的文件与构建并签名的产物完全一致——参见校验。

3. 解压

Windows 压缩包是自包含的：已捆绑 VC++ 2015–2022 运行时 DLL，因此可以在全新安装的 Windows 10/11 机器上运行。Linux 压缩包需要上文列出的运行时库。

Expand-Archive clearcote-149.0.7827.114-windows-x64.zip -DestinationPath C:\clearcote

# you now have:
#   C:\clearcote\chrome.exe
#   C:\clearcote\chrome.dll  + runtime, locales, ICU, ANGLE, VC++ DLLs

4. 冒烟测试

带上一个种子（seed）启动，并打开一个指纹检测页面：

C:\clearcote\chrome.exe --fingerprint=seed-123 --fingerprint-platform=windows https://abrahamjuliot.github.io/creepjs/

相同的 --fingerprint 种子 ⇒ 每次启动都是同一个身份；换一个新种子 ⇒ 一个全新的身份。如果想上报真实机器采集到的值，而不是由种子派生的值，请导入采集到的 profile——参见指纹参数。然后把它接入 Playwright 或 Puppeteer。

在 Docker 中运行

官方镜像以 CDP 端点的形式运行 Clearcote——拉取镜像后，让任意 Playwright、Puppeteer 或 browser-use 客户端通过 Chrome DevTools Protocol 连接它即可，无需改代码。

bash
docker run -d --rm -p 127.0.0.1:9222:9222 -e CC_FINGERPRINT=user-7423 teamflatearth/clearcote   # CDP on http://localhost:9222
python
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp("http://localhost:9222")   # your code, unchanged
    page = browser.new_page(); page.goto("https://example.com")

通过环境变量配置身份画像（persona）——CC_PLATFORM（windows/linux/macos/android）、CC_FINGERPRINT（种子）、CC_BRAND（Edge…）、CC_ACCEPT_LANGUAGE、CC_TIMEZONE、CC_TLS_PROFILE。请为每个身份单独设置 CC_FINGERPRINT：不设置的话，所有容器都会共用同一个默认种子。镜像内置的是开源版构建；加上 -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache 即可运行最新的授权版构建，它只会下载一次并存入该卷。浏览器在虚拟显示器上以有头模式运行（CC_HEADLESS=1 为纯无头模式），镜像架构为 linux/amd64。Dockerfile 可供审计——你也可以自己重新构建。CDP 端点意味着对浏览器的完全控制，因此只应将其发布到受信任的网络（-p 127.0.0.1:9222:9222 可将其限制在本机）。更多内容参见部署。

系统要求

  • Windows 10 / 11 x64，或装有上述运行时库的 Linux x64（glibc）。
  • Windows 上无需另装 VC++ 可再发行组件——它已捆绑在压缩包中。
  • SDK：Node 20+、Python 3.8+ 或 .NET 8。每个 SDK 都会引入各自的 Playwright 驱动（playwright-core、playwright、Microsoft.Playwright）。
  • 直接使用开源版构建的二进制文件时：沿用你现有的 Playwright 或 Puppeteer 安装即可（Clearcote 替换的是浏览器，而不是驱动）。