Zum Inhalt springen

Lokal oder Cloud: ein SDK

Dasselbe launch(), das Clearcote auf Ihrem Rechner startet, startet es auch auf unseren Servern. Übergeben Sie cloud=True (Python) oder cloud: true (Node) oder setzen Sie CLEARCOTE_CLOUD=1, und Sie erhalten dasselbe Playwright-Browser-Objekt zurück, verbunden mit einem gehosteten Browser. Der Rest Ihres Skripts bleibt, wie er ist.

Ein Skript in der Cloud ausführen

Sie brauchen SDK 0.34.0 oder neuer und einen API-Schlüssel von der Seite API keys. Legen Sie den Schlüssel in CLEARCOTE_API_KEY ab, dann:

from clearcote import launch

browser = launch(cloud=True, fingerprint="acct-1", country="de")
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
browser.close()   # ends the cloud session
Dieser Tab läuft auf Ihrem Rechner.

Hinter dem Aufruf erstellt das SDK mit POST /api/v1/browsers eine Session, verbindet sich per CDP mit ihr und richtet Humanize so ein wie bei einem lokalen Start. Öffnen Sie Seiten in browser.contexts[0]: Dieser Kontext trägt das Profil der Session. browser.new_page() funktioniert auch, öffnet aber einen separaten Kontext ohne die Cookies des Profils (das SDK schaltet auch dort den emulierten Viewport von Playwright ab, wie lokal).

Die gehostete Session hinter dem Browser finden Sie in Python unter browser.cloud_session und in Node unter cloudSessionOf(browser) (auch browser.cloudSession): die Antwort auf das Erstellen mit id, worker und expiresAt, ohne die nur einmal gültige connectUrl. Mit der id nutzen Sie den Cloud-Client für die Übergabe sowie für Aufzeichnungen und Ereignisse.

Per Umgebungsvariable umschalten

Lassen Sie cloud im Aufruf weg, dann entscheidet die Umgebung. So läuft ein und dasselbe Skript auf Ihrem Laptop lokal und in der Produktion in der Cloud, ohne Codeänderung.

VariableBedeutung
CLEARCOTE_CLOUD1, true oder yes: Ein launch() ohne cloud-Argument startet einen Cloud-Browser. Jeder andere Wert oder nicht gesetzt: einen lokalen.
CLEARCOTE_API_KEYIhr cc_live_…-Schlüssel. Für jeden Cloud-Aufruf nötig.
CLEARCOTE_API_URLDie API, mit der gesprochen wird. Standard https://www.clearcotelabs.com; ändern Sie das nur für eine Control Plane in der Entwicklung. Sie muss https:// sein; einfaches http:// wird nur für diesen Rechner akzeptiert (localhost, 127.0.0.1, ::1), damit der Schlüssel nie unverschlüsselt durch ein Netzwerk geht.
bash
export CLEARCOTE_API_KEY=cc_live_...

python scrape.py                     # a local browser
CLEARCOTE_CLOUD=1 python scrape.py   # the same script on a hosted browser

Ein explizites Argument gewinnt immer: cloud=False / cloud: false startet lokal, egal was CLEARCOTE_CLOUD sagt.

Optionen

Im Cloud-Modus nimmt launch() die Optionen von POST /api/v1/browsers. Node verwendet die Namen der API unverändert; Python verwendet snake_case, und das SDK benennt sie um. Die vollständigen Regeln zu jeder Option stehen in der Referenz Gehostete Browser.

PythonNode und APIBedeutung
identityidentityEin Label pro Konto: dasselbe Gerät und dieselbe Residential-IP, solange diese IP online bleibt.
fingerprintfingerprintGeräte-Seed. Derselbe Seed ergibt dasselbe Geräteprofil.
light_stealthlightStealthStandard true.
platformplatformwindows, macos, linux oder android.
brandbrandChrome, Edge, Opera oder Vivaldi.
timezonetimezoneIANA-Name, zum Beispiel Europe/Berlin.
locale, accept_languagelocaleAccept-Language, zum Beispiel de-DE,de. accept_language (Node: acceptLanguage) ist ein Alias.
geoIdentitygeoIdentityDefault "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event.
geoipgeoipZeitzone und Sprache richten sich nach der Exit-IP.
proxyproxy"managed" (der Standard), { server, username, password } oder eine URL wie http://user:pass@host:8080, die das SDK für Sie in dieses Objekt zerlegt.
countrycountryExit-Land im verwalteten Residential-Pool.
statestateExit-Bundesland oder -Region im verwalteten Pool. Erfordert country.
citycityExit-Stadt im verwalteten Pool. Erfordert state.
proxy_sessionproxySessionSticky-Label: Dasselbe Label bekommt später dieselbe Exit-IP zurück.
timeout_sectimeoutSecFeste Obergrenze für die Dauer der Session, in Sekunden.
idle_timeout_secidleTimeoutSecBeendet die Session, wenn so lange kein CDP-Befehl kommt.
max_gbmaxGbStoppt die Session nach so viel Traffic.
headlessheadlessStandard true. Mit false (ein echtes Fenster) meldet die Seite das Display des Servers, nicht die Bildschirmgröße der Identität.
humanizehumanizeDefault true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input".
keep_alivekeepAliveLässt den Browser weiterlaufen, nachdem Sie die Verbindung getrennt haben.
versionversionEin bestimmtes Clearcote-Release starten.
profileprofileEin Cloud-Profil: "name" lädt es, { name, persist: true } speichert es außerdem zurück.
urlurlWird im ersten Tab geöffnet, bevor Sie den Browser bekommen.
adblockadblockBlockiert bekannte Werbe- und Tracker-Hosts, bevor sie laden.
solve_sliderssolveSlidersStandard true: Slide-to-verify-Challenges werden für Sie gezogen. false schaltet das ab; SDK 0.35.0 und älter lehnen den Namen ab (dort ist es immer an).
solve_checkboxessolveCheckboxesStandard true: Checkboxen der Art „verify you are human“ werden für Sie angeklickt. false schaltet das ab; SDK 0.36.2 und älter lehnen den Namen ab (dort ist es immer an).
solve_press_holdsolvePressHoldStandard true: „Press and hold“-Prüfknöpfe werden für Sie gedrückt gehalten, bis sie fertig melden. false schaltet das ab; SDK 0.49.0 und älter lehnen den Namen ab (dort ist es immer an).
challenge_servicechallengeServiceStandard aus. true oder { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur } (Python nimmt auch max_solves, max_spend_eur, api_key): Challenges, die die kostenlosen Aktionen nicht lösen, gehen an einen Lösungsdienst, mit Ihrem Schlüssel oder unserem. Erfordert SDK 0.38.0 oder neuer.
recordrecordZeichnet die Session als MP4 auf.
notenoteIhr eigenes Label für die Session.
workerworkerStartet auf demselben Server wie eine frühere Session.
humanizehumanizeNicht gesetzt oder True (SDK 0.44.0+): das Humanize des SDK selbst für Maus, Tastatur und Scrollen, wie bei einem lokalen Start, das des Servers ist dabei aus. False: keins. Vor 0.44.0 überließ ein nicht gesetzter Wert das dem gehosteten Browser, der nur die Maus bewegt.
show_cursorshowCursorZeigt einen roten Punkt, der der Maus folgt, zum Zuschauen oder Debuggen. Läuft im SDK, wie humanize.
api_key, api_urlapiKey, apiUrlDas Konto und der API-Server für diesen Start. Standard CLEARCOTE_API_KEY und CLEARCOTE_API_URL. Werden nie als Optionen gesendet.
timeout, slow_motimeout, slowMoDie eigenen Optionen von Playwright für die CDP-Verbindung, in Millisekunden. Werden nicht an die API gesendet.

Was gleich bleibt, was sich unterscheidet

Gleich:

  • Sie bekommen ein Playwright-Objekt. launch() gibt einen Browser zurück und launch_persistent_context() einen BrowserContext, synchron oder asynchron, genau wie lokal.
  • Menschliche Eingaben sind standardmäßig an. Ab SDK 0.44.0 übernimmt bei einem Cloud-Start das SDK das Humanize, wie bei einem lokalen Start mit humanize=True: Die Maus bewegt sich auf menschlichen Bahnen, Tasten werden einzeln getippt, gescrollt wird in Mausrad-Rasten, und Klicks auf Koordinaten spielt die Engine selbst ab. Jeder Schritt geht über das Netzwerk, daher ist das langsamer als einfache Eingaben; übergeben Sie humanize=False für einfache, schnelle Eingaben. In beiden Fällen schaltet der Start die eigene Mausbewegung des gehosteten Browsers ab, sodass nur einer von beiden den Cursor bewegt. Clients, die sich ohne das SDK verbinden, behalten die des gehosteten Browsers: Sie führt die Maus auf dem Server, hält jeden Klick so lange wie ein menschlicher Druck und zerlegt großes Scrollen in ganze Mausrad-Rasten.
  • Dieselbe Engine. Gehostete Sessions laufen mit denselben Clearcote-Releases, die das SDK herunterlädt. Die Persona-Optionen bedeuten also an beiden Orten dasselbe, und version pinnt denselben Build.

Anders:

  • Nur-lokale Optionen werden abgelehnt. executable_path, args, user_data_dir, extensions, ignore_default_args und die anderen Optionen, die nur für ein Binary auf Ihrem Rechner Sinn ergeben, lösen in Python ValueError("<name> is not available for cloud browsers") aus (in Node einen Fehler mit derselben Meldung), statt ignoriert zu werden.
  • Profile statt Ordner. Ein Cloud-Browser hat keinen Ordner auf Ihrer Festplatte. Um Cookies und Website-Speicher zwischen Läufen zu behalten, verwenden Sie ein benanntes Cloud-Profil (siehe unten).
  • profile bedeutet ein Cloud-Profil. Lokal wählt profile ein erfasstes Geräteprofil ("auto"). Im Cloud-Modus benennt es ein gespeichertes Cloud-Profil: Cookies, localStorage und IndexedDB.
  • Gehostete Standardwerte. Eine Cloud-Session startet mit den gehosteten Standardwerten: eine Windows-Persona, lightStealth an, ein Seed, Zeitzone und Sprache, die sich nach der Exit-IP richten, das Widevine-Modul, das ein Google Chrome hat, menschliche Mausbewegung und eine Residential-Exit-IP, sofern Sie keinen eigenen proxy übergeben.
  • Schließen. browser.close() trennt die Verbindung, und die Session endet, sobald ihr Client weg ist; zur Sicherheit stoppt das SDK sie zusätzlich über die API. Mit keep_alive / keepAlive läuft der Browser stattdessen weiter, bis Sie ihn stoppen oder ein Limit greift.
  • Gehostete Limits. Kein file://, keine Erweiterungen, keine privaten Netzwerke, Downloads werden über die Verbindung geholt (siehe Dateien herunterladen), und page.on("console") bleibt stumm. Siehe die Limits.
  • Abrechnung. Ein Cloud-Browser wird wie jede gehostete Session abgerechnet, pro GB Traffic aus Ihrem Prepaid-Guthaben. Ein lokaler Browser kostet nichts über Ihre Lizenz hinaus.

Ein persistenter Kontext auf einem Cloud-Profil

launch_persistent_context() mit cloud=True nimmt statt eines Ordners einen Profilnamen. Es gibt den ersten Kontext einer Cloud-Session zurück, die mit profile: { name, persist: true } gestartet wurde: Die Session lädt das Profil, und das Schließen des Kontexts beendet die Session und speichert Cookies und Website-Speicher zurück ins Profil.

from clearcote import launch_persistent_context

ctx = launch_persistent_context(cloud=True, profile="shop-account", country="de")
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://shop.example.com/account")
ctx.close()   # ends the session and saves "shop-account"
Dieser Tab läuft auf Ihrem Rechner.

Wer zusammen mit cloud=True ein user_data_dir übergibt, erhält einen ValueError, der auf profile= verweist. Es kann immer nur eine Session gleichzeitig in ein Profil speichern. Um ein Profil aus Cookies zu starten, die Sie schon haben, verwenden Sie den Cookie-Sync.

Der Cloud-Client

Für alles andere, was die API kann, gibt es einen Client: Sessions, Agent-Runs, Profile und Webhooks. Er liest CLEARCOTE_API_KEY und CLEARCOTE_API_URL oder nimmt sie als Argumente. Der Python-Client nutzt nur die Standardbibliothek; AsyncCloud hat dieselben Methoden für asyncio.

from clearcote.cloud import Cloud, CloudError

cloud = Cloud()   # or Cloud(api_key="cc_live_...", base_url="https://www.clearcotelabs.com")

session = cloud.browsers.create(country="de", record=True)
print(session["id"], session["connectUrl"])

try:
    cloud.browsers.stop(session["id"])
except CloudError as e:
    print(e.status, e.code, e.message)
Dieser Tab läuft auf Ihrem Rechner.
NamespaceMethoden
browserscreate(**options), get(id), list(status=None, note=None, limit=None, before=None), stop(id), live(id, control=False), share(id, control=None, minutes=None, recording=None), handoff(id, reason=None, timeout_sec=None), handoff_done(id), wait_handoff(id, timeout=None, poll=2.0), events(id, after=0, limit=None), recording_url(id), download_recording(id, path)
runscreate(task, url=None, schema=None, secrets=None, wait=True, timeout=None, poll=1.5, on_update=None, **options), get(id), list(limit=None, before=None), cancel(id), wait(id, timeout=None, poll=1.5, on_update=None)
profileslist(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …)
webhookscreate(url, events=None, description=None), list(), delete(id), test(id)

Jede Methode gibt das JSON des Endpoints unverändert zurück: ein Dict in Python, ein einfaches Objekt in Node. List-Aufrufe geben das Objekt der API zurück, zum Beispiel { balanceEur, sessions } oder { runs }, keine nackte Liste. Wartezeiten, die das SDK selbst abwartet (timeout, poll), sind in beiden Sprachen in Sekunden angegeben.

Node hat dieselben Methoden in camelCase (handoffDone, waitHandoff, importCookies, recordingUrl, downloadRecording), mit den optionalen Argumenten in einem Objekt: live(id, { control }), events(id, { after, limit }), runs.create(task, { url, schema, country, … }), importCookies(name, cookies, { mode }), webhooks.create(url, { events }). Ein fehlgeschlagener Aufruf löst CloudError aus, mit dem HTTP-status (0, wenn die API nicht erreichbar war), dem code der API und ihrer message; die Codes sind unter Fehler aufgeführt. Ein Warten, das über sein timeout hinausläuft, löst stattdessen CloudTimeoutError aus, dessen last den letzten Zustand enthält, den das SDK gelesen hat; der Run oder die Übergabe läuft auf dem Server weiter. Eine ungültige Option löst in Python ValueError aus (in Node einen Error), bevor irgendetwas gesendet wird. Das SDK exportiert außerdem verify_webhook / verifyWebhook für Webhook-Signaturen.

Der Befehl clearcote cloud

Der Befehl clearcote, der mit dem SDK kommt (pip install clearcote oder npx clearcote), hat eine Gruppe cloud für dieselbe API:

bash
# an agent run: prints the result when it finishes
clearcote cloud run "Find the price of the cheapest plan" --url https://example.com/pricing \
  [--schema schema.json] [--secret name=value]... [--secret-domain name=host]... [--handoff] [--record] [--json]

# sessions
clearcote cloud sessions
clearcote cloud stop <id>
clearcote cloud events <id>
clearcote cloud recording <id> -o session.mp4

# copy cookies into a cloud profile (--domain or --all-domains is required)
clearcote cloud profile sync <name> (--from-profile DIR | --from-cdp URL | --from-file state.json | --login URL) \
  (--domain example.com... | --all-domains) [--replace]

# webhooks
clearcote cloud webhooks add https://example.com/hooks/clearcote [--event run.finished]...
clearcote cloud webhooks list
clearcote cloud webhooks rm <id>
clearcote cloud webhooks test <id>

Jeder Befehl nimmt --json, um statt einer Zusammenfassung die Antwort der API auszugeben. run wartet auf das Ergebnis und endet nur dann mit 0, wenn der Run succeeded ist (sonst 1, 2 bei einem Bedienfehler), so funktioniert er in einem Shell-Skript. recording speichert ohne -o nach <id>.mp4. Führen Sie clearcote cloud --help aus, um alle Flags zu sehen.

Jeder Befehl hat seine eigene Seite: Agent-Runs, Aufzeichnungen und Ereignisse, Profil-Sync und Webhooks.

MCP: ein Cloud-Browser für Ihren KI-Assistenten

Der MCP-Server hat denselben Schalter. Mit CLEARCOTE_CLOUD=1 und CLEARCOTE_API_KEY in seinem env ist der gemeinsame Browser, den seine Tools steuern, ein Cloud-Browser. Ist ein API-Schlüssel gesetzt, bekommt er außerdem ein Tool run_task, das eine ganze Aufgabe an einen Agent-Run übergibt und das Ergebnis-JSON zurückgibt.

json
{
  "mcpServers": {
    "clearcote": {
      "command": "npx",
      "args": ["-y", "clearcote-mcp"],
      "env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
    }
  }
}

Aktualisiert am 18. Okt. 2026 · SDK 0.70.5 · Browser r63

War diese Seite hilfreich?