Für Agenten & LLMs

Clearcote ist so aufgebaut, dass sich automatisierte Tools darin genauso leicht zurechtfinden, es integrieren und dazu beitragen können wie ein Mensch. Sie richten Clearcote für jemanden ein? Folgen Sie dem Setup-Runbook.

Setup-Runbook für Coding-Agenten

Wenn Sie ein KI-Coding-Agent sind (Claude Code, Codex, Cursor, Windsurf, Cline und ähnliche) und Clearcote für jemanden einrichten sollen, arbeiten Sie die folgenden Schritte der Reihe nach ab: installiert, Lizenz gesetzt, läuft, verifiziert. Jeder Schritt hat eine Prüfung, und ein Schritt ist erst erledigt, wenn seine Prüfung besteht. Halten Sie Ihren Fortschritt in einer Datei fest, damit eine neue Session oder ein Nutzer, der morgen zurückkommt, beim ersten nicht erledigten Schritt weitermacht, statt von vorn zu beginnen. Dasselbe Runbook gibt es als einzelne Markdown-Datei unter /setup.md, der Adresse, die auf der Startseite zum Einfügen in einen Agenten steht. Sie ist die maßgebliche Fassung, und dieser Abschnitt folgt ihr Überschrift für Überschrift.

Regeln

• Führen Sie jeden Befehl selbst aus und lesen Sie seine Ausgabe. Wenn ein Schritt fehlschlägt, halten Sie an und melden Sie es. Nennen Sie dem Nutzer den fehlgeschlagenen Schritt, den ausgeführten Befehl und die genaue Fehlerzeile, dazu die Lösung aus der Tabelle unten. Arbeiten Sie nicht ohne Rückfrage an einer fehlgeschlagenen Prüfung vorbei (Verifizierung überspringen, einen älteren Build festpinnen, den Build wechseln).
• Installieren Sie nur aus den offiziellen Quellen: das Paket clearcote auf PyPI, npm oder NuGet, clearcote-mcp auf PyPI und npm, das Docker-Image teamflatearth/clearcote und die Releases von clearcotelabs/clearcote-browser. Das SDK lädt den Browser selbst herunter und prüft seinen SHA-256-Hash: Holen Sie einen Browser-Build niemals von anderswo, und schalten Sie diese Prüfung niemals ab.
• Bitten Sie den Nutzer niemals, einen Lizenzschlüssel oder API-Key in den Chat einzufügen, und geben Sie einen Schlüssel nie aus, loggen oder committen Sie ihn nie. Wird trotzdem einer eingefügt, wiederholen Sie ihn nicht, schreiben Sie ihn in keine Datei, die Sie anlegen, und empfehlen Sie, ihn auf der Seite Licenses zu rotieren.
• Ist ein Link abgelaufen oder tot, suchen Sie keine Kopie. Die Download-Links, die das SDK nutzt, sind kurzlebig, und es fordert bei jedem Lauf einen neuen an; führen Sie den Befehl also erneut aus, statt eine URL wiederzuverwenden. Bei jedem anderen Link (eine Anmeldung, ein Gerätecode, eine Dashboard-Seite, ein Link, den der Nutzer weitergeleitet hat) gehen Sie dorthin zurück, woher er stammt, oder bitten den Nutzer um einen neuen. Weichen Sie niemals auf einen Mirror, eine zwischengespeicherte Kopie oder ein inoffizielles Paket aus.
• Installieren Sie in das Projekt des Nutzers (seine virtuelle Umgebung, package.json oder .csproj), nicht global, sofern der Nutzer nichts anderes wünscht. Fragen Sie, bevor Sie Konfiguration außerhalb des Projekts bearbeiten (etwa die Konfiguration eines MCP-Clients) und bevor Sie etwas starten, das Geld kostet (gehostete Browser werden pro GB abgerechnet).
• Fertig heißt: Die genaue Browser-Version ist bestätigt — nicht, dass ein Paket installiert wurde.

Eine Fortschrittsdatei führen

Legen Sie clearcote-setup.json im Projektverzeichnis an (sie enthält keine Geheimnisse) und aktualisieren Sie sie nach jeder Prüfung. route ist python, node, dotnet, mcp oder docker; build ist open (ohne Schlüssel) oder licensed („Kostenlos mit GitHub“ oder Pro); blocked hält fest, worauf Sie warten.

{
  "route": "python",
  "build": "licensed",
  "steps": {
    "installed":   { "done": true,  "checked": "2026-10-06T10:12:00Z", "evidence": "clearcote SDK 0.45.0" },
    "licence_set": { "done": false },
    "running":     { "done": false },
    "verified":    { "done": false, "browser_version": null }
  },
  "blocked": { "step": "licence_set", "waiting_for": "user approves the device sign-in" }
}

Lesen Sie zu Beginn einer Session die Datei und machen Sie beim ersten nicht erledigten Schritt weiter. Führen Sie die Prüfung jedes früheren Schritts, auf den Sie sich stützen, erneut aus, denn zwischen zwei Sessions kann ein Schlüssel ablaufen oder ein Cache geleert werden.

Schritt 0: Weg und Build wählen

Fragen Sie den Nutzer einmal und halten Sie die Antworten fest.

• Der Weg. Für den eigenen Code des Nutzers: das SDK in der Sprache des Projekts, Python 3.8+, Node 20+ oder .NET 8 (gibt es noch kein Projekt, schlagen Sie Python vor). Für Sie, den Agenten, zum Browsen: der MCP-Server (Python 3.10+). Als CDP-Endpunkt für ein bestehendes Framework: das Docker-Image.
• Der Build. Der offene Build braucht keinen Schlüssel und keine Registrierung: Chromium 150, Open Source (BSD-3), gut genug für den Anfang. Der neueste Build ist Chromium 154, mit einem Lizenzschlüssel: mit GitHub kostenlos für jeweils einen Browser oder mit Pro für bis zu 250 Browser gleichzeitig.

Der Browser läuft unter Windows x64 und Linux x64, und auch das Docker-Image ist x64. Auf macOS oder einem ARM-Rechner halten Sie an und sagen das; gehostete Browser sind die Option, die keinen lokalen Browser braucht.

Schritt 1: installiert

pip install -U clearcote                  # Python, inside the project's virtualenv
npm install clearcote                     # Node
dotnet add package Clearcote              # .NET (see below for the checks)
pip install -U clearcote clearcote-mcp    # MCP server: Python 3.10+, no mcp pin needed
docker pull teamflatearth/clearcote       # Docker

Die Prüfung: clearcote version (Node: npx clearcote version) gibt 0.45.0 oder neuer aus. Für Docker listet docker image ls teamflatearth/clearcote das Image auf.

.NET hat keinen eigenen Befehl clearcote. Prüfen Sie, dass dotnet list package Clearcote auflistet, und führen Sie dann jeden clearcote-Befehl in den Schritten 1 bis 3 als npx -y clearcote <command> (Node 20+) oder pipx run clearcote <command> (Python 3.8+) aus. Das fügt dem Projekt nichts hinzu, und der Befehl nutzt denselben Browser-Cache und dieselbe Lizenzdatei (~/.clearcote/license.key) wie das .NET-SDK. Hat der Rechner weder Node noch Python, bitten Sie den Nutzer, eines von beiden zu installieren: Ohne den Befehl lässt sich die Browser-Version nicht bestätigen und das Setup damit nicht verifizieren.

Schritt 2: Lizenz gesetzt

Für den offenen Build markieren Sie diesen Schritt mit dem Nachweis open build, no key als erledigt. Für den neuesten Build gelangt der Schlüssel auf den Rechner des Nutzers, ohne über Sie zu laufen:

• Wenn clearcote --help den Befehl clearcote login --device aufführt, führen Sie clearcote login --device aus (Node: npx clearcote login --device). Der Befehl gibt einen Link und einen kurzen Code aus. Der Nutzer öffnet den Link in seinem eigenen Browser, meldet sich an und bestätigt (ein kostenloser Schlüssel setzt ein GitHub-Konto voraus, das mindestens 30 Tage alt ist), und das SDK speichert den Schlüssel in ~/.clearcote/license.key, ohne ihn anzuzeigen.
• Andernfalls holt sich der Nutzer auf der Seite Licenses einen Schlüssel ab und führt in seinem eigenen Terminal clearcote login aus (Node: npx clearcote login), wo er den Schlüssel einfügt: Er erscheint auf seinem Bildschirm, niemals im Chat. Nennen Sie ihm diese Schritte und warten Sie, bis er sagt, dass es erledigt ist. Stattdessen kann er auch CLEARCOTE_LICENSE_KEY selbst setzen: in seinem Shell-Profil, in CI-Secrets, im env-Block seiner MCP-Client-Konfiguration oder in seiner Docker-Umgebung (docker run -e CLEARCOTE_LICENSE_KEY übergibt ihn dann, ohne dass der Wert im Befehl auftaucht).

Führen Sie clearcote login <key> niemals selbst aus: Der Schlüssel landete sonst in Ihrem Transkript und in der Shell-History. Öffnen Sie auch ~/.clearcote/license.key nicht. Die Prüfung: clearcote info --quick zeigt die Licence-Zeile als maskierten Schlüssel mit from file oder from env — mehr müssen Sie nicht sehen. none (free build) bedeutet, dass kein Schlüssel gefunden wurde. Ein Schlüssel, der nur in der Konfiguration eines MCP-Clients oder in einem Container gesetzt ist, ist für Ihre Shell unsichtbar; prüfen Sie, dass der Variablenname dort steht, ohne seinen Wert auszugeben.

Schritt 3: läuft

clearcote install    # downloads and verifies the build the key allows
clearcote info       # starts the browser once, headless

(Node: npx clearcote install und npx clearcote info.) Die Prüfung: clearcote info gibt Launch test ok mit der Browser-Version aus (mit --json: launch.ok ist true, launch.version enthält die Version und binary.tag den Build). Mit einem kostenlosen Schlüssel belegt das kurz den einen Browser-Platz, schließen Sie also vorher jeden anderen Clearcote-Browser. Danach, je nach Weg:

• SDK: Führen Sie ein erstes Script aus, clearcote_hello.py oder clearcote_hello.mjs. Die Prüfung: Es gibt Example Domain und einen Chrome-User-Agent aus und beendet sich dann. Unter .NET verwenden Sie den C#-Tab von Playwright & Puppeteer. Der fingerprint-Seed ist die Identität: Derselbe Seed ergibt jedes Mal dasselbe Gerät, verwenden Sie also einen Seed pro Konto.
• MCP-Server: Registrieren Sie den Befehl clearcote-mcp beim Client (fragen Sie vorher; geben Sie den vollständigen Pfad an, wenn er in einer virtuellen Umgebung liegt), wie unter MCP-Server beschrieben. Starten Sie den Client neu und rufen Sie dort das Tool navigate mit https://example.com auf; es liefert die finale URL und den Seitentitel.
• Docker: Starten Sie einen Container und lesen Sie sein Log und seinen Endpunkt aus, wie unten gezeigt.

import clearcote

browser = clearcote.launch(fingerprint="first-run")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
print(page.evaluate("navigator.userAgent"))
browser.close()

Schritt 4: verifiziert

Vergleichen Sie, was Schritt 3 ausgegeben hat, mit dem Build, den der Nutzer haben sollte. In Docker ist das Build-Tag Teil des Engine-Pfads in der Logzeile.

Ein Pro-Tarif, der einen älteren Build festpinnt, meldet stattdessen diesen Build. Ist es nicht der Build, den der Nutzer gewählt hat, halten Sie an und sagen Sie es ihm. Stimmt die Version, setzen Sie verified mit der Version auf erledigt und nennen dem Nutzer: den Weg, die SDK-Version, welcher Build läuft und seine genaue Browser-Version, wo das erste Script liegt und wie man es ausführt, wo der Schlüssel liegt (Datei oder Umgebungsvariable, niemals der Schlüssel selbst) sowie die Dokumentation.

Wenn ein Schritt fehlschlägt

Optional, nur wenn der Nutzer es möchte

• Ein Proxy. Übergeben Sie einen Playwright-Proxy und geoip=True, damit Zeitzone und Sprache der Exit-IP des Proxys folgen. Siehe Proxys & geoip.
• Ein Browser für Sie, den Agenten, über MCP, falls das nicht der gewählte Weg war: pip install -U clearcote-mcp (Python 3.10+), dann registrieren Sie ihn wie in Schritt 3. Für den neuesten Build findet der Server den in Schritt 2 gespeicherten Schlüssel, oder der Nutzer trägt CLEARCOTE_LICENSE_KEY selbst in den env-Block dieses Servers ein.
• Keine Rechner, auf denen es laufen kann. Gehostete Browser starten denselben Browser mit einem einzigen API-Aufruf auf den Servern von Clearcote. Sie brauchen einen API-Key und werden pro GB abgerechnet, fragen Sie also vorher.

Maschinenlesbare Zusammenfassung

Eine knappe Projektzusammenfassung als reiner Text liegt unter /llms.txt, die komplette Dokumentation als eine einzige promptfertige Datei unter /llms-full.txt. Das Repository enthält außerdem eine AGENTS.md, die Aufbau und Konventionen für Beitragende beschreibt.

{
  "name": "Clearcote",
  "kind": "anti-detect Chromium browser (the open build is open source)",
  "base": "ungoogled-chromium — open build 150 (v0.1.0-pre.23), licensed build 154.0.8037.57-r36",
  "identity_model": "engine-level, coherent seed persona + per-site render noise",
  "automation": "SDK (npm/PyPI/NuGet package clearcote) returning Playwright objects; CDP endpoint for Puppeteer and others",
  "platforms": ["windows-x64", "linux-x64"],
  "license": "BSD-3-Clause (open build + SDKs); the licensed build adds unpublished patches",
  "repo": "https://github.com/clearcotelabs/clearcote-browser",
  "verify": "open build: GPG-signed SHA256SUMS + pinned key; every SDK download: SHA-256",
  "control_via": "SDK options, or chromium command-line switches (args) on the open build"
}

Minimales Integrationsrezept

1. Installieren Sie das SDK (pip install clearcote / npm i clearcote) — es lädt den Browser herunter und verifiziert ihn.
2. Leiten Sie einen deterministischen fingerprint-Seed aus der Identität ab, in deren Namen Sie handeln.
3. Hinter einem Proxy übergeben Sie geoip=True, damit Zeitzone, Sprache und WebRTC dem Proxy-Exit folgen.
4. Für Frameworks, die eine CDP-URL erwarten (browser-use, Stagehand, Crawl4AI), nutzen Sie stattdessen serve() oder clearcote serve.

from clearcote import launch

task_id = "1234"
SEED = "agent:" + task_id          # stable, reproducible identity per task

browser = launch(fingerprint=SEED, geoip=True, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

Die Binary des offenen Builds direkt über executablePath zu steuern funktioniert ebenfalls, aber der lizenzierte Build startet nur über das SDK, und bei einem direkten Start fehlen die Standardeinstellungen des SDK — siehe Playwright & Puppeteer. Für eine originalgetreuere Identität starten Sie statt mit einem Seed mit einem echten, erfassten Profil: launch(profile="auto") wählt aus der Profilbibliothek (lizenzierter Build) eines, das zu diesem Rechner passt, oder Sie übergeben fingerprint_profile="profile.json" (Node: fingerprintProfile). Kombinieren Sie ein Profil nicht mit einem fingerprint-Seed.

KI-Agent im Browser

Clearcote bringt einen optionalen KI-Agenten mit, den Sie ausdrücklich einschalten müssen und der eine echte Seite selbstständig steuert. Er erfasst die Live-Seite, fragt ein von Ihnen konfiguriertes LLM, was als Nächstes zu tun ist, und handelt über Chromes Actor-Framework mit echten, vertrauenswürdigen Eingabe-Events statt mit injiziertem Script. Er ist standardmäßig aus (inaktiv, solange Sie keinen Agent-Schlüssel und keine Agent-Switches angeben) und arbeitet mit Ihrem eigenen Schlüssel: Richten Sie ihn auf einen beliebigen OpenAI-kompatiblen / OpenRouter-Endpunkt. Passwortfelder werden geschwärzt, bevor irgendetwas an das Modell geht. Nutzen Sie launch_agent() (ein persistenter Kontext) — das ist der unterstützte Weg.

Im SDK liefert launch_agent (Node: launchAgent) einen persistenten BrowserContext, und run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) steuert ihn und gibt { success, finalText, steps, stepsJson } zurück. Übergeben Sie ein Profilverzeichnis als erstes Argument (in Node userDataDir), um ein Profil wiederzuverwenden; ohne Profilverzeichnis legt jeder Aufruf einen neuen temporären Profilordner an, der beim Schließen nicht entfernt wird. Nur Python & Node.

import os
from clearcote import launch_agent, run_agent_task

# Returns a persistent BrowserContext.
ctx = launch_agent(
    agent_llm_key=os.environ["OPENROUTER_API_KEY"],   # required: the SDK does not read env vars (the CLI does)
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(
    page,
    goal="Find the pricing page and read the cheapest plan",
    model="openai/gpt-4o-mini",                # optional per-task override
    max_steps=20,
)
print(result["success"], result["finalText"], result["steps"])

Die Startoptionen des Agenten entsprechen direkt Switches der Binary: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) sowie agent_typing / agentTyping. Ein Task läuft, sobald der Agent eine URL (standardmäßig OpenRouter), einen Schlüssel und ein Modell hat. Der Agent bittet das Modell um eine JSON-Antwort als reinen Text, der Endpunkt braucht also keine Tool-Call-Unterstützung; agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) wird akzeptiert, hat derzeit aber keine Wirkung.

agent_typing / agentTyping stellt den Tipprhythmus des Agenten ein: human (Standard) tippt mit keydown/keyup-Timing pro Taste und gibt auch lange Texte Taste für Taste ein, fast ist der schnelle Engine-Rhythmus, und instant gibt alles auf einmal ein. Der Standard vermeidet die beiden typischen Tipp-Erkennungsmerkmale — gleichförmiges, maschinell perfektes Timing und lange Texte, die sofort eingefügt werden (was keinerlei Tastatur-Events erzeugt).

Die CLI clearcote-agent

Derselbe Agent steht als CLI für schnelle, skriptbare Läufe bereit. Übergeben Sie ein einmaliges Ziel oder wechseln Sie in eine interaktive REPL. Der Modellschlüssel kommt aus --key oder aus den Umgebungsvariablen $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY.

# One-shot: run a single goal against a URL, then exit
clearcote-agent --goal "Accept cookies and list the top 3 headlines" --url https://example.com

# Interactive REPL: keep the browser open and issue goals one at a time
clearcote-agent -i

# Use a custom endpoint/model, persistent profile, proxy and step cap
clearcote-agent --llm-url http://localhost:8000/v1 --model local/model \
  --profile ~/.clearcote/agent-profile --proxy http://user:pass@host:8080 \
  --max-steps 12 --goal "Open the dashboard" --url example.com

# Provide the key explicitly (otherwise read from the environment)
clearcote-agent --key sk-or-... --json \
  --goal "Search for 'clearcote' and open the first result" --url https://example.com

Zu den CLI-Optionen gehören --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone und --json. Ein bloßer Host, der an --url übergeben wird, wird auf HTTPS hochgestuft.

Wo Sie was finden

• Fingerprint-Flags — die vollständige Switch-Referenz (auch maschinenfreundlich).
• Playwright & Puppeteer — Start-Muster als Drop-in-Ersatz.
• Beispiele — Rezepte zum Kopieren für SDK, Profile, Proxys, Canvas-Bridge, CI und Agenten.
• KI-Agent im Browser — selbstständige Seitensteuerung per Opt-in und die CLI clearcote-agent.
• MCP-Server — Clearcote aus Claude Desktop, Cursor oder Cline steuern.
• Deployment — clearcote serve: eine CDP-URL, eine eigene Identität pro Verbindung.
• Empfehlungen — welche Einstellungen Sie aktivieren und welche Sie besser in Ruhe lassen.
• Verifizierung — die Binary prüfen, bevor Sie sie ausführen.
• Quellcode-Repository — Patches, Build-Pipeline, AGENTS.md.

Bauen Sie deterministische Identitäten: Leiten Sie den Seed aus einer stabilen ID ab (Mandant, Konto, Task), damit derselbe Akteur immer denselben Browser-Fingerprint bekommt — reproduzierbar und gut zu debuggen.