跳到正文

安装

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

Clearcote 仍在积极开发中。目前提供 Windows x64 和 Linux x64 构建——SDK 会下载与你的操作系统对应的那一个。没有原生的 macOS 构建：在 macOS 上，launch() 会替你运行 Clearcote Docker 镜像（SDK 0.40.0+，参见 macOS）。在精简的 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 150.0.7871.114（v0.1.0-pre.23）。BSD-3 许可，可从公开源码复现。GitHub Releases，版本由 SDK 版本锁定
有密钥授权版构建——Chromium 154.0.8037.57-r36。GitHub 免费版同一时间可运行一个浏览器，或选择 Pro。clearcotelabs.com，每次启动都使用当前构建

设置许可证密钥

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

bash
clearcote login --device                # sign in from a browser on any device; nothing to paste
clearcote login                         # asks for the key; what you paste is not shown
clearcote login cc_lic_...              # for scripts: checks the key, saves it to ~/.clearcote/license.key
export CLEARCOTE_LICENSE_KEY=cc_lic_...  # or per process / per container

从另一台设备登录

clearcote login --device（SDK 0.40.0+，适用于 Python 和 Node；如果是在项目本地用 npm 安装的，请用 npx clearcote login --device）无需你复制密钥就能保存密钥。它会打印一个链接和一个短码。在任意一台能登录 clearcotelabs.com 的设备上用浏览器打开该链接，确认页面上显示的代码与终端中的一致，勾选确认该终端属于你的复选框，然后批准。页面会提示该设备已登录，终端则会打印 Signed in as，后面是你账号的邮箱地址（部分隐藏），以及密钥的保存位置、套餐和到期时间。密钥本身从不会被打印出来，页面上和终端里都不会。

代码的有效期为 10 分钟；过期后重新运行该命令即可获得新代码。等待期间按 Ctrl-C 不会保存任何内容，再按一次 Ctrl-C 会立即退出。在通过 SSH 访问的服务器上、在容器中，或者由编码智能体替你配置 Clearcote 时，请使用 --device：批准在你自己的浏览器中完成，任何机密信息都不会经过终端、终端历史记录或聊天。如果密钥就在你自己的机器上，用 clearcote login 也一样好：从 0.40.0 起，它读取密钥时不会显示出来。

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

每个命令都支持 --help。从 SDK 0.40.0 起，clearcote info 会测试 launch() 实际会运行的构建，包括 CLEARCOTE_BROWSER_VERSION 指定的构建；如果密钥是用 clearcote login --device 保存的，它还会显示密钥何时到期（粘贴的密钥没有许可证服务告知其到期时间）。从 0.41.0 起，它在 Linux 上还会报告一次启动所能看到的字体可以绘制哪些书写系统（参见在 Linux 上使用你自己的字体）。用 clearcote install --version 154 或 --channel preview 可以选择特定构建；参见选择构建。接下来，把它接入 Playwright 或 Puppeteer。

macOS

没有原生的 macOS 构建。从 SDK 0.40.0 起，launch() 在 macOS 上会启动 Clearcote Docker 镜像（teamflatearth/clearcote:sdk-<SDK version>，一个 linux/amd64 镜像，Docker Desktop 可以在 Intel 和 Apple 芯片上运行它），连接到它，并返回与本地启动相同的 Playwright 浏览器。你的代码无需改动，close() 会停止并删除容器。这适用于 Python（同步和异步）、Node 和 .NET（LaunchAsync）中的 launch()；其他入口，例如持久化上下文和 serve()，仍然需要 Clearcote 二进制文件，因此在 Mac 上请直接在 Docker 镜像中运行它们。

from clearcote import launch

browser = launch(fingerprint="acct-1")   # on macOS: runs teamflatearth/clearcote:sdk-<version>
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()                          # stops and removes the container
  • 必须安装并运行 Docker Desktop。否则 launch() 会抛出 DockerUnavailableError（.NET：DockerUnavailableException），并说明该怎么做。首次启动会把镜像（有许可证密钥时还有最新构建）下载一次，存入 clearcote-cache 卷；之后的启动只需几秒。
  • 哪些内容会传入容器：身份画像选项、headless、proxy、args、version 和许可证密钥（查找方式与在其他任何机器上一样，包括 clearcote login 保存的密钥）。容器无法接受的选项会被拒绝，并指出选项名称。密钥和代理以文件形式传入容器，容器读取一次后即删除该文件，因此 docker inspect 看不到它们；如果容器没有运行授权版构建或没有使用该代理，带密钥或代理的启动会被拒绝。
  • 不会留下任何运行中的容器。如果你的程序没有调用 close() 就退出或被终止，它的容器会在没有任何连接约 30 秒后自行停止，下一次启动还会清理所属程序已不存在的残留容器。属于其他正在运行的程序、其他用户或其他机器的容器，一律不会被触碰。从 SDK 0.41.0 起，close() 要等 Docker 删除容器及其卷之后才返回，因此之后 docker ps -a 不会再列出它。
  • Chrome 保留其沙箱（SDK 0.41.0+，搭配 sdk-0.41.0 起的镜像）：启动时会传入镜像的 seccomp 配置文件，因此 Chrome 在容器内带着沙箱运行（参见Chrome 的沙箱）。这需要 Docker 运行在 x86_64 CPU 上；在 Apple silicon 上镜像以模拟方式运行，目前沙箱保持关闭。
  • 容器运行的是 Linux，因此它的默认身份画像是 Linux 身份画像。要在容器中声明其他平台，请先阅读部署。
设置作用
docker=False（Node 为 docker: false，.NET 为 Docker = false）或 CLEARCOTE_DOCKER=0不使用 Docker。此时在 macOS 上，你需要自己通过 executable_path 指定一个兼容的 Clearcote 二进制文件。
docker=True 或 CLEARCOTE_DOCKER=1在任何装有 Docker 的操作系统上使用 Docker 镜像。
docker_image=（Node 为 dockerImage，.NET 为 DockerImage）或 CLEARCOTE_DOCKER_IMAGE运行其他镜像或标签，例如固定使用 teamflatearth/clearcote:sdk-0.40.0。早于 sdk-0.40.0 的镜像仍然可用，但会给出警告：它以变量形式获取密钥和代理，docker inspect 能看到这些变量；而且如果你的程序意外终止，它不会自行停止。
CLEARCOTE_DOCKER_IDLE_EXIT无人连接的容器在停止前等待的秒数（默认 30，0 = 从不停止）。
CLEARCOTE_DOCKER_CACHE_VOLUME存放授权版构建的卷（默认 clearcote-cache）。

镜像会在对应的 SDK 版本发布几分钟后发布，因此刚升级完时，匹配的标签可能还不存在；错误信息会说明这一点，在此期间可以用 CLEARCOTE_DOCKER_IMAGE 指向一个更早的标签。

手动安装（开源版构建）

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

1. 下载

下载最新的 v0.1.0-pre.* 版本——目前是 v0.1.0-pre.23（Chromium 150.0.7871.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-150.0.7871.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）。
  • macOS（Intel 或 Apple 芯片）：使用 launch() 需要已安装并正在运行的 Docker Desktop（SDK 0.40.0+）。
  • Windows 上无需另装 VC++ 可再发行组件——它已捆绑在压缩包中。
  • SDK：Node 20+、Python 3.8+ 或 .NET 8。每个 SDK 都会引入各自的 Playwright 驱动（playwright-core、playwright、Microsoft.Playwright）。
  • 直接使用开源版构建的二进制文件时：沿用你现有的 Playwright 或 Puppeteer 安装即可（Clearcote 替换的是浏览器，而不是驱动）。