Chuyển đến nội dung

Tùy chọn khởi chạy

Các tùy chọn khởi chạy chưa được đề cập ở những trang khác: extension, Privacy Sandbox và phần còn lại của danh sách.

Các tùy chọn khởi chạy khác

  • extensions — danh sách đường dẫn tới thư mục của các extension dạng unpacked (sinh ra --load-extension + --disable-extensions-except).
  • disablePrivacySandbox / disable_privacy_sandbox — đặt true để tắt các API Privacy Sandbox (Topics, FLEDGE / Protected Audience, Shared Storage, Private Aggregation, Fenced Frames). Tùy chọn này mặc định tắt từ 0.23: persona mặc định thể hiện là Google Chrome, vốn có sẵn tất cả các API đó. Chỉ bật khi persona là Chromium đã loại bỏ Google. WebUSB không bị ảnh hưởng.
  • agentTyping / agent_typing — nhịp gõ phím của agent (human là mặc định / fast / instant). Xem Agent.
  • tlsProfile — giữ TLS ClientHello nhất quán với phiên bản Chrome mà persona khai báo, để lớp mạng khớp với UA (chứ không dùng TLS gốc của bản build). Mặc định, "match-persona" đi theo brandVersion; "native" giữ nguyên không đổi; "chrome-<major>" cố định một major. Xem Các flag fingerprint.
  • platform: "android" — một persona di động ở mức best-effort (cảm ứng, con trỏ coarse, màn hình/DPR di động, WebGL Mali/Adreno, viewport điện thoại). Trên engine desktop, phần render GPU vẫn là của desktop — hãy kết hợp với canvas bridge để render nhất quán.
  • storageQuota, fingerprintProfile, canvasBridge, webrtcIp, acceptLanguage, disableGpuFingerprint, fingerprintNoise — xem Các flag fingerprint.

Tùy chọn mới hơn (bản build có giấy phép)

Các tùy chọn này cần bản build có giấy phép (Miễn phí với GitHub hoặc Pro). Revision engine mà mỗi tùy chọn yêu cầu được ghi trong ngoặc vuông; trên engine cũ hơn, SDK bỏ qua các tùy chọn 152 r22 kèm cảnh báo, kiểm tra engine với từng tùy chọn 154 r32 và để tắt tùy chọn đó khi bản build không có, còn engine thì bỏ qua những tùy chọn còn lại.

  • stockRuntime / stock_runtime / StockRuntime (hoặc CLEARCOTE_STOCK_RUNTIME=1) — trả lại cho Playwright hành vi DevTools gốc cho một lần chạy debug: các sự kiện console và page-error, page.setContent(), và exposeFunction() sau khi điều hướng. Mặc định tắt, vì trang có thể quan sát thấy nó; engine không có switch này sẽ khởi chạy mà không có nó và SDK cảnh báo một lần. Chỉ áp dụng cho khởi chạy local và Docker. Xem Sự kiện và gỡ lỗi. [154 r32; SDK 0.41.0]
  • personaEnv / persona_env / PersonaEnv — bật theo mặc định từ SDK 0.41.0. Các switch persona (seed, mọi giá trị ghi đè persona, thông tin đăng nhập proxy và token canvas-bridge) đến trình duyệt qua biến môi trường của nó thay vì qua dòng lệnh, thứ mà bất kỳ người dùng local nào cũng đọc được trong danh sách tiến trình (/proc/<pid>/cmdline trên Linux, phần chi tiết tiến trình trên Windows). Engine cũng giữ chúng ngoài dòng lệnh của các tiến trình phụ (helper process) của nó. false hoặc CLEARCOTE_PERSONA_ENV=0 giữ chúng trên dòng lệnh, chẳng hạn cho một công cụ của bạn đọc chúng từ đó. Image Docker cũng làm như vậy với trình duyệt của container. [154 r32]
  • Persona token — trên bản dựng Chromium 156 có giấy phép (từ r51), ở mỗi lần khởi chạy SDK lấy một persona đã ký cho seed hoặc hồ sơ của bạn từ dịch vụ persona của Clearcote và chuyển cho trình duyệt cùng các switch ở trên. Không có tùy chọn tắt; không có nó trình duyệt không khởi động. Cần SDK 0.63.0, Profile Manager 0.27.0 hoặc ảnh Docker tương ứng. [156 r51; SDK 0.63.0]
  • Sáng hoặc tối — từ 154 r32, persona quyết định color scheme (khoảng một phần ba số profile ưu tiên nền tối), và CSS, matchMedia, request header Sec-CH-Prefers-Color-Scheme cùng các màu hệ thống đều đi theo nó. Playwright giả lập nền sáng trong mọi context mà nó tạo ra, điều mà một persona tối sẽ mâu thuẫn, nên từ SDK 0.41.0, trên bản build như vậy, các context mà một lần khởi chạy local tạo ra sẽ để nguyên color scheme. Truyền colorScheme / color_scheme / ColorScheme nếu vẫn muốn giả lập một chế độ, hoặc --fingerprint-color-scheme=light|dark trong args để chính persona là sáng hoặc tối. Bản build cũ hơn giữ mặc định của Playwright. [154 r32]
  • allowThirdPartyCookies / allow_third_party_cookies — cookie bên thứ ba, được cho phép theo mặc định như Chrome gốc (SDK 0.45.0+); false sẽ chặn chúng. Các frame đăng nhập nhúng, thanh toán và challenge dựa vào chúng. Các bản build trước 152 r22 luôn chặn chúng. [152 r22]
  • transparentProxy / transparent_proxy — ẩn proxy khỏi header của request và thời gian kết nối (request HTTP thường không mang header proxy nào; kết nối qua proxy báo thời gian như một kết nối được tái sử dụng). Cần có proxy. [152 r22]
  • fingerprintVoices: false / fingerprint_voices=False — giữ các giọng đọc (speech voice) của chính máy này thay vì danh sách của persona. [152 r22]
  • fingerprint: "off" — khởi chạy hoàn toàn không có persona, để khắc phục sự cố. [152 r22]
  • socks5Udp / socks5_udp — truyền UDP của WebRTC qua một proxy socks5://, để voice, video và kết nối peer hoạt động mà vẫn đi ra từ địa chỉ của proxy. Proxy phải cho phép điều này; nhiều pool proxy dân cư không cho phép. [151 r17]
  • portableProfile / encryptionKey — profile có thể sao chép giữa các máy (xem ở trên). [151 r14; Python, Node & .NET (0.58.0+)]
  • personaSchema / persona_schema — mô hình danh tính dùng để sinh danh tính từ seed. Để trống để dùng mô hình hiện tại, 7 (được phục vụ từ 2026-10-26, r52): card đồ họa quyết định loại máy (laptop hay desktop), bộ xử lý, số luồng, bộ nhớ và màn hình của nó, mỗi thứ phổ biến đúng như trong lưu lượng trình duyệt thực tế. 5 sinh ra chính xác những gì r45 đến r51 đã sinh, 4 những gì 154 r37 đến 155 r44, 3 những gì 154 r36 và 2 những gì 153 r29 đến 154 r35 đã sinh; hãy đặt một giá trị để giữ các danh tính đã tạo trên những bản build đó. 1 là mô hình ban đầu từ trước r29. Không có 6. Mọi SDK chấp nhận 5 và 7 từ 0.64.1. Xem cùng một seed trên các máy khác nhau. Chỉ thêm realGpuHost / real_gpu_host trên máy có card đồ họa thật. [151 r19; Python, Node & .NET]
  • shaderDialect: "hlsl" — bật theo mặc định cho persona Windows trên máy host Linux hoặc macOS kể từ SDK 0.39.0; false sẽ tắt nó. Xem Shader dialect. [151 r15]
  • profile: "auto" — khởi chạy bằng một fingerprint thật đã thu thập, được chọn cho máy này, thay vì dùng seed; tinh chỉnh bằng profileSelect / profile_select. Python, Node & .NET (LocalProfile = "auto", 0.58.0+). Trong Node, tùy chọn này hoạt động với launch() mặc định, launchPersistentContext() và serve() từ SDK 0.31.1; bản 0.31.0 trở về trước cần ephemeralProfile: false và lỗi với serve().

Không phụ thuộc vào bản build engine:

  • version / releaseChannel — chọn bản build; xem chọn bản build.
  • licenseKey / license_key / LicenseKey — khóa giấy phép, nếu khóa không nằm trong CLEARCOTE_LICENSE_KEY hoặc ~/.clearcote/license.key.
  • licenseThroughProxy / license_through_proxy (hoặc CLEARCOTE_LICENSE_THROUGH_PROXY=1) — gửi các lệnh gọi cấp phép qua proxy của lần khởi chạy thay vì gửi từ máy này.
  • ephemeralProfile / userDataDir trên launch() — xem ghi chú trong phần Dùng SDK ở trên.
  • widevine: true — phát nội dung có DRM (cả hai bản build); xem Widevine & DRM.
  • quiet — tắt các cảnh báo và thông tin tiến trình của SDK khi khởi chạy.
  • fontDirs / font_dirs / FontDirs — font của riêng bạn trên Linux; xem bên dưới.

Font của riêng bạn trên Linux (fontDirs)

Trên Linux, trình duyệt chỉ thấy các font mà SDK trỏ nó tới: bộ font đi kèm bản phát hành, gồm các font thay thế tương thích metric với Windows (Arial→Arimo, Segoe UI→Selawik, Times New Roman→Tinos, …). Không font nào được cài trên host đến được trình duyệt, nên không thứ gì trên máy có thể làm thay đổi những gì trang đo được. Từ SDK 0.41.0 (Python, Node và .NET; launch(), persistent context và serve()), có hai thiết lập để thêm thư mục:

  • fontDirs / font_dirs / FontDirs, hoặc CLEARCOTE_FONT_DIRS — font của riêng bạn, thường là bản sao thư mục C:\Windows\Fonts của một máy Windows, được liệt kê trước bộ font đi kèm. Trên bản build có giấy phép từ 154 r32, mọi họ font mà chúng cung cấp đều được render đúng là chính nó, dưới tên riêng của nó, thay vì bằng font thay thế, và các tên đại diện cho họ font đó trên Windows cũng đi theo: Helvetica, Times và Courier, cùng các họ generic của CSS (sans-serif → Arial, serif → Times New Roman, monospace → Consolas, system-ui → Segoe UI). Engine cũ hơn vẫn vẽ font thay thế cho các họ font mà persona liệt kê, và chỉ dùng các thư mục này cho những ký tự không font nào khác hỗ trợ. Một đường dẫn không phải thư mục sẽ khiến lần khởi chạy thất bại ngay lập tức, trước khi chiếm một slot giấy phép.
  • CLEARCOTE_FALLBACK_FONT_DIRS — các font chỉ dùng cho những ký tự không font nào khác hỗ trợ (CJK, chữ viết Ấn Độ, emoji, …), được liệt kê sau bộ font đi kèm. Chúng không thay thế họ font nào. Image Docker đặt biến này thành các font chữ viết mà image đi kèm.
from clearcote import launch

# a copy of a Windows machine's C:\Windows\Fonts, on the Linux host
browser = launch(fingerprint="acct-1", platform="windows", font_dirs=["/srv/windows-fonts"])
# or: CLEARCOTE_FONT_DIRS=/srv/windows-fonts (several directories: separate them with ":")
  • Cả hai biến đều là danh sách phân tách bằng :. Tên họ font được đọc từ chính các tệp font, nên không cần công cụ fontconfig nào. Đừng bao giờ trỏ biến nào trong hai biến này vào toàn bộ /usr/share/fonts: khi đó các họ font Latin của host sẽ cạnh tranh với bộ font đi kèm và làm thay đổi độ rộng mà persona Windows báo.
  • clearcote info (Python và Node) cho biết, trên Linux, 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 trong số 29 hệ chữ viết, các thư mục font của bạn, và những họ font Windows chủ chốt nào thực sự được chúng cung cấp.
  • Để giữ font thay thế ngay cả khi đã liệt kê font của bạn, hãy truyền --disable-genuine-font-faces trong args (154 r32+). SDK nhận ra switch này và giữ nguyên các quy tắc font của chính nó, nên engine và fontconfig thống nhất với nhau về mọi họ font.
  • Bị bỏ qua trên Windows và macOS, vốn dùng font của riêng chúng, và bị từ chối với lần khởi chạy trên cloud và lần khởi chạy qua Docker trên macOS: trong container của riêng bạn, hãy mount các font và đặt CLEARCOTE_FONT_DIRS ở đó (xem Triển khai). Chỉ dùng những font mà bạn có giấy phép sử dụng.
  • Trước 0.41.0, .NET SDK hoàn toàn không trỏ trình duyệt tới bộ font đi kèm, nên một lần khởi chạy .NET trên Linux dùng font của host và không có font thay thế nào. Giờ đây nó đã giống Python và Node, điều này làm thay đổi những gì một persona Windows đo được ở đó.