Pular para o conteúdo principal

​
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:

​
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 profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw 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 doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Orientação detalhada: Solução de problemas do navegador

​
Ciclo de vida

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw 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 profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
Use um perfil específico: 
openclaw browser --browser-profile work tabs

​
Abas

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw 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 snapshot
openclaw browser snapshot --urls
Captura de tela: 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw 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.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw 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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw 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 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
Cookies + armazenamento: 
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear

​
Depuração

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw 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 tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw 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:9222
openclaw 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