OmeniaClaw browser

Gerencie a superfície de controle de navegador do OmeniaClaw e execute ações de navegador (ciclo de vida, perfis, abas, snapshots, capturas de tela, navegação, entrada, emulação de estado e depuração).

Relacionado:

• Ferramenta de navegador + API: Ferramenta de navegador

Flags comuns

• --url <gatewayWsUrl>: URL WebSocket do Gateway (usa a configuração por padrão).
• --token <token>: token do Gateway (se necessário).
• --timeout <ms>: tempo limite da solicitação (ms).
• --expect-final: aguarda uma resposta final do Gateway.
• --browser-profile <name>: escolhe um perfil de navegador (padrão da configuração).
• --json: saída legível por máquina (quando compatível).

Início rápido (local)

OmeniaClaw browser profilesOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw open https://example.comOmeniaClaw browser --browser-profile OmeniaClaw snapshot

Agentes podem executar a mesma verificação de prontidão com browser({ action: "doctor" }).

Solução rápida de problemas

Se start falhar com not reachable after start, investigue primeiro a prontidão do CDP. Se start e tabs funcionarem, mas open ou navigate falhar, o plano de controle do navegador está saudável e a falha geralmente é a política de SSRF de navegação.

Sequência mínima:

OmeniaClaw browser --browser-profile OmeniaClaw doctorOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw tabsOmeniaClaw browser --browser-profile OmeniaClaw open https://example.com

Orientação detalhada: Solução de problemas do navegador

Ciclo de vida

OmeniaClaw browser statusOmeniaClaw browser doctorOmeniaClaw browser doctor --deepOmeniaClaw browser startOmeniaClaw browser start --headlessOmeniaClaw browser stopOmeniaClaw browser --browser-profile OmeniaClaw reset-profile

Observações:

• doctor --deep adiciona uma sondagem de snapshot em tempo real. Isso é útil quando a prontidão básica do CDP está verde, mas você quer prova de que a aba atual pode ser inspecionada.
• Para perfis attachOnly e CDP remoto, OmeniaClaw browser stop fecha a sessão de controle ativa e limpa substituições temporárias de emulação mesmo quando o OmeniaClaw não iniciou o processo do navegador.
• Para perfis locais gerenciados, OmeniaClaw browser stop interrompe o processo do navegador iniciado.
• OmeniaClaw browser start --headless se aplica apenas a essa solicitação de inicialização e somente quando o OmeniaClaw inicia um navegador local gerenciado. Ele não reescreve browser.headless nem a configuração do perfil, e não tem efeito para um navegador que já está em execução.
• Em hosts Linux sem DISPLAY ou WAYLAND_DISPLAY, perfis locais gerenciados executam automaticamente em modo headless, a menos que OmeniaClaw_BROWSER_HEADLESS=0, browser.headless=false ou browser.profiles.<name>.headless=false solicite explicitamente um navegador visível.

Se o comando estiver ausente

Se OmeniaClaw browser for um comando desconhecido, verifique plugins.allow em ~/.OmeniaClaw/OmeniaClaw.json.

Quando plugins.allow estiver presente, liste explicitamente o Plugin de navegador incluído, a menos que a configuração já tenha um bloco raiz browser:

{  plugins: {    allow: ["telegram", "browser"],  },}

Um bloco raiz browser explícito, por exemplo browser.enabled=true ou browser.profiles.<name>, também ativa o Plugin de navegador incluído sob uma lista restritiva de Plugins permitidos.

Relacionado: Ferramenta de navegador

Perfis

Perfis são configurações nomeadas de roteamento de navegador. Na prática:

• OmeniaClaw: inicia ou anexa a uma instância dedicada do Chrome gerenciada pelo OmeniaClaw (diretório de dados de usuário isolado).
• user: controla sua sessão existente do Chrome com login por meio do Chrome DevTools MCP.
• perfis CDP personalizados: apontam para um endpoint CDP local ou remoto.

OmeniaClaw browser profilesOmeniaClaw browser create-profile --name work --color "#FF5A36"OmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name remote --cdp-url https://browser-host.example.comOmeniaClaw browser delete-profile --name work

Use um perfil específico:

OmeniaClaw browser --browser-profile work tabs

Abas

OmeniaClaw browser tabsOmeniaClaw browser tab new --label docsOmeniaClaw browser tab label t1 docsOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://omeniaclaw.com --label docsOmeniaClaw browser focus docsOmeniaClaw browser close t1

tabs retorna suggestedTargetId primeiro, depois o tabId estável, como t1, o rótulo opcional e o targetId bruto. Agentes devem passar suggestedTargetId de volta para focus, close, snapshots e ações. Você pode atribuir um rótulo com open --label, tab new --label ou tab label; rótulos, IDs de aba, IDs de destino brutos e prefixos únicos de ID de destino são todos aceitos. Quando o Chromium substitui o destino bruto subjacente durante uma navegação ou envio de formulário, o OmeniaClaw mantém o tabId/rótulo estável anexado à aba substituta quando consegue comprovar a correspondência. IDs de destino brutos continuam voláteis; prefira suggestedTargetId.

Snapshot / captura de tela / ações

Snapshot:

OmeniaClaw browser snapshotOmeniaClaw browser snapshot --urls

Captura de tela:

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref e12OmeniaClaw browser screenshot --labels

Observações:

• --full-page é apenas para capturas de página; não pode ser combinado com --ref ou --element.
• Perfis existing-session / user aceitam capturas de tela de página e capturas --ref a partir da saída de snapshot, mas não capturas de tela CSS --element.
• --labels sobrepõe as referências atuais do snapshot na captura de tela.
• snapshot --urls acrescenta destinos de links descobertos a snapshots de IA para que agentes possam escolher destinos diretos de navegação em vez de inferir apenas pelo texto do link.

Navegar/clicar/digitar (automação de UI baseada em ref):

OmeniaClaw browser navigate https://example.comOmeniaClaw browser click <ref>OmeniaClaw browser click-coords 120 340OmeniaClaw browser type <ref> "hello"OmeniaClaw browser press EnterOmeniaClaw browser hover <ref>OmeniaClaw browser scrollintoview <ref>OmeniaClaw browser drag <startRef> <endRef>OmeniaClaw browser select <ref> OptionA OptionBOmeniaClaw browser fill --fields '[{"ref":"1","value":"Ada"}]'OmeniaClaw browser wait --text "Done"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref <ref>

Respostas de ação retornam o targetId bruto atual após substituição de página acionada por ação quando o OmeniaClaw consegue comprovar a aba substituta. Scripts ainda devem armazenar e passar suggestedTargetId/rótulos para fluxos de trabalho duradouros.

Auxiliares de arquivo + diálogo:

OmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdf --ref <ref>OmeniaClaw browser waitfordownloadOmeniaClaw browser download <ref> report.pdfOmeniaClaw browser dialog --accept

Perfis gerenciados do Chrome salvam downloads comuns acionados por clique no diretório de downloads do OmeniaClaw (/tmp/OmeniaClaw/downloads por padrão, ou a raiz temporária configurada). Use waitfordownload ou download quando o agente precisar aguardar um arquivo específico e retornar seu caminho; esses aguardadores explícitos controlam o próximo download.

Estado e armazenamento

Viewport + emulação:

OmeniaClaw browser resize 1280 720OmeniaClaw browser set viewport 1280 720OmeniaClaw browser set offline onOmeniaClaw browser set media darkOmeniaClaw browser set timezone Europe/LondonOmeniaClaw browser set locale en-GBOmeniaClaw browser set geo 51.5074 -0.1278 --accuracy 25OmeniaClaw browser set device "iPhone 14"OmeniaClaw browser set headers '{"x-test":"1"}'OmeniaClaw browser set credentials myuser mypass

Cookies + armazenamento:

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url https://example.comOmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set token abc123OmeniaClaw browser storage session clear

Depuração

OmeniaClaw browser console --level errorOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api"OmeniaClaw browser highlight <ref>OmeniaClaw browser errors --clearOmeniaClaw browser requests --filter apiOmeniaClaw browser trace startOmeniaClaw browser trace stop --out trace.zip

Chrome existente via MCP

Use o perfil integrado user, ou crie seu próprio perfil existing-session:

OmeniaClaw browser --browser-profile user tabsOmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"OmeniaClaw browser --browser-profile chrome-live tabs

Esse caminho é apenas para host. Para Docker, servidores headless, Browserless ou outras configurações remotas, use um perfil CDP.

Limites atuais de existing-session:

• ações orientadas por snapshot usam refs, não seletores CSS
• browser.actionTimeoutMs define o padrão de solicitações act compatíveis para 60000 ms quando chamadores omitem timeoutMs; timeoutMs por chamada ainda prevalece.
• click é apenas clique esquerdo
• type não oferece suporte a slowly=true
• press não oferece suporte a delayMs
• hover, scrollintoview, drag, select, fill e evaluate rejeitam substituições de tempo limite por chamada
• select aceita apenas um valor
• wait --load networkidle não é compatível
• uploads de arquivos exigem --ref / --input-ref, não oferecem suporte a CSS --element e atualmente aceitam um arquivo por vez
• hooks de diálogo não oferecem suporte a --timeout
• capturas de tela aceitam capturas de página e --ref, mas não CSS --element
• responsebody, interceptação de download, exportação de PDF e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto

Controle remoto de navegador (proxy de host Node)

Se o Gateway estiver em execução em uma máquina diferente do navegador, execute um host Node na máquina que tem Chrome/Brave/Edge/Chromium. O Gateway encaminhará ações de navegador para esse node (nenhum servidor separado de controle de navegador é necessário).

Use gateway.nodes.browser.mode para controlar o roteamento automático e gateway.nodes.browser.node para fixar um node específico se vários estiverem conectados.

Segurança + configuração remota: Ferramenta de navegador, Acesso remoto, Tailscale, Segurança

Relacionado

• Referência da CLI
• Navegador