安装

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

Clearcote 仍在积极开发中。目前提供 Windows x64 和 Linux x64 构建——SDK 会下载与你的操作系统对应的那一个。在 Apple Silicon Mac 上，浏览器原生运行（授权版构建以预览版形式运行，没有许可证密钥时则运行开源 150 构建）；在 Intel Mac 上，launch() 会替你运行 Clearcote Docker 镜像（参见 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 会替你处理这一点。

安装 SDK（推荐）

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 驱动，并自行获取浏览器。你拿到的是哪个构建，取决于是否设置了许可证密钥：

设置许可证密钥

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

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 包不包含这个命令。

clearcote install              # download + verify the browser now (CI, Docker builds)
clearcote info                 # this machine, 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 bench --proxy <url>  # what each browser costs here in CPU and RAM, page timings, how many fit at once
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 connect [code]       # start the helper for the web Profile Manager — see below

每个命令都支持 --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。

从 0.56.0 起，clearcote info 会先显示机器本身的情况（处理器、内存、操作系统、是否为虚拟机或容器，以及是否有浏览器可以用来绘制的显卡）。clearcote bench 会启动 --concurrency 个浏览器（默认 3 个），反复加载 --url，持续 --duration 秒（默认 30 秒），如果给了 --proxy 就通过该代理，然后报告每个浏览器在这台机器上占用多少 CPU 线程和内存、页面加载时间、错误、这台机器大约能同时运行多少个浏览器，以及应该改什么。可用内存看起来不够时，它会少启动一些浏览器（--force 会全部启动），每个浏览器运行期间占用一个许可证席位。把输出贴到支持请求里即可。在 .NET 中，ClearcoteBench.RunAsync 和 ClearcoteHost.Info 可以在代码里得到同样的报告。

从 0.61.0 起，clearcote connect 会在该终端中启动 Clearcote Helper，让 app.clearcotelabs.com 上的网页版 Profile Manager能在这台电脑上启动你的配置文件。在它的 Connect 窗口中选择 I use the Clearcote SDK，运行显示的带一次性代码的命令（npx clearcote connect 4F7-K2Q）， 该标签页就会自动连接，无需确认页面。首次运行时，SDK 会下载它固定的 Helper 版本并校验 SHA-256。请保持终端开启；按 Ctrl+C 会关闭 Helper 及其浏览器。

macOS

在 Apple Silicon Mac（M1 或更新，macOS 13 或更高版本）上，有许可证密钥时，SDK（0.51.1+）会下载授权版 macOS 构建并原生启动它，与 Windows 和 Linux 上一样。它是预览版，可能落后于 Windows 和 Linux：目前它是 155.0.8059.39-r49，而它们运行的是 156.0.8078.47-r57。没有许可证密钥时，SDK（0.68.4+）会下载面向 Apple Silicon 的开源 150 构建（v0.1.0-pre.24，比开源的 Windows 和 Linux 构建落后一个 Chromium 版本），并同样原生启动它。

在 Intel Mac 上（以及使用 SDK 0.40.0 至 0.68.3 时，在任何没有许可证密钥的 Mac 上），launch() 会启动 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 身份画像。要在容器中声明其他平台，请先阅读部署。

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

手动安装（开源版构建）

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

1. 下载

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

• 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 分离签名及公钥

2. 校验（推荐）

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

3. 解压

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

Expand-Archive clearcote-151.0.7922.108-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 连接它即可，无需改代码。

# Chrome's sandbox profile, shipped in the image
docker run --rm --tmpfs /opt/xdg-cache --entrypoint cat teamflatearth/clearcote /etc/clearcote/seccomp.json > clearcote-seccomp.json
docker run -d --rm --shm-size=1g -p 127.0.0.1:9222:9222 --security-opt seccomp=clearcote-seccomp.json -e CC_FINGERPRINT=user-7423 teamflatearth/clearcote   # CDP on http://localhost:9222

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 可将其限制在本机）。更多内容参见部署。

下载限制

授权版构建的下载按许可证限速，避免每次启动都下载完整压缩包的配置失控。在缓存中找到构建的启动不会下载任何 内容，也从不计数——只有真正的下载才计数。

超出限制时，SDK 会收到带 JSON 正文的 HTTP 429——code 为 DOWNLOAD_RATE_LIMITED（按构建的额度）或 DOWNLOAD_LIMIT_EXCEEDED（免费套餐）——以及 Retry-After 头，表示距离限额重置还有多少秒。构建已在缓存中的启动不受影响。从 SDK 0.62.0 起，无法下载新构建的启动不会失败，而是启动缓存中同一 Chromium 版本的最新构建，并等到Retry-After 之后才重试该下载。固定到某个确切修订版（r50）的启动仍只会得到该构建或报错。

当许多全新的机器或容器同时启动、且各自缓存为空时，就会触及这些限制。每台机器只下载一次每个构建，而不是每次 启动都下载——这样启动也更快，省去约 460 MB 的下载：

• 把缓存放在卷上。将 CLEARCOTE_CACHE 指向重启后仍保留的目录。共享它的启动会 等待第一次下载完成并复用它。
• 把浏览器打包进镜像。在构建镜像时运行 clearcote install，让每个容器启动时 构建已就位。升级时重新构建镜像。

# 1. a shared, persistent cache
docker run -v clearcote-cache:/clearcote-cache -e CLEARCOTE_CACHE=/clearcote-cache …

# 2. or in your Dockerfile: download once while the image is built (the key stays out of the layers)
ENV CLEARCOTE_CACHE=/opt/clearcote-cache
RUN --mount=type=secret,id=clearcote_key \
    CLEARCOTE_LICENSE_KEY="$(cat /run/secrets/clearcote_key)" clearcote install

身份画像限制

每次启动都会从身份画像服务获取它的身份画像（即种子和选项所描述的指纹）。每个许可证每天可以获取一定数量的不同身份画像。获取今天已经用过的身份画像不计数，因此一组固定的配置文件可以随意重复启动。

一个身份画像就是一个种子加一组指纹选项（品牌、平台等），因此同一个种子分别作为 Chrome 和 Edge 会计为两个。计数在 UTC 00:00 重置。超出限制后，启动会失败，身份画像服务返回 HTTP 429（daily persona quota reached），直到重置为止。

如果每次启动都使用一个全新的随机种子，就会碰到这个限制。请改为复用一组固定的种子，例如轮流使用一份几百个名字的列表：每个种子每次启动都保持同一个指纹，重复启动也不会再次计数。

系统要求

• Windows 10 / 11 x64，或装有上述运行时库的 Linux x64（glibc）。
• macOS：在 Apple Silicon（macOS 13+）上无需额外安装（有许可证密钥时 SDK 0.51.1+，没有时 0.68.4+）。在 Intel Mac 上，使用 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 替换的是浏览器，而不是驱动）。