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. Không có bản build native cho macOS: trên macOS, launch() tự chạy image Docker của Clearcote cho bạn (SDK 0.40.0+, 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                 # 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

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.

macOS

Không có bản build native cho macOS. Từ SDK 0.40.0, launch() trên macOS sẽ 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.23 (Chromium 150.0.7871.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-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. 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.

docker run -d --rm -p 127.0.0.1:9222:9222 -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.

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 (Intel hoặc Apple silicon): 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).