Saltar al contenido

Para agentes & LLM

Clearcote está organizado para que las herramientas automatizadas puedan recorrerlo, integrarlo y contribuir con la misma facilidad que una persona.

Dale el proyecto completo a tu agente

Con un clic copias la documentación: todas las páginas, aplanadas en un solo bloque listo para usar como prompt. Pégalo en Claude, Codex o Cursor para darle el contexto completo del proyecto.

Ver /llms-full.txt ↗

Resumen legible por máquinas

En /llms.txt hay un resumen conciso del proyecto en texto plano, y en /llms-full.txt está toda la documentación aplanada en un único archivo listo para usar como prompt. El repositorio también incluye un AGENTS.md que describe la estructura y las convenciones para quienes contribuyen.

json
{
  "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"
}

Receta mínima de integración

  1. Instala el SDK (pip install clearcote / npm i clearcote): descarga y verifica el navegador.
  2. Deriva un seed de fingerprint determinista a partir de la identidad con la que actúas.
  3. Detrás de un proxy, pasa geoip=True para que la zona horaria, el idioma y WebRTC sigan a la salida del proxy.
  4. Para los frameworks que piden una URL de CDP (browser-use, Stagehand, Crawl4AI), usa en su lugar serve() o clearcote serve.
python
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")

Controlar directamente el binario del build abierto con executablePath también funciona, pero el build con licencia solo se inicia a través del SDK, y un lanzamiento directo pierde los valores por defecto del SDK; consulta Playwright & Puppeteer. Para una identidad más fiel, lanza un perfil real capturado en lugar de un seed: launch(profile="auto") elige de la biblioteca de perfiles (build con licencia) uno que encaje con esta máquina, o pasa fingerprint_profile="profile.json" (Node: fingerprintProfile). No combines un perfil con un seed de fingerprint.

Agente de IA integrado en el navegador

Clearcote incluye un agente de IA opcional —solo funciona si lo activas— que controla una página real de forma autónoma. Percibe la página en vivo, le pregunta a un LLM configurado por el usuario qué hacer a continuación y actúa a través del framework Actor de Chrome con eventos de entrada reales y de confianza (trusted), no con scripts inyectados. Está desactivado por defecto (inactivo salvo que proporciones una clave de agente o los switches del agente) y funciona con tu propia clave: apúntalo a cualquier endpoint compatible con OpenAI / OpenRouter. Los campos de contraseña se ocultan antes de enviar nada al modelo. Usa launch_agent() (un contexto persistente): es la vía soportada.

Desde el SDK, launch_agent (Node: launchAgent) devuelve un BrowserContext persistente, y run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) lo controla y devuelve { success, finalText, steps, stepsJson }. Pasa un directorio de perfil como primer argumento (userDataDir en Node) para reutilizar un perfil; sin él, cada llamada crea una carpeta de perfil temporal nueva que no se elimina al cerrar. Solo Python & Node.

python
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"])

Las opciones de lanzamiento del agente se corresponden directamente con switches del binario: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) y agent_typing / agentTyping. Una tarea se ejecuta cuando el agente tiene una URL (OpenRouter por defecto), una clave y un modelo. El agente le pide al modelo una respuesta JSON en texto plano, así que el endpoint no necesita soporte de tool calls; agent_tool_mode / agentToolMode (--agent-tool-mode, en la CLI --tool-mode) se acepta, pero por ahora no tiene ningún efecto.

agent_typing / agentTyping ajusta la cadencia de tecleo del agente: human (por defecto) escribe con tiempos de keydown/keyup por tecla y mantiene los textos largos tecla por tecla, fast es la cadencia rápida del motor e instant lo escribe todo de una sola vez. El valor por defecto evita las dos señales delatoras al escribir: tiempos uniformes, de una perfección mecánica, y textos largos pegados al instante (lo que no emite ningún evento de teclado).

La CLI clearcote-agent

El mismo agente está disponible como CLI para ejecuciones rápidas y fáciles de automatizar con scripts. Pásale un objetivo para una sola ejecución o entra en un REPL interactivo. La clave del modelo se toma de --key o de las variables de entorno $OPENROUTER_API_KEY / $CLEARCOTE_AGENT_KEY.

bash
# 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

Entre las opciones de la CLI están --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone y --json. Un host sin esquema que se pase a --url se convierte a HTTPS.

Dónde buscar

Crea identidades deterministas: deriva el seed de un ID estable (tenant, cuenta, tarea) para que el mismo actor reciba siempre la misma huella digital del navegador, reproducible y fácil de depurar.