Pular para o conteúdo

Opções de inicialização

As opções de inicialização que as outras páginas não cobrem: extensões, o Privacy Sandbox e o resto da lista.

Mais opções de inicialização

  • extensions — uma lista de caminhos de diretórios de extensões descompactadas (gera --load-extension + --disable-extensions-except).
  • disablePrivacySandbox / disable_privacy_sandbox — defina como true para desligar as APIs do Privacy Sandbox (Topics, FLEDGE / Protected Audience, Shared Storage, Private Aggregation, Fenced Frames). Desativada por padrão desde a 0.23: a persona padrão se apresenta como Google Chrome, que traz todas elas. Ative-a só quando a persona for um Chromium sem serviços do Google. O WebUSB não é afetado.
  • agentTyping / agent_typing — o ritmo de digitação do agente (human, o padrão / fast / instant). Veja Agente.
  • tlsProfile — mantém o TLS ClientHello coerente com a versão do Chrome que a persona declara, para que a camada de rede acompanhe o UA (e não o TLS nativo do build). O padrão, "match-persona", segue brandVersion; "native" não mexe nele; "chrome-<major>" fixa uma versão major. Veja Flags de fingerprint.
  • platform: "android" — uma persona mobile no modo best-effort (toque, ponteiro coarse, tela/DPR de celular, WebGL Mali/Adreno, viewport de celular). Num motor de desktop, a renderização da GPU continua sendo de desktop — combine com a canvas bridge para ter coerência de renderização.
  • storageQuota, fingerprintProfile, canvasBridge, webrtcIp, acceptLanguage, disableGpuFingerprint, fingerprintNoise — veja Flags de fingerprint.

Opções mais novas (build licenciado)

Estas exigem o build licenciado (Grátis com GitHub ou Pro). A revisão do motor que cada uma exige aparece entre colchetes; num motor mais antigo, o SDK pula as de 152 r22 com um aviso, verifica no motor cada uma das de 154 r32 e a deixa desligada quando o build não a tem, e o motor ignora as demais.

  • stockRuntime / stock_runtime / StockRuntime (ou CLEARCOTE_STOCK_RUNTIME=1) — devolve ao Playwright o comportamento padrão do DevTools para uma execução de depuração: eventos de console e de erro da página, page.setContent() e exposeFunction() depois de uma navegação. Desligado por padrão, porque as páginas conseguem percebê-lo; um motor sem o switch inicia sem ele e o SDK avisa uma vez. Só para inicializações locais e no Docker. Veja Eventos e depuração. [154 r32; SDK 0.41.0]
  • personaEnv / persona_env / PersonaEnv — ligado por padrão a partir do SDK 0.41.0. Os switches da persona (o seed, cada override da persona, as credenciais do proxy e o token da canvas bridge) chegam ao navegador pelo ambiente dele, e não pela linha de comando, que qualquer usuário local pode ler na lista de processos (/proc/<pid>/cmdline no Linux, os detalhes do processo no Windows). O motor também os mantém fora das linhas de comando dos seus processos auxiliares. false ou CLEARCOTE_PERSONA_ENV=0 os mantém na linha de comando, por exemplo para uma ferramenta sua que os lê ali. A imagem Docker faz o mesmo com o navegador do contêiner. [154 r32]
  • Token de persona — na build licenciada do Chromium 156 (r51 em diante), o SDK busca a cada lançamento uma persona assinada para sua seed ou perfil no serviço de personas da Clearcote e a repassa ao navegador junto com os switches acima. Não há opção para desativar; sem ela o navegador não inicia. Requer SDK 0.63.0, Profile Manager 0.27.0 ou a imagem Docker correspondente. [156 r51; SDK 0.63.0]
  • Claro ou escuro — a partir do 154 r32, a persona decide o esquema de cores (cerca de um perfil em cada três prefere o escuro), e o CSS, o matchMedia, o header de requisição Sec-CH-Prefers-Color-Scheme e as cores do sistema seguem essa escolha. O Playwright emula o modo claro em todo contexto que cria, o que contradiria uma persona escura; por isso, a partir do SDK 0.41.0, os contextos que uma inicialização local cria não mexem no esquema de cores num build assim. Passe colorScheme / color_scheme / ColorScheme para emular um mesmo assim, ou --fingerprint-color-scheme=light|dark em args para tornar a própria persona clara ou escura. Um build mais antigo mantém o padrão do Playwright. [154 r32]
  • allowThirdPartyCookies / allow_third_party_cookies — cookies de terceiros, permitidos por padrão, assim como no Chrome padrão (SDK 0.45.0+); false os bloqueia. Frames incorporados de login, pagamento e desafio dependem deles. Builds anteriores a 152 r22 sempre os bloqueiam. [152 r22]
  • transparentProxy / transparent_proxy — esconde o proxy dos headers das requisições e do timing da conexão (requisições HTTP simples não levam header de proxy; conexões via proxy reportam timing como o de uma conexão reutilizada). Exige um proxy. [152 r22]
  • fingerprintVoices: false / fingerprint_voices=False — mantém as vozes de síntese de fala desta máquina, em vez da lista da persona. [152 r22]
  • fingerprint: "off" — inicia sem nenhuma persona, para diagnosticar problemas. [152 r22]
  • socks5Udp / socks5_udp — leva o UDP do WebRTC por um proxy socks5://, para que voz, vídeo e conexões peer funcionem e continuem saindo pelo endereço do proxy. O proxy precisa permitir isso; muitos pools residenciais não permitem. [151 r17]
  • portableProfile / encryptionKey — perfis que você pode copiar entre máquinas (veja acima). [151 r14; Python, Node & .NET (0.58.0+)]
  • personaSchema / persona_schema — qual modelo de identidade uma seed deriva. Deixe sem definir para usar o modelo atual, 7 (servido desde 2026-10-26, r52): a placa de vídeo define o tipo de máquina (notebook ou desktop), o processador, os threads, a memória e a tela, cada um tão comum quanto no tráfego real de navegadores. 5 deriva exatamente o que os builds do r45 ao r51 derivavam, 4 o que os do 154 r37 ao 155 r44 derivavam, 3 o que o 154 r36 derivava e 2 o que os do 153 r29 ao 154 r35 derivavam; defina um deles para manter as identidades criadas nesses builds. 1 é o modelo original, de antes do r29. Não existe 6. Todos os SDKs aceitam 5 e 7 a partir do 0.64.1. Veja a mesma seed em máquinas diferentes. Adicione realGpuHost / real_gpu_host só numa máquina com placa de vídeo real. [151 r19; Python, Node & .NET]
  • shaderDialect: "hlsl" — ligado por padrão para uma persona Windows num host Linux ou macOS desde o SDK 0.39.0; false o desliga. Veja Dialeto de shader. [151 r15]
  • profile: "auto" — inicia com um fingerprint real capturado, escolhido para esta máquina, em vez de um seed; ajuste a escolha com profileSelect / profile_select. Python, Node & .NET (LocalProfile = "auto", 0.58.0+). No Node, funciona com o launch() padrão, com launchPersistentContext() e com serve() a partir do SDK 0.31.1; a 0.31.0 e as anteriores exigiam ephemeralProfile: false e falhavam com serve().

Sem vínculo com um build específico do motor:

  • version / releaseChannel — escolhe um build; veja como escolher um build.
  • licenseKey / license_key / LicenseKey — a chave de licença, caso ela não esteja em CLEARCOTE_LICENSE_KEY nem em ~/.clearcote/license.key.
  • licenseThroughProxy / license_through_proxy (ou CLEARCOTE_LICENSE_THROUGH_PROXY=1) — envia as chamadas de licença pelo proxy da inicialização, em vez de saírem direto desta máquina.
  • ephemeralProfile / userDataDir no launch() — veja a nota em Pelo SDK, mais acima.
  • widevine: true — reprodução com DRM (nos dois builds); veja Widevine & DRM.
  • quiet — silencia os avisos de inicialização e a saída de progresso do SDK.
  • fontDirs / font_dirs / FontDirs — suas próprias fontes no Linux; veja abaixo.

Suas próprias fontes no Linux (fontDirs)

No Linux, o navegador só enxerga as fontes para as quais o SDK o aponta: o pacote da versão, com substitutas das fontes do Windows de métricas compatíveis (Arial→Arimo, Segoe UI→Selawik, Times New Roman→Tinos, …). Nenhuma fonte instalada no host chega até ele, então nada na máquina pode mudar o que uma página mede. A partir do SDK 0.41.0 (Python, Node e .NET; launch(), contextos persistentes e serve()), duas configurações acrescentam diretórios:

  • fontDirs / font_dirs / FontDirs, ou CLEARCOTE_FONT_DIRS — suas próprias fontes, normalmente uma cópia da C:\Windows\Fonts de uma máquina Windows, listadas antes do pacote. No build licenciado a partir do 154 r32, cada família que elas fornecem é renderizada como ela mesma, com o próprio nome, em vez da substituta, e os nomes que a representam no Windows acompanham: Helvetica, Times e Courier, e as famílias genéricas do CSS (sans-serif → Arial, serif → Times New Roman, monospace → Consolas, system-ui → Segoe UI). Um motor mais antigo continua desenhando as substitutas para as famílias que a persona lista e usa os diretórios só para caracteres que nada mais cobre. Um caminho que não é um diretório faz a inicialização falhar na hora, antes de ocupar um slot da licença.
  • CLEARCOTE_FALLBACK_FONT_DIRS — fontes usadas só para caracteres que nada mais cobre (CJK, escritas índicas, emoji, …), listadas depois do pacote. Elas não assumem nenhuma família. A imagem Docker define essa variável com as fontes de escrita que traz.
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 ":")
  • As duas variáveis são listas separadas por :. Os nomes das famílias são lidos dos próprios arquivos de fonte, então nenhuma ferramenta do fontconfig é necessária. Nunca aponte nenhuma delas para todo o /usr/share/fonts: as famílias latinas do host passam a competir com o pacote e mudam as larguras que uma persona Windows reporta.
  • clearcote info (Python e Node) informa, no Linux, quais de 29 sistemas de escrita as fontes que uma inicialização enxergaria conseguem desenhar, os seus diretórios de fontes e quais das principais famílias do Windows elas fornecem de verdade.
  • Para manter as substitutas mesmo com as suas fontes listadas, passe --disable-genuine-font-faces em args (154 r32+). O SDK percebe isso e mantém as próprias regras de fontes como estão, para que o motor e o fontconfig concordem em todas as famílias.
  • Ignorado no Windows e no macOS, que usam as próprias fontes, e recusado numa inicialização na nuvem e na inicialização Docker do macOS: no seu próprio contêiner, monte as fontes e defina CLEARCOTE_FONT_DIRS lá (veja Deploy). Use só fontes que você tem licença para usar.
  • Antes da 0.41.0, o SDK .NET não apontava o navegador para o pacote, então uma inicialização .NET no Linux usava as fontes do host e nenhuma das substitutas. Agora ele se comporta como o Python e o Node, o que muda o que uma persona Windows mede ali.