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. Trên máy Mac Apple Silicon, trình duyệt chạy native (bản build có giấy phép ở dạng preview, hoặc bản build mở 150 khi không có khóa giấy phép); trên máy Mac Intel, launch() tự chạy image Docker của Clearcote cho bạn (xem macOS). 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.

Cài SDK (khuyến nghị)

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:

Đặ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.

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

Đăng nhập từ một thiết bị khác

clearcote login --device (SDK 0.40.0+, Python và Node; npx clearcote login --device nếu cài npm cục bộ) lưu khóa mà bạn không cần tự sao chép. Lệnh này in ra một link và một mã ngắn. Hãy mở link trong trình duyệt trên bất kỳ thiết bị nào bạn có thể đăng nhập vào clearcotelabs.com, kiểm tra trang hiển thị đúng mã giống trong terminal, đánh dấu vào ô xác nhận terminal đó là của bạn, rồi phê duyệt. Trang sẽ báo thiết bị đã được đăng nhập, còn terminal in ra Signed in as kèm địa chỉ email của tài khoản (được che một phần), nơi đã lưu khóa, cùng gói và ngày hết hạn. Bản thân khóa không bao giờ được in ra, dù trên trang hay trong terminal.

Mỗi mã có hiệu lực 10 phút; sau đó, hãy chạy lại lệnh để lấy mã mới. Nhấn Ctrl-C trong lúc lệnh đang chờ thì không có gì được lưu, và nhấn Ctrl-C lần thứ hai sẽ dừng ngay. Hãy dùng --device trên một server bạn truy cập qua SSH, trong một container, hoặc khi một coding agent cài đặt Clearcote giúp bạn: việc phê duyệt diễn ra trong chính trình duyệt của bạn và không có thông tin bí mật nào đi qua terminal, lịch sử của terminal hay một cuộc chat. Khi đã có sẵn khóa trên máy của mình, clearcote login cũng tốt không kém: từ 0.40.0, lệnh này đọc khóa mà không hiển thị nó.

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.

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

Mọi lệnh đều nhận --help. Từ SDK 0.40.0, clearcote info kiểm tra bản build mà launch() sẽ chạy, kể cả bản do CLEARCOTE_BROWSER_VERSION chỉ định, và cho biết khi nào khóa hết hạn nếu khóa được lưu bằng clearcote login --device (dịch vụ giấy phép không báo ngày hết hạn của khóa được dán vào). Từ 0.41.0, trên Linux lệnh này còn cho biết các font mà một lần khởi chạy sẽ thấy có thể hiển thị những hệ chữ viết nào (xem font của riêng bạn trên Linux). clearcote install --version 154 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.

Từ 0.56.0, clearcote info bắt đầu bằng thông tin về chính máy (bộ xử lý, bộ nhớ, hệ điều hành, máy ảo hay container, và có card đồ họa mà trình duyệt dùng để vẽ được hay không). clearcote bench khởi chạy --concurrency trình duyệt (mặc định 3), tải --url trong --duration giây (mặc định 30), qua --proxy nếu có, rồi báo mỗi trình duyệt tốn bao nhiêu luồng CPU và RAM trên máy này, thời gian tải trang, lỗi, máy chạy được khoảng bao nhiêu trình duyệt cùng lúc và nên thay đổi gì. Khi bộ nhớ trống có vẻ quá ít, nó chạy ít trình duyệt hơn (--force chạy tất cả), và mỗi trình duyệt chiếm một suất giấy phép trong khi chạy. Hãy dán kết quả vào yêu cầu hỗ trợ. Trong .NET, ClearcoteBench.RunAsync và ClearcoteHost.Info trả về cùng báo cáo đó từ mã.

Từ 0.61.0, clearcote connect chạy Clearcote Helper ngay trong terminal đó, để bản web của Profile Manager tại app.clearcotelabs.com có thể mở các profile của bạn trên máy tính này. Trong cửa sổ Connect, chọn I use the Clearcote SDK rồi chạy lệnh được hiển thị kèm mã dùng một lần (npx clearcote connect 4F7-K2Q): tab đó tự kết nối, không cần trang phê duyệt. Lần chạy đầu tiên, SDK tải bản phát hành Helper mà nó ghim và kiểm tra SHA-256. Hãy để terminal mở; Ctrl+C sẽ đóng Helper và các trình duyệt của nó.

macOS

Trên máy Mac Apple Silicon (M1 trở lên, macOS 13 trở lên) có khóa giấy phép, SDK (0.51.1+) tải bản build macOS có giấy phép và khởi động nó native, như trên Windows và Linux. Đây là bản preview, và có thể đi sau Windows và Linux: hiện tại nó là 155.0.8059.39-r49 trong khi hai nền tảng kia chạy 156.0.8078.47-r57. Khi không có khóa giấy phép, SDK (0.68.4+) tải bản build mở 150 cho Apple Silicon (v0.1.0-pre.24, đi sau các bản build mở cho Windows và Linux một phiên bản Chromium) và cũng khởi động nó native.

Trên máy Mac Intel (và với SDK 0.40.0 đến 0.68.3, trên mọi máy Mac không có khóa giấy phép), launch() khởi động image Docker của Clearcote (teamflatearth/clearcote:sdk-<SDK version>, một image linux/amd64 mà Docker Desktop chạy được trên cả Intel lẫn Apple silicon), kết nối vào đó và trả về cùng một browser Playwright như khi khởi chạy cục bộ. Code của bạn giữ nguyên, và close() sẽ dừng rồi xóa container. Điều này áp dụng cho launch() trong Python (sync và async), Node và .NET (LaunchAsync); các entry point khác, như persistent context và serve(), vẫn cần một binary Clearcote, nên trên máy Mac hãy chạy chúng trực tiếp trong image 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 phải được cài đặt và đang chạy. Nếu không, launch() sẽ báo lỗi DockerUnavailableError (.NET: DockerUnavailableException) kèm hướng dẫn cần làm gì. Lần khởi chạy đầu tiên sẽ tải image, và nếu có khóa giấy phép thì tải cả bản build mới nhất, chỉ một lần, vào volume clearcote-cache; những lần khởi chạy sau sẽ khởi động trong vài giây.
• Những gì được chuyển vào container: các tùy chọn persona, headless, proxy, args, version và khóa giấy phép (được tìm như trên mọi máy khác, kể cả khóa mà clearcote login đã lưu). Tùy chọn nào container không nhận được sẽ bị từ chối, có nêu rõ tên. Khóa và proxy được đưa vào container dưới dạng một tệp mà container đọc một lần rồi xóa, nên docker inspect không hiển thị chúng, và một lần khởi chạy có khóa hoặc proxy sẽ bị từ chối nếu container không chạy bản build có giấy phép hoặc không chạy qua proxy đó.
• Không để lại gì đang chạy. Nếu chương trình của bạn thoát hoặc bị kill mà không gọi close(), container của nó sẽ tự dừng khoảng 30 giây sau khi không còn gì kết nối tới, và lần khởi chạy tiếp theo sẽ xóa những container còn sót lại mà chương trình của chúng không còn nữa. Container thuộc về các chương trình khác đang chạy, người dùng khác hoặc máy khác thì không bao giờ bị động đến. Từ SDK 0.41.0, close() chỉ trả về khi Docker đã xóa container và volume của nó, nên sau đó docker ps -a không còn liệt kê container này nữa.
• Chrome giữ nguyên sandbox (SDK 0.41.0+ với image từ sdk-0.41.0): lần khởi chạy truyền seccomp profile của image, nên Chrome chạy với sandbox của nó bên trong container (xem sandbox của Chrome). Điều này cần Docker trên CPU x86_64; trên Apple silicon, image chạy ở chế độ giả lập và sandbox tạm thời vẫn tắt.
• Container chạy Linux, nên persona mặc định của nó là persona Linux. Hãy đọc Triển khai trước khi khai báo một nền tảng khác từ container.

Image được phát hành vài phút sau bản phát hành SDK tương ứng, nên ngay sau khi nâng cấp, tag khớp phiên bản có thể chưa tồn tại; thông báo lỗi sẽ nói rõ điều đó, và trong lúc chờ, CLEARCOTE_DOCKER_IMAGE có thể trỏ tới một tag cũ hơn.

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.25 (Chromium 151.0.7922.108). 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-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. 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.

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

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. Nếu không có CC_FINGERPRINT, mỗi container sẽ nhận một seed ngẫu nhiên riêng, được giữ nguyên qua các lần khởi động lại; hãy đặt biến này để chọn hoặc dùng lại một danh tí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.

Giới hạn tải xuống

Lượt tải bản dựng có giấy phép bị giới hạn theo từng giấy phép, để một cấu hình tải lại toàn bộ gói mỗi lần khởi động không vượt tầm kiểm soát. Lần khởi chạy tìm thấy bản dựng trong cache sẽ không tải gì và không bao giờ bị tính — chỉ lượt tải thật mới được tính.

Khi vượt giới hạn, SDK nhận HTTP 429 kèm nội dung JSON — code là DOWNLOAD_RATE_LIMITED (hạn mức theo bản dựng) hoặc DOWNLOAD_LIMIT_EXCEEDED (gói miễn phí) — và header Retry-After: số giây cho đến khi giới hạn được đặt lại. Các lần khởi chạy có bản dựng đã nằm trong cache vẫn chạy bình thường. Từ SDK 0.62.0, một lần khởi chạy không tải được bản dựng mới sẽ mở bản dựng mới nhất cùng phiên bản Chromium đã có trong cache thay vì báo lỗi, và chờ hết Retry-After rồi mới thử tải lại. Một lần khởi chạy được ghim vào một revision cụ thể (r50) vẫn nhận đúng bản dựng đó hoặc một lỗi.

Bạn gặp các giới hạn này khi nhiều máy hoặc container mới khởi động cùng lúc, mỗi cái với cache trống. Hãy tải mỗi bản dựng một lần cho mỗi máy thay vì mỗi lần khởi động — khởi động cũng nhanh hơn, không phải tải khoảng 460 MB:

• Đặt cache trên một volume. Trỏ CLEARCOTE_CACHE tới một thư mục còn lại sau khi khởi động lại. Các lần khởi động dùng chung sẽ chờ lượt tải đầu tiên rồi dùng lại nó.
• Đưa trình duyệt vào image. Chạy clearcote install lúc build, để mọi container khởi động với bản dựng có sẵn. Build lại image khi nâng cấp.

# 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

Giới hạn persona

Mỗi lần khởi chạy lấy persona của nó (fingerprint mà seed và các tùy chọn mô tả) từ persona service. Mỗi giấy phép có thể lấy một số lượng persona khác nhau nhất định mỗi ngày. Lấy lại một persona bạn đã dùng trong ngày không tốn gì, nên một bộ profile cố định có thể khởi chạy lại bao nhiêu lần tùy ý.

Một persona là một seed với một bộ tùy chọn fingerprint (thương hiệu, nền tảng, v.v.), nên cùng một seed dưới dạng Chrome và dưới dạng Edge được tính hai lần. Số đếm được đặt lại lúc 00:00 UTC. Khi vượt giới hạn, lần khởi chạy thất bại với HTTP 429 từ persona service (daily persona quota reached) cho đến lúc đặt lại.

Bạn gặp giới hạn này khi mỗi lần khởi chạy dùng một seed ngẫu nhiên hoàn toàn mới. Thay vào đó, hãy dùng lại một nhóm seed cố định, ví dụ một danh sách vài trăm cái tên mà bạn xoay vòng: mỗi seed giữ cùng một fingerprint mỗi lần khởi động, và khởi chạy lại nó không bao giờ bị tính thêm.

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.
• macOS: trên Apple Silicon (macOS 13+), không cần gì thêm (SDK 0.51.1+ khi có khóa giấy phép, 0.68.4+ khi không có). Trên máy Mac Intel, cần Docker Desktop đang chạy để dùng launch() (SDK 0.40.0+).
• 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).