Saltar para o conteúdo principal
A CLI Gologin Agent Browser transforma os perfis de navegador do Gologin em um ambiente de execução persistente e programável para agentes de IA. As sessões rodam no Gologin Cloud Browser ou no Orbita, na sua própria máquina. Ela oferece snapshots compactos da página, interação baseada em refs, memória de sessão e saída adequada para uso no shell. Diferente de escrever código Puppeteer/Playwright do zero, esta CLI oferece aos agentes um conjunto pronto de comandos para automação de navegador — sem código repetitivo e sem código de gerenciamento de sessão.

Execução na nuvem ou local

A CLI tem dois ambientes de execução com os mesmos comandos. Ambos usam perfis, fingerprints e proxies do Gologin, e um daemon mantém as sessões ativas entre as chamadas da CLI. Escolha o ambiente de execução por comando com --runtime cloud|local|auto, ou defina GOLOGIN_AGENT_BROWSER_RUNTIME uma única vez:
Por padrão (auto), os comandos de perfil, runbook e job rodam localmente e todo o resto roda na nuvem. Depois de abrir uma sessão local, passe --runtime local também aos comandos seguintes. Consulte Ambiente local para ver os requisitos e os comandos exclusivos do modo local.

Instalação

Ou execute sem instalação global:
Requer Node.js >= 18. O ambiente local requer Node.js 20 ou superior.

Credenciais

Obtenha um token

  1. Cadastre-se ou faça login em gologin.com
  2. Abra API & MCP no painel
  3. Abra a aba API
  4. Clique em Novo Token
  5. Copie o token de acesso gerado

Arquivo de configuração

~/.gologin-agent-browser/config.json

Arquitetura

Duas partes:
  1. CLI gologin-agent-browser — interpreta os comandos, escolhe o ambiente de execução, inicia automaticamente o daemon correspondente e imprime uma saída compacta
  2. Daemons locais persistentes, um por ambiente de execução — controlam as sessões ativas do navegador, conectam-se ao Gologin Cloud Browser ou ao Orbita local por meio do connectOverCDP do Playwright, mantêm a página ativa na memória, geram snapshots, resolvem refs e acompanham os metadados da sessão
O transporte é somente local. O daemon da nuvem escuta em:
  • Socket Unix em ${TMPDIR:-/tmp}/gologin-agent-browser.sock
  • HTTP em localhost, em 127.0.0.1:${GOLOGIN_DAEMON_PORT:-44777}
No ambiente de nuvem, se você não informar um ID de perfil, o daemon cria um perfil temporário do Gologin na nuvem por meio da API.

Como funcionam as refs

O snapshot imprime uma visão compacta da página e atribui refs como @e1, @e2, @e3 aos elementos interativos. Você age diretamente sobre elas:
As refs funcionam em regime de melhor esforço e devem ser geradas novamente após uma navegação ou mudanças grandes no DOM. Os comandos também aceitam seletores CSS no lugar das refs. Em páginas dinâmicas, o find costuma ser uma alternativa melhor do que refs desatualizadas: ele localiza o elemento na página ativa e age sobre ele em uma única etapa.

Início rápido


Exemplo de loop de agente

Um loop típico de agente de IA:

Referência completa de comandos

Diagnóstico

Gerenciamento de sessões

Leitura da página

Interação

Teclado e rolagem

Abas

Cookies e armazenamento

Avançado

Perfis, proxies e a API do Gologin

Estes comandos chamam a API do Gologin com o seu token e não precisam do daemon do navegador.
Adicione --help a qualquer comando para exibir seu modo de uso.

Somente no ambiente local

profiles, profile, profile-create, profile-update, profile-import, profile-sync, profile-delete, run, batch, jobs e job gerenciam perfis locais, runbooks e o histórico de jobs. Consulte Ambiente local.

Aliases


Casos de uso e exemplos

Verifique se o seu site passa nos testes anti-detect

Faça login em um aplicativo web e extraia dados do painel

Preencha um formulário de várias etapas

Tire capturas de tela de páginas de concorrentes

Pesquise em um site que bloqueia scraping

Alguns sites exigem execução de JavaScript, login ou interação antes de mostrar os resultados. Use o navegador para pesquisar:

Salve e restaure o estado da sessão

Exporte cookies e armazenamento para reutilizá-los entre sessões:

Sessões paralelas

Use IDs --session explícitos para tarefas independentes na nuvem. Faça a limpeza com close --all ou sessions --prune --older-than-ms.

Regras de proxy

  • Perfis pré-configurados: o proxy é definido no perfil pelo painel do Gologin ou pela API, por exemplo proxy add-gologin <profileId> --country us
  • Perfis temporários na nuvem: sem proxy, ou com o seu próprio proxy usando --proxy-host e --proxy-port (além de --proxy-mode http|socks4|socks5, --proxy-user, --proxy-pass)
  • No ambiente de nuvem, o open não aceita --proxy-country. Para usar tráfego de proxy do Gologin de um país, adicione um proxy do Gologin a um perfil e abra-o com --profile
  • No ambiente local, open, profile-create e profile-update aceitam --proxy-country

Veja também

Pacote npm

gologin-agent-browser-cli

Código-fonte

GologinLabs/agent-browser