chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
64707e6a3e
commit
c165430bb5
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer servir modelos a partir da sua própria máquina com GPU.
|
||||
- Você está configurando o LM Studio ou um proxy compatível com OpenAI.
|
||||
- Você precisa das orientações mais seguras para modelos locais.
|
||||
- Você quer servir modelos da sua própria máquina com GPU
|
||||
- Você está configurando o LM Studio ou um proxy compatível com OpenAI
|
||||
- Você precisa das orientações mais seguras para modelos locais
|
||||
summary: Execute o OpenClaw em LLMs locais (LM Studio, vLLM, LiteLLM, endpoints OpenAI personalizados)
|
||||
title: Modelos locais
|
||||
x-i18n:
|
||||
generated_at: "2026-04-13T08:50:40Z"
|
||||
generated_at: "2026-04-14T13:04:28Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a
|
||||
source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7
|
||||
source_path: gateway/local-models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Modelos locais
|
||||
|
||||
Local é viável, mas o OpenClaw espera contexto grande + defesas robustas contra injeção de prompt. Placas menores truncam o contexto e enfraquecem a segurança. Mire alto: **≥2 Mac Studios no máximo ou rig de GPU equivalente (~US$ 30 mil+)**. Uma única GPU de **24 GB** funciona apenas para prompts mais leves, com latência mais alta. Use a **maior / variante de tamanho completo do modelo que você conseguir executar**; checkpoints agressivamente quantizados ou “small” aumentam o risco de injeção de prompt (veja [Segurança](/pt-BR/gateway/security)).
|
||||
Localmente é viável, mas o OpenClaw espera contexto grande + defesas fortes contra injeção de prompt. Placas pequenas truncam o contexto e enfraquecem a segurança. Mire alto: **≥2 Mac Studios no máximo ou uma máquina com GPU equivalente (~US$ 30 mil+)**. Uma única GPU de **24 GB** funciona apenas para prompts mais leves, com latência maior. Use a **maior variante / variante de tamanho completo do modelo que você conseguir executar**; checkpoints agressivamente quantizados ou “small” aumentam o risco de injeção de prompt (veja [Segurança](/pt-BR/gateway/security)).
|
||||
|
||||
Se você quiser a configuração local com menos atrito, comece com [LM Studio](/pt-BR/providers/lmstudio) ou [Ollama](/pt-BR/providers/ollama) e `openclaw onboard`. Esta página é o guia opinativo para stacks locais mais avançadas e servidores locais personalizados compatíveis com OpenAI.
|
||||
Se você quer a configuração local com menos atrito, comece com [LM Studio](/pt-BR/providers/lmstudio) ou [Ollama](/pt-BR/providers/ollama) e `openclaw onboard`. Esta página é o guia opinativo para stacks locais de nível mais alto e servidores locais personalizados compatíveis com OpenAI.
|
||||
|
||||
## Recomendado: LM Studio + modelo local grande (API Responses)
|
||||
## Recomendado: LM Studio + modelo local grande (Responses API)
|
||||
|
||||
Melhor stack local no momento. Carregue um modelo grande no LM Studio (por exemplo, uma build completa de Qwen, DeepSeek ou Llama), ative o servidor local (padrão `http://127.0.0.1:1234`) e use a API Responses para manter o raciocínio separado do texto final.
|
||||
Melhor stack local atual. Carregue um modelo grande no LM Studio (por exemplo, uma versão completa do Qwen, DeepSeek ou Llama), habilite o servidor local (padrão `http://127.0.0.1:1234`), e use a Responses API para manter o raciocínio separado do texto final.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -45,7 +45,7 @@ Melhor stack local no momento. Carregue um modelo grande no LM Studio (por exemp
|
||||
models: [
|
||||
{
|
||||
id: “my-local-model”,
|
||||
name: “Modelo Local”,
|
||||
name: “Local Model”,
|
||||
reasoning: false,
|
||||
input: [“text”],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -62,15 +62,15 @@ Melhor stack local no momento. Carregue um modelo grande no LM Studio (por exemp
|
||||
**Checklist de configuração**
|
||||
|
||||
- Instale o LM Studio: [https://lmstudio.ai](https://lmstudio.ai)
|
||||
- No LM Studio, baixe a **maior build de modelo disponível** (evite variantes “small”/fortemente quantizadas), inicie o servidor e confirme que `http://127.0.0.1:1234/v1/models` o lista.
|
||||
- No LM Studio, baixe a **maior versão de modelo disponível** (evite variantes “small”/fortemente quantizadas), inicie o servidor e confirme que `http://127.0.0.1:1234/v1/models` o lista.
|
||||
- Substitua `my-local-model` pelo ID real do modelo mostrado no LM Studio.
|
||||
- Mantenha o modelo carregado; o carregamento a frio adiciona latência de inicialização.
|
||||
- Ajuste `contextWindow`/`maxTokens` se a sua build do LM Studio for diferente.
|
||||
- Para WhatsApp, mantenha a API Responses para que apenas o texto final seja enviado.
|
||||
- Mantenha o modelo carregado; carregamento a frio adiciona latência de inicialização.
|
||||
- Ajuste `contextWindow`/`maxTokens` se a sua versão do LM Studio for diferente.
|
||||
- Para WhatsApp, mantenha a Responses API para que apenas o texto final seja enviado.
|
||||
|
||||
Mantenha modelos hospedados configurados mesmo ao executar localmente; use `models.mode: "merge"` para que os fallbacks continuem disponíveis.
|
||||
|
||||
### Configuração híbrida: primário hospedado, fallback local
|
||||
### Configuração híbrida: principal hospedado, fallback local
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -97,7 +97,7 @@ Mantenha modelos hospedados configurados mesmo ao executar localmente; use `mode
|
||||
models: [
|
||||
{
|
||||
id: "my-local-model",
|
||||
name: "Modelo Local",
|
||||
name: "Local Model",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -111,18 +111,18 @@ Mantenha modelos hospedados configurados mesmo ao executar localmente; use `mode
|
||||
}
|
||||
```
|
||||
|
||||
### Local primeiro com rede de segurança hospedada
|
||||
### Prioridade local com rede de segurança hospedada
|
||||
|
||||
Troque a ordem do primário e dos fallbacks; mantenha o mesmo bloco de providers e `models.mode: "merge"` para poder recorrer a Sonnet ou Opus quando a máquina local estiver fora do ar.
|
||||
Troque a ordem do principal e do fallback; mantenha o mesmo bloco de providers e `models.mode: "merge"` para poder recorrer a Sonnet ou Opus quando a máquina local estiver fora do ar.
|
||||
|
||||
### Hospedagem regional / roteamento de dados
|
||||
|
||||
- Variantes hospedadas de MiniMax/Kimi/GLM também existem no OpenRouter com endpoints fixados por região (por exemplo, hospedados nos EUA). Escolha a variante regional lá para manter o tráfego na jurisdição desejada enquanto ainda usa `models.mode: "merge"` para fallbacks de Anthropic/OpenAI.
|
||||
- Somente local continua sendo o caminho mais forte em privacidade; roteamento regional hospedado é o meio-termo quando você precisa de recursos do provider, mas quer controlar o fluxo de dados.
|
||||
- Variantes hospedadas de MiniMax/Kimi/GLM também existem no OpenRouter com endpoints fixados por região (por exemplo, hospedados nos EUA). Escolha ali a variante regional para manter o tráfego na jurisdição desejada, enquanto continua usando `models.mode: "merge"` para fallbacks de Anthropic/OpenAI.
|
||||
- Somente local continua sendo o caminho mais forte em privacidade; o roteamento regional hospedado é o meio-termo quando você precisa de recursos do provedor, mas quer controle sobre o fluxo de dados.
|
||||
|
||||
## Outros proxies locais compatíveis com OpenAI
|
||||
|
||||
vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um endpoint `/v1` no estilo OpenAI. Substitua o bloco do provider acima pelo seu endpoint e ID do modelo:
|
||||
vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um endpoint `/v1` no estilo OpenAI. Substitua o bloco do provider acima pelo seu endpoint e ID de modelo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -136,7 +136,7 @@ vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um en
|
||||
models: [
|
||||
{
|
||||
id: "my-local-model",
|
||||
name: "Modelo Local",
|
||||
name: "Local Model",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -150,26 +150,40 @@ vLLM, LiteLLM, OAI-proxy ou gateways personalizados funcionam se expuserem um en
|
||||
}
|
||||
```
|
||||
|
||||
Mantenha `models.mode: "merge"` para que os modelos hospedados continuem disponíveis como fallbacks.
|
||||
Mantenha `models.mode: "merge"` para que modelos hospedados continuem disponíveis como fallbacks.
|
||||
|
||||
Observação de comportamento para backends `/v1` locais/com proxy:
|
||||
|
||||
- O OpenClaw trata esses backends como rotas compatíveis com OpenAI no estilo proxy, não como endpoints OpenAI nativos
|
||||
- a formatação de requisição exclusiva do OpenAI nativo não se aplica aqui: sem `service_tier`, sem `store` da Responses, sem formatação de payload de compatibilidade de raciocínio do OpenAI e sem dicas de cache de prompt
|
||||
- cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, `User-Agent`) não são injetados nessas URLs de proxy personalizadas
|
||||
- O OpenClaw trata isso como rotas compatíveis com OpenAI no estilo proxy, não como endpoints OpenAI nativos
|
||||
- a modelagem de requisição específica do OpenAI nativo não se aplica aqui: sem
|
||||
`service_tier`, sem `store` da Responses, sem modelagem de payload de compatibilidade de raciocínio do OpenAI, e sem dicas de cache de prompt
|
||||
- cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, `User-Agent`)
|
||||
não são injetados nesses URLs de proxy personalizados
|
||||
|
||||
Notas de compatibilidade para backends compatíveis com OpenAI mais rígidos:
|
||||
Observações de compatibilidade para backends compatíveis com OpenAI mais rígidos:
|
||||
|
||||
- Alguns servidores aceitam apenas `messages[].content` como string em Chat Completions, e não arrays estruturados de partes de conteúdo. Defina `models.providers.<provider>.models[].compat.requiresStringContent: true` para esses endpoints.
|
||||
- Alguns backends locais menores ou mais rígidos são instáveis com o formato completo de prompt do runtime de agentes do OpenClaw, especialmente quando esquemas de ferramentas estão incluídos. Se o backend funcionar para chamadas diretas pequenas de `/v1/chat/completions`, mas falhar em turnos normais de agentes do OpenClaw, tente primeiro `models.providers.<provider>.models[].compat.supportsTools: false`.
|
||||
- Se o backend ainda falhar apenas em execuções maiores do OpenClaw, o problema restante normalmente é capacidade do modelo/servidor upstream ou um bug do backend, não da camada de transporte do OpenClaw.
|
||||
- Alguns servidores aceitam apenas `messages[].content` como string em Chat Completions, não
|
||||
arrays estruturados de partes de conteúdo. Defina
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true` para
|
||||
esses endpoints.
|
||||
- Alguns backends locais menores ou mais rígidos ficam instáveis com o formato completo de prompt do runtime do agente do OpenClaw,
|
||||
especialmente quando esquemas de ferramentas estão incluídos. Se o
|
||||
backend funciona para chamadas diretas pequenas de `/v1/chat/completions`, mas falha em turnos normais de agente do
|
||||
OpenClaw, tente primeiro
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false`.
|
||||
- Se o backend ainda falhar apenas em execuções maiores do OpenClaw, o problema restante
|
||||
geralmente está na capacidade do modelo/servidor upstream ou em um bug do backend, não na camada de transporte do OpenClaw.
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
- O Gateway consegue alcançar o proxy? `curl http://127.0.0.1:1234/v1/models`.
|
||||
- Modelo do LM Studio descarregado? Recarregue; inicialização a frio é uma causa comum de “travamento”.
|
||||
- O modelo do LM Studio foi descarregado? Recarregue; inicialização a frio é uma causa comum de “travamento”.
|
||||
- O OpenClaw avisa quando a janela de contexto detectada está abaixo de **32k** e bloqueia abaixo de **16k**. Se você atingir essa verificação prévia, aumente o limite de contexto do servidor/modelo ou escolha um modelo maior.
|
||||
- Erros de contexto? Reduza `contextWindow` ou aumente o limite do seu servidor.
|
||||
- O servidor compatível com OpenAI retorna `messages[].content ... expected a string`?
|
||||
Adicione `compat.requiresStringContent: true` nessa entrada de modelo.
|
||||
- Chamadas diretas pequenas de `/v1/chat/completions` funcionam, mas `openclaw infer model run` falha em Gemma ou outro modelo local? Desative primeiro os esquemas de ferramentas com `compat.supportsTools: false` e teste novamente. Se o servidor ainda travar apenas em prompts maiores do OpenClaw, trate isso como uma limitação do servidor/modelo upstream.
|
||||
- Segurança: modelos locais ignoram filtros do provider; mantenha os agentes restritos e a Compaction ativada para limitar o raio de impacto da injeção de prompt.
|
||||
- Chamadas diretas pequenas para `/v1/chat/completions` funcionam, mas `openclaw infer model run`
|
||||
falha com Gemma ou outro modelo local? Primeiro desative os esquemas de ferramentas com
|
||||
`compat.supportsTools: false`, depois teste novamente. Se o servidor ainda travar apenas
|
||||
com prompts maiores do OpenClaw, trate isso como uma limitação do modelo/servidor upstream.
|
||||
- Segurança: modelos locais ignoram filtros do lado do provedor; mantenha os agentes restritos e a Compaction ativada para limitar o raio de impacto de injeção de prompt.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Adição de automação de navegador controlada por agente
|
||||
- Depuração do motivo pelo qual o openclaw está interferindo no seu próprio Chrome
|
||||
- Implementação de configurações e ciclo de vida do navegador no app macOS
|
||||
- Adicionando automação de navegador controlada por agente
|
||||
- Depurando por que o openclaw está interferindo no seu próprio Chrome
|
||||
- Implementando configurações do navegador + ciclo de vida no app para macOS
|
||||
summary: Serviço integrado de controle do navegador + comandos de ação
|
||||
title: Navegador (gerenciado pelo OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:47:39Z"
|
||||
generated_at: "2026-04-14T13:04:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f
|
||||
source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -22,19 +22,19 @@ serviço local de controle dentro do Gateway (somente loopback).
|
||||
|
||||
Visão para iniciantes:
|
||||
|
||||
- Pense nele como um **navegador separado, só para o agente**.
|
||||
- O perfil `openclaw` **não** toca no seu perfil pessoal do navegador.
|
||||
- O agente pode **abrir abas, ler páginas, clicar e digitar** em uma faixa segura.
|
||||
- O perfil integrado `user` se conecta à sua sessão real autenticada do Chrome via Chrome MCP.
|
||||
- Pense nele como um **navegador separado, apenas para o agente**.
|
||||
- O perfil `openclaw` **não** interfere no perfil do seu navegador pessoal.
|
||||
- O agente pode **abrir abas, ler páginas, clicar e digitar** em uma área segura.
|
||||
- O perfil `user` integrado se conecta à sua sessão real do Chrome autenticada via Chrome MCP.
|
||||
|
||||
## O que você recebe
|
||||
## O que você obtém
|
||||
|
||||
- Um perfil de navegador separado chamado **openclaw** (com destaque laranja por padrão).
|
||||
- Controle determinístico de abas (listar/abrir/focar/fechar).
|
||||
- Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela, PDFs.
|
||||
- Suporte opcional a múltiplos perfis (`openclaw`, `work`, `remote`, ...).
|
||||
- Suporte opcional a vários perfis (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Este navegador **não** é o seu navegador principal do dia a dia. É uma superfície segura e isolada para
|
||||
Este navegador **não** é o seu navegador principal do dia a dia. Ele é uma superfície segura e isolada para
|
||||
automação e verificação pelo agente.
|
||||
|
||||
## Início rápido
|
||||
@ -46,15 +46,15 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
Se você receber “Browser disabled”, habilite-o na configuração (veja abaixo) e reinicie o
|
||||
Se você receber “Browser disabled”, ative-o na configuração (veja abaixo) e reinicie o
|
||||
Gateway.
|
||||
|
||||
Se `openclaw browser` estiver totalmente ausente, ou se o agente disser que a ferramenta de navegador
|
||||
Se `openclaw browser` estiver ausente por completo, ou se o agente disser que a ferramenta de navegador
|
||||
não está disponível, vá para [Comando ou ferramenta de navegador ausente](/pt-BR/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Controle por plugin
|
||||
## Controle por Plugin
|
||||
|
||||
A ferramenta `browser` padrão agora é um plugin empacotado que é enviado habilitado por
|
||||
A ferramenta `browser` padrão agora é um Plugin incluído que vem habilitado por
|
||||
padrão. Isso significa que você pode desativá-lo ou substituí-lo sem remover o restante do
|
||||
sistema de plugins do OpenClaw:
|
||||
|
||||
@ -70,30 +70,33 @@ sistema de plugins do OpenClaw:
|
||||
}
|
||||
```
|
||||
|
||||
Desative o plugin empacotado antes de instalar outro plugin que forneça o
|
||||
Desative o Plugin incluído antes de instalar outro Plugin que forneça o
|
||||
mesmo nome de ferramenta `browser`. A experiência padrão do navegador precisa de ambos:
|
||||
|
||||
- `plugins.entries.browser.enabled` não desativado
|
||||
- `browser.enabled=true`
|
||||
|
||||
Se você desligar apenas o plugin, a CLI de navegador empacotada (`openclaw browser`),
|
||||
o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle do navegador desaparecem todos juntos. Sua configuração `browser.*` permanece intacta para que um
|
||||
plugin de substituição a reutilize.
|
||||
Se você desligar apenas o Plugin, a CLI de navegador incluída (`openclaw browser`),
|
||||
o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle do navegador
|
||||
desaparecem juntos. Sua configuração `browser.*` permanece intacta para ser reutilizada por um
|
||||
Plugin substituto.
|
||||
|
||||
O plugin de navegador empacotado também agora é proprietário da implementação de runtime do navegador.
|
||||
O core mantém apenas helpers compartilhados do Plugin SDK mais reexportações de compatibilidade para
|
||||
caminhos de importação internos mais antigos. Na prática, remover ou substituir o pacote do plugin de navegador remove o conjunto de recursos do navegador em vez de deixar um segundo runtime de propriedade do core para trás.
|
||||
O Plugin de navegador incluído agora também é responsável pela implementação do runtime do navegador.
|
||||
O core mantém apenas helpers compartilhados do Plugin SDK, além de reexports de compatibilidade para
|
||||
caminhos internos de importação mais antigos. Na prática, remover ou substituir o pacote do Plugin de navegador
|
||||
remove o conjunto de recursos do navegador em vez de deixar um segundo runtime controlado pelo
|
||||
core para trás.
|
||||
|
||||
Alterações de configuração do navegador ainda exigem reinicialização do Gateway para que o plugin empacotado
|
||||
Alterações na configuração do navegador ainda exigem um reinício do Gateway para que o Plugin incluído
|
||||
possa registrar novamente seu serviço de navegador com as novas configurações.
|
||||
|
||||
## Comando ou ferramenta de navegador ausente
|
||||
|
||||
Se `openclaw browser` de repente virar um comando desconhecido após uma atualização, ou
|
||||
Se `openclaw browser` de repente se tornar um comando desconhecido após uma atualização, ou
|
||||
se o agente informar que a ferramenta de navegador está ausente, a causa mais comum é uma
|
||||
lista restritiva `plugins.allow` que não inclui `browser`.
|
||||
lista restritiva em `plugins.allow` que não inclui `browser`.
|
||||
|
||||
Exemplo de configuração quebrada:
|
||||
Exemplo de configuração com problema:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -103,7 +106,7 @@ Exemplo de configuração quebrada:
|
||||
}
|
||||
```
|
||||
|
||||
Corrija adicionando `browser` à allowlist de plugins:
|
||||
Corrija isso adicionando `browser` à allowlist de plugins:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -117,8 +120,8 @@ Observações importantes:
|
||||
|
||||
- `browser.enabled=true` por si só não é suficiente quando `plugins.allow` está definido.
|
||||
- `plugins.entries.browser.enabled=true` por si só também não é suficiente quando `plugins.allow` está definido.
|
||||
- `tools.alsoAllow: ["browser"]` **não** carrega o plugin empacotado de navegador. Isso apenas ajusta a política de ferramentas depois que o plugin já foi carregado.
|
||||
- Se você não precisa de uma allowlist restritiva de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador empacotado.
|
||||
- `tools.alsoAllow: ["browser"]` **não** carrega o Plugin de navegador incluído. Ele apenas ajusta a política da ferramenta depois que o Plugin já foi carregado.
|
||||
- Se você não precisa de uma allowlist restritiva de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador incluído.
|
||||
|
||||
Sintomas típicos:
|
||||
|
||||
@ -128,15 +131,15 @@ Sintomas típicos:
|
||||
|
||||
## Perfis: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: navegador gerenciado e isolado (não requer extensão).
|
||||
- `user`: perfil integrado de conexão do Chrome MCP para sua **sessão real autenticada do Chrome**.
|
||||
- `openclaw`: navegador gerenciado e isolado (nenhuma extensão necessária).
|
||||
- `user`: perfil integrado de conexão ao Chrome MCP para sua **sessão real do Chrome autenticada**.
|
||||
|
||||
Para chamadas da ferramenta de navegador pelo agente:
|
||||
Para chamadas da ferramenta de navegador do agente:
|
||||
|
||||
- Padrão: use o navegador isolado `openclaw`.
|
||||
- Prefira `profile="user"` quando sessões autenticadas existentes importarem e o usuário
|
||||
estiver no computador para clicar/aprovar qualquer prompt de conexão.
|
||||
- `profile` é a substituição explícita quando você deseja um modo específico de navegador.
|
||||
- Prefira `profile="user"` quando sessões autenticadas já existentes forem importantes e o usuário
|
||||
estiver no computador para clicar/aprovar qualquer solicitação de conexão.
|
||||
- `profile` é a substituição explícita quando você quiser um modo específico de navegador.
|
||||
|
||||
Defina `browser.defaultProfile: "openclaw"` se quiser o modo gerenciado por padrão.
|
||||
|
||||
@ -149,14 +152,14 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
|
||||
browser: {
|
||||
enabled: true, // padrão: true
|
||||
ssrfPolicy: {
|
||||
// dangerouslyAllowPrivateNetwork: true, // opte por isso apenas para acesso confiável a rede privada
|
||||
// dangerouslyAllowPrivateNetwork: true, // opte por isso apenas para acesso confiável à rede privada
|
||||
// allowPrivateNetwork: true, // alias legado
|
||||
// hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
// allowedHostnames: ["localhost"],
|
||||
},
|
||||
// cdpUrl: "http://127.0.0.1:18792", // substituição legada de perfil único
|
||||
remoteCdpTimeoutMs: 1500, // timeout de HTTP CDP remoto (ms)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // timeout do handshake WebSocket CDP remoto (ms)
|
||||
remoteCdpTimeoutMs: 1500, // tempo limite de HTTP do CDP remoto (ms)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // tempo limite do handshake WebSocket do CDP remoto (ms)
|
||||
defaultProfile: "openclaw",
|
||||
color: "#FF4500",
|
||||
headless: false,
|
||||
@ -186,21 +189,21 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
|
||||
Observações:
|
||||
|
||||
- O serviço de controle do navegador se vincula ao loopback em uma porta derivada de `gateway.port`
|
||||
(padrão: `18791`, que é gateway + 2).
|
||||
(padrão: `18791`, que é a porta do gateway + 2).
|
||||
- Se você substituir a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
|
||||
as portas derivadas do navegador mudam para permanecer na mesma “família”.
|
||||
- `cdpUrl` usa por padrão a porta CDP local gerenciada quando não está definido.
|
||||
- `remoteCdpTimeoutMs` se aplica a verificações de alcançabilidade de CDP remotas (não loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcançabilidade do handshake WebSocket de CDP remoto.
|
||||
- Navegação/abertura de aba no navegador é protegida por SSRF antes da navegação e verificada novamente em regime best-effort na URL final `http(s)` após a navegação.
|
||||
- No modo SSRF estrito, descoberta/sondas de endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também são verificadas.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` vem desativado por padrão. Defina como `true` somente quando você confiar intencionalmente no acesso do navegador à rede privada.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado para compatibilidade.
|
||||
- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução.”
|
||||
- `color` + `color` por perfil tingem a UI do navegador para que você possa ver qual perfil está ativo.
|
||||
- O perfil padrão é `openclaw` (navegador independente gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador autenticado do usuário.
|
||||
- `cdpUrl` assume por padrão a porta CDP local gerenciada quando não está definido.
|
||||
- `remoteCdpTimeoutMs` se aplica a verificações de alcance do CDP remoto (não loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcance do WebSocket do CDP remoto.
|
||||
- A navegação/abertura de aba do navegador é protegida contra SSRF antes da navegação e verificada novamente, na medida do possível, na URL final `http(s)` após a navegação.
|
||||
- No modo SSRF estrito, a descoberta/sondas de endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também são verificadas.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado por padrão. Defina-o como `true` apenas quando você confiar intencionalmente no acesso do navegador à rede privada.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` continua com suporte como alias legado para compatibilidade.
|
||||
- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução”.
|
||||
- `color` + `color` por perfil tingem a interface do navegador para que você possa ver qual perfil está ativo.
|
||||
- O perfil padrão é `openclaw` (navegador independente gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador do usuário autenticado.
|
||||
- Ordem de autodetecção: navegador padrão do sistema se for baseado em Chromium; caso contrário Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Perfis locais `openclaw` atribuem automaticamente `cdpPort`/`cdpUrl` — defina esses valores apenas para CDP remoto.
|
||||
- Perfis `openclaw` locais atribuem automaticamente `cdpPort`/`cdpUrl` — defina esses valores apenas para CDP remoto.
|
||||
- `driver: "existing-session"` usa Chrome DevTools MCP em vez de CDP bruto. Não
|
||||
defina `cdpUrl` para esse driver.
|
||||
- Defina `browser.profiles.<name>.userDataDir` quando um perfil existing-session
|
||||
@ -208,11 +211,11 @@ Observações:
|
||||
|
||||
## Usar Brave (ou outro navegador baseado em Chromium)
|
||||
|
||||
Se o seu navegador **padrão do sistema** for baseado em Chromium (Chrome/Brave/Edge/etc),
|
||||
o OpenClaw o usará automaticamente. Defina `browser.executablePath` para substituir a
|
||||
Se o navegador **padrão do sistema** for baseado em Chromium (Chrome/Brave/Edge/etc),
|
||||
o OpenClaw o usa automaticamente. Defina `browser.executablePath` para substituir a
|
||||
autodetecção:
|
||||
|
||||
Exemplo na CLI:
|
||||
Exemplo de CLI:
|
||||
|
||||
```bash
|
||||
openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
@ -244,47 +247,47 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
## Controle local vs remoto
|
||||
|
||||
- **Controle local (padrão):** o Gateway inicia o serviço de controle em loopback e pode iniciar um navegador local.
|
||||
- **Controle remoto (host de nó):** execute um host de nó na máquina que tem o navegador; o Gateway faz proxy das ações do navegador para ele.
|
||||
- **Controle remoto (host do node):** execute um host do node na máquina que tem o navegador; o Gateway encaminha as ações do navegador para ele.
|
||||
- **CDP remoto:** defina `browser.profiles.<name>.cdpUrl` (ou `browser.cdpUrl`) para
|
||||
conectar-se a um navegador remoto baseado em Chromium. Nesse caso, o OpenClaw não iniciará um navegador local.
|
||||
se conectar a um navegador remoto baseado em Chromium. Nesse caso, o OpenClaw não iniciará um navegador local.
|
||||
|
||||
O comportamento de parada difere por modo de perfil:
|
||||
|
||||
- perfis gerenciados locais: `openclaw browser stop` para o processo do navegador que
|
||||
- perfis locais gerenciados: `openclaw browser stop` interrompe o processo do navegador que
|
||||
o OpenClaw iniciou
|
||||
- perfis attach-only e CDP remoto: `openclaw browser stop` fecha a sessão ativa
|
||||
de controle e libera substituições de emulação do Playwright/CDP (viewport,
|
||||
esquema de cores, localidade, fuso horário, modo offline e estado semelhante), mesmo
|
||||
- perfis somente conexão e perfis CDP remotos: `openclaw browser stop` fecha a sessão de
|
||||
controle ativa e libera as substituições de emulação do Playwright/CDP (viewport,
|
||||
esquema de cores, localidade, fuso horário, modo offline e estados semelhantes), mesmo
|
||||
que nenhum processo de navegador tenha sido iniciado pelo OpenClaw
|
||||
|
||||
URLs remotas de CDP podem incluir autenticação:
|
||||
As URLs de CDP remoto podem incluir autenticação:
|
||||
|
||||
- Tokens de query (por exemplo, `https://provider.example?token=<token>`)
|
||||
- Autenticação HTTP Basic (por exemplo, `https://user:pass@provider.example`)
|
||||
|
||||
O OpenClaw preserva a autenticação ao chamar endpoints `/json/*` e ao se conectar
|
||||
ao WebSocket CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para
|
||||
tokens em vez de fazer commit deles em arquivos de configuração.
|
||||
tokens em vez de registrá-los em arquivos de configuração.
|
||||
|
||||
## Proxy de navegador do nó (padrão sem configuração)
|
||||
## Proxy de navegador do Node (padrão sem configuração)
|
||||
|
||||
Se você executar um **host de nó** na máquina que tem o seu navegador, o OpenClaw pode
|
||||
rotear automaticamente chamadas da ferramenta de navegador para esse nó sem nenhuma configuração extra de navegador.
|
||||
Esse é o caminho padrão para gateways remotos.
|
||||
Se você executar um **host do node** na máquina que tem o seu navegador, o OpenClaw pode
|
||||
encaminhar automaticamente as chamadas da ferramenta de navegador para esse node sem nenhuma configuração adicional de navegador.
|
||||
Este é o caminho padrão para gateways remotos.
|
||||
|
||||
Observações:
|
||||
|
||||
- O host de nó expõe seu servidor local de controle do navegador por meio de um **comando de proxy**.
|
||||
- Os perfis vêm da própria configuração `browser.profiles` do nó (igual ao local).
|
||||
- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados permanecem acessíveis pelo proxy, incluindo rotas de criar/excluir perfil.
|
||||
- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw tratará isso como um limite de menor privilégio: apenas perfis na allowlist poderão ser usados como alvo, e rotas persistentes de criar/excluir perfil serão bloqueadas na superfície de proxy.
|
||||
- O host do node expõe seu servidor local de controle do navegador por meio de um **comando proxy**.
|
||||
- Os perfis vêm da configuração `browser.profiles` do próprio node (igual ao local).
|
||||
- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe-o vazio para o comportamento legado/padrão: todos os perfis configurados continuam acessíveis por meio do proxy, incluindo rotas de criação/exclusão de perfil.
|
||||
- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw o trata como um limite de menor privilégio: apenas perfis na allowlist podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy.
|
||||
- Desative se não quiser isso:
|
||||
- No nó: `nodeHost.browserProxy.enabled=false`
|
||||
- No node: `nodeHost.browserProxy.enabled=false`
|
||||
- No gateway: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless (CDP remoto hospedado)
|
||||
|
||||
[Browserless](https://browserless.io) é um serviço Chromium hospedado que expõe
|
||||
[Browserless](https://browserless.io) é um serviço hospedado de Chromium que expõe
|
||||
URLs de conexão CDP por HTTPS e WebSocket. O OpenClaw pode usar qualquer uma das formas, mas
|
||||
para um perfil de navegador remoto a opção mais simples é a URL WebSocket direta
|
||||
da documentação de conexão do Browserless.
|
||||
@ -311,15 +314,15 @@ Exemplo:
|
||||
Observações:
|
||||
|
||||
- Substitua `<BROWSERLESS_API_KEY>` pelo seu token real do Browserless.
|
||||
- Escolha o endpoint de região que corresponde à sua conta Browserless (veja a documentação deles).
|
||||
- Escolha o endpoint regional que corresponde à sua conta do Browserless (consulte a documentação deles).
|
||||
- Se o Browserless fornecer uma URL base HTTPS, você pode convertê-la para
|
||||
`wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar o OpenClaw
|
||||
descobrir `/json/version`.
|
||||
|
||||
## Provedores CDP de WebSocket direto
|
||||
## Provedores CDP WebSocket diretos
|
||||
|
||||
Alguns serviços de navegador hospedados expõem um endpoint **WebSocket direto** em vez de
|
||||
a descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece suporte a ambos:
|
||||
Alguns serviços hospedados de navegador expõem um endpoint **WebSocket direto** em vez
|
||||
da descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece suporte a ambos:
|
||||
|
||||
- **Endpoints HTTP(S)** — o OpenClaw chama `/json/version` para descobrir a
|
||||
URL do depurador WebSocket e então se conecta.
|
||||
@ -332,7 +335,7 @@ a descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece s
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) é uma plataforma em nuvem para executar
|
||||
navegadores headless com resolução integrada de CAPTCHA, modo furtivo e
|
||||
navegadores headless com resolução de CAPTCHA integrada, modo furtivo e
|
||||
proxies residenciais.
|
||||
|
||||
```json5
|
||||
@ -355,79 +358,79 @@ proxies residenciais.
|
||||
Observações:
|
||||
|
||||
- [Cadastre-se](https://www.browserbase.com/sign-up) e copie sua **API Key**
|
||||
do [painel Overview](https://www.browserbase.com/overview).
|
||||
no [painel Overview](https://www.browserbase.com/overview).
|
||||
- Substitua `<BROWSERBASE_API_KEY>` pela sua chave de API real do Browserbase.
|
||||
- O Browserbase cria automaticamente uma sessão de navegador ao conectar via WebSocket, então
|
||||
nenhuma etapa manual de criação de sessão é necessária.
|
||||
- O Browserbase cria automaticamente uma sessão de navegador ao conectar por WebSocket, então
|
||||
não é necessária nenhuma etapa manual de criação de sessão.
|
||||
- O plano gratuito permite uma sessão simultânea e uma hora de navegador por mês.
|
||||
Consulte [pricing](https://www.browserbase.com/pricing) para os limites dos planos pagos.
|
||||
- Consulte a [documentação do Browserbase](https://docs.browserbase.com) para a referência completa da
|
||||
API, guias de SDK e exemplos de integração.
|
||||
Consulte os [preços](https://www.browserbase.com/pricing) para os limites dos planos pagos.
|
||||
- Consulte a [documentação do Browserbase](https://docs.browserbase.com) para a
|
||||
referência completa da API, guias de SDK e exemplos de integração.
|
||||
|
||||
## Segurança
|
||||
|
||||
Ideias principais:
|
||||
|
||||
- O controle do navegador é somente loopback; o acesso passa pela autenticação do Gateway ou pelo emparelhamento do nó.
|
||||
- A API HTTP autônoma do navegador em loopback usa **apenas autenticação por segredo compartilhado**:
|
||||
autenticação bearer com token do gateway, `x-openclaw-password` ou autenticação HTTP Basic com a
|
||||
- O controle do navegador é somente loopback; o acesso flui pela autenticação do Gateway ou pelo pareamento de node.
|
||||
- A API HTTP de navegador em loopback independente usa **somente autenticação por segredo compartilhado**:
|
||||
autenticação bearer por token do gateway, `x-openclaw-password` ou autenticação HTTP Basic com a
|
||||
senha configurada do gateway.
|
||||
- Cabeçalhos de identidade do Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **não**
|
||||
autenticam essa API autônoma do navegador em loopback.
|
||||
- Se o controle do navegador estiver habilitado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
|
||||
autenticam esta API de navegador em loopback independente.
|
||||
- Se o controle do navegador estiver ativado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
|
||||
gera automaticamente `gateway.auth.token` na inicialização e o persiste na configuração.
|
||||
- O OpenClaw **não** gera automaticamente esse token quando `gateway.auth.mode` já é
|
||||
- O OpenClaw **não** gera esse token automaticamente quando `gateway.auth.mode` já está em
|
||||
`password`, `none` ou `trusted-proxy`.
|
||||
- Mantenha o Gateway e quaisquer hosts de nó em uma rede privada (Tailscale); evite exposição pública.
|
||||
- Trate URLs/tokens remotos de CDP como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
|
||||
- Mantenha o Gateway e quaisquer hosts de node em uma rede privada (Tailscale); evite exposição pública.
|
||||
- Trate URLs/tokens de CDP remotos como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
|
||||
|
||||
Dicas para CDP remoto:
|
||||
Dicas de CDP remoto:
|
||||
|
||||
- Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração quando possível.
|
||||
- Evite incorporar tokens de longa duração diretamente em arquivos de configuração.
|
||||
|
||||
## Perfis (múltiplos navegadores)
|
||||
## Perfis (vários navegadores)
|
||||
|
||||
O OpenClaw oferece suporte a vários perfis nomeados (configurações de roteamento). Os perfis podem ser:
|
||||
|
||||
- **gerenciados pelo openclaw**: uma instância dedicada de navegador baseado em Chromium com seu próprio diretório de dados do usuário + porta CDP
|
||||
- **remoto**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar)
|
||||
- **sessão existente**: seu perfil Chrome existente via conexão automática do Chrome DevTools MCP
|
||||
- **remotos**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar)
|
||||
- **sessão existente**: seu perfil existente do Chrome via autoconexão do Chrome DevTools MCP
|
||||
|
||||
Padrões:
|
||||
|
||||
- O perfil `openclaw` é criado automaticamente se estiver ausente.
|
||||
- O perfil `user` é integrado para conexão a sessão existente do Chrome MCP.
|
||||
- Perfis de sessão existente são opt-in além de `user`; crie-os com `--driver existing-session`.
|
||||
- Portas CDP locais são alocadas de **18800–18899** por padrão.
|
||||
- O perfil `user` é integrado para conexão existing-session do Chrome MCP.
|
||||
- Perfis existing-session são opt-in além de `user`; crie-os com `--driver existing-session`.
|
||||
- Portas CDP locais são alocadas em **18800–18899** por padrão.
|
||||
- Excluir um perfil move seu diretório de dados local para a Lixeira.
|
||||
|
||||
Todos os endpoints de controle aceitam `?profile=<name>`; a CLI usa `--browser-profile`.
|
||||
|
||||
## Sessão existente via Chrome DevTools MCP
|
||||
## Existing-session via Chrome DevTools MCP
|
||||
|
||||
O OpenClaw também pode se conectar a um perfil de navegador baseado em Chromium já em execução por meio do
|
||||
servidor oficial Chrome DevTools MCP. Isso reutiliza as abas e o estado de login
|
||||
já abertos nesse perfil de navegador.
|
||||
já abertos nesse perfil do navegador.
|
||||
|
||||
Referências oficiais de contexto e configuração:
|
||||
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
- [README do Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
|
||||
Perfil integrado:
|
||||
|
||||
- `user`
|
||||
|
||||
Opcional: crie seu próprio perfil personalizado de sessão existente se quiser um
|
||||
nome, cor ou diretório de dados do navegador diferente.
|
||||
Opcional: crie seu próprio perfil existing-session personalizado se quiser um
|
||||
nome, cor ou diretório de dados do navegador diferentes.
|
||||
|
||||
Comportamento padrão:
|
||||
|
||||
- O perfil integrado `user` usa conexão automática do Chrome MCP, que tem como alvo o
|
||||
- O perfil integrado `user` usa autoconexão do Chrome MCP, que tem como alvo o
|
||||
perfil local padrão do Google Chrome.
|
||||
|
||||
Use `userDataDir` para Brave, Edge, Chromium ou um perfil Chrome não padrão:
|
||||
Use `userDataDir` para Brave, Edge, Chromium ou um perfil do Chrome que não seja o padrão:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -447,8 +450,8 @@ Use `userDataDir` para Brave, Edge, Chromium ou um perfil Chrome não padrão:
|
||||
Então, no navegador correspondente:
|
||||
|
||||
1. Abra a página de inspeção desse navegador para depuração remota.
|
||||
2. Habilite a depuração remota.
|
||||
3. Mantenha o navegador em execução e aprove o prompt de conexão quando o OpenClaw se conectar.
|
||||
2. Ative a depuração remota.
|
||||
3. Mantenha o navegador em execução e aprove a solicitação de conexão quando o OpenClaw se conectar.
|
||||
|
||||
Páginas de inspeção comuns:
|
||||
|
||||
@ -456,7 +459,7 @@ Páginas de inspeção comuns:
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Teste smoke de conexão ao vivo:
|
||||
Teste rápido de conexão ao vivo:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -465,46 +468,46 @@ openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot --format ai
|
||||
```
|
||||
|
||||
Como é um caso de sucesso:
|
||||
Como é o sucesso:
|
||||
|
||||
- `status` mostra `driver: existing-session`
|
||||
- `status` mostra `transport: chrome-mcp`
|
||||
- `status` mostra `running: true`
|
||||
- `tabs` lista suas abas de navegador já abertas
|
||||
- `snapshot` retorna refs da aba ao vivo selecionada
|
||||
- `tabs` lista as abas do navegador que já estão abertas
|
||||
- `snapshot` retorna refs da aba ativa selecionada
|
||||
|
||||
O que verificar se a conexão não funcionar:
|
||||
|
||||
- o navegador baseado em Chromium alvo é versão `144+`
|
||||
- a depuração remota está habilitada na página de inspeção desse navegador
|
||||
- o navegador exibiu e você aceitou o prompt de consentimento da conexão
|
||||
- `openclaw doctor` migra a configuração antiga de navegador baseada em extensão e verifica que
|
||||
o Chrome está instalado localmente para perfis padrão de conexão automática, mas ele não pode
|
||||
habilitar a depuração remota do lado do navegador para você
|
||||
- o navegador baseado em Chromium de destino está na versão `144+`
|
||||
- a depuração remota está ativada na página de inspeção desse navegador
|
||||
- o navegador exibiu e você aceitou o prompt de consentimento de conexão
|
||||
- `openclaw doctor` migra a configuração antiga de navegador baseada em extensão e verifica se
|
||||
o Chrome está instalado localmente para perfis padrão de autoconexão, mas ele não pode
|
||||
ativar a depuração remota do lado do navegador para você
|
||||
|
||||
Uso pelo agente:
|
||||
|
||||
- Use `profile="user"` quando precisar do estado do navegador autenticado do usuário.
|
||||
- Se você usar um perfil personalizado de sessão existente, passe esse nome de perfil explícito.
|
||||
- Escolha esse modo somente quando o usuário estiver no computador para aprovar o prompt
|
||||
de conexão.
|
||||
- o Gateway ou host de nó pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
- Se você usar um perfil existing-session personalizado, passe esse nome de perfil explícito.
|
||||
- Escolha esse modo apenas quando o usuário estiver no computador para aprovar o
|
||||
prompt de conexão.
|
||||
- o Gateway ou host de node pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Observações:
|
||||
|
||||
- Esse caminho tem risco maior do que o perfil isolado `openclaw`, porque ele pode
|
||||
agir dentro da sua sessão autenticada do navegador.
|
||||
- Esse caminho tem risco maior que o perfil isolado `openclaw`, porque ele pode
|
||||
agir dentro da sua sessão de navegador autenticada.
|
||||
- O OpenClaw não inicia o navegador para esse driver; ele se conecta apenas a uma
|
||||
sessão existente.
|
||||
- O OpenClaw usa aqui o fluxo oficial `--autoConnect` do Chrome DevTools MCP. Se
|
||||
`userDataDir` estiver definido, o OpenClaw o repassa para ter como alvo esse diretório explícito
|
||||
de dados de usuário do Chromium.
|
||||
- Capturas de tela de sessão existente oferecem suporte a capturas de página e capturas
|
||||
`userDataDir` estiver definido, o OpenClaw o repassa para direcionar aquele diretório
|
||||
explícito de dados do usuário do Chromium.
|
||||
- Capturas de tela em existing-session oferecem suporte a capturas de página e capturas
|
||||
de elemento com `--ref` a partir de snapshots, mas não a seletores CSS `--element`.
|
||||
- Capturas de tela de página em sessão existente funcionam sem Playwright por meio do Chrome MCP.
|
||||
- Capturas de tela de página em existing-session funcionam sem Playwright via Chrome MCP.
|
||||
Capturas de elemento baseadas em ref (`--ref`) também funcionam ali, mas `--full-page`
|
||||
não pode ser combinado com `--ref` ou `--element`.
|
||||
- As ações de sessão existente ainda são mais limitadas do que o caminho do navegador
|
||||
- As ações de existing-session ainda são mais limitadas que o caminho do navegador
|
||||
gerenciado:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` exigem
|
||||
refs de snapshot em vez de seletores CSS
|
||||
@ -513,22 +516,22 @@ Observações:
|
||||
- `press` não oferece suporte a `delayMs`
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` e `evaluate` não
|
||||
oferecem suporte a substituições de timeout por chamada
|
||||
- `select` atualmente oferece suporte apenas a um único valor
|
||||
- `wait --url` de sessão existente oferece suporte a padrões exatos, substring e glob
|
||||
- `select` atualmente oferece suporte a apenas um único valor
|
||||
- `wait --url` em existing-session oferece suporte a padrões exatos, por substring e glob
|
||||
como outros drivers de navegador. `wait --load networkidle` ainda não é compatível.
|
||||
- Hooks de upload de sessão existente exigem `ref` ou `inputRef`, oferecem suporte a um arquivo
|
||||
por vez e não oferecem suporte a direcionamento por CSS `element`.
|
||||
- Hooks de diálogo de sessão existente não oferecem suporte a substituições de timeout.
|
||||
- Alguns recursos ainda exigem o caminho do navegador gerenciado, incluindo
|
||||
ações em lote, exportação em PDF, interceptação de download e `responsebody`.
|
||||
- Sessão existente é local ao host. Se o Chrome estiver em outra máquina ou em um
|
||||
namespace de rede diferente, use CDP remoto ou um host de nó.
|
||||
- Hooks de upload em existing-session exigem `ref` ou `inputRef`, oferecem suporte a um arquivo
|
||||
por vez e não oferecem suporte a direcionamento CSS `element`.
|
||||
- Hooks de diálogo em existing-session não oferecem suporte a substituições de timeout.
|
||||
- Alguns recursos ainda exigem o caminho do navegador gerenciado, incluindo ações
|
||||
em lote, exportação em PDF, interceptação de download e `responsebody`.
|
||||
- Existing-session é local ao host. Se o Chrome estiver em outra máquina ou em um
|
||||
namespace de rede diferente, use CDP remoto ou um host de node.
|
||||
|
||||
## Garantias de isolamento
|
||||
|
||||
- **Diretório de dados do usuário dedicado**: nunca toca no seu perfil pessoal do navegador.
|
||||
- **Diretório de dados do usuário dedicado**: nunca toca o perfil do seu navegador pessoal.
|
||||
- **Portas dedicadas**: evita `9222` para prevenir colisões com fluxos de trabalho de desenvolvimento.
|
||||
- **Controle determinístico de abas**: as abas são direcionadas por `targetId`, não pela “última aba”.
|
||||
- **Controle determinístico de abas**: direciona abas por `targetId`, não pela “última aba”.
|
||||
|
||||
## Seleção do navegador
|
||||
|
||||
@ -545,8 +548,8 @@ Você pode substituir isso com `browser.executablePath`.
|
||||
Plataformas:
|
||||
|
||||
- macOS: verifica `/Applications` e `~/Applications`.
|
||||
- Linux: procura por `google-chrome`, `brave`, `microsoft-edge`, `chromium` etc.
|
||||
- Windows: verifica locais comuns de instalação.
|
||||
- Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium` etc.
|
||||
- Windows: verifica locais de instalação comuns.
|
||||
|
||||
## API de controle (opcional)
|
||||
|
||||
@ -574,15 +577,15 @@ Se a autenticação do gateway por segredo compartilhado estiver configurada, as
|
||||
|
||||
Observações:
|
||||
|
||||
- Esta API autônoma do navegador em loopback **não** consome cabeçalhos de proxy confiável nem
|
||||
- Esta API de navegador em loopback independente **não** consome `trusted-proxy` nem
|
||||
cabeçalhos de identidade do Tailscale Serve.
|
||||
- Se `gateway.auth.mode` for `none` ou `trusted-proxy`, essas rotas de navegador em loopback
|
||||
não herdam esses modos com identidade; mantenha-as somente em loopback.
|
||||
não herdam esses modos baseados em identidade; mantenha-as somente em loopback.
|
||||
|
||||
### Contrato de erro de `/act`
|
||||
|
||||
`POST /act` usa uma resposta de erro estruturada para falhas de validação em nível de rota e
|
||||
de política:
|
||||
`POST /act` usa uma resposta de erro estruturada para falhas de validação e
|
||||
política no nível da rota:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
@ -592,68 +595,68 @@ Valores atuais de `code`:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` está ausente ou não é reconhecido.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): o payload da ação falhou na normalização ou validação.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` foi usado com um tipo de ação incompatível.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desabilitado por configuração.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nível superior ou em lote entra em conflito com o alvo da solicitação.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis de sessão existente.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` foi usado com um tipo de ação não compatível.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desativado pela configuração.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` no nível superior ou em lote entra em conflito com o alvo da solicitação.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis existing-session.
|
||||
|
||||
Outras falhas de runtime ainda podem retornar `{ "error": "<message>" }` sem um
|
||||
Outras falhas em runtime ainda podem retornar `{ "error": "<message>" }` sem um
|
||||
campo `code`.
|
||||
|
||||
### Requisito do Playwright
|
||||
|
||||
Alguns recursos (navigate/act/snapshot AI/snapshot por função, capturas de tela de elemento,
|
||||
PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornam
|
||||
Alguns recursos (navigate/act/AI snapshot/role snapshot, capturas de tela de elementos,
|
||||
PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornarão
|
||||
um erro 501 claro.
|
||||
|
||||
O que ainda funciona sem Playwright:
|
||||
|
||||
- Snapshots ARIA
|
||||
- Capturas de tela de página para o navegador gerenciado `openclaw` quando um WebSocket
|
||||
- Capturas de tela de página para o navegador `openclaw` gerenciado quando um WebSocket
|
||||
CDP por aba estiver disponível
|
||||
- Capturas de tela de página para perfis `existing-session` / Chrome MCP
|
||||
- Capturas de tela baseadas em ref (`--ref`) de `existing-session` a partir da saída de snapshot
|
||||
- Capturas de tela baseadas em `--ref` em `existing-session` a partir da saída de snapshot
|
||||
|
||||
O que ainda precisa de Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- snapshots AI / snapshots por função
|
||||
- capturas de tela de elemento por seletor CSS (`--element`)
|
||||
- exportação completa de PDF do navegador
|
||||
- AI snapshots / role snapshots
|
||||
- Capturas de tela de elemento por seletor CSS (`--element`)
|
||||
- Exportação completa de PDF do navegador
|
||||
|
||||
Capturas de tela de elemento também rejeitam `--full-page`; a rota retorna `fullPage is
|
||||
not supported for element screenshots`.
|
||||
|
||||
Se você vir `Playwright is not available in this gateway build`, instale o pacote completo
|
||||
do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o
|
||||
Se você vir `Playwright is not available in this gateway build`, instale o pacote completo do
|
||||
Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o
|
||||
OpenClaw com suporte a navegador.
|
||||
|
||||
#### Instalação do Playwright no Docker
|
||||
|
||||
Se o seu Gateway executa no Docker, evite `npx playwright` (conflitos de override do npm).
|
||||
Use a CLI empacotada:
|
||||
Se o seu Gateway estiver em execução no Docker, evite `npx playwright` (conflitos de override do npm).
|
||||
Use a CLI incluída:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli \
|
||||
node /app/node_modules/playwright-core/cli.js install chromium
|
||||
```
|
||||
|
||||
Para persistir downloads do navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
|
||||
Para persistir os downloads do navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
|
||||
`/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido via
|
||||
`OPENCLAW_HOME_VOLUME` ou um bind mount. Consulte [Docker](/pt-BR/install/docker).
|
||||
`OPENCLAW_HOME_VOLUME` ou um bind mount. Veja [Docker](/pt-BR/install/docker).
|
||||
|
||||
## Como funciona (interno)
|
||||
## Como funciona (internamente)
|
||||
|
||||
Fluxo de alto nível:
|
||||
|
||||
- Um pequeno **servidor de controle** aceita solicitações HTTP.
|
||||
- Um pequeno **servidor de controle** aceita requisições HTTP.
|
||||
- Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
|
||||
- Para ações avançadas (clicar/digitar/snapshot/PDF), ele usa **Playwright** sobre
|
||||
o CDP.
|
||||
- Quando o Playwright está ausente, apenas operações que não dependem de Playwright ficam disponíveis.
|
||||
- Quando o Playwright está ausente, apenas operações que não usam Playwright ficam disponíveis.
|
||||
|
||||
Esse design mantém o agente em uma interface estável e determinística, permitindo ao mesmo tempo
|
||||
Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo em que permite
|
||||
trocar navegadores e perfis locais/remotos.
|
||||
|
||||
## Referência rápida da CLI
|
||||
@ -692,8 +695,8 @@ Inspeção:
|
||||
|
||||
Observação sobre ciclo de vida:
|
||||
|
||||
- Para perfis attach-only e CDP remoto, `openclaw browser stop` ainda é o
|
||||
comando correto de limpeza após os testes. Ele fecha a sessão ativa de controle e
|
||||
- Para perfis somente conexão e perfis CDP remotos, `openclaw browser stop` ainda é o
|
||||
comando correto de limpeza após testes. Ele fecha a sessão de controle ativa e
|
||||
limpa substituições temporárias de emulação em vez de encerrar o navegador
|
||||
subjacente.
|
||||
- `openclaw browser errors --clear`
|
||||
@ -746,45 +749,45 @@ Estado:
|
||||
|
||||
Observações:
|
||||
|
||||
- `upload` e `dialog` são chamadas de **armamento**; execute-as antes do clique/tecla
|
||||
que dispara o seletor/diálogo.
|
||||
- Caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
|
||||
- `upload` e `dialog` são chamadas de **preparação**; execute-as antes do clique/pressionamento
|
||||
que aciona o seletor/diálogo.
|
||||
- Os caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
|
||||
- traces: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
|
||||
- downloads: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- Caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
|
||||
- Os caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
|
||||
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` também pode definir inputs de arquivo diretamente por `--input-ref` ou `--element`.
|
||||
- `upload` também pode definir diretamente entradas de arquivo via `--input-ref` ou `--element`.
|
||||
- `snapshot`:
|
||||
- `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot AI com refs numéricos (`aria-ref="<n>"`).
|
||||
- `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot de IA com refs numéricos (`aria-ref="<n>"`).
|
||||
- `--format aria`: retorna a árvore de acessibilidade (sem refs; apenas inspeção).
|
||||
- `--efficient` (ou `--mode efficient`): preset compacto de snapshot por função (interactive + compact + depth + maxChars menor).
|
||||
- Padrão de configuração (somente ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando o chamador não passar um modo (consulte [Configuração do Gateway](/pt-BR/gateway/configuration-reference#browser)).
|
||||
- Opções de snapshot por função (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em função com refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` restringe snapshots por função a um iframe (em conjunto com refs por função como `e12`).
|
||||
- `--interactive` produz uma lista plana e fácil de escolher de elementos interativos (melhor para conduzir ações).
|
||||
- `--labels` adiciona uma captura de tela apenas do viewport com rótulos de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (seja numérico `12` ou ref por função `e12`).
|
||||
- `--efficient` (ou `--mode efficient`): preset compacto de snapshot por role (interactive + compact + depth + maxChars menor).
|
||||
- Padrão de configuração (somente ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando o chamador não passar um modo (veja [Configuração do Gateway](/pt-BR/gateway/configuration-reference#browser)).
|
||||
- Opções de snapshot por role (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em role com refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita snapshots por role a um iframe (em conjunto com refs por role como `e12`).
|
||||
- `--interactive` produz uma lista plana e fácil de escolher de elementos interativos (melhor para executar ações).
|
||||
- `--labels` adiciona uma captura de tela somente da viewport com labels de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (seja numérico `12` ou ref por role `e12`).
|
||||
Seletores CSS intencionalmente não são compatíveis para ações.
|
||||
|
||||
## Snapshots e refs
|
||||
|
||||
O OpenClaw oferece suporte a dois estilos de “snapshot”:
|
||||
|
||||
- **Snapshot AI (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- Saída: um snapshot em texto que inclui refs numéricos.
|
||||
- **Snapshot de IA (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- Saída: um snapshot de texto que inclui refs numéricos.
|
||||
- Ações: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, o ref é resolvido por meio de `aria-ref` do Playwright.
|
||||
- Internamente, o ref é resolvido via `aria-ref` do Playwright.
|
||||
|
||||
- **Snapshot por função (refs de função como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em função com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- **Snapshot por role (refs por role como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em role com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- Ações: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Internamente, o ref é resolvido por meio de `getByRole(...)` (mais `nth()` para duplicados).
|
||||
- Adicione `--labels` para incluir uma captura de tela do viewport com rótulos `e12` sobrepostos.
|
||||
- Internamente, o ref é resolvido via `getByRole(...)` (mais `nth()` para duplicatas).
|
||||
- Adicione `--labels` para incluir uma captura de tela da viewport com labels `e12` sobrepostos.
|
||||
|
||||
Comportamento de ref:
|
||||
Comportamento dos refs:
|
||||
|
||||
- Refs **não são estáveis entre navegações**; se algo falhar, execute `snapshot` novamente e use um ref novo.
|
||||
- Se o snapshot por função foi tirado com `--frame`, os refs por função ficam restritos a esse iframe até o próximo snapshot por função.
|
||||
- Se o snapshot por role foi feito com `--frame`, os refs por role ficam limitados àquele iframe até o próximo snapshot por role.
|
||||
|
||||
## Recursos avançados de espera
|
||||
|
||||
@ -796,10 +799,10 @@ Você pode esperar por mais do que apenas tempo/texto:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- Esperar por um predicado JS:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- Esperar por um seletor se tornar visível:
|
||||
- Esperar por um seletor ficar visível:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Isso pode ser combinado:
|
||||
Eles podem ser combinados:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -811,10 +814,10 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Fluxos de depuração
|
||||
|
||||
Quando uma ação falha (por exemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
Quando uma ação falhar (por exemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs por função no modo interativo)
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs por role no modo interativo)
|
||||
3. Se ainda falhar: `openclaw browser highlight <ref>` para ver o que o Playwright está direcionando
|
||||
4. Se a página se comportar de forma estranha:
|
||||
- `openclaw browser errors --clear`
|
||||
@ -837,11 +840,11 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Snapshots por função em JSON incluem `refs` mais um pequeno bloco `stats` (linhas/chars/refs/interactive), para que ferramentas possam raciocinar sobre tamanho e densidade do payload.
|
||||
Snapshots por role em JSON incluem `refs` mais um pequeno bloco `stats` (lines/chars/refs/interactive) para que ferramentas possam raciocinar sobre tamanho e densidade do payload.
|
||||
|
||||
## Controles de estado e ambiente
|
||||
|
||||
Eles são úteis para fluxos do tipo “fazer o site se comportar como X”:
|
||||
Eles são úteis para fluxos de trabalho do tipo “faça o site se comportar como X”:
|
||||
|
||||
- Cookies: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
@ -861,11 +864,11 @@ Eles são úteis para fluxos do tipo “fazer o site se comportar como X”:
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` e `wait --fn`
|
||||
executam JavaScript arbitrário no contexto da página. Injeção de prompt pode direcionar
|
||||
isso. Desative com `browser.evaluateEnabled=false` se você não precisar disso.
|
||||
- Para observações sobre logins e anti-bot (X/Twitter etc.), consulte [Login no navegador + publicação no X/Twitter](/pt-BR/tools/browser-login).
|
||||
- Mantenha o Gateway/host de nó privado (somente loopback ou tailnet).
|
||||
- Endpoints CDP remotos são poderosos; encapsule e proteja-os.
|
||||
- Para logins e observações sobre anti-bot (X/Twitter etc.), veja [Login no navegador + postagem no X/Twitter](/pt-BR/tools/browser-login).
|
||||
- Mantenha o Gateway/host de node privado (somente loopback ou tailnet).
|
||||
- Endpoints CDP remotos são poderosos; faça tunnel e proteja-os.
|
||||
|
||||
Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
Exemplo de modo estrito (bloquear destinos privados/internos por padrão):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -873,7 +876,7 @@ Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // permissão exata opcional
|
||||
allowedHostnames: ["localhost"], // allow exato opcional
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -881,19 +884,76 @@ Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
Para problemas específicos do Linux (especialmente Chromium por snap), consulte
|
||||
Para problemas específicos do Linux (especialmente snap Chromium), veja
|
||||
[Solução de problemas do navegador](/pt-BR/tools/browser-linux-troubleshooting).
|
||||
|
||||
Para configurações separadas de host WSL2 Gateway + Windows Chrome, consulte
|
||||
Para configurações divididas entre Gateway no WSL2 + Chrome no Windows em hosts separados, veja
|
||||
[Solução de problemas de WSL2 + Windows + CDP remoto do Chrome](/pt-BR/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
### Falha de inicialização do CDP vs bloqueio SSRF de navegação
|
||||
|
||||
Essas são classes de falha diferentes e apontam para caminhos de código diferentes.
|
||||
|
||||
- **Falha de inicialização ou prontidão do CDP** significa que o OpenClaw não consegue confirmar que o plano de controle do navegador está íntegro.
|
||||
- **Bloqueio SSRF de navegação** significa que o plano de controle do navegador está íntegro, mas um destino de navegação de página é rejeitado pela política.
|
||||
|
||||
Exemplos comuns:
|
||||
|
||||
- Falha de inicialização ou prontidão do CDP:
|
||||
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
|
||||
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
|
||||
- Bloqueio SSRF de navegação:
|
||||
- fluxos `open`, `navigate`, snapshot ou de abertura de aba falham com um erro de política de navegador/rede, enquanto `start` e `tabs` continuam funcionando
|
||||
|
||||
Use esta sequência mínima para separar os dois:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw tabs
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
```
|
||||
|
||||
Como interpretar os resultados:
|
||||
|
||||
- Se `start` falhar com `not reachable after start`, primeiro resolva o problema de prontidão do CDP.
|
||||
- Se `start` tiver êxito, mas `tabs` falhar, o plano de controle ainda não está íntegro. Trate isso como um problema de alcance do CDP, não como um problema de navegação de página.
|
||||
- Se `start` e `tabs` tiverem êxito, mas `open` ou `navigate` falhar, o plano de controle do navegador está ativo e a falha está na política de navegação ou na página de destino.
|
||||
- Se `start`, `tabs` e `open` tiverem êxito, o caminho básico de controle do navegador gerenciado está íntegro.
|
||||
|
||||
Detalhes importantes de comportamento:
|
||||
|
||||
- A configuração do navegador usa por padrão um objeto de política SSRF fail-closed mesmo quando você não configura `browser.ssrfPolicy`.
|
||||
- Para o perfil gerenciado local em loopback `openclaw`, as verificações de integridade do CDP intencionalmente ignoram a imposição de alcance SSRF do navegador para o próprio plano de controle local do OpenClaw.
|
||||
- A proteção de navegação é separada. Um resultado bem-sucedido em `start` ou `tabs` não significa que um alvo posterior de `open` ou `navigate` seja permitido.
|
||||
|
||||
Orientação de segurança:
|
||||
|
||||
- **Não** relaxe a política SSRF do navegador por padrão.
|
||||
- Prefira exceções restritas de host, como `hostnameAllowlist` ou `allowedHostnames`, em vez de acesso amplo à rede privada.
|
||||
- Use `dangerouslyAllowPrivateNetwork: true` apenas em ambientes intencionalmente confiáveis em que o acesso do navegador à rede privada seja necessário e revisado.
|
||||
|
||||
Exemplo: navegação bloqueada, plano de controle íntegro
|
||||
|
||||
- `start` tem êxito
|
||||
- `tabs` tem êxito
|
||||
- `open http://internal.example` falha
|
||||
|
||||
Isso normalmente significa que a inicialização do navegador está correta e o destino de navegação precisa de revisão da política.
|
||||
|
||||
Exemplo: inicialização bloqueada antes que a navegação importe
|
||||
|
||||
- `start` falha com `not reachable after start`
|
||||
- `tabs` também falha ou não pode ser executado
|
||||
|
||||
Isso aponta para inicialização do navegador ou alcance do CDP, não para um problema de allowlist de URL de página.
|
||||
|
||||
## Ferramentas do agente + como o controle funciona
|
||||
|
||||
O agente recebe **uma ferramenta** para automação do navegador:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
Como isso é mapeado:
|
||||
Como isso se mapeia:
|
||||
|
||||
- `browser snapshot` retorna uma árvore de UI estável (AI ou ARIA).
|
||||
- `browser act` usa os IDs `ref` do snapshot para clicar/digitar/arrastar/selecionar.
|
||||
@ -901,14 +961,14 @@ Como isso é mapeado:
|
||||
- `browser` aceita:
|
||||
- `profile` para escolher um perfil de navegador nomeado (openclaw, chrome ou CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) para selecionar onde o navegador está.
|
||||
- Em sessões com sandbox, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` for omitido: sessões com sandbox usam `sandbox` por padrão, sessões sem sandbox usam `host` por padrão.
|
||||
- Se um nó com capacidade de navegador estiver conectado, a ferramenta pode ser roteada automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
- Em sessões em sandbox, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` for omitido: sessões em sandbox usam `sandbox` por padrão; sessões sem sandbox usam `host` por padrão.
|
||||
- Se um node com capacidade de navegador estiver conectado, a ferramenta poderá encaminhar automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
|
||||
Isso mantém o agente determinístico e evita seletores frágeis.
|
||||
|
||||
## Relacionado
|
||||
## Relacionados
|
||||
|
||||
- [Visão geral das ferramentas](/pt-BR/tools) — todas as ferramentas de agente disponíveis
|
||||
- [Sandboxing](/pt-BR/gateway/sandboxing) — controle do navegador em ambientes com sandbox
|
||||
- [Segurança](/pt-BR/gateway/security) — riscos e hardening do controle do navegador
|
||||
- [Segurança](/pt-BR/gateway/security) — riscos e reforço de segurança do controle do navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user