跳到正文

启动选项

其他页面没有涉及的启动选项:扩展、Privacy Sandbox,以及列表中的其余选项。

更多启动选项

  • extensions——未打包扩展的目录路径列表(会生成 --load-extension + --disable-extensions-except)。
  • disablePrivacySandbox / disable_privacy_sandbox——设为 true 可关闭 Privacy Sandbox API(Topics、FLEDGE / Protected Audience、Shared Storage、Private Aggregation、Fenced Frames)。自 0.23 起此选项默认关闭:默认身份画像呈现为 Google Chrome,而 Google Chrome 提供了上述所有 API。只有当身份画像是去 Google 化的 Chromium 时才开启它。WebUSB 不受影响。
  • agentTyping / agent_typing——智能体的击键节奏(默认 human / fast / instant)。参见智能体。
  • tlsProfile——让 TLS ClientHello 与身份画像声称的 Chrome 版本保持一致,使网络层跟随 UA(而不是构建自身原生的 TLS)。默认值 "match-persona" 跟随 brandVersion;"native" 保持原样不做改动;"chrome-<major>" 固定为某个主版本。参见指纹参数。
  • platform: "android"——尽力而为的移动端身份画像(触控、粗略指针、移动端屏幕/DPR、Mali/Adreno WebGL、手机视口)。在桌面引擎上,GPU 渲染仍然是桌面端的——请搭配 canvas bridge 实现渲染一致性。
  • storageQuota、fingerprintProfile、canvasBridge、webrtcIp、acceptLanguage、disableGpuFingerprint、fingerprintNoise——参见指纹参数。

较新的选项(授权版构建)

以下选项需要授权版构建(GitHub 免费版或 Pro)。方括号中是各选项所需的引擎修订版本;在较旧的引擎上,SDK 会跳过标注 152 r22 的选项并给出警告;对每个标注 154 r32 的选项,SDK 会先检查引擎,构建不支持时就不启用它;其余选项则会被引擎忽略。

  • stockRuntime / stock_runtime / StockRuntime(或 CLEARCOTE_STOCK_RUNTIME=1)——在调试运行中让 Playwright 恢复原版的 DevTools 行为:控制台和页面错误事件、page.setContent(),以及导航之后的 exposeFunction()。默认关闭,因为页面能察觉到它;没有该开关的引擎会在不启用它的情况下启动,SDK 会警告一次。仅适用于本地和 Docker 启动。参见事件与调试。[154 r32;SDK 0.41.0]
  • personaEnv / persona_env / PersonaEnv——从 SDK 0.41.0 起默认开启。身份画像相关的开关(种子、每一项身份画像覆盖、代理凭据以及 canvas bridge 令牌)通过浏览器的环境变量传入,而不是通过命令行——任何本地用户都能在进程列表中读到命令行(Linux 上的 /proc/<pid>/cmdline,Windows 上的进程详细信息)。引擎也不会让它们出现在其辅助进程的命令行中。false 或 CLEARCOTE_PERSONA_ENV=0 会把它们保留在命令行上,例如当你自己的某个工具需要从命令行读取它们时。Docker 镜像对容器内的浏览器也是同样处理。[154 r32]
  • Persona 令牌 — 在授权版 Chromium 156 构建(r51 及更新)上,SDK 每次启动都会从 Clearcote 的 persona 服务为你的 seed 或配置获取一个已签名的 persona,并与上述开关一起传给浏览器。没有关闭它的选项;没有它浏览器不会启动。需要 SDK 0.63.0、Profile Manager 0.27.0 或对应的 Docker 镜像。[156 r51; SDK 0.63.0]
  • 浅色或深色——从 154 r32 起,由身份画像决定配色方案(大约每三个身份画像中有一个偏好深色),CSS、matchMedia、Sec-CH-Prefers-Color-Scheme 请求头以及系统颜色都会跟随它。Playwright 会在它创建的每个上下文中模拟浅色,这与深色身份画像相矛盾,因此从 SDK 0.41.0 起,在这类构建上,本地启动所创建的上下文不再改动配色方案。如果仍想模拟某种配色方案,请传入 colorScheme / color_scheme / ColorScheme;或者在 args 中传入 --fingerprint-color-scheme=light|dark,让身份画像本身成为浅色或深色。较旧的构建保留 Playwright 的默认行为。[154 r32]
  • allowThirdPartyCookies / allow_third_party_cookies——第三方 Cookie,默认允许,与原版 Chrome 一致(SDK 0.45.0+);设为 false 则阻止。嵌入式登录、支付和验证框架依赖它们。152 r22 之前的构建始终阻止第三方 Cookie。[152 r22]
  • transparentProxy / transparent_proxy——在请求头和连接时序中隐藏代理(纯 HTTP 请求不携带代理请求头;经代理的连接上报的时序与复用连接相同)。需要配合代理使用。[152 r22]
  • fingerprintVoices: false / fingerprint_voices=False——保留本机自己的语音,而不使用身份画像的语音列表。[152 r22]
  • fingerprint: "off"——完全不使用身份画像启动,用于排查问题。[152 r22]
  • socks5Udp / socks5_udp——让 WebRTC 的 UDP 流量经由 socks5:// 代理传输,这样语音、视频和点对点连接都能正常工作,而且仍然从代理的地址发出。代理必须允许这样做;很多住宅代理池并不允许。[151 r17]
  • portableProfile / encryptionKey——可在机器之间复制的 profile(见上文)。[151 r14;Python、Node & .NET(0.58.0+)]
  • personaSchema / persona_schema——种子派生所用的身份模型。不设置即使用当前模型 7(自 2026-10-26 起提供,r52):由显卡决定机器的类型(笔记本或台式机)及其处理器、线程数、内存和屏幕,每一项出现的概率都与真实浏览器流量中的相同。5 派生的结果与 r45 到 r51 完全相同,4 与 154 r37 到 155 r44 相同,3 与 154 r36 相同,2 与 153 r29 到 154 r35 相同;要保留在这些构建上创建的身份,请设置其中之一。1 是 r29 之前的原始模型。不存在 6。从 0.64.1 起,所有 SDK 都接受 5 和 7。参见不同机器上的同一个种子。只在配有真实显卡的机器上添加 realGpuHost / real_gpu_host。[151 r19;Python, Node & .NET]
  • shaderDialect: "hlsl"——从 SDK 0.39.0 起,Linux 或 macOS 主机上的 Windows 身份画像默认开启;false 可将其关闭。参见着色器方言。[151 r15]
  • profile: "auto"——启动一个为本机挑选的真实采集指纹,而不是使用种子;可以用 profileSelect / profile_select 调整。支持 Python、Node & .NET(LocalProfile = "auto",0.58.0+)。在 Node 中,从 SDK 0.31.1 起它可用于默认的 launch()、launchPersistentContext() 和 serve();0.31.0 及更早版本需要 ephemeralProfile: false,且配合 serve() 使用时会失败。

与引擎构建无关的选项:

  • version / releaseChannel——选择构建;参见选择构建。
  • licenseKey / license_key / LicenseKey——许可证密钥(如果它不在 CLEARCOTE_LICENSE_KEY 或 ~/.clearcote/license.key 中)。
  • licenseThroughProxy / license_through_proxy(或 CLEARCOTE_LICENSE_THROUGH_PROXY=1)——通过本次启动所用的代理发送许可证请求,而不是从本机直接发出。
  • launch() 上的 ephemeralProfile / userDataDir——参见上文使用 SDK 一节中的说明。
  • widevine: true——DRM 播放(两种构建均支持);参见 Widevine & DRM。
  • quiet——关闭 SDK 的启动警告和进度输出。
  • fontDirs / font_dirs / FontDirs——在 Linux 上使用你自己的字体;见下文。

在 Linux 上使用你自己的字体(fontDirs)

在 Linux 上,浏览器只能看到 SDK 指给它的字体:该版本自带的一组与 Windows 字体度量兼容的替代字体(Arial→Arimo、Segoe UI→Selawik、Times New Roman→Tinos……)。主机上安装的任何字体都不会到达浏览器,因此这台机器上的任何东西都无法改变页面测量到的结果。从 SDK 0.41.0 起(Python、Node 和 .NET;launch()、持久化上下文和 serve()),可以用两个设置添加字体目录:

  • fontDirs / font_dirs / FontDirs,或 CLEARCOTE_FONT_DIRS——你自己的字体,通常是一台 Windows 机器上 C:\Windows\Fonts 的副本,排在自带字体之前。在 154 r32 起的授权版构建上,这些目录提供的每个字体族都会以它本身、以它自己的名称渲染,而不再使用替代字体;在 Windows 上代表这些字体族的名称也随之生效:Helvetica、Times 和 Courier,以及 CSS 通用字体族(sans-serif → Arial,serif → Times New Roman,monospace → Consolas,system-ui → Segoe UI)。较旧的引擎对身份画像列出的字体族仍使用替代字体绘制,只把这些目录用于其他字体都不覆盖的字符。如果某个路径不是目录,启动会立即失败,此时尚未占用许可证名额。
  • CLEARCOTE_FALLBACK_FONT_DIRS——只用于其他字体都不覆盖的字符(CJK、印度系文字、emoji……)的字体,排在自带字体之后。它们不会接管任何字体族。Docker 镜像会把它设置为镜像自带的各书写系统字体。
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 ":")
  • 两个变量都是以 : 分隔的列表。字体族名称直接从字体文件中读取,因此不需要 fontconfig 工具。切勿把任何一个变量指向整个 /usr/share/fonts:那样主机的拉丁字体族会与自带字体竞争,改变 Windows 身份画像报告的字宽。
  • 在 Linux 上,clearcote info(Python 和 Node)会报告:一次启动所能看到的字体可以绘制 29 种书写系统中的哪些、你的字体目录,以及这些目录真正提供了哪些关键的 Windows 字体族。
  • 如果列出了你自己的字体但仍想保留替代字体,请在 args 中传入 --disable-genuine-font-faces(154 r32+)。SDK 会识别它并保持自己的字体规则不变,这样引擎和 fontconfig 对每个字体族的认定都一致。
  • 在 Windows 和 macOS 上会被忽略(它们使用自己的字体);云端启动和 macOS Docker 启动会拒绝这些设置:在你自己的容器中,请挂载字体并在容器里设置 CLEARCOTE_FONT_DIRS(参见部署)。只使用你已获得授权的字体。
  • 在 0.41.0 之前,.NET SDK 根本没有把浏览器指向自带字体,因此 Linux 上的 .NET 启动使用的是主机字体,没有用到任何替代字体。现在它与 Python 和 Node 保持一致,这会改变 Windows 身份画像在那里的测量结果。