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.

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 149 (v0.1.0-pre.22), licensed build 153.0.8010.36-r28",
  "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.