Pular para o conteúdo

Perfis, sincronização de cookies, segredos e 2FA

A maioria das tarefas que vale a pena automatizar fica atrás de um login. Há três formas de deixar um navegador hospedado logado sem colocar uma senha no seu código: faça login uma vez e guarde a sessão em um perfil, copie para um perfil os cookies que você já tem com a sincronização de cookies, ou deixe uma execução de agente digitar o login a partir de segredos que o modelo nunca vê, códigos 2FA incluídos.

Perfis

Um perfil guarda os cookies, o localStorage e o IndexedDB de uma sessão sob um nome. Inicie uma sessão com profile: { name: "shop-account", persist: true } para carregá-lo e salvá-lo de volta quando a sessão terminar, ou com profile: "shop-account" para carregá-lo somente para leitura. A menos que você passe identity ou fingerprint, um perfil também traz a própria identidade: o mesmo dispositivo, e o mesmo IP residencial enquanto esse IP continuar online. As regras completas estão em Perfis: faça login uma vez só; pelo SDK, veja um contexto persistente em um perfil na nuvem.

Para ver o que um perfil contém, sem os valores:

bash
curl -H "authorization: Bearer cc_live_..." https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account
# {
#   "name": "shop-account",
#   "cookies": 42,
#   "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211,
#   "storage": "Local Storage,IndexedDB",
#   "updatedAt": "2026-10-02T09:20:11.000Z"
# }

domains lista até 50 sites, em ordem, sem ponto inicial. bytes é o tamanho comprimido. storage indica o armazenamento de site salvo junto (Local Storage, IndexedDB); fica vazio em um perfil que só contém cookies importados. Um nome desconhecido retorna 404 NOT_FOUND.

Nenhum endpoint retorna o valor de um cookie. O conteúdo de um perfil só é aberto nos nossos servidores: para mesclar uma importação, para contar o que ele contém e no servidor que executa uma sessão nele.

Se você já está logado em algum lugar (seu próprio navegador, um Clearcote local, um script do Playwright), copie esses cookies para um perfil na nuvem e toda sessão nesse perfil começa logada:

bash
curl -X PUT https://www.clearcotelabs.com/api/v1/browsers/profiles/shop-account/cookies \
  -H "authorization: Bearer cc_live_..." -H "content-type: application/json" \
  -d '{
    "mode": "merge",
    "cookies": [
      { "name": "session_id", "value": "…", "domain": "shop.example.com", "path": "/",
        "secure": true, "httpOnly": true, "sameSite": "Lax", "expires": 1798761600 }
    ]
  }'
# { "name": "shop-account", "cookies": 42, "imported": 1, "domains": ["example.com", "shop.example.com"],
#   "bytes": 18211, "updatedAt": "…" }
  • Qualquer formato de cookie comum. O formato do CDP (Network.getCookies, Network.Cookie / CookieParam) e o do Playwright (context.cookies(), os cookies de um arquivo de storage state) funcionam como estão; uma url pode substituir domain. Sem expires, com expires: -1 (qualquer valor até 0) ou com session: true, é um cookie de sessão, e um cookie que já expirou é ignorado. sameSite é Lax, Strict ou None, em maiúsculas ou minúsculas, e None exige secure: true.
  • Validados como o Chrome valida. Um cookie que o Chrome recusaria (um ; em um valor, sameSite: "None" sem secure, um cookie __Secure- ou __Host- que quebra as regras deles, um caminho que não começa com /) transforma a importação inteira em um 400 cuja mensagem o identifica.
  • Armazenados como name, value, domain (em minúsculas), path (padrão /), secure, httpOnly, sameSite (só se você o enviou) e expires (ausente em um cookie de sessão). Outros campos, como partitionKey, são descartados.
  • mode: "merge" (o padrão) adiciona seus cookies e substitui os que têm o mesmo nome, domínio e caminho. mode: "replace" deixa os cookies do perfil exatamente iguais à lista que você envia. Em ambos os casos, o localStorage e o IndexedDB do perfil são mantidos.
  • Limites: no máximo 5000 cookies por requisição, e 5000 no perfil depois de uma mesclagem (400 TOO_MANY); nomes de até 256 caracteres, valores de até 4096, caminhos de até 1024; o perfil inteiro, no máximo 3.5 MB comprimido (413 TOO_LARGE); 60 importações a cada 10 minutos.
  • Um perfil que ainda não existe é criado. Enquanto uma sessão que salva no perfil (persist: true) estiver iniciando ou em execução, uma importação é recusada com 409 PROFILE_IN_USE: a sessão a sobrescreveria ao terminar.
  • Cookies de sessão importados (sem expiração) são carregados nas próximas sessões como qualquer outro. Uma sessão que salva o perfil os descarta, como um navegador real faz ao reiniciar; então importe-os de novo se precisar deles depois disso.

A resposta informa quantos cookies o perfil tem depois da importação (cookies) e quantos dos seus foram aceitos (imported: cookies expirados e duplicados ficam de fora), e lista os primeiros 50 domínios dele, em ordem.

Da sua máquina, com o SDK

O comando clearcote lê os cookies de onde você os tem e envia apenas os domínios que você indicar:

bash
# a local Clearcote profile folder (the user_data_dir of launch_persistent_context)
clearcote cloud profile sync shop-account --from-profile ./profiles/shop --domain example.com

# a browser that is running with a CDP endpoint, for example clearcote serve
clearcote cloud profile sync shop-account --from-cdp http://127.0.0.1:9222 --domain example.com

# a Playwright storage-state file: context.storage_state(path="state.json")
clearcote cloud profile sync shop-account --from-file state.json --domain example.com --domain example-cdn.net

# sign in by hand: opens a local Clearcote window on a throwaway profile at the URL,
# you sign in and press Enter, and the cookies for the chosen domains are uploaded
clearcote cloud profile sync shop-account --login https://shop.example.com/login --domain example.com
  • --domain (repita para vários) escolhe os cookies que um navegador enviaria para esse domínio: os dele, os dos subdomínios e os dos domínios pais (--domain shop.example.com também pega cookies de .example.com, nunca os de um sufixo isolado como .com). Sem --domain ou --all-domains, o comando se recusa a rodar, para que nada envie por acidente todos os cookies de um perfil.
  • --all-domains envia tudo. Use só em um perfil criado para essa única tarefa.
  • --replace envia mode: "replace"; o padrão é mesclar.
  • No código, profiles.sync(name, …) aceita as mesmas escolhas: exatamente um entre from_profile, from_cdp, from_file ou login_url (Node: fromProfile, fromCdp, fromFile, loginUrl), depois domains=[…] ou all_domains=True (allDomains: true), e replace=True. Retorna a resposta de importação descrita acima e lança ValueError (um Error no Node) sem enviar nada quando nenhum cookie corresponde.
from clearcote import launch_persistent_context
from clearcote.cloud import Cloud

cloud = Cloud()

# the same as the command line
cloud.profiles.sync("shop-account", from_file="state.json", domains=["example.com"])

# or upload cookies you have in hand, here from a local profile you signed in with
# (cloud=False: this folder is on your machine, whatever CLEARCOTE_CLOUD says)
ctx = launch_persistent_context("./profiles/shop", cloud=False)
cookies = ctx.cookies("https://shop.example.com")       # only this site's cookies
ctx.close()
cloud.profiles.import_cookies("shop-account", cookies)  # mode="merge"

Enquanto é válido, um cookie vale tanto quanto uma senha: quem tem um cookie de sessão está logado como você. Envie os domínios de que a tarefa precisa e nada mais. Alguns sites vinculam um login ao dispositivo ou ao IP em que ele foi feito e deslogam um cookie copiado; nesses casos, faça login uma vez dentro de uma sessão hospedada com persist: true.

Segredos e 2FA

Uma execução de agente pode digitar valores que o modelo nunca vê: senhas, números de conta e o código atual de um autenticador TOTP. Coloque-os em secrets e faça referência a eles na tarefa como {{name}}:

import os
from clearcote.cloud import Cloud

run = Cloud().runs.create(
    "Sign in with {{email}} and {{password}}. If a code is asked for, enter {{otp}}. "
    "Then open Orders and read the number of the latest order.",
    url="https://shop.example.com/login",
    secrets={
        "email": "me@example.com",
        "password": {"value": os.environ["SHOP_PASSWORD"]},
        "otp": {"totp": os.environ["SHOP_TOTP_SECRET"]},
    },
    schema={"type": "object", "properties": {"order": {"type": "string"}}, "required": ["order"]},
    profile={"name": "shop-account", "persist": True},   # next time it starts signed in
)
print(run["status"], run["result"]["output"])
Esta aba roda na sua máquina.
CampoTipoSignificado
"name": "value"stringUm valor simples, digitado no host da url da execução (e nos subdomínios dele).
valuestringO valor, de 1 a 1024 caracteres.
totpbase32 stringUm segredo de 2FA no lugar de um valor: a chave de configuração mostrada ao lado do QR code (letras A–Z e dígitos 2–7, no máximo 128; espaços e minúsculas são aceitos). A execução digita o código atual.
digits6 | 8Só TOTP. Padrão 6.
period30 | 60Só TOTP, em segundos. Padrão 30.
domainsstring[]Os hosts em que ele pode ser digitado: de 1 a 10 nomes de host como example.com (pelo menos dois rótulos; sem esquema, caminho, porta nem *), cada um incluindo seus subdomínios. Padrão: o host de url.
  • Um segredo é uma string, { value, domains? } ou { totp, domains?, digits?, period? }. No máximo 20 por execução. Os nomes começam com uma letra e usam letras, dígitos e _, com até 32 caracteres.
  • Um {{name}} na tarefa que não está em secrets retorna 400 (unknown secret "name"). O mesmo vale para um segredo sem domains em uma execução sem url: não há host ao qual vinculá-lo. Escreva a referência exatamente como {{name}}, sem espaços.
  • Um segredo que a tarefa nunca menciona é permitido; os warnings da resposta de criação avisam sobre isso.
  • Atenção ao host. Por padrão, um segredo fica vinculado ao host de url e aos subdomínios dele: https://shop.example.com/login cobre shop.example.com, não login.example.com. Se o formulário de login estiver em outro host (single sign-on, um provedor de identidade), inclua-o em domains.
  • Os códigos TOTP seguem a RFC 6238 com SHA-1, que é o que os apps autenticadores usam. O código é calculado no momento em que é digitado, então é sempre o atual.
  • Os segredos pertencem a uma única execução. Eles não são armazenados com um perfil nem mantidos depois da execução: envie-os de novo na próxima (ou rode a próxima em um perfil já logado e pule o login).

O que o modelo vê

Antes de o Jet começar, cada {{name}} na tarefa é substituído por um placeholder aleatório como CCSECRET_password_k3x9qa, e a tarefa recebe uma frase dizendo que os placeholders devem ser digitados exatamente como estão escritos. Isso é tudo o que o modelo recebe. Quando o Jet digita um placeholder, a camada do navegador no servidor coloca no lugar o valor real, ou o código TOTP atual, naquele momento, e só se o host da página for um dos domains do segredo ou um subdomínio de um deles (para um campo dentro de um iframe, o host do frame também). Em qualquer outro host, a etapa para com needs_input (“secret password is not allowed on other.example”) e nada é digitado.

Tudo o que volta é limpo do mesmo jeito: em detail, markdown, no text de cada etapa, no JSON de output e nos eventos, o valor de um segredo, o código TOTP atual dele e o placeholder aparecem como {{name}}. Uma consequência: se a página mostrar um segredo (por exemplo, o endereço de e-mail depois do login) e o seu schema pedir esse dado, você recebe {{email}}, não o endereço.

Modelo de segurança

O que protege o quê, e onde estão os limites:

  1. Sua chave de API é a sua conta. Com ela é possível iniciar navegadores com o seu saldo, usar seus perfis e ler suas execuções. Mantenha-a em um servidor, nunca em um navegador ou em um app que você distribui.
  2. Os perfis são privados e criptografados. Cada um é armazenado criptografado (AES-256-GCM, com uma chave por cliente) e aberto apenas nos nossos servidores: para mesclar uma importação, para contar o que contém e no servidor que executa uma sessão nele. O perfil de outro cliente com o mesmo nome é um perfil diferente. Nenhum endpoint retorna o valor de um cookie (uma sessão no perfil pode, é claro, ler os próprios cookies via CDP).
  3. A sincronização de cookies envia o que você escolhe. Só você pode importar para os seus perfis, dentro dos limites acima (5000 cookies, 3.5 MB), e nunca para um perfil em que uma sessão iniciando ou em execução está salvando. A escolha dos domínios acontece do seu lado: clearcote cloud profile sync e profiles.sync() se recusam a enviar o conjunto de cookies inteiro, a menos que você passe --all-domains / all_domains=True.
  4. Os segredos ficam lacrados até a execução começar. Eles são armazenados criptografados da mesma forma, dentro das configurações da execução, e abertos apenas quando um servidor pega a execução. São entregues a esse servidor uma única vez, e as configurações armazenadas são apagadas nesse momento. No servidor, ficam na memória e chegam ao processo do Jet pela entrada padrão: nunca em variáveis de ambiente, linhas de comando, logs ou eventos. Se não puderem mais ser abertos quando um servidor pegar a execução, ela termina como failed com session.endReason secrets_unreadable.
  5. O modelo nunca recebe um segredo. Ele trabalha com placeholders, e o valor real só é digitado nos hosts que você permitiu. Uma página que tenta convencer o agente a digitar sua senha em outro lugar (prompt injection) recebe uma etapa recusada, não a senha.
  6. As saídas são limpas. Valores, códigos TOTP e placeholders são substituídos por {{name}} em tudo o que uma execução retorna ou armazena.
  7. O Jet roda separado das credenciais do próprio servidor. Cada execução é um processo à parte com um ambiente explícito e mínimo: as chaves do servidor e as credenciais do proxy nunca são passadas a ele nem ao navegador. O navegador mantém as proteções do ambiente hospedado: nada de arquivos locais, nada de redes privadas.

E o que isso não cobre:

  • O site em que você faz login recebe o valor. Esse é o objetivo; escolha os domains com cuidado.
  • A página pode exibi-lo. Depois que um valor é digitado em um campo comum, a página o exibe. O Jet troca um valor digitado de volta pelo placeholder antes de o modelo ler a página, mas só onde ele aparece exatamente como foi digitado (ou codificado para URL): uma página que o mostra alterado, por exemplo reformatado ou parcialmente oculto, não é detectada. Campos de senha nunca são lidos.
  • As gravações mostram a tela. Um valor em um campo comum aparece no vídeo. Deixe record desligado em logins que você não quer registrados.
  • A tarefa não é secreta. Ela é armazenada com a execução e exibida no painel e na lista de execuções. Nunca escreva um valor na própria tarefa; use sempre {{name}}.
  • Links são chaves. Um link de transferência ou de controle permite que quem o tiver controle o navegador, logado, até ele expirar. Envie-o só para a pessoa que deve agir.

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

Esta página foi útil?