Zum Inhalt springen

Profile, Cookie-Sync, Secrets und 2FA

Die meisten Aufgaben, die sich zu automatisieren lohnen, liegen hinter einem Login. Es gibt drei Wege, einen gehosteten Browser anzumelden, ohne ein Passwort in Ihren Code zu schreiben: einmal anmelden und die Sitzung in einem Profil behalten, vorhandene Cookies per Cookie-Sync in ein Profil kopieren, oder einen Agent-Run den Login aus Secrets eingeben lassen, die das Modell nie sieht, 2FA-Codes eingeschlossen.

Profile

Ein Profil speichert Cookies, localStorage und IndexedDB einer Sitzung unter einem Namen. Starten Sie eine Sitzung mit profile: { name: "shop-account", persist: true }, um es zu laden und beim Ende der Sitzung zurückzuspeichern, oder mit profile: "shop-account", um es schreibgeschützt zu laden. Sofern Sie weder identity noch fingerprint übergeben, bringt ein Profil auch seine eigene Identität mit: dasselbe Gerät und dieselbe Residential-IP, solange diese IP online bleibt. Die vollständigen Regeln stehen unter Profile: einmal anmelden; für das SDK siehe einen persistenten Kontext auf einem Cloud-Profil.

So sehen Sie, was ein Profil enthält, ohne dessen Werte:

bash
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
#   "name": "shop-account",
#   "cookies": 42,
#   "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211,
#   "storage": "Local Storage,IndexedDB",
#   "updatedAt": "2026-10-02T09:20:11.000Z"
# }

domains listet bis zu 50 Sites, sortiert, ohne führenden Punkt. bytes ist die komprimierte Größe. storage nennt den mitgespeicherten Site-Speicher (Local Storage, IndexedDB); bei einem Profil, das nur importierte Cookies enthält, ist es leer. Ein unbekannter Name ergibt 404 NOT_FOUND.

Kein Endpunkt gibt einen Cookie-Wert zurück. Der Inhalt eines Profils wird nur auf unseren Servern geöffnet: um einen Import zusammenzuführen, um zu zählen, was es enthält, und auf dem Server, auf dem eine Sitzung damit läuft.

Wenn Sie irgendwo bereits angemeldet sind (Ihr eigener Browser, ein lokales Clearcote, ein Playwright-Skript), kopieren Sie diese Cookies in ein Cloud-Profil, und jede Sitzung auf diesem Profil startet angemeldet:

bash
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{
    "mode": "merge",
    "cookies": [
      { "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
        "secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
    ]
  }'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211, "updatedAt": "…" }
  • Jedes gängige Cookie-Format. Das CDP-Format (Network.getCookies, Network.Cookie / CookieParam) und das Playwright-Format (context.cookies(), die cookies einer Storage-State-Datei) funktionieren unverändert; eine url kann statt domain stehen. Kein expires, expires: -1 (jeder Wert bis 0) oder session: true bedeutet ein Session-Cookie, und ein bereits abgelaufenes Cookie wird übersprungen. sameSite ist Lax, Strict oder None in beliebiger Schreibweise, und None erfordert secure: true.
  • Geprüft wie in Chrome. Ein Cookie, das Chrome ablehnen würde (ein ; in einem Wert, sameSite: "None" ohne secure, ein __Secure-- oder __Host--Cookie, das gegen dessen Regeln verstößt, ein Pfad, der nicht mit / beginnt), macht den ganzen Import zu einem 400, dessen Meldung das Cookie nennt.
  • Gespeichert werden name, value, domain (in Kleinbuchstaben), path (Standard /), secure, httpOnly, sameSite (nur wenn Sie es mitgeschickt haben) und expires (fehlt bei einem Session-Cookie). Andere Felder wie partitionKey werden verworfen.
  • mode: "merge" (Standard) fügt Ihre Cookies hinzu und ersetzt solche mit gleichem Namen, gleicher Domain und gleichem Pfad. mode: "replace" macht die Cookies des Profils genau zu der Liste, die Sie senden. In beiden Fällen bleiben localStorage und IndexedDB des Profils erhalten.
  • Limits: höchstens 5000 Cookies pro Request und 5000 im Profil nach einem Merge (400 TOO_MANY); Namen bis 256 Zeichen, Werte bis 4096, Pfade bis 1024; das ganze Profil höchstens 3.5 MB komprimiert (413 TOO_LARGE); 60 Importe pro 10 Minuten.
  • Ein Profil, das noch nicht existiert, wird angelegt. Solange eine Sitzung, die in das Profil speichert (persist: true), startet oder läuft, wird ein Import mit 409 PROFILE_IN_USE abgelehnt: Die Sitzung würde ihn beim Beenden überschreiben.
  • Importierte Session-Cookies (ohne Ablaufdatum) werden wie alle anderen in die nächsten Sitzungen geladen. Eine Sitzung, die das Profil speichert, verwirft sie, wie ein echter Browser beim Neustart; importieren Sie sie also erneut, wenn Sie sie danach noch brauchen.

Die Antwort zählt die Cookies des Profils nach dem Import (cookies) und wie viele Ihrer Cookies übernommen wurden (imported: abgelaufene Cookies und Duplikate fallen weg), und listet die ersten 50 seiner Domains, sortiert.

Von Ihrem Rechner, mit dem SDK

Der Befehl clearcote liest Cookies dort, wo Sie sie haben, und lädt nur die Domains hoch, die Sie angeben:

bash
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com

# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com

# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net

# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com
  • --domain (für mehrere wiederholen) wählt die Cookies, die ein Browser an diese Domain senden würde: ihre eigenen, die ihrer Subdomains und die ihrer übergeordneten Domains (--domain shop.example.com nimmt auch .example.com-Cookies mit, nie aber solche auf einem bloßen Suffix wie .com). Ohne --domain oder --all-domains verweigert der Befehl die Ausführung, damit nichts versehentlich alle Cookies eines Profils hochlädt.
  • --all-domains lädt alles hoch. Verwenden Sie es nur für ein Profil, das eigens für diese eine Aufgabe angelegt wurde.
  • --replace sendet mode: "replace"; standardmäßig wird zusammengeführt.
  • Im Code nimmt profiles.sync(name, …) dieselben Optionen: genau eines von from_profile, from_cdp, from_file oder login_url (Node: fromProfile, fromCdp, fromFile, loginUrl), dann domains=[…] oder all_domains=True (allDomains: true), und replace=True. Es gibt die oben beschriebene Import-Antwort zurück und wirft ValueError (in Node einen Error), ohne etwas hochzuladen, wenn kein Cookie passt.
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud

cloud = Cloud()

# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])

# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com")       # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies)  # mode="merge"

Ein Cookie ist, solange es gültig ist, so viel wert wie ein Passwort: Wer ein Session-Cookie besitzt, ist als Sie angemeldet. Laden Sie nur die Domains hoch, die die Aufgabe braucht, und nichts sonst. Manche Sites binden einen Login an das Gerät oder die IP, auf dem er erfolgt ist, und melden ein kopiertes Cookie ab; melden Sie sich bei solchen Sites stattdessen einmal innerhalb einer gehosteten Sitzung mit persist: true an.

Secrets und 2FA

Ein Agent-Run kann Werte eingeben, die das Modell nie sieht: Passwörter, Kontonummern und den aktuellen Code eines TOTP-Authenticators. Legen Sie sie in secrets ab und verweisen Sie in der Aufgabe mit {{name}} darauf:

import os
from clearcote.cloud import Cloud

run = Cloud().runs.create(
    "Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
    "Then open Orders and read the number of the latest order.",
    url="https://shop.example.com/login",
    secrets={
        "email": "me@example.com",
        "password": {"value": os.environ["SHOP_PASSWORD"]},
        "otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
    },
    schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
    profile={"name": "shop-account", "persist": True},   # next time it starts signed in
)
print(run["status"], run["result"]["output"])
Dieser Tab läuft auf Ihrem Rechner.
FeldTypBedeutung
"name": "value"stringEin einfacher Wert, der auf dem Host der url des Runs (und seinen Subdomains) eingegeben wird.
valuestringDer Wert, 1 bis 1024 Zeichen.
totpbase32 stringEin 2FA-Secret statt eines Werts: der Einrichtungsschlüssel neben dem QR-Code (Buchstaben A–Z und Ziffern 2–7, höchstens 128; Leerzeichen und Kleinbuchstaben sind erlaubt). Der Run gibt den jeweils aktuellen Code ein.
digits6 | 8Nur TOTP. Standard 6.
period30 | 60Nur TOTP, in Sekunden. Standard 30.
domainsstring[]Die Hosts, auf denen es eingegeben werden darf: 1 bis 10 Hostnamen wie example.com (mindestens zwei Labels; kein Schema, Pfad, Port und kein *), jeweils inklusive Subdomains. Standard: der Host von url.
  • Ein Secret ist ein String, { value, domains? } oder { totp, domains?, digits?, period? }. Höchstens 20 pro Run. Namen beginnen mit einem Buchstaben und bestehen aus Buchstaben, Ziffern und _, bis zu 32 Zeichen.
  • Ein {{name}} in der Aufgabe, das nicht in secrets steht, ergibt 400 (unknown secret "name"). Ebenso ein Secret ohne domains bei einem Run ohne url: Es gibt keinen Host, an den es gebunden werden kann. Schreiben Sie den Verweis genau als {{name}}, ohne Leerzeichen.
  • Ein Secret, das die Aufgabe nie erwähnt, ist erlaubt; die warnings der Antwort beim Anlegen weisen darauf hin.
  • Achten Sie auf den Host. Standardmäßig wird ein Secret an den Host von url und dessen Subdomains gebunden: https://shop.example.com/login deckt shop.example.com ab, nicht login.example.com. Liegt das Login-Formular auf einem anderen Host (Single Sign-on, ein Identity Provider), tragen Sie ihn in domains ein.
  • TOTP-Codes folgen RFC 6238 mit SHA-1, wie es Authenticator-Apps verwenden. Der Code wird erst in dem Moment berechnet, in dem er eingegeben wird, und ist daher immer der aktuelle.
  • Secrets gehören zu einem einzigen Run. Sie werden nicht mit einem Profil gespeichert und nach dem Run nicht aufbewahrt: Senden Sie sie mit dem nächsten Run erneut (oder führen Sie den nächsten auf einem angemeldeten Profil aus und überspringen Sie den Login).

Was das Modell sieht

Bevor Jet startet, wird jedes {{name}} in der Aufgabe durch einen zufälligen Platzhalter wie CCSECRET_password_k3x9qa ersetzt, und die Aufgabe erhält einen Satz, der besagt, dass Platzhalter genau so einzugeben sind, wie sie geschrieben stehen. Mehr bekommt das Modell nie. Wenn Jet einen Platzhalter eingibt, setzt die Browserschicht auf dem Server in diesem Moment den echten Wert oder den aktuellen TOTP-Code ein, und zwar nur, wenn der Host der Seite zu den domains des Secrets gehört oder eine Subdomain davon ist (bei einem Feld in einem iframe gilt das auch für den Host des Frames). Auf jedem anderen Host stoppt der Schritt mit needs_input („secret password is not allowed on other.example“), und es wird nichts eingegeben.

Alles, was zurückkommt, wird auf dieselbe Weise bereinigt: In detail, markdown, dem text jedes Schritts, dem output-JSON und den Ereignissen erscheinen der Wert eines Secrets, sein aktueller TOTP-Code und sein Platzhalter als {{name}}. Eine Folge davon: Wenn die Seite ein Secret anzeigt (etwa die E-Mail-Adresse nach der Anmeldung) und Ihr Schema danach fragt, erhalten Sie {{email}}, nicht die Adresse.

Sicherheitsmodell

Was was schützt und wo die Grenzen liegen:

  1. Ihr API-Schlüssel ist Ihr Konto. Mit ihm lassen sich Browser auf Ihr Guthaben starten, Ihre Profile verwenden und Ihre Runs lesen. Bewahren Sie ihn auf einem Server auf, nie in einem Browser oder einer App, die Sie ausliefern.
  2. Profile sind privat und verschlüsselt. Jedes wird verschlüsselt gespeichert (AES-256-GCM, mit einem Schlüssel pro Kunde) und nur auf unseren Servern geöffnet: um einen Import zusammenzuführen, um zu zählen, was es enthält, und auf dem Server, auf dem eine Sitzung damit läuft. Das gleichnamige Profil eines anderen Kunden ist ein anderes Profil. Kein Endpunkt gibt einen Cookie-Wert zurück (eine Sitzung auf dem Profil kann ihre eigenen Cookies natürlich über CDP lesen).
  3. Cookie-Sync lädt hoch, was Sie auswählen. Nur Sie können in Ihre Profile importieren, innerhalb der oben genannten Limits (5000 Cookies, 3.5 MB), und nie in eines, in das eine startende oder laufende Sitzung speichert. Die Auswahl der Domains geschieht auf Ihrer Seite: clearcote cloud profile sync und profiles.sync() verweigern das Hochladen einer ganzen Cookie-Sammlung, sofern Sie nicht --all-domains / all_domains=True übergeben.
  4. Secrets bleiben versiegelt, bis der Run startet. Sie werden auf dieselbe Weise verschlüsselt in den Einstellungen des Runs gespeichert und erst geöffnet, wenn ein Server den Run übernimmt. Sie werden diesem Server einmal übergeben, und die gespeicherten Einstellungen werden in diesem Moment gelöscht. Auf dem Server bleiben sie im Arbeitsspeicher und gehen über die Standardeingabe an den Jet-Prozess: nie in Umgebungsvariablen, Befehlszeilen, Logs oder Ereignisse. Lassen sie sich nicht mehr öffnen, wenn ein Server den Run übernimmt, endet der Run mit failed und session.endReason secrets_unreadable.
  5. Das Modell erhält nie ein Secret. Es arbeitet mit Platzhaltern, und der echte Wert wird nur auf den Hosts eingegeben, die Sie erlaubt haben. Eine Seite, die den Agenten dazu bringen will, Ihr Passwort anderswo einzugeben (Prompt Injection), bekommt einen abgelehnten Schritt, nicht das Passwort.
  6. Ausgaben werden bereinigt. Werte, TOTP-Codes und Platzhalter werden in allem, was ein Run zurückgibt oder speichert, durch {{name}} ersetzt.
  7. Jet läuft getrennt von den Zugangsdaten des Servers. Jeder Run ist ein eigener Prozess mit einer expliziten, minimalen Umgebung: Die Schlüssel des Servers und die Proxy-Zugangsdaten werden weder an ihn noch an den Browser weitergegeben. Der Browser behält die Schutzmechanismen des Hostings: keine lokalen Dateien, keine privaten Netzwerke.

Und was dies nicht abdeckt:

  • Die Site, bei der Sie sich anmelden, erhält den Wert. Darum geht es ja; wählen Sie domains mit Bedacht.
  • Die Seite kann ihn anzeigen. Nachdem ein Wert in ein gewöhnliches Feld eingegeben wurde, zeigt die Seite ihn an. Jet ersetzt einen eingegebenen Wert wieder durch seinen Platzhalter, bevor das Modell die Seite liest, aber nur dort, wo er genau so erscheint, wie er eingegeben wurde (oder URL-kodiert): Eine Seite, die ihn verändert anzeigt, etwa umformatiert oder teilweise verdeckt, wird nicht erfasst. Passwortfelder werden nie gelesen.
  • Aufzeichnungen zeigen den Bildschirm. Ein Wert in einem gewöhnlichen Feld ist im Video zu sehen. Lassen Sie record bei Logins ausgeschaltet, die Sie nicht gespeichert haben möchten.
  • Die Aufgabe ist nicht geheim. Sie wird mit dem Run gespeichert und im Dashboard und in der Run-Liste angezeigt. Schreiben Sie nie einen Wert in die Aufgabe selbst; verwenden Sie immer {{name}}.
  • Links sind Schlüssel. Ein Übergabe- oder Steuerungslink lässt jeden, der ihn hat, den Browser angemeldet steuern, bis er abläuft. Senden Sie ihn nur an die Person, die handeln soll.

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

War diese Seite hilfreich?