Pular para o conteúdo

Local ou na nuvem: um só SDK

O mesmo launch() que inicia o Clearcote na sua máquina o inicia nos nossos servidores. Passe cloud=True (Python) ou cloud: true (Node), ou defina CLEARCOTE_CLOUD=1, e você recebe o mesmo Browser do Playwright, conectado a um navegador hospedado. O resto do seu script continua igual.

Execute um script na nuvem

Você precisa do SDK 0.34.0 ou mais recente e de uma chave de API da página API keys. Coloque a chave em CLEARCOTE_API_KEY e então:

from clearcote import launch

browser = launch(cloud=True, fingerprint="acct-1", country="de")
page = browser.contexts[0].new_page()
page.goto("https://example.com")
print(page.title())
browser.close()   # ends the cloud session
Esta aba roda na sua máquina.

Por trás da chamada, o SDK cria uma sessão com POST /api/v1/browsers, conecta-se a ela via CDP e configura o humanize como faz uma inicialização local. Abra as páginas em browser.contexts[0]: ele carrega o perfil da sessão. browser.new_page() também funciona, mas abre um contexto separado sem os cookies do perfil (o SDK ainda desliga nele o viewport emulado do Playwright, como faz localmente).

A sessão hospedada por trás do navegador fica em browser.cloud_session no Python e em cloudSessionOf(browser) no Node (também browser.cloudSession): a resposta da criação com seu id, worker e expiresAt, sem a connectUrl de uso único. Use o id com o cliente Cloud para a transferência e para gravações e eventos.

Alterne com variáveis de ambiente

Deixe cloud fora da chamada e o ambiente decide: assim, um mesmo script roda localmente no seu notebook e na nuvem em produção, sem mudar o código.

VariávelSignificado
CLEARCOTE_CLOUD1, true ou yes: um launch() sem argumento cloud inicia um navegador na nuvem. Qualquer outro valor, ou não definida: um local.
CLEARCOTE_API_KEYSua chave cc_live_…. Necessária em toda chamada à nuvem.
CLEARCOTE_API_URLA API com que falar. Padrão https://www.clearcotelabs.com; mude só para um control plane de desenvolvimento. Precisa ser https://; http:// simples só é aceito para esta máquina (localhost, 127.0.0.1, ::1), para que a chave nunca atravesse uma rede sem criptografia.
bash
export CLEARCOTE_API_KEY=cc_live_...

python scrape.py                     # a local browser
CLEARCOTE_CLOUD=1 python scrape.py   # the same script on a hosted browser

Um argumento explícito sempre vence: cloud=False / cloud: false inicia localmente, independentemente do que diga CLEARCOTE_CLOUD.

Opções

No modo nuvem, launch() aceita as opções de POST /api/v1/browsers. O Node usa os nomes da API como estão; o Python usa snake_case, e o SDK os renomeia. As regras completas de cada opção estão na referência de navegadores hospedados.

PythonNode e APISignificado
identityidentityUm rótulo por conta: o mesmo dispositivo e o mesmo IP residencial enquanto esse IP continuar online.
fingerprintfingerprintSeed do dispositivo. O mesmo seed gera o mesmo perfil de dispositivo.
light_stealthlightStealthPadrão true.
platformplatformwindows, macos, linux ou android.
brandbrandChrome, Edge, Opera ou Vivaldi.
timezonetimezoneNome IANA, por exemplo Europe/Berlin.
locale, accept_languagelocaleAccept-Language, por exemplo de-DE,de. accept_language (Node: acceptLanguage) é um alias.
geoIdentitygeoIdentityDefault "strict". Timezone, languages, Accept-Language, location and WebRTC address are resolved together from the exit IP, and checked against each other and against what you set, before the browser starts. strict: a contradiction refuses the launch: the connect answers 422 with the GEO_* code, and the session ends (not billed) with endReason geo_refused:<code>. warn and auto: the browser starts and the finding is reported. manual: your values as given, checked but never derived. off: the behaviour of geoip before geoIdentity. acknowledge: GEO_* codes you accept on purpose. localePolicy: "weighted" (the default: a fingerprint seed may draw any widely used language of the exit country) or "majority". The identity the browser presents is in the session.started event.
geoipgeoipO fuso horário e o idioma seguem o IP de saída.
proxyproxy"managed" (o padrão), { server, username, password } ou uma URL como http://user:pass@host:8080, que o SDK divide nesse objeto para você.
countrycountryPaís de saída no pool residencial gerenciado.
statestateEstado ou região de saída no pool gerenciado. Requer country.
citycityCidade de saída no pool gerenciado. Requer state.
proxy_sessionproxySessionRótulo sticky: o mesmo rótulo recebe o mesmo IP de saída de volta mais tarde.
timeout_sectimeoutSecLimite rígido da duração da sessão, em segundos.
idle_timeout_secidleTimeoutSecEncerra a sessão após esse tempo sem nenhum comando CDP.
max_gbmaxGbPara a sessão após essa quantidade de tráfego.
headlessheadlessPadrão true. Com false (uma janela real), a página informa a tela do próprio servidor, não o tamanho de tela da identidade.
humanizehumanizeDefault true. Your mouse moves along human paths: when a move or click lands far from the cursor, the server running the browser first walks there the way a hand would, pauses a moment before the press and holds each click for a human press time. A scroll of more than one wheel notch (100 px) arrives as whole notches at a human pace, and the page still scrolls exactly the distance you asked. Works for any client (Playwright, Puppeteer, raw CDP); drags, keys and touch are left as sent. false turns it off. See "Human input".
keep_alivekeepAliveMantém o navegador rodando depois que você se desconecta.
versionversionExecuta uma versão específica do Clearcote.
profileprofileUm perfil na nuvem: "name" para carregá-lo, { name, persist: true } para também salvá-lo de volta.
urlurlAberta na primeira aba antes de você receber o navegador.
adblockadblockRecusa hosts conhecidos de anúncios e rastreadores antes que carreguem.
solve_sliderssolveSlidersPadrão true: os desafios “slide to verify” são arrastados para você. false desativa isso; o SDK 0.35.0 e anteriores recusam o nome (para eles fica sempre ativo).
solve_checkboxessolveCheckboxesPadrão true: as caixas de seleção “verify you are human” são clicadas para você. false desativa isso; o SDK 0.36.2 e anteriores recusam o nome (para eles fica sempre ativo).
solve_press_holdsolvePressHoldPadrão true: os botões de verificação “press and hold” são mantidos pressionados para você até indicarem que terminaram. false desativa isso; o SDK 0.49.0 e anteriores recusam o nome (para eles fica sempre ativo).
challenge_servicechallengeServiceDesativado por padrão. true, ou { categories, sites, key, apiKey, mode, maxSolves, maxSpendEur } (Python também aceita max_solves, max_spend_eur, api_key): os desafios que as ações gratuitas não conseguem resolver vão para um serviço de resolução, com a sua chave ou a nossa. Requer o SDK 0.38.0 ou mais recente.
recordrecordGrava um MP4 da sessão.
notenoteSeu rótulo para a sessão.
workerworkerInicia no mesmo servidor de uma sessão anterior.
humanizehumanizeNão definido ou True (SDK 0.44.0+): o humanize do próprio SDK, com mouse, teclado e rolagem, como em uma inicialização local, com o do servidor desligado. False: nenhum. Antes da 0.44.0, não definido deixava isso para o navegador hospedado, que move apenas o mouse.
show_cursorshowCursorMostra um ponto vermelho que segue o mouse, para acompanhar ou depurar. Do lado do SDK, como humanize.
api_key, api_urlapiKey, apiUrlA conta e o servidor de API desta inicialização. Padrão CLEARCOTE_API_KEY e CLEARCOTE_API_URL. Nunca enviados como opções.
timeout, slow_motimeout, slowMoAs opções próprias do Playwright para a conexão CDP, em milissegundos. Não enviadas à API.

O que continua igual e o que muda

Igual:

  • Você recebe um objeto do Playwright. launch() retorna um Browser e launch_persistent_context() um BrowserContext, síncrono ou assíncrono, exatamente como localmente.
  • A entrada humanizada vem ativada por padrão. A partir do SDK 0.44.0, uma inicialização na nuvem humaniza no SDK, como uma inicialização local com humanize=True: o mouse se move por trajetórias humanas, as teclas são digitadas uma a uma, a rolagem acontece em passos da roda e os cliques por coordenadas são reproduzidos pelo próprio motor. Cada passo atravessa a rede, então isso é mais lento que a entrada simples; passe humanize=False para uma entrada simples e rápida. Em ambos os casos, a inicialização desliga o movimento de mouse próprio do navegador hospedado, para que só um dos dois mova o cursor. Clientes que se conectam sem o SDK mantêm o do navegador hospedado, que move o mouse no servidor, segura cada clique por um tempo de pressão humano e transforma rolagens grandes em passos inteiros da roda.
  • O mesmo motor. As sessões hospedadas rodam as mesmas versões do Clearcote que o SDK baixa, então as opções de persona significam o mesmo nos dois lugares, e version fixa o mesmo build.

Diferente:

  • Opções só locais são recusadas. executable_path, args, user_data_dir, extensions, ignore_default_args e as outras opções que só fazem sentido para um binário na sua máquina lançam ValueError("<name> is not available for cloud browsers") no Python (um erro com a mesma mensagem no Node) em vez de serem ignoradas.
  • Perfis em vez de pastas. Um navegador na nuvem não tem pasta no seu disco. Para manter cookies e o armazenamento dos sites entre execuções, use um perfil na nuvem com nome (abaixo).
  • profile significa um perfil na nuvem. Localmente, profile escolhe um perfil de dispositivo capturado ("auto"). No modo nuvem, ele nomeia um perfil na nuvem salvo: cookies, localStorage e IndexedDB.
  • Padrões hospedados. Uma sessão na nuvem começa com os padrões hospedados: uma persona Windows, lightStealth ativado, um seed, fuso horário e idioma que seguem o IP de saída, o módulo Widevine que um Google Chrome tem, movimento humano do mouse e um IP de saída residencial, a menos que você passe seu próprio proxy.
  • Encerramento. browser.close() desconecta, e a sessão termina quando seu cliente sai; o SDK também a para pela API, por garantia. Com keep_alive / keepAlive, o navegador continua rodando, até você pará-lo ou um limite fazer isso.
  • Limites da hospedagem. Sem file://, sem extensões, sem redes privadas, os downloads são buscados pela conexão (veja Baixando arquivos) e page.on("console") fica em silêncio. Veja os limites.
  • Cobrança. Um navegador na nuvem é cobrado como qualquer sessão hospedada, por GB de tráfego, do seu saldo pré-pago. Um navegador local não custa nada além da sua licença.

Um contexto persistente em um perfil na nuvem

launch_persistent_context() com cloud=True recebe um nome de perfil em vez de uma pasta. Ele retorna o primeiro contexto de uma sessão na nuvem iniciada com profile: { name, persist: true }: a sessão carrega o perfil, e fechar o contexto encerra a sessão e salva nele os cookies e o armazenamento dos sites.

from clearcote import launch_persistent_context

ctx = launch_persistent_context(cloud=True, profile="shop-account", country="de")
page = ctx.pages[0] if ctx.pages else ctx.new_page()
page.goto("https://shop.example.com/account")
ctx.close()   # ends the session and saves "shop-account"
Esta aba roda na sua máquina.

Passar um user_data_dir junto com cloud=True lança um ValueError que aponta para profile=. Só uma sessão por vez pode salvar em um perfil. Para começar um perfil a partir de cookies que você já tem, use a sincronização de cookies.

O cliente Cloud

Todo o resto que a API faz tem um cliente: sessões, execuções de agente, perfis e webhooks. Ele lê CLEARCOTE_API_KEY e CLEARCOTE_API_URL, ou os recebe como argumentos. O cliente Python usa apenas a biblioteca padrão; AsyncCloud tem os mesmos métodos para asyncio.

from clearcote.cloud import Cloud, CloudError

cloud = Cloud()   # or Cloud(api_key="cc_live_...", base_url="https://www.clearcotelabs.com")

session = cloud.browsers.create(country="de", record=True)
print(session["id"], session["connectUrl"])

try:
    cloud.browsers.stop(session["id"])
except CloudError as e:
    print(e.status, e.code, e.message)
Esta aba roda na sua máquina.
NamespaceMétodos
browserscreate(**options), get(id), list(status=None, note=None, limit=None, before=None), stop(id), live(id, control=False), share(id, control=None, minutes=None, recording=None), handoff(id, reason=None, timeout_sec=None), handoff_done(id), wait_handoff(id, timeout=None, poll=2.0), events(id, after=0, limit=None), recording_url(id), download_recording(id, path)
runscreate(task, url=None, schema=None, secrets=None, wait=True, timeout=None, poll=1.5, on_update=None, **options), get(id), list(limit=None, before=None), cancel(id), wait(id, timeout=None, poll=1.5, on_update=None)
profileslist(), get(name), delete(name), import_cookies(name, cookies, mode="merge"), sync(name, …)
webhookscreate(url, events=None, description=None), list(), delete(id), test(id)

Todo método retorna o JSON do endpoint como ele é: um dict no Python, um objeto simples no Node. As chamadas de listagem retornam o objeto da API, por exemplo { balanceEur, sessions } ou { runs }, não uma lista pura. As durações que o próprio SDK espera (timeout, poll) são em segundos nas duas linguagens.

O Node tem os mesmos métodos em camelCase (handoffDone, waitHandoff, importCookies, recordingUrl, downloadRecording), com os argumentos opcionais em um objeto: live(id, { control }), events(id, { after, limit }), runs.create(task, { url, schema, country, … }), importCookies(name, cookies, { mode }), webhooks.create(url, { events }). Uma chamada com falha lança CloudError com o status HTTP (0 quando não foi possível alcançar a API), o code da API e sua message; os códigos estão listados em Erros. Uma espera que passa do seu timeout lança, em vez disso, CloudTimeoutError, cujo last guarda o último estado que o SDK leu; a execução ou a transferência continua no servidor. Uma opção inválida lança ValueError no Python (um Error no Node) antes de qualquer envio. O SDK também exporta verify_webhook / verifyWebhook para assinaturas de webhook.

O comando clearcote cloud

O comando clearcote que vem com o SDK (pip install clearcote, ou npx clearcote) tem um grupo cloud para a mesma API:

bash
# an agent run: prints the result when it finishes
clearcote cloud run "Find the price of the cheapest plan" --url https://example.com/pricing \
  [--schema schema.json] [--secret name=value]... [--secret-domain name=host]... [--handoff] [--record] [--json]

# sessions
clearcote cloud sessions
clearcote cloud stop <id>
clearcote cloud events <id>
clearcote cloud recording <id> -o session.mp4

# copy cookies into a cloud profile (--domain or --all-domains is required)
clearcote cloud profile sync <name> (--from-profile DIR | --from-cdp URL | --from-file state.json | --login URL) \
  (--domain example.com... | --all-domains) [--replace]

# webhooks
clearcote cloud webhooks add https://example.com/hooks/clearcote [--event run.finished]...
clearcote cloud webhooks list
clearcote cloud webhooks rm <id>
clearcote cloud webhooks test <id>

Todo comando aceita --json para imprimir a resposta da API em vez de um resumo. run espera o resultado e sai com 0 só quando a execução termina como succeeded (1 caso contrário, 2 para um erro de uso), então funciona em um script de shell. Sem -o, recording salva em <id>.mp4. Rode clearcote cloud --help para ver todos os flags.

Cada comando tem sua própria página: execuções, gravações e eventos, sincronização de perfis e webhooks.

MCP: um navegador na nuvem para o seu assistente de IA

O servidor MCP tem o mesmo seletor. Com CLEARCOTE_CLOUD=1 e CLEARCOTE_API_KEY no seu env, o navegador compartilhado que as ferramentas dele controlam é um navegador na nuvem. Com uma chave de API definida, ele também ganha uma ferramenta run_task que entrega uma tarefa inteira a uma execução de agente e retorna o JSON do resultado.

json
{
  "mcpServers": {
    "clearcote": {
      "command": "npx",
      "args": ["-y", "clearcote-mcp"],
      "env": { "CLEARCOTE_CLOUD": "1", "CLEARCOTE_API_KEY": "cc_live_..." }
    }
  }
}

Atualizado em 18 de out. de 2026 · SDK 0.70.5 · navegador r63

Esta página foi útil?