Pular para o conteúdo

Para agentes & LLMs

O Clearcote é organizado para que ferramentas automatizadas consigam navegar, integrar e contribuir com a mesma facilidade que uma pessoa.

Coloque o projeto inteiro no seu agente

Um clique copia a documentação — todas as páginas, achatadas em um único bloco pronto para usar no prompt. Cole no Claude, no Codex ou no Cursor para ter o contexto completo do projeto.

Ver /llms-full.txt ↗

Resumo legível por máquina

Um resumo conciso do projeto, em texto puro, fica em /llms.txt, e a documentação completa, achatada em um único arquivo pronto para prompt, está em /llms-full.txt. O repositório também inclui um AGENTS.md que descreve a estrutura e as convenções para quem quer contribuir.

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

Receita mínima de integração

  1. Instale o SDK (pip install clearcote / npm i clearcote) — ele baixa e verifica o navegador.
  2. Derive uma seed de fingerprint determinística a partir da identidade em nome da qual você está agindo.
  3. Atrás de um proxy, passe geoip=True para que fuso horário, idioma e WebRTC acompanhem o IP de saída.
  4. Para frameworks que esperam uma URL CDP (browser-use, Stagehand, Crawl4AI), use serve() ou clearcote serve em vez disso.
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 o binário do build aberto diretamente com executablePath também funciona, mas o build licenciado só inicia pelo SDK, e uma inicialização direta perde os padrões do SDK — veja Playwright & Puppeteer. Para uma identidade de maior fidelidade, inicie um perfil real capturado em vez de uma seed: launch(profile="auto") escolhe, na biblioteca de perfis (build licenciado), um que combine com esta máquina; ou passe fingerprint_profile="profile.json" (Node: fingerprintProfile). Não combine um perfil com uma seed de fingerprint.

Agente de IA no navegador

O Clearcote traz um agente de IA opcional (opt-in) que controla uma página real de forma autônoma. Ele observa a página ao vivo, pergunta a um LLM configurado pelo usuário o que fazer em seguida e age por meio do framework Actor do Chrome, com eventos de entrada reais e confiáveis em vez de script injetado. Ele vem desativado por padrão (fica inativo a menos que você forneça uma chave de agente ou os switches do agente) e usa a sua própria chave: aponte-o para qualquer endpoint compatível com OpenAI / OpenRouter. Campos de senha são ocultados antes de qualquer coisa ser enviada ao modelo. Use launch_agent() (um contexto persistente) — esse é o caminho suportado.

Pelo SDK, launch_agent (Node: launchAgent) retorna um BrowserContext persistente, e run_agent_task(page, goal, max_steps=...) (Node: runAgentTask) o controla, retornando { success, finalText, steps, stepsJson }. Passe um diretório de perfil como primeiro argumento (userDataDir no Node) para reaproveitar um perfil; sem ele, cada chamada cria uma nova pasta de perfil temporária, que não é removida ao fechar. Somente 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"])

As opções de inicialização do agente correspondem diretamente a switches do binário: agent_llm_url / agentLlmUrl (--agent-llm-url), agent_llm_key / agentLlmKey (--agent-llm-key), agent_model / agentModel (--agent-model) e agent_typing / agentTyping. Uma tarefa roda assim que o agente tem uma URL (OpenRouter por padrão), uma chave e um modelo. O agente pede ao modelo uma resposta em JSON em texto puro, então o endpoint não precisa suportar tool calls; o agent_tool_mode / agentToolMode (--agent-tool-mode, CLI --tool-mode) é aceito, mas por enquanto não tem efeito.

O agent_typing / agentTyping ajusta o ritmo de digitação do agente: human (padrão) digita com timing de keydown/keyup por tecla e mantém a digitação de textos longos tecla por tecla, fast é o ritmo rápido do motor e instant digita tudo de uma vez. O padrão evita os dois indícios de digitação — timing uniforme, com precisão de máquina, e texto longo colado instantaneamente (o que não gera nenhum evento de tecla).

CLI clearcote-agent

O mesmo agente está disponível como CLI para execuções rápidas e fáceis de automatizar em scripts. Passe um objetivo avulso ou entre em um REPL interativo. A chave do modelo vem de --key ou das variáveis de ambiente $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

As opções da CLI incluem --llm-url, --model, --max-steps, --profile, --headless, --executable, --fingerprint, --proxy, --timezone e --json. Um host sem protocolo passado em --url passa a usar HTTPS.

Onde procurar

Crie identidades determinísticas: derive a seed de um ID estável (tenant, conta, tarefa) para que o mesmo ator sempre receba o mesmo fingerprint do navegador — reproduzível e fácil de depurar.