openclaw browser

Gerencie a superfície de controle de navegador do OpenClaw 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)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

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

Solução de problemas rápida

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á íntegro e a falha normalmente é a política SSRF de navegação.

Sequência mínima:

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

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

Ciclo de vida

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

Observações:

• doctor --deep adiciona uma sondagem de snapshot em tempo real. Ela é ú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, openclaw browser stop fecha a sessão de controle ativa e limpa substituições temporárias de emulação, mesmo quando o OpenClaw não iniciou o processo do navegador por conta própria.
• Para perfis locais gerenciados, openclaw browser stop interrompe o processo de navegador gerado.
• openclaw browser start --headless se aplica apenas a essa solicitação de inicialização e somente quando o OpenClaw inicia um navegador local gerenciado. Ele não reescreve browser.headless nem a configuração do perfil, e não faz nada para um navegador que já está em execução.
• Em hosts Linux sem DISPLAY ou WAYLAND_DISPLAY, perfis locais gerenciados rodam em modo headless automaticamente, a menos que OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false ou browser.profiles.<name>.headless=false solicite explicitamente um navegador visível.

Se o comando estiver ausente

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

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

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

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

Relacionado: Ferramenta de navegador

Perfis

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

• openclaw: inicia ou anexa a uma instância dedicada do Chrome gerenciada pelo OpenClaw (diretório de dados do 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.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Use um perfil específico:

openclaw browser --browser-profile work tabs

Abas

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs retorna primeiro suggestedTargetId, 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 abas, IDs de destino brutos e prefixos exclusivos de ID de destino são todos aceitos. O campo da solicitação ainda se chama targetId por compatibilidade, mas aceita essas referências de aba. Trate IDs de destino brutos como identificadores de diagnóstico, não como memória durável do agente. Quando o Chromium substitui o destino bruto subjacente durante uma navegação ou envio de formulário, o OpenClaw mantém o tabId/rótulo estável anexado à aba substituta quando consegue comprovar a correspondência. IDs de destino brutos permanecem voláteis; prefira suggestedTargetId.

Snapshot / captura de tela / ações

Snapshot:

openclaw browser snapshotopenclaw browser snapshot --urls

Captura de tela:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

Observações:

• --full-page é apenas para capturas de página; ele não pode ser combinado com --ref ou --element.
• Perfis existing-session / user oferecem suporte a capturas de tela de página e capturas de tela --ref a partir da saída de snapshot, mas não a capturas de tela CSS --element.
• --labels sobrepõe as referências do snapshot atual na captura de tela. Em perfis baseados em Playwright, ele funciona com --full-page (sobreposição de rótulos em página inteira), --ref (sobreposição de rótulos em recorte de elemento por referência ARIA) e --element (sobreposição de rótulos em recorte de elemento por seletor CSS); nos modos de recorte de elemento, os rótulos são projetados em relação ao elemento. A resposta também inclui um array annotations com a caixa delimitadora de cada referência. Cada item tem ref, number, role, name opcional e box: {x, y, width, height}; as coordenadas estão no espaço da imagem capturada (viewport / página inteira / relativo ao elemento). O campo é omitido quando está vazio. Perfis existing-session renderizam uma sobreposição chrome-mcp nas capturas de tela de página, mas não usam o auxiliar de projeção do Playwright e não incluem annotations; capturas de tela CSS --element não são compatíveis nesse caso. Sem Playwright ou chrome-mcp, capturas de tela com rótulos não estão disponíveis. Versões anteriores ignoravam --full-page, --ref e --element em capturas de tela rotuladas do Playwright e sempre retornavam uma captura de viewport; capturas de tela rotuladas agora respeitam esses escopos.
• snapshot --urls anexa destinos de links descobertos a snapshots de IA para que agentes possam escolher destinos de navegação direta em vez de inferir apenas pelo texto do link.

Navegar/clicar/digitar (automação de UI baseada em referência):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn aceita o código-fonte de uma função, uma expressão ou um corpo de instruções. Corpos de instruções são encapsulados como funções assíncronas, então use return para o valor que você quer receber de volta. Use evaluate --timeout-ms <ms> quando a função no lado da página puder precisar de mais tempo que o tempo limite padrão de avaliação.

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

Auxiliares de arquivo + diálogo:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Perfis gerenciados do Chrome salvam downloads comuns acionados por clique no diretório de downloads do OpenClaw (/tmp/openclaw/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. Uploads aceitam arquivos da raiz temporária de uploads do OpenClaw e mídia de entrada gerenciada pelo OpenClaw, incluindo referências media://inbound/<id> e media/inbound/<id> relativas ao sandbox. Referências de mídia aninhadas, travessia e caminhos locais arbitrários continuam rejeitados. Quando uma ação abre uma caixa de diálogo modal, a resposta da ação retorna blockedByDialog com browserState.dialogs.pending; passe --dialog-id para respondê-la diretamente. Diálogos tratados fora do OpenClaw aparecem em browserState.dialogs.recent.

Estado e armazenamento

Viewport + emulação:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookies + armazenamento:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Depuração

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Chrome existente via MCP

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

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

O caminho padrão de existing-session é a conexão automática do Chrome MCP somente no host. Se o navegador já estiver em execução com um endpoint DevTools, passe --cdp-url para que o Chrome MCP se anexe a esse endpoint. Para Docker, Browserless ou outras configurações remotas em que a semântica do Chrome MCP não é necessária, use um perfil CDP.

Limites atuais de existing-session:

• ações orientadas por snapshots usam referências, não seletores CSS
• browser.actionTimeoutMs define por padrão solicitações act compatíveis para 60000 ms quando os chamadores omitem timeoutMs; o 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 oferece suporte a apenas um valor
• wait --load networkidle não é compatível com perfis de sessão existentes (funciona em CDP gerenciado e bruto/remoto)
• uploads de arquivos exigem --ref / --input-ref, não oferecem suporte a --element CSS e atualmente oferecem suporte a um arquivo por vez
• hooks de diálogo não oferecem suporte a --timeout
• capturas de tela oferecem suporte a capturas de página e --ref, mas não a --element CSS
• responsebody, interceptação de download, exportação de PDF e ações em lote ainda exigem um navegador gerenciado ou um perfil CDP bruto

Controle remoto do navegador (proxy de host Node)

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

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

Relacionados

• Referência da CLI
• Navegador