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 comotruepara 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", seguebrandVersion;"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(ouCLEARCOTE_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()eexposeFunction()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>/cmdlineno Linux, os detalhes do processo no Windows). O motor também os mantém fora das linhas de comando dos seus processos auxiliares.falseouCLEARCOTE_PERSONA_ENV=0os 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çãoSec-CH-Prefers-Color-Schemee 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. PassecolorScheme/color_scheme/ColorSchemepara emular um mesmo assim, ou--fingerprint-color-scheme=light|darkemargspara 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+);falseos 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 proxysocks5://, 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.5deriva exatamente o que os builds do r45 ao r51 derivavam,4o que os do 154 r37 ao 155 r44 derivavam,3o que o 154 r36 derivava e2o 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 existe6. Todos os SDKs aceitam 5 e 7 a partir do 0.64.1. Veja a mesma seed em máquinas diferentes. AdicionerealGpuHost/real_gpu_hostsó 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;falseo 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 comprofileSelect/profile_select. Python, Node & .NET (LocalProfile = "auto", 0.58.0+). No Node, funciona com olaunch()padrão, comlaunchPersistentContext()e comserve()a partir do SDK 0.31.1; a 0.31.0 e as anteriores exigiamephemeralProfile: falsee falhavam comserve().
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 emCLEARCOTE_LICENSE_KEYnem em~/.clearcote/license.key.licenseThroughProxy/license_through_proxy(ouCLEARCOTE_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/userDataDirnolaunch()— 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, ouCLEARCOTE_FONT_DIRS— suas próprias fontes, normalmente uma cópia daC:\Windows\Fontsde 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-facesemargs(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_DIRSlá (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.