Zum Inhalt springen

Beispiele

Rezepte zum Kopieren für gängige Clearcote-Workflows. Beginnen Sie mit dem kleinsten, das zu Ihrer Aufgabe passt, und ergänzen Sie Optionen erst, wenn Sie sie brauchen.

Die Rezepte zeigen die SDKs für Python, Node und .NET (pip install clearcote / npm install clearcote / dotnet add package Clearcote). Das .NET-SDK deckt die Kern-Workflows ab – Launch, persistente Kontexte, Serve, Proxy, geoip (Geoip = true) und Canvas-Bridge, wobei humanisierte Eingaben über explizite Aufrufe von HumanClickAsync / HumanTypeAsync laufen statt über ein Launch-Flag; gespeicherte Profile, Widevine und der In-Browser-Agent sind vorerst nur für Python & Node verfügbar.

Jedes Rezept nutzt den offenen Build, solange kein Lizenzschlüssel gesetzt ist; mit einem (clearcote login, CLEARCOTE_LICENSE_KEY oder license_key=) läuft derselbe Code mit dem neuesten lizenzierten Build. Mit „Kostenlos mit GitHub“ läuft jeweils nur ein Browser. Was viele überrascht: Die Engine leitet Konsolen- und Page-Error-Events grundsätzlich nicht weiter, daher empfängt page.on("console") bewusst nichts – sammeln Sie die Ausgabe in der Seite und lesen Sie sie mit page.evaluate() aus.

1. Einen verifizierten Browser aus dem SDK starten

Das SDK lädt den Browser bei der ersten Verwendung herunter und prüft ihn per SHA-256 – standardmäßig den offenen Build, den neuesten lizenzierten Build, wenn ein Schlüssel gesetzt ist. Es liefert ganz normale Playwright-Objekte, der Rest Ihrer Automatisierung bleibt also vertraut. (Seit 0.23 läuft launch() im synchronen Python und in Node auf einem Wegwerf-Profil, und new_context() gibt genau dieses Profil zurück; übergeben Sie ephemeral_profile=False / ephemeralProfile: false, wenn Sie isolierte Kontexte brauchen.)

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. Einen Stealth-CDP-Endpoint für beliebige Frameworks bereitstellen

serve() betreibt Clearcote als dauerhaft laufenden CDP-Endpoint und gibt eine cdp_url zurück. Es startet das Binary direkt – ohne --enable-automation – und jeder Client von Playwright, Puppeteer, browser-use, Crawl4AI oder Stagehand hängt sich ohne Codeänderung per CDP an. Öffnen Sie Seiten in contexts[0], um das bereitgestellte Profil zu nutzen; new_page() auf dem Browser erzeugt einen separaten, isolierten Kontext. Für einen KI-Agenten richten Sie Claude / Cursor / Cline auf den clearcote-mcp-Server (pip install clearcote-mcp oder npx -y clearcote-mcp, das Python 3.10+ voraussetzt). Aus einer Shell heraus betreibt clearcote serve denselben Endpoint und kann jeder Verbindung eine eigene Identität geben – siehe Deployment.

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. Eine stabile Identität pro Account

Verwenden Sie einen deterministischen Seed und ein persistentes User-Data-Verzeichnis. Der Seed hält die Browser-Identität stabil; das Profilverzeichnis bewahrt Cookies, Local Storage, Berechtigungen und den Session-Zustand.

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. Zeitzone, Sprache, Standort und WebRTC an einen Proxy anpassen

Ist geoip aktiviert, ermittelt Clearcote die Exit-IP des Proxys über den Proxy selbst und füllt nicht gesetzte Werte für Zeitzone, Sprache, Standort und WebRTC-Adresse aus einer GeoIP-Datenbank (wird bei der ersten Verwendung heruntergeladen, etwa 50 MB). So müssen Sie nicht für jeden Proxy von Hand eine passende Zeitzone einstellen. Lässt sich die Region nicht innerhalb von CLEARCOTE_GEOIP_TIMEOUT_SECONDS (Standard 20) auflösen, bricht der Start mit GeoipError ab, statt mit Uhrzeit und Sprache dieses Rechners zu starten; setzen Sie sowohl timezone als auch accept_language, um trotzdem zu starten. In .NET setzen Sie Geoip = true.

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. Ein benanntes Profil speichern und wiederverwenden

Ein gespeichertes Profile ist nützlich, wenn sich mehrere Skripte eine benannte Persona teilen sollen. Halten Sie Geheimnisse aus der Versionsverwaltung heraus: Profildateien liegen im Klartext vor.

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Die Canvas-Bridge nur dort einsetzen, wo es darauf ankommt

Der Bridge-Modus lässt sich auf registrierbare Domains beschränken. Das Beispiel unten leitet Canvas-/WebGL-Readbacks nur auf den aufgeführten Origins über die Bridge und rendert überall sonst lokal. Setzen Sie die GPU-Strings auf die der Render-GPU (den Renderer, den der Bridge-Server ausgibt), damit die gemeldete GPU zu den über die Bridge gelieferten Pixeln passt. Mit aktivierter Bridge läuft der Renderer ohne die Sandbox von Chromium (das SDK setzt --no-sandbox für den gesamten Browser, unabhängig vom Modus) – aktivieren Sie die Bridge also nur in Sessions, die sie brauchen.

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

Starten Sie zuerst den Bridge-Host. Serverbefehl, Hinweise zum Netzwerk und das Fallback-Verhalten finden Sie unter Canvas-Bridge.

7. DRM-Videos mit Widevine abspielen

Clearcote liefert die EME-Infrastruktur mit, aber nie Googles proprietäres CDM. widevine lädt das Widevine-CDM einmalig vom Komponentenserver von Google, verifiziert es, legt es im Profil ab und aktiviert es – dadurch wird requestMediaKeySystemAccess('com.widevine.alpha') aufgelöst, und DRM-Streams spielen ab wie in einem echten Chrome.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

Bewusst opt-in – das Paket verteilt Googles CDM nie; Sie lösen den einmaligen Download selbst aus (gecacht unter ~/.clearcote/WidevineCdm). Funktioniert mit launch() und launch_persistent_context() im synchronen Python; in Node verwenden Sie wie oben launchPersistentContext() (der TypeScript-Typ von launch() deklariert widevine noch nicht). Nicht mit dem asynchronen launch() in Python, das inkognito läuft, und nicht in .NET. Software-secure (L3). Dass ein Browser, der sich als Google Chrome ausgibt, die Widevine-Abfrage nicht beantworten kann, kann jede Seite auslesen – genau deshalb schaltet man es ein. Siehe Widevine & DRM.

8. Den Browser in der CI vorab laden

Wärmen Sie den Cache mit dem verifizierten Browser vor, bevor Ihre Test-Suite startet. So treten Fehler früh auf, noch bevor parallele Jobs beginnen. Ohne Schlüssel wird der offene Build geladen; ist CLEARCOTE_LICENSE_KEY gesetzt, der lizenzierte. Mit einem Schlüssel für „Kostenlos mit GitHub“ läuft jeweils nur ein Browser, führen Sie Browser-Tests also nacheinander aus oder nutzen Sie Pro.

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. Eine Agent-Aufgabe ausführen und den Trace behalten

Der In-Browser-Agent ist opt-in. Geben Sie ihm ein persistentes Profilverzeichnis, einen OpenAI-kompatiblen Endpoint/Key und eine begrenzte Schrittzahl mit, damit der Lauf reproduzierbar und nachvollziehbar ist.

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. Reines Playwright, wenn Sie das SDK nicht wollen

Das SDK ist der bequeme Weg, aber der offene Build ist ein normales Chromium-Binary, das Sie direkt aus Playwright oder Puppeteer starten können. Der lizenzierte Build braucht das SDK – es hält das Lizenz-Token, das die Engine beim Start prüft. Die zusätzlichen Argumente unten sind die Defaults, die das SDK sonst für Sie ergänzen würde.

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Halten Sie das Rezept zunächst klein. Profilimport, Canvas-Bridge, Agent-Modus oder manuelle GPU-Overrides fügen Sie erst hinzu, wenn Ihr Ziel-Workflow sie tatsächlich braucht.