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

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. 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, 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.
• Para perfis locais gerenciados, openclaw browser stop interrompe o processo do navegador iniciado.
• 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 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 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 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:

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

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

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; 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):

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>

Respostas de ação retornam o targetId bruto atual após 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 duradouros.

Auxiliares de arquivo + diálogo:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept

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.

# 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 integrado user, 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 --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