Triển khai — Docker & endpoint CDP

Chạy Clearcote như một endpoint CDP thường trực và trỏ bất kỳ framework nào bạn đang dùng vào đó — Playwright, Puppeteer, browser-use, Crawl4AI, Stagehand — mà không cần sửa code. Nó khởi chạy binary trực tiếp (không có --enable-automation), nên navigator.webdriver vẫn là false: kín đáo ngay từ cách thiết kế.

Image Docker chính thức

Pull image về là dùng được ngay. Mọi client CDP đều kết nối qua cổng được mở ra.

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.contexts[0].new_page()                            # the container's own profile
    page.goto("https://example.com")
    print(page.title())

Image được đóng gói sẵn bản build mở cho Linux đã xác minh SHA-256 cùng các font metric-clone của Windows (để chữ Latin có kích thước đo được giống font của persona; bộ font của bản build mở không có font CJK, nên chữ Trung, Nhật và Hàn sẽ hiển thị mà không có font cho đến khi bạn chạy bản build có giấy phép, vốn có kèm các font này), và mặc định dùng một persona Linux native nhất quán. 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). Mọi cấu hình đều thực hiện qua biến môi trường:

docker run -d -p 127.0.0.1:9222:9222 -e CC_PLATFORM=linux -e CC_FINGERPRINT=user-7423 -e CC_ACCEPT_LANGUAGE=en-US -e CC_TIMEZONE=America/New_York teamflatearth/clearcote

Hãy khai báo đúng hệ điều hành mà container đang chạy. Một phần những gì trang web đọc được đến từ hệ điều hành host bên dưới trình duyệt, và không thiết lập persona nào chạm tới được phần đó. Trong image Linux này, chữ được tính kích thước bằng bộ scaler FreeType của Linux và font lấy từ fontconfig, bất kể CC_PLATFORM ghi gì. Đo trên image này với CC_PLATFORM=windows: tăng cỡ chữ từng bước 0.01 px làm thay đổi độ rộng văn bản ở 66% số bước (Chrome thật trên Windows: 99%), còn Segoe UI và Georgia được đo như đã cài nhưng không thể nạp theo tên. Bài kiểm tra fingerprint gắn cờ cả hai điểm này. Persona Linux mặc định thì đạt. Nếu cần danh tính Windows, hãy chạy bản build cho Windows hoặc dùng trình duyệt được lưu trữ sẵn (hosted), vốn chạy trên máy Windows. Điều tương tự cũng áp dụng cho serve() và launch() trên máy chủ Linux. Chi tiết: font stack bên dưới user agent.

Bản build có giấy phép trong Docker — truyền khóa, mount cache

Image có sẵn bản build mở bên trong. Đặt CLEARCOTE_LICENSE_KEY và container sẽ dùng bản build có giấy phép thay thế — bản mới nhất, hoặc với gói Pro là một bản cụ thể qua CC_VERSION. Khóa miễn phí luôn chạy bản build mới nhất, và việc cố định phiên bản sẽ bị từ chối.

docker run -d -p 127.0.0.1:9222:9222 -v clearcote-cache:/opt/xdg-cache -e CLEARCOTE_LICENSE_KEY=cc_lic_... teamflatearth/clearcote

# Pro only: pin a major, an exact build, or a revision
#   -e CC_VERSION=153        -e CC_VERSION=153.0.8010.36        -e CC_VERSION=r28

Luôn mount volume cache. Container có giấy phép sẽ tải engine về ở lần khởi động đầu tiên; nếu không có volume được lưu giữ, mọi container đều phải tải lại. Có volume, các container sau sẽ khởi động từ bản build đã cache.

Log khởi động cho bạn biết mình đang dùng engine nào, nhờ vậy một khóa cấu hình sai sẽ lộ ra ngay, thay vì đến request bị chặn đầu tiên mới biết:

[clearcote] engine: /opt/xdg-cache/clearcote/pro-153.0.8010.36-r28/browser/chrome (licensed)
[clearcote] licence lease acquired

Yêu cầu image được build từ SDK 0.26.1 trở lên, và 0.30.0 trở lên nếu dùng khóa miễn phí từ GitHub — trình duyệt có giấy phép yêu cầu container miễn phí liên tục gia hạn giấy phép trong khi chạy, và sẽ từ chối image cũ hơn. Các image cũ đã phát hành sẽ bỏ qua khóa và lặng lẽ chạy bản build mở — chạy docker pull teamflatearth/clearcote để cập nhật. Một lần chạy có giấy phép cũng phải lấy một concurrency lease (suất chạy đồng thời) lúc khởi động, nên container cần truy cập ra ngoài tới API giấy phép; nếu không lấy được lease, container sẽ thoát kèm lý do thay vì khởi động một engine không thể chạy. Một khóa miễn phí chỉ chạy một trình duyệt tại một thời điểm trên tất cả container của bạn — xem cách tính số trình duyệt có giấy phép.

Bảo mật: endpoint CDP đồng nghĩa với toàn quyền điều khiển trình duyệt. 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. docker/ Dockerfile có thể audit được — hãy tự build lại và xác minh.

Endpoint CDP thường trực từ SDK — serve()

Tự khởi chạy binary và nhận một cdp_url để bất kỳ client nào cũng kết nối vào được. Vẫn là kiểu khởi chạy trực tiếp kín đáo như image, nhưng được điều khiển từ chính tiến trình của bạn.

from clearcote import serve

srv = serve(fingerprint="seed-123", platform="windows")   # -> srv.cdp_url
# attach ANY CDP client:
#   playwright:  p.chromium.connect_over_cdp(srv.cdp_url)
#   puppeteer:   puppeteer.connect({ browserURL: srv.cdp_url, defaultViewport: null })
#   browser-use / Crawl4AI / Stagehand: point them at srv.cdp_url
srv.close()

import { serve } from "clearcote";
const srv = await serve({ fingerprint: "seed-123", platform: "windows" });
// srv.cdpUrl -> connectOverCDP / puppeteer.connect({ browserURL, defaultViewport: null })
await srv.close();

Khi chạy headless, trình duyệt được serve sẽ có một màn hình kích thước thật — của persona, hoặc lấy từ các máy desktop thật — và cửa sổ được căn vừa vùng làm việc trước khi bất kỳ client nào kết nối, nên mọi trang, tab và popup đều báo cáo một cửa sổ vừa với màn hình của nó (SDK 0.31+). Truyền windowSize: { width, height } (window_size trong Python, WindowSize trong .NET) để có cửa sổ nhỏ hơn, hoặc tự đặt --window-size trong args để tự kiểm soát hoàn toàn.

Một endpoint, nhiều danh tính — clearcote serve

Từ shell (gói Python và Node, 0.29+), clearcote serve chạy một endpoint thường trực, khởi động một trình duyệt riêng cho mỗi danh tính mà một kết nối yêu cầu — seed, proxy, múi giờ và ngôn ngữ lấy từ URL kết nối. Cùng một seed sẽ dùng lại trình duyệt đang chạy của seed đó.

clearcote serve --port 9222 --idle-timeout 300 --max-browsers 16

# then, from any Playwright client:
#   chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-1&platform=windows")
#   chromium.connect_over_cdp("http://127.0.0.1:9222?fingerprint=acct-2&proxy=socks5://user:pass@host:1080&geoip=true")
#   (a password-protected proxy needs the licensed build)

Mặc định nó chỉ bind vào localhost và từ chối những request mà một trang web có thể tạo ra. Danh tính nhàn rỗi sẽ bị đóng sau --idle-timeout giây, --max-browsers giới hạn số trình duyệt chạy cùng lúc (các danh tính tiếp theo sẽ nhận HTTP 429), --data-dir giữ profile của từng danh tính qua các lần khởi động lại, còn --allow-host / --allow-origin cho phép chạy sau reverse proxy. Mở http://127.0.0.1:9222/ để xem những gì đang chạy. Với khóa Miễn phí với GitHub, mỗi lúc chỉ chạy được một trình duyệt. Script đơn danh tính cũ clearcote-serve --port 9222 --fingerprint seed-123 vẫn còn trong gói Python.

Trực tiếp — bản build mở, không dùng SDK

Bản build mở trên trang Releases là một binary Chromium thuần mà bạn có thể tự khởi chạy bằng executable_path và các switch. Bản build có giấy phép cần SDK, nơi giữ token giấy phép của nó. Các tham số bổ sung dưới đây là những giá trị mặc định chính mà SDK thêm vào cho seed này trên Windows (SDK còn gộp thêm các feature flag và, khi dùng proxy, tắt QUIC):

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=r"C:\clearcote\chrome.exe",
        ignore_default_args=["--enable-automation", "--enable-unsafe-swiftshader"],
        args=[
            "--fingerprint=seed-123",
            "--fingerprint-platform=windows",
            "--fingerprint-brand=chrome",
            "--accept-lang=en-US,en",
            "--lang=en-US",
            "--timezone=America/New_York",
            "--webrtc-ip-handling-policy=disable_non_proxied_udp",
            "--ignore-gpu-blocklist",
        ],
    )
    browser.new_page().goto("https://example.com")

Tự build image (dùng SDK)

Clearcote có sẵn binary Linux x64, nên chạy headless được trong container. Image cần các thư viện runtime của trình duyệt, fontconfig và SDK. Trình duyệt dùng bộ font đi kèm bản phát hành của nó thay vì font hệ thống; giống như image chính thức, bản build mở không có font CJK (bộ font của bản build có giấy phép thì có). Trên Linux, persona mặc định là một danh tính Linux native nhất quán. Cơ chế chống rò rỉ WebRTC được bật theo mặc định; các API Privacy Sandbox vẫn bật, như trong Google Chrome.

FROM node:22-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
      xz-utils libnss3 libnspr4 libgbm1 libasound2 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
      libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libxfixes3 libxext6 libxrender1 \
      libpango-1.0-0 libcairo2 libx11-6 libxcb1 libexpat1 libdbus-1-3 ca-certificates \
      fontconfig fonts-liberation fonts-noto-color-emoji fonts-unifont fonts-ipafont-gothic fonts-wqy-zenhei \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
RUN npm i clearcote
RUN node --input-type=module -e "import { download } from 'clearcote'; await download();"   # bake the binary in
COPY run.mjs .
CMD ["node", "run.mjs"]

import { launchPersistentContext } from "clearcote";
const ctx = await launchPersistentContext("/tmp/prof", {
  headless: true,
  fingerprint: "user-1",
  proxy: { server: "http://gateway:8080", username: "u", password: "p" },
  geoip: true,      // timezone + languages + WebRTC IP matched to the proxy exit
  humanize: true,   // trusted bezier input; navigator.webdriver stays false
  args: ["--no-sandbox"],
});
const page = ctx.pages()[0] ?? (await ctx.newPage());
await page.goto("https://example.com");
await ctx.close();

Chạy container với --shm-size=1g để tránh crash do /dev/shm trên các trang nặng. Với Python thì y hệt (from clearcote import launch_persistent_context, các tùy chọn dạng snake_case).

Những gì kết nối được qua CDP

Muốn để một AI agent điều khiển thay bạn? Xem MCP server. Tò mò vì sao khởi chạy trực tiếp lại kín đáo hơn? Xem Cơ chế phát hiện hoạt động ra sao.