Zum Inhalt springen

Playwright & Puppeteer

Clearcote ist schlicht Chromium und funktioniert daher als Drop-in-Browser mit den Automatisierungstools, die Sie bereits verwenden.

Das Paket clearcote (npm, PyPI und NuGet) macht aus Identitätsoptionen benannte Argumente und liefert gewöhnliche Playwright-Objekte zurück. Beim ersten Einsatz lädt es den Browser herunter und prüft ihn per SHA-256 — ohne Lizenzschlüssel den offenen Build, mit Schlüssel den neuesten lizenzierten Build (siehe Installation) — und wendet die weiter unten beschriebenen Standardwerte an.

# pip install clearcote
from clearcote import launch

browser = launch(fingerprint="seed-123", platform="windows", brand="Chrome")
page = browser.new_page()
page.goto("https://example.com")
browser.close()

Aktuelles SDK: 0.31.1. Seit 0.23 läuft launch() in Python und Node auf einem echten Wegwerf-Profilverzeichnis (wird beim Schließen gelöscht) statt im Inkognito-Modus. Dadurch entspricht alles, was vom Profil abhängt, einem echten Chrome, und widevine: true kann das DRM-Modul laden. Zurück kommt ein browserähnliches Handle: newPage() funktioniert wie gewohnt, newContext() liefert jedoch denselben Profilkontext statt eines isolierten. Für getrennte Cookie-Jars starten Sie getrennte Browser; übergeben Sie ephemeralProfile: false / ephemeral_profile=False für den alten Inkognito-Browser oder userDataDir / user_data_dir, um das Profil zu behalten.

Die Async-API (clearcote.async_api) nimmt innerhalb einer asyncio-Schleife dieselben Persona- und Proxy-Optionen entgegen und liefert die Async-Objekte von Playwright; ihr launch() startet inkognito, für ein Profil (und für widevine=True) verwenden Sie daher launch_persistent_context(). Das .NET-SDK umfasst LaunchEphemeralProfileAsync (empfohlen — LaunchAsync startet unter .NET inkognito und kann das Fenster headless nicht an den Bildschirm anpassen), LaunchPersistentContextAsync,ServeAsync, den verifizierten Download, die Lizenzierung, Geoip und menschenähnliche Eingaben (explizite Aufrufe von HumanClickAsync / HumanTypeAsync / HumanSelectOptionAsync statt eines Launch-Flags). Gespeicherte Profile, profile: "auto", Render-Kohärenzprüfungen, Widevine und die Agent-Helfer gibt es vorerst nur für Python & Node. Komplette Workflows zum Kopieren finden Sie unter Beispiele.

Puppeteer und andere CDP-Clients (serve)

Einen Puppeteer-Launcher hat das SDK nicht. Stattdessen startet serve() Clearcote mit den Launch-Einstellungen des SDK (Persona, Proxy, Standardwerte) und einem CDP-Endpunkt auf Loopback, an den sich jeder CDP-Client anhängen kann — Puppeteer, connectOverCDP von Playwright, browser-use, Crawl4AI, Stagehand. Das funktioniert mit dem lizenzierten Build, und nichts fügt --enable-automation hinzu. humanize arbeitet auf der Playwright-Seite und greift daher nicht bei einem Client, der auf diesem Weg verbunden ist.

import { serve } from "clearcote";
import puppeteer from "puppeteer-core";

const srv = await serve({ fingerprint: "seed-123", platform: "windows" });
const browser = await puppeteer.connect({ browserURL: srv.cdpUrl, defaultViewport: null });
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.disconnect();
await srv.close();

Im Headless-Modus gibt serve() dem Browser ein Display in realer Größe und passt sein Fenster an den Arbeitsbereich an, bevor sich ein Client verbindet (0.31+); für ein kleineres Fenster übergeben Sie windowSize / window_size. Aus der Shell erledigt clearcote serve dasselbe als dauerhafter Dienst — und kann jeder Verbindung einen eigenen Browser geben, mit Identität, Proxy, Zeitzone und Sprache aus der Verbindungs-URL. Siehe Deployment.

Das Binary direkt ansteuern (offener Build)

Sie können auch Ihren eigenen Launcher per executablePath (Node) oder executable_path (Python) auf den offenen Build richten und die Identitätsoptionen als args übergeben. Der lizenzierte Build startet auf diese Weise nicht — er braucht das Lizenz-Token, das das SDK bezieht; nehmen Sie also launch() oder serve() von oben. Lassen Sie --enable-automation weg, wie es das SDK tut (Puppeteer und ältere Playwright-Versionen setzen es; es schaltet Chromium in seinen Automatisierungsmodus). Keine der Standardeinstellungen des SDK (Sprache, WebRTC-Richtlinie, Fenstergeometrie) greift auf diesem Weg.

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=r"C:\clearcote\chrome.exe",
        headless=False,
        ignore_default_args=["--enable-automation"],
        args=[
            "--fingerprint=seed-123",
            "--fingerprint-platform=windows",
            "--timezone=America/New_York",
        ],
    )
    page = browser.new_page()
    page.goto("https://abrahamjuliot.github.io/creepjs/")
    browser.close()

Das verifizierte Binary auflösen oder vorab laden

Das SDK ermittelt den Browser in dieser Reihenfolge: ein explizit angegebener executablePath / executable_path, dann CLEARCOTE_BINARY, dann eine von Ihnen angeforderte version (oder CLEARCOTE_BROWSER_VERSION), dann der lizenzierte Build, sofern ein Lizenzschlüssel gefunden wird (die Option licenseKey, CLEARCOTE_LICENSE_KEY oder ~/.clearcote/license.key), und zuletzt der offene Build, den diese SDK-Version fest vorgibt. Ein von Ihnen angegebener Pfad wird vor dem Start auf fehlende oder abgeschnittene Dateien geprüft. Rufen Sie download / executable_path auf, wenn Sie den Cache ohne Start vorwärmen, ein eigenes Cache-Verzeichnis verwenden oder zur Laufzeit per Opt-in den neuesten offenen Build von GitHub beziehen möchten.

from clearcote import download, launch

chrome = download(cache_dir=r"C:\clearcote-cache", auto_update=True)
browser = launch(executable_path=chrome, fingerprint="seed-123")

Im gepinnten Modus werden die fest ins SDK eingebauten SHA-256-Werte geprüft. autoUpdate / auto_update ist Opt-in und prüft das Prüfsummen-Manifest des Releases; ist gpg verfügbar, wird zusätzlich das signierte Manifest gegen den fest hinterlegten Fingerprint des Clearcote-Signaturschlüssels geprüft. Das gilt nur für den offenen Build: Mit Lizenzschlüssel holt download() stattdessen den aktuellen lizenzierten Build (einen bestimmten wählen Sie mit version oder releaseChannel — siehe Build auswählen). Unter .NET holt DownloadAsync nur den offenen Build; den lizenzierten laden Sie vorab mit ExecutablePathAsync(new LaunchOptions { LicenseKey = … }).

Ein echtes Chrome-Profil importieren

Statt der synthetischen, aus dem Seed abgeleiteten Persona kann Clearcote auch die auf einem echten Rechner erfassten Werte melden. Erfassen Sie ein Profil aus einem Spender-Chrome mit dem Collector unter tools/fingerprint-collect (collect.html öffnen, auf Capture klicken, schon wird ein JSON-Profil heruntergeladen), oder starten Sie mit dem Open-Source-Datensatz chrome-fingerprints (10k Einträge) und dem mitgelieferten Konverter convert_dataset.py. Die Erfassung umfasst Navigator, Bildschirmgeometrie, WebGL-Vendor/-Renderer + getParameter-Limits, Web Audio, Sprachsynthese-Stimmen, Schriften, Codecs und CSS-@media-Merkmale.

Übergeben Sie das Profil dem SDK als Dateipfad, Objekt oder JSON-String — das Packen mit gzip + base64 übernimmt es für Sie. Felder, die im Profil vorhanden sind, überschreiben, was der Browser sonst melden würde; fehlende Felder fallen auf die Standardwerte des Browsers zurück. Außerdem leitet das SDK Accept-Language aus navigator.languages des Profils ab, wenn Sie den Header nicht explizit setzen. Beide Builds lesen importierte Profile; auf dem lizenzierten Build greifen sie ab 151 r19 vollständig.

Übergeben Sie keinen fingerprint-Seed zusätzlich zu einem Profil. Der Seed aktiviert die Farbling-Schicht, die strenges Scoring als Canvas-Manipulation wertet, und er bringt Ihnen nichts, was das Profil nicht ohnehin liefert. Nehmen Sie das eine oder das andere. Ein Profil ersetzt nur gemeldete Werte — es ändert nie, was Ihre Pixel rendert; zwei Accounts mit zwei verschiedenen Profilen auf einem Rechner erzeugen also weiterhin ein identisches Canvas. Brauchen Sie pro Account getrennte Render-Ergebnisse, verwenden Sie einen Seed pro Account und kein Profil.

from clearcote import launch

browser = launch(fingerprint_profile="profile.json", disable_gpu_fingerprint=True, fingerprint_noise=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

Standardmäßig kohärent (ohne zusätzliche Flags)

Egal, womit Sie starten: Die Engine hält die sekundären Signale im Einklang mit der gewählten Persona — bei einer Windows-Persona mit dem, was ein echter Chrome-Desktop unter Windows meldet. Die Plattform der Persona entspricht standardmäßig Ihrem Host-Betriebssystem; auf einem Linux-Host folgen diese Werte also einer Linux-Persona, sofern Sie nicht platform übergeben. Die WebGL-Limits von getParameter (WebGL1 + WebGL2) melden die Werte der Persona, begrenzt auf das, was die GPU dieses Rechners tatsächlich leisten kann, und UNMASKED_RENDERER / UNMASKED_VENDOR sind für die ganze Session konstant (auf jeder Website dieselbe GPU, passend zur Persona). Bei einer Windows-Persona meldet navigator.getBattery() einen Desktop am Stromnetz, navigator.connection einen privaten Internetanschluss und AudioContext die passende Windows-WASAPI-Samplerate und -Latenz. getScreenDetails() meldet einen einzelnen Monitor, und @media (pointer: fine) / (hover: hover) entsprechen einem Desktop mit Maus.

Geprüft mit 153 r26, headed unter Windows (September 2026): BrowserScan meldet keinen Bot, und CreepJS zeigt 0 % Stealth. Hinter einem Proxy fügen Sie geoip hinzu, damit Zeitzone und WebRTC zum Exit passen.

Console- und Page-Error-Events

Die Engine leitet Console- und Page-Error-Events nicht an Automatisierungs-Clients weiter, daher empfangen page.on("console") und page.on("pageerror") nichts. Das ist Absicht — genau diese Weiterleitung misst eine Probe, die nach Automatisierung sucht. In-Page-Handler für window.onerror und unhandledrejection feuern ganz normal; um die Konsolenausgabe mitzuschneiden, sammeln Sie sie also in der Seite und lesen sie mit page.evaluate() zurück. Die Python- und Node-SDKs weisen beim Start einmalig darauf hin.

Region des Proxys automatisch übernehmen (geoip)

Übergeben Sie geoip zusammen mit einem Proxy, und das SDK ermittelt die Exit-IP des Proxys — nachgeschlagen in der Offline-Datenbank geoip-all-in-one — und setzt für diese Region eine kohärente Kombination aus Zeitzone + primärer Navigator-Sprache + Accept-Language + WebRTC-IP. Sie müssen also nicht mehr für jeden Proxy die Zeitzone von Hand anpassen:

from clearcote import launch

browser = launch(
    fingerprint="user-7423",
    proxy={"server": "http://host:8080", "username": "u", "password": "p"},
    geoip=True,  # timezone + language auto-matched to the proxy's region
)

Außerdem setzt es für die Region die Geolocation und die vollständige Liste navigator.languages, funktioniert über HTTP- und SOCKS5-Proxys (inklusive Zugangsdaten) und steckt in allen drei SDKs (Geoip = true in .NET). Beim ersten Lauf wird die Datenbank heruntergeladen (rund 50 MB). Lässt sich die Region nicht ermitteln, bricht der Start mit einem GeoipError ab, statt stillschweigend mit Uhr und Sprache dieses Rechners zu starten; setzen Sie sowohl timezone als auch acceptLanguage, um trotzdem zu starten. Für den Lookup gibt es 20 Sekunden (CLEARCOTE_GEOIP_TIMEOUT_SECONDS); unter .NET heißt der Fehler GeoipException. Ohne geoip oder eine explizite timezone folgt die Zeitzone der Sprache — en-US bedeutet New York, auch hinter einem deutschen Proxy.

Lieber selbst einstellen? Verwenden Sie acceptLanguage (Node) / accept_language (Python), z. B. "en-US,en" — das setzt den Accept-Language-Header, das komplette Array navigator.languages und navigator.language —, und auch Intl / toLocaleString richten sich danach.

Menschenähnliche Eingaben (humanize & showCursor)

Übergeben Sie humanize, und alle Eingaben — Bewegen, Klicken, Ziehen, Scrollen und Tippen — laufen nach einem einheitlichen, menschenähnlichen Standard ab, sowohl auf Page-Ebene (page.click / hover / type / fill / mouse.* / keyboard.type) als auch auf Locator-Ebene (locator.click / type / fill / pressSequentially / dragTo / …). Bewegungen folgen einem leicht gewölbten kubischen Bézier-Pfad ab der letzten Cursorposition und werden als Min-Jerk-Summe von Teilbewegungen abgefahren (eine ballistische Hauptbewegung + eine Korrekturbewegung — das mehrgipflige Geschwindigkeitsprofil echter Zielbewegungen statt einer einzigen symmetrischen Glockenkurve), und alles wird als echte, vertrauenswürdige Events ausgelöst (isTrusted === true, und navigator.webdriver bleibt false). Auf Pro folgen Koordinaten-Klicks (mouse.click(x, y)) Bewegungen, die bei echten Menschen aufgezeichnet wurden; alles andere sowie jeder Klick auf dem offenen Build und mit „Kostenlos mit GitHub“ nutzt generierte Pfade. Mit showCursor blenden Sie einen Punkt ein, der der Bewegung folgt, sodass Sie zusehen können.

Weil Bewegungen nativen Input nutzen, bleibt eine mit mouse.down() gedrückte Taste während der Bewegung gehalten — down → move → up ist also echtes Ziehen mit gehaltener Taste (Bedienelemente wie Slider, die man an eine Position zieht, erhalten einen wirklich gedrückten Drag), und auch locator.dragTo ist menschenähnlich. Getippt wird Taste für Taste mit zufälligen Abständen zwischen den Anschlägen + Pausen an Wortgrenzen und gelegentlich einem korrigierten Vertipper; beim Scrollen gibt es Ease-out-Trägheit mit gelegentlichen Lesepausen. fill fokussiert das Feld und tippt den Wert aus (Werte über ~200 Zeichen bleiben atomar, damit große Füllvorgänge nicht dahinkriechen).

from clearcote import launch

browser = launch(fingerprint="seed-123", humanize=True, show_cursor=True)
page = browser.new_page()
page.goto("https://example.com")

page.click("text=Sign in")               # eased curve, then a trusted click
page.fill("#email", "you@example.com")   # focus + key-by-key human typing
page.locator("#password").type("s3cr3t") # locators are humanized too

# held-button drag (e.g. a slider): the press stays held across the move
x0, y0, x1 = 100, 300, 400               # the handle's start, and where to release it
page.mouse.move(x0, y0); page.mouse.down()
page.mouse.move(x1, y0); page.mouse.up()
browser.close()

Kohärenzprüfung des Render-Backends (checkRenderCoherence)

Eine Persona kann eine GPU angeben. Wird die Seite aber tatsächlich von einem Software-Rasterizer gezeichnet (SwiftShader / llvmpipe — headless ohne GPU üblich), kann ein strenger Detektor das erkennen. Prüfen Sie eine geladene Seite: Die Funktion liest den (unmaskierten) WebGL-Vendor/-Renderer, den die Seite tatsächlich sieht, meldet einen Fallback auf einen Software-Rasterizer (ein fatales Headless-Indiz — aktivieren Sie die Canvas-Bridge oder starten Sie headed auf einer echten GPU) oder ein inkohärentes Vendor/Renderer-Paar und liefert ein strukturiertes Ergebnis zurück. Übergeben Sie die angegebene GPU, um zusätzlich die gerenderte GPU-Familie zu prüfen. Verfügbar synchron, asynchron und in Node.

from clearcote import launch, check_render_coherence

browser = launch(fingerprint="seed-123")
page = browser.new_page(); page.goto("about:blank")

verdict = check_render_coherence(page)   # {'renderer', 'software_suspected', 'coherent', 'warnings'}
if not verdict["coherent"]:
    print(verdict["warnings"])            # e.g. software rasterizer / incoherent GPU family
browser.close()

Profile & Persistenz

Eine stabile Identität über mehrere Läufe erhalten Sie, indem Sie denselben fingerprint-Seed wiederverwenden; Cookies/Storage bleiben mit einem User-Data-Verzeichnis erhalten:

from clearcote import launch_persistent_context

ctx = launch_persistent_context(r"C:\clearcote\profiles\acme", fingerprint="acme-tenant-7", headless=False)
page = ctx.pages[0] if ctx.pages else ctx.new_page()

Die Cookies eines Profilverzeichnisses sind mit einem Schlüssel verschlüsselt, der an den Rechner gebunden ist, auf dem das Profil angelegt wurde. Um ein Profil samt Cookies auf einen anderen Rechner zu kopieren, übergeben Sie portableProfile: true / portable_profile=True (der Schlüssel wandert mit dem Profil) oder encryptionKey / encryption_key (der Schlüssel wird aus Ihrem Secret abgeleitet, und nichts Sensibles landet auf der Festplatte). Lizenzierter Build, Python & Node.

Das SDK kennt außerdem gespeicherte Personas: Ein Profile legt Fingerprint-Optionen, Proxy-Einstellungen, Canvas-Bridge-Einstellungen und weitere Launch-Optionen als JSON unter ~/.clearcote/profiles ab (ändern lässt sich das mit CLEARCOTE_PROFILE_DIR).

from clearcote import Profile, launch, launch_persistent_context

Profile("acct-1", {
    "fingerprint": "acct-1",
    "gpu_vendor": "Google Inc. (Intel)",
    "gpu_renderer": "ANGLE (Intel, Intel(R) UHD Graphics ... D3D11)",
    "canvas_bridge": {"url": "ws://127.0.0.1:8443", "auth": "user:secret"},
}).save()

ctx = launch_persistent_context(r"C:\clearcote\profiles\acct-1", profile="acct-1")
browser = launch(profile="acct-1", headless=False)
Gespeicherte Profile liegen im Klartext vor und können Zugangsdaten wie canvasBridge.auth enthalten. Behandeln Sie Profildateien als vertrauenswürdige Eingabe, und committen oder teilen Sie sie nicht.

Weitere Launch-Optionen

  • extensions — eine Liste von Verzeichnispfaden entpackter Erweiterungen (erzeugt --load-extension + --disable-extensions-except).
  • disablePrivacySandbox / disable_privacy_sandbox — auf true setzen, um die Privacy-Sandbox-APIs abzuschalten (Topics, FLEDGE / Protected Audience, Shared Storage, Private Aggregation, Fenced Frames). Seit 0.23 standardmäßig aus: Die Standard-Persona tritt als Google Chrome auf, und das bringt alle diese APIs mit. Schalten Sie die Option nur ein, wenn die Persona ein Chromium ohne Google-Dienste darstellt. WebUSB ist nicht betroffen.
  • agentTyping / agent_typing — der Tipp-Rhythmus des Agenten (human als Standard / fast / instant). Siehe Agent.
  • tlsProfile — hält den TLS-ClientHello kohärent mit der Chrome-Version, die die Persona angibt, damit die Netzwerkschicht dem UA folgt (und nicht dem nativen TLS des Builds). Der Standardwert "match-persona" folgt brandVersion; "native" lässt ihn unverändert; "chrome-<major>" pinnt eine Major-Version. Siehe Fingerprint-Flags.
  • platform: "android" — eine mobile Persona auf Best-Effort-Basis (Touch, grober Pointer, mobiler Bildschirm/DPR, Mali/Adreno-WebGL, Smartphone-Viewport). Auf einer Desktop-Engine bleibt das GPU-Rendering das eines Desktops — für Render-Kohärenz kombinieren Sie die Persona mit der Canvas-Bridge.
  • storageQuota, fingerprintProfile, canvasBridge, webrtcIp, acceptLanguage, disableGpuFingerprint, fingerprintNoise — siehe Fingerprint-Flags.

Neuere Optionen (lizenzierter Build)

Diese Optionen setzen den lizenzierten Build voraus (Kostenlos mit GitHub oder Pro). Die jeweils nötige Engine-Revision steht in eckigen Klammern; auf einer älteren Engine überspringt das SDK die mit 152 r22 gekennzeichneten mit einer Warnung, die übrigen ignoriert die Engine.

  • allowThirdPartyCookies / allow_third_party_cookies — erlaubt Drittanbieter-Cookies wie ein Standard-Chrome. Die Basis ohne Google-Dienste blockiert sie standardmäßig, was eingebettete Anmelde-, Zahlungs- und Challenge-Frames lahmlegt, die darauf angewiesen sind. [152 r22]
  • transparentProxy / transparent_proxy — verbirgt den Proxy in Request-Headern und im Verbindungs-Timing (reine HTTP-Requests tragen keinen Proxy-Header; Verbindungen über den Proxy melden ein Timing wie eine wiederverwendete Verbindung). Erfordert einen Proxy. [152 r22]
  • fingerprintVoices: false / fingerprint_voices=False — behält die eigenen Sprachausgabe-Stimmen dieses Rechners statt der Liste der Persona. [152 r22]
  • fingerprint: "off" — startet ganz ohne Persona, zur Fehlersuche. [152 r22]
  • socks5Udp / socks5_udp — leitet das UDP von WebRTC über einen socks5://-Proxy, sodass Sprach-, Video- und Peer-Verbindungen funktionieren und trotzdem von der Adresse des Proxys ausgehen. Der Proxy muss das zulassen; viele Residential-Pools tun das nicht. [151 r17]
  • portableProfile / encryptionKey — Profile, die Sie zwischen Rechnern kopieren können (siehe oben). [151 r14; Python & Node]
  • personaSchema: 2 / persona_schema=2 — ein optionales Identitätsmodell, bei dem Bildschirm und Grafikchip zu dem Prozessor und Arbeitsspeicher passen, die die Persona angibt. Standardmäßig aus, damit jeder bestehende Seed seine Identität behält. Fügen Sie realGpuHost / real_gpu_host nur auf einem Rechner mit echter Grafikkarte hinzu. [151 r19; Python & Node]
  • shaderDialect: "hlsl" — siehe Shader-Dialekt. [151 r15]
  • profile: "auto" — startet statt eines Seeds einen echten erfassten Fingerprint, der für diesen Rechner ausgewählt wird; feinjustieren lässt sich die Auswahl mit profileSelect / profile_select. Python & Node. In Node funktioniert es ab SDK 0.31.1 mit dem Standard-launch(), mit launchPersistentContext() und mit serve(); 0.31.0 und älter brauchten ephemeralProfile: false und scheiterten an serve().

Nicht an einen Engine-Build gebunden:

  • version / releaseChannel — wählt einen Build; siehe Build auswählen.
  • licenseKey / license_key / LicenseKey — der Lizenzschlüssel, falls er nicht in CLEARCOTE_LICENSE_KEY oder ~/.clearcote/license.key liegt.
  • licenseThroughProxy / license_through_proxy (oder CLEARCOTE_LICENSE_THROUGH_PROXY=1) — schickt die Lizenzaufrufe über den Proxy des Launches statt direkt von diesem Rechner.
  • ephemeralProfile / userDataDir bei launch() — siehe den Hinweis unter Über das SDK oben.
  • widevine: true — DRM-Wiedergabe (beide Builds); siehe Widevine & DRM.
  • quiet — unterdrückt die Launch-Warnungen und Fortschrittsausgaben des SDK.

Kohärente Standardwerte (überschreibbar)

Das SDK setzt einige stealth-gerechte Standardwerte, damit die offensichtlichen Indizien nicht durchrutschen:

  • Headed-Starts verwenden standardmäßig keinen emulierten Viewport (viewport: null / no_viewport=True), sodass window.innerWidth dem echten OS-Fenster folgt — ein emulierter Viewport von 1280×720 in einem echten Fenster verrät ein unmögliches Fenster. Zum Überschreiben übergeben Sie einen expliziten viewport.
  • WebRTC verwendet standardmäßig disable_non_proxied_udp, sodass kein UDP am Proxy vorbei nach außen geht und die eigene Adresse Ihres Rechners privat bleibt. Überschrieben wird das nur durch Ihre eigene --webrtc-ip-handling-policy in args — und auf dem offenen Build durch webrtcIp / geoip, die WebRTC-UDP wieder über Ihre eigene Verbindung hinauslassen (der lizenzierte Build blockiert WebRTC-UDP in jedem Fall). Mit dieser Richtlinie und ohne webrtcIp erhält eine Seite überhaupt keine ICE-Kandidaten — hinter einem Proxy übergeben Sie daher geoip (oder webrtcIp), damit WebRTC die Adresse des Proxys meldet, oder socks5Udp, um echtes UDP über einen SOCKS5-Proxy zu leiten.
  • Hinter einem Proxy ist QUIC / HTTP-3 aus, wie bei einem echten Chrome hinter einem Proxy — es wird also kein UDP am Proxy vorbei versucht.
  • Die Plattform der Persona entspricht standardmäßig Ihrem Host-Betriebssystem, die Marke ist standardmäßig Google Chrome. Ohne timezone und ohne geoip folgt die Zeitzone der Sprache (en-US → New York).
  • Proxy-Zugangsdaten gehen an den Browser, nicht an Playwright, sofern die Engine das unterstützt: bei SOCKS5 immer (Playwright kann sich bei SOCKS5 überhaupt nicht authentifizieren), bei HTTP(S) ab 151 r19, damit der Seiten-Cache aktiv bleibt (Python & Node). Siehe unten.
  • humanize führt vor jedem vertrauenswürdigen Klick einen Actionability-Pre-Flight durch (sichtbar / aktiviert / stabil + eine Verdeckungsprüfung per elementFromPoint) und fällt auf den nativen Klick zurück, sodass ein vertrauenswürdiger Klick nie unter einem Overlay oder mitten in einer Animation ausgelöst wird.

SOCKS5 mit Zugangsdaten

Standard-Chromium kann sich bei einem SOCKS5-Proxy überhaupt nicht authentifizieren — die Benutzername/Passwort-Subnegotiation ist schlicht nicht implementiert —, deshalb ist der übliche Workaround ein lokales Relay, das die Zugangsdaten hält. Der lizenzierte Build implementiert sie in der Engine (RFC 1929), ein Relay ist also nicht nötig. Übergeben Sie Benutzername und Passwort als separate Felder oder in der Adresse (socks5://user:pass@host:port); in beiden Fällen reicht das SDK sie an die Engine weiter. Zugangsdaten in der Adresse erfordern SDK 0.31.1 oder neuer: Bei älteren SDKs hat Playwright sie verworfen, und der Proxy sah keinen Login.

from clearcote import launch_persistent_context

ctx = launch_persistent_context(
    "./profile",
    proxy={"server": "socks5://proxy.example.net:1080", "username": "user", "password": "pass"},
)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://api.ipify.org?format=json")   # confirm the exit IP is the proxy's

Erfordert den lizenzierten Build (Kostenlos mit GitHub oder Pro, Engine 151 r14 oder neuer); der offene Build kann sich nicht bei einem SOCKS5-Proxy authentifizieren, verwenden Sie mit ihm also ein lokales Relay oder einen HTTP-Proxy.

Prüfen Sie immer die Exit-Adresse, bevor Sie einer Session vertrauen. Ein Proxy, der unbemerkt fail-open ausfällt, schickt den Traffic von Ihrer eigenen IP ab, und jede andere Vorsichtsmaßnahme wird bedeutungslos. Prüfen Sie die Adresse einmal beim Start gegen einen IP-Echo-Dienst, statt sie einfach vorauszusetzen.

Tipp: Leiten Sie den Seed aus Ihrer eigenen Account-/Tenant-ID ab, damit jede Identität reproduzierbar ist — gleicher Seed, gleicher Browser-Fingerprint, jedes Mal. Die vollständige Liste der Switches finden Sie unter Fingerprint-Flags.