From c165430bb5d49f3a41dd53787a89bdf1ef6d8b51 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 14 Apr 2026 13:06:40 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/gateway/local-models.md | 80 +++-- docs/pt-BR/tools/browser.md | 480 ++++++++++++++++------------- 2 files changed, 317 insertions(+), 243 deletions(-) diff --git a/docs/pt-BR/gateway/local-models.md b/docs/pt-BR/gateway/local-models.md index 3d8561811..643cc448d 100644 --- a/docs/pt-BR/gateway/local-models.md +++ b/docs/pt-BR/gateway/local-models.md @@ -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..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..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..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..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. diff --git a/docs/pt-BR/tools/browser.md b/docs/pt-BR/tools/browser.md index ab95c8472..c42ea8c3d 100644 --- a/docs/pt-BR/tools/browser.md +++ b/docs/pt-BR/tools/browser.md @@ -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..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..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=`) - 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 `` 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 `` 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=`; 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": "", "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": "" }` sem um +Outras falhas em runtime ainda podem retornar `{ "error": "" }` 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=""`). + - `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot de IA com refs numéricos (`aria-ref=""`). - `--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 "