Cài đặt

Cài SDK và để nó tự tải về một trình duyệt đã được xác minh — hoặc tự tải và xác minh một bản build.

Clearcote đang được phát triển tích cực. Hiện đã có bản build cho Windows x64 và Linux x64 — SDK sẽ tải đúng bản cho hệ điều hành của bạn. macOS đã có trong lộ trình; trong thời gian chờ, người dùng macOS có thể chạy image Docker. Trên một máy Linux tối giản, hãy cài các thư viện runtime của trình duyệt (libnss3 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libpango-1.0-0 …) — clearcote info sẽ liệt kê những thư viện còn thiếu. Nếu bạn tự chạy binary bằng quyền root (thường gặp trong container), hãy truyền --no-sandbox; SDK và clearcote serve đã tự lo việc này.

MớiBản build mới nhất miễn phí với GitHub cho một trình duyệt. Không cần thẻ.

Nhận miễn phí

Cài SDK (khuyến nghị)

bash

npm i clearcote                # Node 20+
pip install clearcote          # Python 3.8+
dotnet add package Clearcote   # .NET 8

Lần gọi launch() đầu tiên sẽ tải trình duyệt cho hệ điều hành của bạn, kiểm tra SHA-256 và lưu vào cache. Bạn không cần chạy playwright install — mỗi SDK tự mang theo Playwright driver và tự tải trình duyệt của riêng nó. Bạn nhận được bản build nào tùy thuộc vào việc đã đặt khóa giấy phép hay chưa:

	Bản build	Tải từ đâu
Không có khóa	Bản build mở — Chromium 149.0.7827.114 (v0.1.0-pre.22). BSD-3, tái lập được từ mã nguồn công khai.	GitHub Releases, cố định theo phiên bản SDK
Có khóa	Bản build có giấy phép — Chromium 153.0.8010.36-r28. Miễn phí với GitHub cho một trình duyệt tại một thời điểm, hoặc Pro.	clearcotelabs.com, luôn là bản build hiện hành ở mỗi lần khởi chạy

Đặt khóa giấy phép

SDK tìm khóa theo thứ tự sau: tùy chọn khởi chạy licenseKey / license_key / LicenseKey, sau đó là biến môi trường CLEARCOTE_LICENSE_KEY, rồi đến ~/.clearcote/license.key — tệp do clearcote login ghi ra. Mọi SDK, kể cả .NET, đều đọc tệp này. Lấy khóa miễn phí trong mục “Licenses” của dashboard.

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

Lệnh clearcote

Gói Python và gói Node sẽ cài lệnh clearcote (nếu cài npm cục bộ trong project, hãy chạy bằng npx clearcote …). Gói .NET không kèm lệnh này.

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 hoặc --channel preview sẽ chọn một bản build cụ thể; xem chọn bản build. Tiếp theo, hãy tích hợp vào Playwright hoặc Puppeteer.

Cài đặt thủ công (bản build mở)

Muốn dùng binary trần? GitHub Releases có sẵn bản build mở. Bản build có giấy phép không được phát hành ở đó: nó chạy qua SDK, clearcote serve hoặc image Docker, và sẽ không khởi động nếu thiếu run token do SDK cung cấp.

1. Tải về

Tải bản phát hành v0.1.0-pre.* mới nhất — hiện tại là v0.1.0-pre.22 (Chromium 149.0.7827.114). Mỗi bản phát hành gồm:

clearcote-<version>-windows-x64.zip — bản build cho Windows (Chromium + runtime + các DLL VC++)
clearcote-<version>-linux-x64.tar.xz — bản build cho Linux
Các tệp .sha256 và SHA256SUMS.txt — checksum
Các tệp .asc + clearcote-signing-key.asc — chữ ký GPG dạng tách rời (detached) và public key

2. Xác minh (khuyến nghị)

Bản build mở được xây dựng sao cho bạn không cần phải tin chúng tôi. Trước khi giải nén, hãy xác nhận tệp tải về đúng y như những gì đã được build và ký — xem Xác minh.

3. Giải nén

Archive cho Windows là gói tự chứa: các DLL runtime VC++ 2015–2022 đã được đóng gói sẵn, nên chạy được trên một máy Windows 10/11 mới cài. Archive cho Linux cần các thư viện runtime đã liệt kê ở trên.

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. Chạy thử nhanh (smoke test)

Khởi chạy với một seed và mở một trang kiểm tra fingerprint:

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

Cùng seed --fingerprint ⇒ cùng một danh tính ở mọi lần khởi chạy; seed mới ⇒ một danh tính mới. Để báo cáo các giá trị thu được từ một máy thật thay vì các giá trị suy ra từ seed, hãy import một profile đã thu thập — xem Các flag fingerprint. Sau đó tích hợp vào Playwright hoặc Puppeteer.

Chạy trong Docker

Image chính thức chạy Clearcote dưới dạng một endpoint CDP — chỉ cần pull về rồi trỏ bất kỳ client Playwright, Puppeteer hay browser-use nào vào đó qua Chrome DevTools Protocol, không phải sửa code.

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")

Cấu hình persona bằng biến môi trường — CC_PLATFORM (windows/linux/macos/android), CC_FINGERPRINT (seed), CC_BRAND (Edge…), CC_ACCEPT_LANGUAGE, CC_TIMEZONE, CC_TLS_PROFILE. Hãy đặt CC_FINGERPRINT riêng cho từng danh tính: nếu không, mọi container sẽ dùng chung một seed mặc định. Image đi kèm bản build mở; thêm -e CLEARCOTE_LICENSE_KEY=cc_lic_… -v clearcote-cache:/opt/xdg-cache để chạy bản build có giấy phép mới nhất, chỉ tải một lần vào volume. Trình duyệt chạy headed trên một màn hình ảo (CC_HEADLESS=1 nếu muốn headless thuần), và image dành cho linux/amd64. Dockerfile có thể audit được — bạn có thể tự build lại. Endpoint CDP đồng nghĩa với toàn quyền điều khiển trình duyệt, vì vậy chỉ công khai nó trong mạng tin cậy (-p 127.0.0.1:9222:9222 giữ nó chỉ truy cập được từ máy host). Xem thêm ở Triển khai.

Yêu cầu

Windows 10 / 11 x64, hoặc Linux x64 (glibc) với các thư viện runtime nêu ở trên.
Trên Windows không cần cài riêng VC++ redistributable — nó đã được đóng gói sẵn trong archive.
SDK: Node 20+, Python 3.8+ hoặc .NET 8. Mỗi SDK tự kéo theo Playwright driver của riêng nó (playwright-core, playwright, Microsoft.Playwright).
Dùng trực tiếp binary của bản build mở: dùng bản Playwright hoặc Puppeteer bạn đã cài sẵn (Clearcote thay thế trình duyệt, không thay driver).