Saltar al contenido

Ejemplos

Recetas para copiar y pegar con los flujos de trabajo más comunes de Clearcote. Empieza por la más pequeña que se ajuste a tu tarea y agrega opciones solo cuando las necesites.

Las recetas se muestran para los SDKs de Python, Node y .NET (pip install clearcote / npm install clearcote / dotnet add package Clearcote). El SDK de .NET cubre los flujos principales: launch, contextos persistentes, serve, proxy, geoip (Geoip = true) y canvas bridge, con la entrada humanizada como llamadas explícitas a HumanClickAsync / HumanTypeAsync en lugar de un flag de lanzamiento; los perfiles guardados, Widevine y el agente integrado en el navegador por ahora son solo para Python & Node.

Todas las recetas ejecutan el build abierto, salvo que haya una clave de licencia configurada; con una (clearcote login, CLEARCOTE_LICENSE_KEY o license_key=), el mismo código ejecuta el build con licencia más reciente. El plan Gratis con GitHub ejecuta un navegador a la vez. Algo que sorprende a mucha gente: el motor nunca reenvía los eventos de consola ni los de errores de página, así que page.on("console") no recibe nada, por diseño; recoge la salida en la página y léela con page.evaluate().

1. Lanza un navegador verificado desde el SDK

El SDK descarga el navegador y verifica su SHA-256 la primera vez que lo usas: el build abierto por defecto, o el build con licencia más reciente si hay una clave configurada. Devuelve objetos normales de Playwright, así que el resto de tu automatización te resultará familiar. (Desde la 0.23, launch() en Python síncrono y en Node se ejecuta sobre un perfil desechable y new_context() devuelve ese mismo perfil; pasa ephemeral_profile=False / ephemeralProfile: false si necesitas contextos aislados.)

from clearcote import launch

browser = launch(fingerprint="demo:user-1", platform="windows", headless=False)
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

2. Sirve un endpoint CDP stealth para cualquier framework

serve() ejecuta Clearcote como un endpoint CDP permanente y devuelve una cdp_url. Lanza el binario directamente, sin --enable-automation, y cualquier cliente de Playwright, Puppeteer, browser-use, Crawl4AI o Stagehand se conecta por CDP sin cambiar nada del código. Abre las páginas en contexts[0] para usar el perfil servido; new_page() sobre el navegador crea un contexto aparte y aislado. Para un agente de IA, apunta Claude / Cursor / Cline al servidor clearcote-mcp (pip install clearcote-mcp, o npx -y clearcote-mcp, que necesita Python 3.10+). Desde una terminal, clearcote serve ejecuta el mismo endpoint y puede darle a cada conexión su propia identidad; consulta Despliegue.

from clearcote import serve
from playwright.sync_api import sync_playwright

srv = serve(fingerprint="demo:user-1", platform="windows")   # same persona options as launch()
print(srv.cdp_url)                                           # http://127.0.0.1:<port>

browser = sync_playwright().start().chromium.connect_over_cdp(srv.cdp_url)
page = browser.contexts[0].new_page(); page.goto("https://example.com"); print(page.title())
srv.close()

3. Una identidad estable por cuenta

Usa un seed determinista y un directorio de datos de usuario persistente. El seed mantiene estable la identidad del navegador; el directorio del perfil conserva las cookies, el almacenamiento local, los permisos y el estado de la sesión.

from clearcote import launch_persistent_context

account_id = "acct_42"

ctx = launch_persistent_context(
    rf"C:\clearcote\profiles\{account_id}",
    fingerprint=f"acct:{account_id}",
    platform="windows",
    timezone="America/New_York",
    accept_language="en-US,en",
    humanize=True,
)
page = ctx.new_page()
page.goto("https://example.com/dashboard")
ctx.close()

4. Ajusta la zona horaria, el idioma, la ubicación y WebRTC al proxy

Cuando geoip está activado, Clearcote averigua la IP de salida del proxy a través del propio proxy y completa la zona horaria, el idioma, la ubicación y la dirección WebRTC que no hayas definido a partir de una base de datos GeoIP (se descarga la primera vez que se usa, unos 50 MB). Así no tienes que ajustar a mano una zona horaria para cada proxy. Si la región no se puede resolver dentro de CLEARCOTE_GEOIP_TIMEOUT_SECONDS (20 por defecto), el lanzamiento se detiene con GeoipError en lugar de arrancar con el reloj y el idioma de esta máquina; define tanto timezone como accept_language para lanzarlo de todos modos. En .NET, usa Geoip = true.

from clearcote import launch

browser = launch(
    fingerprint="proxy:nyc:001",
    platform="windows",
    proxy={"server": "http://host:8080", "username": "user", "password": "pass"},
    geoip=True,
)
page = browser.new_page()
page.goto("https://browserleaks.com/webrtc")
browser.close()

5. Guarda y reutiliza un perfil con nombre

Un Profile guardado es útil cuando quieres una persona con nombre que varios scripts puedan compartir. Mantén los secretos fuera del control de versiones: los archivos de perfil están en texto plano.

from clearcote import Profile, launch

Profile("support-agent", {
    "fingerprint": "support-agent",
    "platform": "windows",
    "timezone": "America/Chicago",
    "accept_language": "en-US,en",
    "storage_quota": 120000,
}).save()

browser = launch(profile="support-agent", headless=False)
page = browser.new_page()
page.goto("https://example.com")
browser.close()

6. Usa el canvas bridge solo donde importa

El modo bridge se puede limitar por dominio registrable. El ejemplo de abajo pasa por el bridge las lecturas de canvas/WebGL solo en los orígenes listados y usa el renderizado local en todos los demás. Configura las cadenas de GPU con las de la GPU que renderiza (el renderer que imprime el servidor del bridge), para que la GPU reportada coincida con los píxeles que llegan por el bridge. Activar el bridge ejecuta el renderer sin el sandbox de Chromium (el SDK agrega --no-sandbox para todo el navegador, sea cual sea el modo), así que activa el bridge solo en las sesiones que lo necesiten.

from clearcote import launch

browser = launch(
    fingerprint="gpu:nvidia:seat-1",
    gpu_vendor="Google Inc. (NVIDIA)",                          # as printed by the bridge server
    gpu_renderer="ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002504) Direct3D11 vs_5_0 ps_5_0, D3D11)",
    canvas_bridge={
        "url": "ws://127.0.0.1:8443",
        "auth": "user:secret",
        "mode": "allow",
        "allow": ["example.com", "browserleaks.com"],
        "fallback": "local",
    },
)
page = browser.new_page()
page.goto("https://browserleaks.com/canvas")
browser.close()

Primero inicia el host del bridge. Consulta Canvas bridge para ver el comando del servidor, las recomendaciones de red y el comportamiento de fallback.

7. Reproduce video con DRM usando Widevine

Clearcote incluye la infraestructura de EME, pero nunca el CDM propietario de Google. widevine descarga una vez el CDM de Widevine desde el servidor de componentes de Google, lo verifica, lo instala en el perfil y lo activa, de modo que requestMediaKeySystemAccess('com.widevine.alpha') se resuelve y los streams con DRM se reproducen, como en un Chrome real.

from clearcote import launch_persistent_context

ctx = launch_persistent_context("C:\\clearcote\\profile-drm", widevine=True)
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://example.com")
# requestMediaKeySystemAccess('com.widevine.alpha') now resolves; DRM playback works
ctx.close()

Solo se activa si lo pides, por diseño: el paquete nunca distribuye el CDM de Google; eres tú quien dispara la descarga única (queda en caché en ~/.clearcote/WidevineCdm). Funciona con launch() y launch_persistent_context() en Python síncrono; en Node usa launchPersistentContext() como arriba (el tipo de TypeScript de launch() todavía no declara widevine). No funciona con el launch() asíncrono de Python, que es incógnito, ni en .NET. Seguridad por software (L3). Un navegador que se presenta como Google Chrome pero no puede responder a la consulta de Widevine es algo que cualquier página puede leer, y esa es la razón para activarlo. Consulta Widevine & DRM.

8. Descarga el navegador de antemano en CI

Llena la caché del navegador verificado antes de que arranque tu suite de tests. Así los fallos aparecen pronto, antes de que empiecen los jobs en paralelo. Sin clave, esto descarga el build abierto; con CLEARCOTE_LICENSE_KEY configurada, descarga el build con licencia. Una clave del plan Gratis con GitHub ejecuta un navegador a la vez, así que ejecuta los tests de navegador en serie o usa Pro.

- name: Install dependencies
  run: |
    python -m pip install clearcote

- name: Prefetch verified Clearcote
  run: |
    clearcote install
    clearcote info --quick

- name: Run tests
  run: |
    pytest

9. Ejecuta una tarea de agente y conserva la traza

El agente integrado en el navegador solo se activa si lo pides. Dale un directorio de perfil persistente, un endpoint/clave compatible con OpenAI y un número acotado de pasos para que la ejecución sea reproducible y revisable.

import os
from clearcote import launch_agent, run_agent_task

ctx = launch_agent(
    os.path.expanduser("~/.clearcote/agent-demo"),   # the profile directory
    fingerprint="agent-demo",
    agent_llm_key="sk-or-...",
    agent_model="openai/gpt-4o-mini",
)
page = ctx.new_page()
page.goto("https://example.com")

result = run_agent_task(page, "Find the contact page and summarize the email address", max_steps=12)
print(result["success"])
print(result["finalText"])
print(result["stepsJson"])
ctx.close()

10. Playwright directo, cuando no quieres el SDK

El SDK es el camino más cómodo, pero el build abierto es un binario normal de Chromium que puedes lanzar directamente desde Playwright o Puppeteer. El build con licencia necesita el SDK: es el que tiene el token de licencia que el motor verifica al arrancar. Los argumentos extra de abajo son los valores por defecto que, de otro modo, el SDK agregaría por ti.

javascript
import { chromium } from "playwright";

const browser = await chromium.launch({
  executablePath: "C:\\clearcote\\chrome.exe",
  headless: false,
  ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader"],   // the SDK strips these two by default
  args: [
    "--fingerprint=raw-playwright-demo",
    "--fingerprint-platform=windows",
    "--fingerprint-brand=chrome",
    "--timezone=America/New_York",
    "--accept-lang=en-US,en",
    "--lang=en-US",
    "--webrtc-ip-handling-policy=disable_non_proxied_udp",
    "--ignore-gpu-blocklist",   // the SDK pairs this with the SwiftShader strip so WebGL keeps working
  ],
});

const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();
Empieza con una receta pequeña. Agrega la importación de perfiles, el canvas bridge, el modo agente o la configuración manual de la GPU solo cuando tu flujo de trabajo realmente lo necesite.