chore(i18n): refresh pt-BR translations

2026-04-11 15:24:01 +00:00 · 2026-04-11 15:24:01 +00:00 · d4c25ee082
commit d4c25ee082
parent 5eea9e3f43
7 changed files with 2218 additions and 1840 deletions
--- a/docs/pt-BR/gateway/configuration-reference.md
+++ b/docs/pt-BR/gateway/configuration-reference.md
--- a/docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md
+++ b/docs/pt-BR/help/gpt54-codex-agentic-parity-maintainers.md
@ -0,0 +1,174 @@
+---
+x-i18n:
+    generated_at: "2026-04-11T15:15:56Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: 910bcf7668becf182ef48185b43728bf2fa69629d6d50189d47d47b06f807a9e
+    source_path: help/gpt54-codex-agentic-parity-maintainers.md
+    workflow: 15
+---
+
+# Notas de manutenção sobre a paridade GPT-5.4 / Codex
+
+Esta nota explica como revisar o programa de paridade GPT-5.4 / Codex como quatro unidades de merge sem perder a arquitetura original de seis contratos.
+
+## Unidades de merge
+
+### PR A: execução agentiva estrita
+
+É responsável por:
+
+- `executionContract`
+- continuidade na mesma rodada com GPT-5 em primeiro lugar
+- `update_plan` como acompanhamento de progresso não terminal
+- estados explícitos de bloqueio em vez de paradas silenciosas apenas no plano
+
+Não é responsável por:
+
+- classificação de falhas de autenticação/runtime
+- veracidade sobre permissões
+- reformulação de replay/continuação
+- benchmark de paridade
+
+### PR B: veracidade de runtime
+
+É responsável por:
+
+- correção do escopo OAuth do Codex
+- classificação tipada de falhas de provider/runtime
+- veracidade sobre a disponibilidade de `/elevated full` e motivos de bloqueio
+
+Não é responsável por:
+
+- normalização do schema de ferramentas
+- estado de replay/liveness
+- benchmark gating
+
+### PR C: correção de execução
+
+É responsável por:
+
+- compatibilidade de ferramentas OpenAI/Codex de propriedade do provider
+- tratamento estrito de schema sem parâmetros
+- exposição de replay inválido
+- visibilidade do estado de tarefas longas pausadas, bloqueadas e abandonadas
+
+Não é responsável por:
+
+- continuação autoeleita
+- comportamento genérico do dialeto Codex fora dos hooks do provider
+- benchmark gating
+
+### PR D: harness de paridade
+
+É responsável por:
+
+- primeiro pacote de cenários de GPT-5.4 vs Opus 4.6
+- documentação de paridade
+- mecânica do relatório de paridade e do gate de release
+
+Não é responsável por:
+
+- mudanças de comportamento em runtime fora do QA-lab
+- simulação de autenticação/proxy/DNS dentro do harness
+
+## Mapeamento de volta para os seis contratos originais
+
+| Contrato original                         | Unidade de merge |
+| ----------------------------------------- | ---------------- |
+| Correção de transporte/autenticação do provider | PR B       |
+| Compatibilidade de contrato/schema de ferramentas | PR C       |
+| Execução na mesma rodada                  | PR A             |
+| Veracidade sobre permissões               | PR B             |
+| Correção de replay/continuação/liveness   | PR C             |
+| Gate de benchmark/release                 | PR D             |
+
+## Ordem de revisão
+
+1. PR A
+2. PR B
+3. PR C
+4. PR D
+
+A PR D é a camada de comprovação. Ela não deve ser o motivo para atrasar PRs de correção de runtime.
+
+## O que observar
+
+### PR A
+
+- execuções do GPT-5 agem ou falham de forma fechada em vez de parar em comentário
+- `update_plan` não parece mais progresso por si só
+- o comportamento continua com GPT-5 em primeiro lugar e com escopo limitado ao Pi embarcado
+
+### PR B
+
+- falhas de autenticação/proxy/runtime deixam de ser colapsadas em um tratamento genérico de “model failed”
+- `/elevated full` só é descrito como disponível quando realmente está disponível
+- os motivos de bloqueio ficam visíveis tanto para o modelo quanto para o runtime voltado ao usuário
+
+### PR C
+
+- o registro estrito de ferramentas OpenAI/Codex se comporta de forma previsível
+- ferramentas sem parâmetros não falham nas verificações estritas de schema
+- resultados de replay e compactação preservam um estado de liveness verdadeiro
+
+### PR D
+
+- o pacote de cenários é compreensível e reproduzível
+- o pacote inclui uma trilha mutável de segurança de replay, e não apenas fluxos somente leitura
+- os relatórios são legíveis por humanos e automação
+- as alegações de paridade são respaldadas por evidências, não anedóticas
+
+Artefatos esperados da PR D:
+
+- `qa-suite-report.md` / `qa-suite-summary.json` para cada execução de modelo
+- `qa-agentic-parity-report.md` com comparação agregada e no nível de cenário
+- `qa-agentic-parity-summary.json` com um veredito legível por máquina
+
+## Gate de release
+
+Não afirme paridade ou superioridade do GPT-5.4 sobre o Opus 4.6 até que:
+
+- PR A, PR B e PR C tenham sido mergeadas
+- PR D execute o primeiro pacote de paridade sem falhas
+- as suítes de regressão de veracidade de runtime permaneçam verdes
+- o relatório de paridade não mostre casos de falso sucesso nem regressão no comportamento de parada
+
+```mermaid
+flowchart LR
+    A["PR A-C merged"] --> B["Run GPT-5.4 parity pack"]
+    A --> C["Run Opus 4.6 parity pack"]
+    B --> D["qa-suite-summary.json"]
+    C --> E["qa-suite-summary.json"]
+    D --> F["qa parity-report"]
+    E --> F
+    F --> G["Markdown report + JSON verdict"]
+    G --> H{"Pass?"}
+    H -- "yes" --> I["Parity claim allowed"]
+    H -- "no" --> J["Keep runtime fixes / review loop open"]
+```
+
+O harness de paridade não é a única fonte de evidência. Mantenha essa separação explícita na revisão:
+
+- a PR D é responsável pela comparação baseada em cenários entre GPT-5.4 e Opus 4.6
+- as suítes determinísticas da PR B continuam sendo responsáveis pelas evidências de autenticação/proxy/DNS e de veracidade sobre acesso total
+
+## Mapa de objetivo para evidência
+
+| Item do gate de conclusão                 | Responsável principal | Artefato de revisão                                                  |
+| ----------------------------------------- | --------------------- | -------------------------------------------------------------------- |
+| Sem travamentos apenas no plano           | PR A                  | testes de runtime agentivo estrito e `approval-turn-tool-followthrough` |
+| Sem progresso falso ou conclusão falsa de ferramenta | PR A + PR D   | contagem de falsos sucessos na paridade mais detalhes do relatório no nível de cenário |
+| Sem orientação falsa sobre `/elevated full` | PR B                | suítes determinísticas de veracidade de runtime                      |
+| Falhas de replay/liveness continuam explícitas | PR C + PR D      | suítes de ciclo de vida/replay mais `compaction-retry-mutating-tool` |
+| GPT-5.4 iguala ou supera Opus 4.6         | PR D                  | `qa-agentic-parity-report.md` e `qa-agentic-parity-summary.json`     |
+
+## Atalho para revisores: antes vs depois
+
+| Problema visível para o usuário antes                       | Sinal de revisão depois                                                                  |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| GPT-5.4 parava após planejar                                | A PR A mostra comportamento de agir-ou-bloquear em vez de conclusão apenas em comentário |
+| O uso de ferramentas parecia frágil com schemas estritos do OpenAI/Codex | A PR C mantém previsível o registro de ferramentas e a invocação sem parâmetros |
+| As dicas de `/elevated full` às vezes eram enganosas        | A PR B vincula a orientação à capacidade real do runtime e aos motivos de bloqueio       |
+| Tarefas longas podiam desaparecer na ambiguidade de replay/compactação | A PR C emite estado explícito de pausado, bloqueado, abandonado e replay inválido |
+| As alegações de paridade eram anedóticas                    | A PR D produz um relatório mais um veredito em JSON com a mesma cobertura de cenários em ambos os modelos |
--- a/docs/pt-BR/help/gpt54-codex-agentic-parity.md
+++ b/docs/pt-BR/help/gpt54-codex-agentic-parity.md
@ -0,0 +1,229 @@
+---
+x-i18n:
+    generated_at: "2026-04-11T15:15:56Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: 7ee6b925b8a0f8843693cea9d50b40544657b5fb8a9e0860e2ff5badb273acb6
+    source_path: help/gpt54-codex-agentic-parity.md
+    workflow: 15
+---
+
+# Paridade Agêntica do GPT-5.4 / Codex no OpenClaw
+
+O OpenClaw já funcionava bem com modelos de fronteira que usam ferramentas, mas os modelos GPT-5.4 e no estilo Codex ainda apresentavam desempenho inferior em alguns aspectos práticos:
+
+- podiam parar após planejar em vez de fazer o trabalho
+- podiam usar incorretamente esquemas de ferramentas estritos do OpenAI/Codex
+- podiam pedir `/elevated full` mesmo quando o acesso total era impossível
+- podiam perder o estado de tarefas longas durante replay ou compactação
+- alegações de paridade em relação ao Claude Opus 4.6 eram baseadas em relatos anedóticos em vez de cenários repetíveis
+
+Este programa de paridade corrige essas lacunas em quatro partes revisáveis.
+
+## O que mudou
+
+### PR A: execução agêntica estrita
+
+Esta parte adiciona um contrato de execução `strict-agentic` opcional para execuções do GPT-5 incorporado no Pi.
+
+Quando ativado, o OpenClaw deixa de aceitar turnos apenas com plano como conclusão “boa o suficiente”. Se o modelo apenas disser o que pretende fazer e não realmente usar ferramentas nem progredir, o OpenClaw tenta novamente com uma orientação para agir agora e depois falha de forma segura com um estado bloqueado explícito, em vez de encerrar a tarefa silenciosamente.
+
+Isso melhora a experiência com GPT-5.4 principalmente em:
+
+- acompanhamentos curtos como “ok, faça isso”
+- tarefas de código em que a primeira etapa é óbvia
+- fluxos em que `update_plan` deve servir para acompanhar progresso, e não como texto de preenchimento
+
+### PR B: veracidade do runtime
+
+Esta parte faz o OpenClaw dizer a verdade sobre duas coisas:
+
+- por que a chamada ao provedor/runtime falhou
+- se `/elevated full` está realmente disponível
+
+Isso significa que o GPT-5.4 recebe sinais de runtime melhores para escopo ausente, falhas de renovação de autenticação, falhas de autenticação HTML 403, problemas de proxy, falhas de DNS ou timeout, e modos de acesso total bloqueados. O modelo fica menos propenso a inventar a remediação errada ou continuar pedindo um modo de permissão que o runtime não pode fornecer.
+
+### PR C: correção de execução
+
+Esta parte melhora dois tipos de correção:
+
+- compatibilidade com esquemas de ferramentas OpenAI/Codex de propriedade do provedor
+- visibilidade de replay e vivacidade de tarefas longas
+
+O trabalho de compatibilidade com ferramentas reduz o atrito de esquema para registro estrito de ferramentas OpenAI/Codex, especialmente em torno de ferramentas sem parâmetros e expectativas estritas de objeto na raiz. O trabalho de replay/vivacidade torna tarefas longas mais observáveis, para que estados pausado, bloqueado e abandonado fiquem visíveis em vez de desaparecerem em um texto genérico de falha.
+
+### PR D: harness de paridade
+
+Esta parte adiciona o primeiro pacote de paridade do QA-lab, para que GPT-5.4 e Opus 4.6 possam ser exercitados nos mesmos cenários e comparados usando evidências compartilhadas.
+
+O pacote de paridade é a camada de prova. Ele não altera o comportamento do runtime por si só.
+
+Depois de ter dois artefatos `qa-suite-summary.json`, gere a comparação do gate de release com:
+
+```bash
+pnpm openclaw qa parity-report \
+  --repo-root . \
+  --candidate-summary .artifacts/qa-e2e/gpt54/qa-suite-summary.json \
+  --baseline-summary .artifacts/qa-e2e/opus46/qa-suite-summary.json \
+  --output-dir .artifacts/qa-e2e/parity
+```
+
+Esse comando grava:
+
+- um relatório Markdown legível por humanos
+- um veredito JSON legível por máquina
+- um resultado de gate explícito `pass` / `fail`
+
+## Por que isso melhora o GPT-5.4 na prática
+
+Antes deste trabalho, o GPT-5.4 no OpenClaw podia parecer menos agêntico que o Opus em sessões reais de programação porque o runtime tolerava comportamentos especialmente prejudiciais para modelos no estilo GPT-5:
+
+- turnos só com comentários
+- atrito de esquema em torno de ferramentas
+- feedback de permissão vago
+- quebra silenciosa de replay ou compactação
+
+O objetivo não é fazer o GPT-5.4 imitar o Opus. O objetivo é dar ao GPT-5.4 um contrato de runtime que recompense progresso real, forneça semântica mais limpa para ferramentas e permissões, e transforme modos de falha em estados explícitos, legíveis por máquina e por humanos.
+
+Isso muda a experiência do usuário de:
+
+- “o modelo tinha um bom plano, mas parou”
+
+para:
+
+- “o modelo ou agiu, ou o OpenClaw mostrou o motivo exato pelo qual ele não pôde agir”
+
+## Antes vs. depois para usuários do GPT-5.4
+
+| Antes deste programa                                                                        | Depois das PRs A-D                                                                      |
+| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| O GPT-5.4 podia parar após um plano razoável sem dar o próximo passo com ferramenta         | A PR A transforma “apenas plano” em “aja agora ou mostre um estado bloqueado”          |
+| Esquemas estritos de ferramentas podiam rejeitar ferramentas sem parâmetros ou no formato OpenAI/Codex de maneiras confusas | A PR C torna o registro e a invocação de ferramentas de propriedade do provedor mais previsíveis |
+| A orientação sobre `/elevated full` podia ser vaga ou incorreta em runtimes bloqueados      | A PR B dá ao GPT-5.4 e ao usuário dicas de runtime e permissões fiéis à realidade      |
+| Falhas de replay ou compactação podiam dar a sensação de que a tarefa simplesmente sumiu    | A PR C mostra explicitamente resultados pausados, bloqueados, abandonados e inválidos para replay |
+| “O GPT-5.4 parece pior que o Opus” era em grande parte anedótico                            | A PR D transforma isso no mesmo pacote de cenários, nas mesmas métricas e em um gate rígido de pass/fail |
+
+## Arquitetura
+
+```mermaid
+flowchart TD
+    A["Solicitação do usuário"] --> B["Runtime Pi incorporado"]
+    B --> C["Contrato de execução agêntica estrita"]
+    B --> D["Compatibilidade de ferramentas de propriedade do provedor"]
+    B --> E["Veracidade do runtime"]
+    B --> F["Replay e estado de vivacidade"]
+    C --> G["Chamada de ferramenta ou estado bloqueado explícito"]
+    D --> G
+    E --> G
+    F --> G
+    G --> H["Pacote de paridade do QA-lab"]
+    H --> I["Relatório de cenário e gate de paridade"]
+```
+
+## Fluxo de release
+
+```mermaid
+flowchart LR
+    A["Partes de runtime mescladas (PRs A-C)"] --> B["Executar pacote de paridade do GPT-5.4"]
+    A --> C["Executar pacote de paridade do Opus 4.6"]
+    B --> D["qa-suite-summary.json"]
+    C --> E["qa-suite-summary.json"]
+    D --> F["openclaw qa parity-report"]
+    E --> F
+    F --> G["qa-agentic-parity-report.md"]
+    F --> H["qa-agentic-parity-summary.json"]
+    H --> I{"Gate aprovado?"}
+    I -- "sim" --> J["Alegação de paridade respaldada por evidências"]
+    I -- "não" --> K["Manter aberto o ciclo de runtime/revisão"]
+```
+
+## Pacote de cenários
+
+O pacote de paridade de primeira onda atualmente cobre cinco cenários:
+
+### `approval-turn-tool-followthrough`
+
+Verifica se o modelo não para em “vou fazer isso” após uma aprovação curta. Ele deve executar a primeira ação concreta no mesmo turno.
+
+### `model-switch-tool-continuity`
+
+Verifica se o trabalho com uso de ferramentas permanece coerente através de limites de troca de modelo/runtime, em vez de reiniciar em comentários ou perder o contexto de execução.
+
+### `source-docs-discovery-report`
+
+Verifica se o modelo consegue ler código-fonte e documentação, sintetizar conclusões e continuar a tarefa de forma agêntica, em vez de produzir um resumo superficial e parar cedo.
+
+### `image-understanding-attachment`
+
+Verifica se tarefas de modo misto que envolvem anexos permanecem acionáveis e não colapsam em uma narração vaga.
+
+### `compaction-retry-mutating-tool`
+
+Verifica se uma tarefa com uma gravação mutável real mantém a insegurança de replay explícita, em vez de parecer silenciosamente segura para replay quando a execução sofre compactação, retry ou perda de estado de resposta sob pressão.
+
+## Matriz de cenários
+
+| Cenário                            | O que testa                              | Bom comportamento do GPT-5.4                                                   | Sinal de falha                                                                  |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `approval-turn-tool-followthrough` | Turnos curtos de aprovação após um plano | Inicia imediatamente a primeira ação concreta com ferramenta, em vez de repetir a intenção | acompanhamento só com plano, nenhuma atividade de ferramenta, ou turno bloqueado sem um bloqueador real |
+| `model-switch-tool-continuity`     | Troca de runtime/modelo durante uso de ferramentas | Preserva o contexto da tarefa e continua agindo de forma coerente              | reinicia em comentários, perde o contexto de ferramenta, ou para após a troca   |
+| `source-docs-discovery-report`     | Leitura de código + síntese + ação       | Encontra fontes, usa ferramentas e produz um relatório útil sem travar         | resumo superficial, trabalho com ferramentas ausente, ou parada de turno incompleta |
+| `image-understanding-attachment`   | Trabalho agêntico guiado por anexo       | Interpreta o anexo, conecta-o às ferramentas e continua a tarefa               | narração vaga, anexo ignorado, ou nenhuma próxima ação concreta                 |
+| `compaction-retry-mutating-tool`   | Trabalho mutável sob pressão de compactação | Executa uma gravação real e mantém a insegurança de replay explícita após o efeito colateral | a gravação mutável acontece, mas a segurança de replay é implícita, ausente ou contraditória |
+
+## Gate de release
+
+O GPT-5.4 só pode ser considerado em paridade ou melhor quando o runtime mesclado passa no pacote de paridade e nas regressões de veracidade do runtime ao mesmo tempo.
+
+Resultados obrigatórios:
+
+- nenhum travamento em plano apenas quando a próxima ação com ferramenta é clara
+- nenhuma conclusão falsa sem execução real
+- nenhuma orientação incorreta sobre `/elevated full`
+- nenhum abandono silencioso por replay ou compactação
+- métricas do pacote de paridade pelo menos tão fortes quanto a baseline acordada do Opus 4.6
+
+Para o harness de primeira onda, o gate compara:
+
+- taxa de conclusão
+- taxa de parada não intencional
+- taxa de chamada de ferramenta válida
+- contagem de sucesso falso
+
+A evidência de paridade é intencionalmente dividida em duas camadas:
+
+- a PR D comprova o comportamento do GPT-5.4 vs. Opus 4.6 nos mesmos cenários com o QA-lab
+- as suítes determinísticas da PR B comprovam veracidade de autenticação, proxy, DNS e `/elevated full` fora do harness
+
+## Matriz objetivo-evidência
+
+| Item do gate de conclusão                               | PR responsável | Fonte de evidência                                                 | Sinal de aprovação                                                                     |
+| ------------------------------------------------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| O GPT-5.4 não trava mais após planejar                  | PR A           | `approval-turn-tool-followthrough` mais as suítes de runtime da PR A | turnos de aprovação disparam trabalho real ou um estado bloqueado explícito            |
+| O GPT-5.4 não finge mais progresso nem conclusão falsa de ferramenta | PR A + PR D    | resultados de cenários do relatório de paridade e contagem de sucesso falso | nenhum resultado de aprovação suspeito e nenhuma conclusão apenas com comentários       |
+| O GPT-5.4 não dá mais orientação falsa sobre `/elevated full` | PR B           | suítes determinísticas de veracidade                               | razões de bloqueio e dicas de acesso total permanecem fiéis ao runtime                 |
+| Falhas de replay/vivacidade permanecem explícitas       | PR C + PR D    | suítes de ciclo de vida/replay da PR C mais `compaction-retry-mutating-tool` | trabalho mutável mantém a insegurança de replay explícita, em vez de desaparecer silenciosamente |
+| O GPT-5.4 iguala ou supera o Opus 4.6 nas métricas acordadas | PR D           | `qa-agentic-parity-report.md` e `qa-agentic-parity-summary.json`   | mesma cobertura de cenários e nenhuma regressão em conclusão, comportamento de parada ou uso válido de ferramentas |
+
+## Como ler o veredito de paridade
+
+Use o veredito em `qa-agentic-parity-summary.json` como a decisão final legível por máquina para o pacote de paridade de primeira onda.
+
+- `pass` significa que o GPT-5.4 cobriu os mesmos cenários que o Opus 4.6 e não regrediu nas métricas agregadas acordadas.
+- `fail` significa que pelo menos um gate rígido foi acionado: conclusão mais fraca, paradas não intencionais piores, uso válido de ferramentas mais fraco, qualquer caso de sucesso falso, ou cobertura de cenários incompatível.
+- “problema de CI compartilhado/base” não é, por si só, um resultado de paridade. Se ruído de CI fora da PR D bloquear uma execução, o veredito deve esperar por uma execução limpa do runtime mesclado, em vez de ser inferido a partir de logs da época do branch.
+- A veracidade de autenticação, proxy, DNS e `/elevated full` continua vindo das suítes determinísticas da PR B, então a alegação final de release precisa dos dois: um veredito de paridade aprovando na PR D e cobertura de veracidade verde na PR B.
+
+## Quem deve ativar `strict-agentic`
+
+Use `strict-agentic` quando:
+
+- espera-se que o agente aja imediatamente quando a próxima etapa for óbvia
+- modelos GPT-5.4 ou da família Codex forem o runtime principal
+- você preferir estados bloqueados explícitos em vez de respostas “úteis” apenas de recapitulação
+
+Mantenha o contrato padrão quando:
+
+- você quiser o comportamento atual mais flexível
+- você não estiver usando modelos da família GPT-5
+- você estiver testando prompts em vez da aplicação do runtime
--- a/docs/pt-BR/plugins/architecture.md
+++ b/docs/pt-BR/plugins/architecture.md
--- a/docs/pt-BR/plugins/manifest.md
+++ b/docs/pt-BR/plugins/manifest.md
@ -1,70 +1,62 @@
 ---
 read_when:
    - Você está criando um plugin do OpenClaw
-    - Você precisa entregar um schema de configuração de plugin ou depurar erros de validação de plugin
-summary: Manifesto de plugin + requisitos do schema JSON (validação estrita de configuração)
-title: Manifesto de plugin
+    - Você precisa fornecer um schema de configuração do plugin ou depurar erros de validação do plugin
+summary: Manifesto do plugin + requisitos do schema JSON (validação estrita de configuração)
+title: Manifesto do plugin
 x-i18n:
-    generated_at: "2026-04-11T02:46:02Z"
+    generated_at: "2026-04-11T15:16:04Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 6b254c121d1eb5ea19adbd4148243cf47339c960442ab1ca0e0bfd52e0154c88
+    source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4
    source_path: plugins/manifest.md
    workflow: 15
 ---

-# Manifesto de plugin (`openclaw.plugin.json`)
+# Manifesto do plugin (`openclaw.plugin.json`)

 Esta página é apenas para o **manifesto nativo de plugin do OpenClaw**.

-Para layouts de bundle compatíveis, veja [Plugin bundles](/pt-BR/plugins/bundles).
+Para layouts de bundle compatíveis, consulte [Bundles de plugin](/pt-BR/plugins/bundles).

 Formatos de bundle compatíveis usam arquivos de manifesto diferentes:

 - Bundle do Codex: `.codex-plugin/plugin.json`
- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude
-  sem manifesto
+- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude sem manifesto
 - Bundle do Cursor: `.cursor-plugin/plugin.json`

-O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados
-em relação ao schema de `openclaw.plugin.json` descrito aqui.
+O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados em relação ao schema `openclaw.plugin.json` descrito aqui.

-Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle mais as
-raízes de Skill declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude,
-padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde
-às expectativas de runtime do OpenClaw.
+Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle, além das raízes de Skills declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude, padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde às expectativas de runtime do OpenClaw.

-Todo plugin nativo do OpenClaw **deve** incluir um arquivo `openclaw.plugin.json` na
-**raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração
-**sem executar código do plugin**. Manifestos ausentes ou inválidos são tratados como
-erros de plugin e bloqueiam a validação da configuração.
+Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na **raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração **sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como erros de plugin e bloqueiam a validação da configuração.

-Veja o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin).
+Consulte o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin).
 Para o modelo nativo de capacidades e a orientação atual de compatibilidade externa:
 [Modelo de capacidades](/pt-BR/plugins/architecture#public-capability-model).

 ## O que este arquivo faz

-`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o
-código do seu plugin.
+`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o código do seu plugin.

 Use-o para:

 - identidade do plugin
 - validação de configuração
- metadados de auth e onboarding que devem estar disponíveis sem iniciar o runtime do plugin
+- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o runtime do plugin
+- dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o runtime ser carregado
+- descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o runtime ser carregado
 - metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin ser carregado
- metadados abreviados de posse de família de modelos que devem autoativar o
-  plugin antes de o runtime ser carregado
- snapshots estáticos de posse de capacidades usados para compatibilidade de bundles e cobertura de contrato
- metadados de configuração específicos de canal que devem ser mesclados nas superfícies de catálogo e validação sem carregar o runtime
+- metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o runtime ser carregado
+- snapshots estáticos de propriedade de capacidades usados para o cabeamento de compatibilidade empacotado e cobertura de contrato
+- metadados de configuração específicos de canal que devem ser mesclados em superfícies de catálogo e validação sem carregar o runtime
 - dicas de UI de configuração

 Não o use para:

 - registrar comportamento de runtime
 - declarar entrypoints de código
- metadados de instalação npm
+- metadados de instalação do npm

 Esses pertencem ao código do seu plugin e ao `package.json`.

@ -87,7 +79,7 @@ Esses pertencem ao código do seu plugin e ao `package.json`.
 {
  "id": "openrouter",
  "name": "OpenRouter",
-  "description": "OpenRouter provider plugin",
+  "description": "Plugin de provedor OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
@ -108,19 +100,19 @@ Esses pertencem ao código do seu plugin e ao `package.json`.
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
-      "choiceLabel": "OpenRouter API key",
+      "choiceLabel": "Chave de API do OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
-      "cliDescription": "OpenRouter API key",
+      "cliDescription": "Chave de API do OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
-      "label": "API key",
+      "label": "Chave de API",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
@ -141,58 +133,58 @@ Esses pertencem ao código do seu plugin e ao `package.json`.

 | Campo                               | Obrigatório | Tipo                             | O que significa                                                                                                                                                                                              |
 | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`                                | Sim         | `string`                         | ID canônico do plugin. Esse é o ID usado em `plugins.entries.<id>`.                                                                                                                                          |
-| `configSchema`                      | Sim         | `object`                         | JSON Schema inline para a configuração deste plugin.                                                                                                                                                         |
-| `enabledByDefault`                  | Não         | `true`                           | Marca um plugin incluído como ativado por padrão. Omita-o ou defina qualquer valor diferente de `true` para manter o plugin desativado por padrão.                                                       |
+| `id`                                | Sim         | `string`                         | ID canônico do plugin. Este é o ID usado em `plugins.entries.<id>`.                                                                                                                                         |
+| `configSchema`                      | Sim         | `object`                         | Schema JSON inline para a configuração deste plugin.                                                                                                                                                         |
+| `enabledByDefault`                  | Não         | `true`                           | Marca um plugin empacotado como habilitado por padrão. Omita-o ou defina qualquer valor diferente de `true` para deixar o plugin desabilitado por padrão.                                                  |
 | `legacyPluginIds`                   | Não         | `string[]`                       | IDs legados que são normalizados para este ID canônico de plugin.                                                                                                                                            |
-| `autoEnableWhenConfiguredProviders` | Não         | `string[]`                       | IDs de provedores que devem autoativar este plugin quando auth, configuração ou referências de modelo os mencionarem.                                                                                       |
+| `autoEnableWhenConfiguredProviders` | Não         | `string[]`                       | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem.                                                                                |
 | `kind`                              | Não         | `"memory"` \| `"context-engine"` | Declara um tipo exclusivo de plugin usado por `plugins.slots.*`.                                                                                                                                             |
-| `channels`                          | Não         | `string[]`                       | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração.                                                                                                                |
+| `channels`                          | Não         | `string[]`                       | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração.                                                                                                                 |
 | `providers`                         | Não         | `string[]`                       | IDs de provedores pertencentes a este plugin.                                                                                                                                                                |
-| `modelSupport`                      | Não         | `object`                         | Metadados abreviados de família de modelos de posse do manifesto usados para carregar automaticamente o plugin antes do runtime.                                                                            |
+| `modelSupport`                      | Não         | `object`                         | Metadados abreviados de família de modelos pertencentes ao manifesto usados para carregar automaticamente o plugin antes do runtime.                                                                         |
 | `cliBackends`                       | Não         | `string[]`                       | IDs de backends de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração.                                              |
-| `commandAliases`                    | Não         | `object[]`                       | Nomes de comandos pertencentes a este plugin que devem produzir configuração sensível ao plugin e diagnósticos de CLI antes de o runtime ser carregado.                                                    |
-| `providerAuthEnvVars`               | Não         | `Record<string, string[]>`       | Metadados simples de env de auth do provedor que o OpenClaw pode inspecionar sem carregar código do plugin.                                                                                                 |
-| `providerAuthAliases`               | Não         | `Record<string, string>`         | IDs de provedores que devem reutilizar outro ID de provedor para busca de auth, por exemplo um provedor de coding que compartilha a chave de API do provedor base e perfis de auth.                       |
-| `channelEnvVars`                    | Não         | `Record<string, string[]>`       | Metadados simples de env de canal que o OpenClaw pode inspecionar sem carregar código do plugin. Use isso para superfícies de configuração ou auth de canal orientadas por env que helpers genéricos de inicialização/configuração devem enxergar. |
-| `providerAuthChoices`               | Não         | `object[]`                       | Metadados simples de escolhas de auth para seletores de onboarding, resolução de provedor preferido e wiring simples de flags da CLI.                                                                      |
-| `contracts`                         | Não         | `object`                         | Snapshot estático de capacidades de bundle para fala, transcrição em tempo real, voz em tempo real, entendimento de mídia, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e posse de ferramentas. |
-| `channelConfigs`                    | Não         | `Record<string, object>`         | Metadados de configuração de canal pertencentes ao manifesto mesclados nas superfícies de descoberta e validação antes de o runtime ser carregado.                                                         |
+| `commandAliases`                    | Não         | `object[]`                       | Nomes de comandos pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI cientes do plugin antes de o runtime ser carregado.                                                     |
+| `providerAuthEnvVars`               | Não         | `Record<string, string[]>`       | Metadados leves de variáveis de ambiente de autenticação de provedor que o OpenClaw pode inspecionar sem carregar o código do plugin.                                                                      |
+| `providerAuthAliases`               | Não         | `Record<string, string>`         | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo, um provedor de programação que compartilha a chave de API do provedor base e perfis de autenticação. |
+| `channelEnvVars`                    | Não         | `Record<string, string[]>`       | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para configuração de canal orientada por env ou superfícies de autenticação que helpers genéricos de inicialização/configuração devem enxergar. |
+| `providerAuthChoices`               | Não         | `object[]`                       | Metadados leves de opções de autenticação para seletores de onboarding, resolução de provedor preferido e cabeamento simples de flags de CLI.                                                              |
+| `activation`                        | Não         | `object`                         | Dicas leves de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real.                              |
+| `setup`                             | Não         | `object`                         | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin.                                                              |
+| `contracts`                         | Não         | `object`                         | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, media-understanding, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e propriedade de ferramentas. |
+| `channelConfigs`                    | Não         | `Record<string, object>`         | Metadados de configuração de canal pertencentes ao manifesto mesclados em superfícies de descoberta e validação antes de o runtime ser carregado.                                                          |
 | `skills`                            | Não         | `string[]`                       | Diretórios de Skills para carregar, relativos à raiz do plugin.                                                                                                                                              |
 | `name`                              | Não         | `string`                         | Nome legível do plugin.                                                                                                                                                                                      |
-| `description`                       | Não         | `string`                         | Resumo curto mostrado nas superfícies de plugin.                                                                                                                                                             |
+| `description`                       | Não         | `string`                         | Resumo curto mostrado em superfícies de plugin.                                                                                                                                                              |
 | `version`                           | Não         | `string`                         | Versão informativa do plugin.                                                                                                                                                                                |
 | `uiHints`                           | Não         | `Record<string, object>`         | Rótulos de UI, placeholders e dicas de sensibilidade para campos de configuração.                                                                                                                            |

 ## Referência de `providerAuthChoices`

-Cada entrada de `providerAuthChoices` descreve uma escolha de onboarding ou auth.
+Cada entrada em `providerAuthChoices` descreve uma opção de onboarding ou autenticação.
 O OpenClaw lê isso antes de o runtime do provedor ser carregado.

-| Campo                 | Obrigatório | Tipo                                            | O que significa                                                                                          |
-| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `provider`            | Sim         | `string`                                        | ID do provedor ao qual esta escolha pertence.                                                            |
-| `method`              | Sim         | `string`                                        | ID do método de auth para o qual encaminhar.                                                             |
-| `choiceId`            | Sim         | `string`                                        | ID estável da escolha de auth usado pelos fluxos de onboarding e CLI.                                    |
-| `choiceLabel`         | Não         | `string`                                        | Rótulo voltado ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback.                         |
-| `choiceHint`          | Não         | `string`                                        | Texto auxiliar curto para o seletor.                                                                     |
-| `assistantPriority`   | Não         | `number`                                        | Valores menores são ordenados antes em seletores interativos orientados pelo assistente.                |
-| `assistantVisibility` | Não         | `"visible"` \| `"manual-only"`                  | Oculta a escolha dos seletores do assistente, mas ainda permite seleção manual pela CLI.                |
-| `deprecatedChoiceIds` | Não         | `string[]`                                      | IDs legados de escolha que devem redirecionar usuários para esta escolha substituta.                     |
-| `groupId`             | Não         | `string`                                        | ID opcional de grupo para agrupar escolhas relacionadas.                                                 |
-| `groupLabel`          | Não         | `string`                                        | Rótulo voltado ao usuário para esse grupo.                                                               |
-| `groupHint`           | Não         | `string`                                        | Texto auxiliar curto para o grupo.                                                                       |
-| `optionKey`           | Não         | `string`                                        | Chave interna de opção para fluxos simples de auth com uma única flag.                                   |
-| `cliFlag`             | Não         | `string`                                        | Nome da flag da CLI, como `--openrouter-api-key`.                                                        |
-| `cliOption`           | Não         | `string`                                        | Formato completo da opção da CLI, como `--openrouter-api-key <key>`.                                     |
-| `cliDescription`      | Não         | `string`                                        | Descrição usada na ajuda da CLI.                                                                         |
-| `onboardingScopes`    | Não         | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta escolha deve aparecer. Se omitido, o padrão é `["text-inference"]`. |
+| Campo                 | Obrigatório | Tipo                                            | O que significa                                                                                           |
+| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `provider`            | Sim         | `string`                                        | ID do provedor ao qual esta opção pertence.                                                               |
+| `method`              | Sim         | `string`                                        | ID do método de autenticação para encaminhamento.                                                         |
+| `choiceId`            | Sim         | `string`                                        | ID estável da opção de autenticação usado por fluxos de onboarding e CLI.                                 |
+| `choiceLabel`         | Não         | `string`                                        | Rótulo visível ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback.                          |
+| `choiceHint`          | Não         | `string`                                        | Texto curto de ajuda para o seletor.                                                                      |
+| `assistantPriority`   | Não         | `number`                                        | Valores menores são ordenados antes em seletores interativos conduzidos pelo assistente.                 |
+| `assistantVisibility` | Não         | `"visible"` \| `"manual-only"`                  | Oculta a opção dos seletores do assistente, mas ainda permite seleção manual pela CLI.                   |
+| `deprecatedChoiceIds` | Não         | `string[]`                                      | IDs legados de opções que devem redirecionar usuários para esta opção de substituição.                   |
+| `groupId`             | Não         | `string`                                        | ID opcional de grupo para agrupar opções relacionadas.                                                    |
+| `groupLabel`          | Não         | `string`                                        | Rótulo visível ao usuário para esse grupo.                                                                |
+| `groupHint`           | Não         | `string`                                        | Texto curto de ajuda para o grupo.                                                                        |
+| `optionKey`           | Não         | `string`                                        | Chave de opção interna para fluxos simples de autenticação com uma única flag.                            |
+| `cliFlag`             | Não         | `string`                                        | Nome da flag da CLI, como `--openrouter-api-key`.                                                         |
+| `cliOption`           | Não         | `string`                                        | Formato completo da opção da CLI, como `--openrouter-api-key <key>`.                                      |
+| `cliDescription`      | Não         | `string`                                        | Descrição usada na ajuda da CLI.                                                                          |
+| `onboardingScopes`    | Não         | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta opção deve aparecer. Se omitido, o padrão é `["text-inference"]`. |

 ## Referência de `commandAliases`

-Use `commandAliases` quando um plugin possui um nome de comando de runtime que os usuários podem
-colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw
-usa esses metadados para diagnósticos sem importar código de runtime do plugin.
+Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw usa esses metadados para diagnósticos sem importar o código de runtime do plugin.

 ```json
 {
@ -206,11 +198,77 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin
 }
 ```

-| Campo        | Obrigatório | Tipo              | O que significa                                                              |
-| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- |
-| `name`       | Sim         | `string`          | Nome do comando que pertence a este plugin.                                  |
+| Campo        | Obrigatório | Tipo              | O que significa                                                                |
+| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ |
+| `name`       | Sim         | `string`          | Nome do comando que pertence a este plugin.                                    |
 | `kind`       | Não         | `"runtime-slash"` | Marca o alias como um comando de barra do chat em vez de um comando raiz da CLI. |
-| `cliCommand` | Não         | `string`          | Comando raiz relacionado da CLI a sugerir para operações na CLI, se existir. |
+| `cliCommand` | Não         | `string`          | Comando raiz relacionado da CLI a ser sugerido para operações de CLI, se existir. |
+
+## Referência de `activation`
+
+Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle devem ativá-lo depois.
+
+Este bloco contém apenas metadados. Ele não registra comportamento de runtime e não substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin.
+
+```json
+{
+  "activation": {
+    "onProviders": ["openai"],
+    "onCommands": ["models"],
+    "onChannels": ["web"],
+    "onRoutes": ["gateway-webhook"],
+    "onCapabilities": ["provider", "tool"]
+  }
+}
+```
+
+| Campo            | Obrigatório | Tipo                                                 | O que significa                                                     |
+| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
+| `onProviders`    | Não         | `string[]`                                           | IDs de provedores que devem ativar este plugin quando solicitados.  |
+| `onCommands`     | Não         | `string[]`                                           | IDs de comandos que devem ativar este plugin.                       |
+| `onChannels`     | Não         | `string[]`                                           | IDs de canais que devem ativar este plugin.                         |
+| `onRoutes`       | Não         | `string[]`                                           | Tipos de rota que devem ativar este plugin.                         |
+| `onCapabilities` | Não         | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Dicas amplas de capacidade usadas pelo planejamento de ativação do plano de controle. |
+
+## Referência de `setup`
+
+Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin antes de o runtime ser carregado.
+
+```json
+{
+  "setup": {
+    "providers": [
+      {
+        "id": "openai",
+        "authMethods": ["api-key"],
+        "envVars": ["OPENAI_API_KEY"]
+      }
+    ],
+    "cliBackends": ["openai-cli"],
+    "configMigrations": ["legacy-openai-auth"],
+    "requiresRuntime": false
+  }
+}
+```
+
+O `cliBackends` de nível superior continua válido e continua descrevendo backends de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para fluxos de configuração/plano de controle que devem permanecer apenas como metadados.
+
+### Referência de `setup.providers`
+
+| Campo         | Obrigatório | Tipo       | O que significa                                                                         |
+| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- |
+| `id`          | Sim         | `string`   | ID do provedor exposto durante a configuração ou onboarding.                            |
+| `authMethods` | Não         | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar todo o runtime. |
+| `envVars`     | Não         | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin ser carregado. |
+
+### Campos de `setup`
+
+| Campo              | Obrigatório | Tipo       | O que significa                                                                |
+| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------ |
+| `providers`        | Não         | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. |
+| `cliBackends`      | Não         | `string[]` | IDs de backend disponíveis no momento da configuração sem ativação completa do runtime. |
+| `configMigrations` | Não         | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. |
+| `requiresRuntime`  | Não         | `boolean`  | Se a configuração ainda precisa da execução do runtime do plugin após a busca do descritor. |

 ## Referência de `uiHints`

@ -220,8 +278,8 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin
 {
  "uiHints": {
    "apiKey": {
-      "label": "API key",
-      "help": "Used for OpenRouter requests",
+      "label": "Chave de API",
+      "help": "Usada para solicitações ao OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
@ -231,19 +289,18 @@ usa esses metadados para diagnósticos sem importar código de runtime do plugin

 Cada dica de campo pode incluir:

-| Campo         | Tipo       | O que significa                        |
-| ------------- | ---------- | -------------------------------------- |
-| `label`       | `string`   | Rótulo do campo voltado ao usuário.    |
-| `help`        | `string`   | Texto auxiliar curto.                  |
-| `tags`        | `string[]` | Tags opcionais de UI.                  |
-| `advanced`    | `boolean`  | Marca o campo como avançado.           |
-| `sensitive`   | `boolean`  | Marca o campo como secreto ou sensível. |
+| Campo         | Tipo       | O que significa                           |
+| ------------- | ---------- | ----------------------------------------- |
+| `label`       | `string`   | Rótulo do campo visível ao usuário.       |
+| `help`        | `string`   | Texto curto de ajuda.                     |
+| `tags`        | `string[]` | Tags opcionais da UI.                     |
+| `advanced`    | `boolean`  | Marca o campo como avançado.              |
+| `sensitive`   | `boolean`  | Marca o campo como secreto ou sensível.   |
 | `placeholder` | `string`   | Texto de placeholder para entradas de formulário. |

 ## Referência de `contracts`

-Use `contracts` apenas para metadados estáticos de posse de capacidade que o OpenClaw pode
-ler sem importar o runtime do plugin.
+Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode ler sem importar o runtime do plugin.

 ```json
 {
@ -263,22 +320,21 @@ ler sem importar o runtime do plugin.

 Cada lista é opcional:

-| Campo                            | Tipo       | O que significa                                                 |
-| -------------------------------- | ---------- | --------------------------------------------------------------- |
-| `speechProviders`                | `string[]` | IDs de provedores de fala pertencentes a este plugin.           |
+| Campo                            | Tipo       | O que significa                                                  |
+| -------------------------------- | ---------- | ---------------------------------------------------------------- |
+| `speechProviders`                | `string[]` | IDs de provedores de fala pertencentes a este plugin.            |
 | `realtimeTranscriptionProviders` | `string[]` | IDs de provedores de transcrição em tempo real pertencentes a este plugin. |
 | `realtimeVoiceProviders`         | `string[]` | IDs de provedores de voz em tempo real pertencentes a este plugin. |
-| `mediaUnderstandingProviders`    | `string[]` | IDs de provedores de entendimento de mídia pertencentes a este plugin. |
+| `mediaUnderstandingProviders`    | `string[]` | IDs de provedores de media-understanding pertencentes a este plugin. |
 | `imageGenerationProviders`       | `string[]` | IDs de provedores de geração de imagem pertencentes a este plugin. |
 | `videoGenerationProviders`       | `string[]` | IDs de provedores de geração de vídeo pertencentes a este plugin. |
-| `webFetchProviders`              | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin.      |
-| `webSearchProviders`             | `string[]` | IDs de provedores de busca na web pertencentes a este plugin.   |
-| `tools`                          | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato de bundles. |
+| `webFetchProviders`              | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin.       |
+| `webSearchProviders`             | `string[]` | IDs de provedores de busca na web pertencentes a este plugin.    |
+| `tools`                          | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato empacotadas. |

 ## Referência de `channelConfigs`

-Use `channelConfigs` quando um plugin de canal precisa de metadados baratos de configuração antes
-de o runtime ser carregado.
+Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o runtime ser carregado.

 ```json
 {
@ -293,12 +349,12 @@ de o runtime ser carregado.
      },
      "uiHints": {
        "homeserverUrl": {
-          "label": "Homeserver URL",
+          "label": "URL do homeserver",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
-      "description": "Matrix homeserver connection",
+      "description": "Conexão com homeserver Matrix",
      "preferOver": ["matrix-legacy"]
    }
  }
@ -307,19 +363,17 @@ de o runtime ser carregado.

 Cada entrada de canal pode incluir:

-| Campo         | Tipo                     | O que significa                                                                        |
-| ------------- | ------------------------ | -------------------------------------------------------------------------------------- |
-| `schema`      | `object`                 | JSON Schema para `channels.<id>`. Obrigatório para cada entrada declarada de configuração de canal. |
-| `uiHints`     | `Record<string, object>` | Rótulos/placeholders/dicas de sensibilidade opcionais de UI para essa seção de configuração do canal. |
-| `label`       | `string`                 | Rótulo do canal mesclado às superfícies de seletor e inspeção quando os metadados de runtime não estão prontos. |
-| `description` | `string`                 | Descrição curta do canal para superfícies de inspeção e catálogo.                      |
-| `preferOver`  | `string[]`               | IDs de plugins legados ou de menor prioridade que este canal deve superar nas superfícies de seleção. |
+| Campo         | Tipo                     | O que significa                                                                                 |
+| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `schema`      | `object`                 | Schema JSON para `channels.<id>`. Obrigatório para cada entrada declarada de configuração de canal. |
+| `uiHints`     | `Record<string, object>` | Rótulos/placeholders/dicas opcionais de sensibilidade da UI para essa seção de configuração de canal. |
+| `label`       | `string`                 | Rótulo do canal mesclado em superfícies de seleção e inspeção quando os metadados de runtime não estiverem prontos. |
+| `description` | `string`                 | Descrição curta do canal para superfícies de inspeção e catálogo.                                |
+| `preferOver`  | `string[]`               | IDs de plugins legados ou de menor prioridade que este canal deve superar em superfícies de seleção. |

 ## Referência de `modelSupport`

-Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de
-IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin
-ser carregado.
+Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin ser carregado.

 ```json
 {
@ -332,74 +386,58 @@ ser carregado.

 O OpenClaw aplica esta precedência:

- referências explícitas `provider/model` usam os metadados de manifesto `providers` do proprietário
+- referências explícitas `provider/model` usam os metadados de manifesto de `providers` correspondentes
 - `modelPatterns` têm precedência sobre `modelPrefixes`
- se um plugin não incluído e um plugin incluído corresponderem, o plugin não incluído
-  vence
- ambiguidades restantes são ignoradas até que o usuário ou a configuração especifique um provedor
+- se um plugin não empacotado e um plugin empacotado corresponderem, o plugin não empacotado vence
+- a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor

 Campos:

 | Campo           | Tipo       | O que significa                                                                  |
-| --------------- | ---------- | -------------------------------------------------------------------------------- |
+| --------------- | ---------- | --------------------------------------------------------------------------------- |
 | `modelPrefixes` | `string[]` | Prefixos comparados com `startsWith` em relação a IDs abreviados de modelo.      |
-| `modelPatterns` | `string[]` | Sources de regex comparados com IDs abreviados de modelo após a remoção do sufixo do perfil. |
+| `modelPatterns` | `string[]` | Fontes de regex comparadas com IDs abreviados de modelo após a remoção do sufixo de perfil. |

-Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para
-mover `speechProviders`, `realtimeTranscriptionProviders`,
-`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
-`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal
-do manifesto não trata mais esses campos de nível superior como
-posse de capacidade.
+Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal do manifesto não trata mais esses campos de nível superior como propriedade de capacidade.

-## Manifesto versus `package.json`
+## Manifesto versus package.json

-Os dois arquivos têm funções diferentes:
+Os dois arquivos servem para funções diferentes:

-| Arquivo                | Use para                                                                                                                        |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha de auth e dicas de UI que devem existir antes de o código do plugin ser executado |
-| `package.json`         | Metadados npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, gating de instalação, setup ou metadados de catálogo |
+| Arquivo                | Use para                                                                                                                          |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de opção de autenticação e dicas de UI que precisam existir antes de o código do plugin ser executado |
+| `package.json`         | Metadados do npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo |

-Se você não tiver certeza sobre onde uma parte dos metadados deve ficar, use esta regra:
+Se você não tiver certeza de onde um metadado pertence, use esta regra:

- se o OpenClaw precisar conhecê-la antes de carregar o código do plugin, coloque-a em `openclaw.plugin.json`
- se for sobre empacotamento, arquivos de entrada ou comportamento de instalação npm, coloque-a em `package.json`
+- se o OpenClaw precisa conhecê-lo antes de carregar o código do plugin, coloque-o em `openclaw.plugin.json`
+- se ele trata de empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json`

 ### Campos de `package.json` que afetam a descoberta

-Alguns metadados de plugin anteriores ao runtime ficam intencionalmente em `package.json` no bloco
-`openclaw` em vez de `openclaw.plugin.json`.
+Alguns metadados de plugin pré-runtime ficam intencionalmente em `package.json`, dentro do bloco `openclaw`, em vez de `openclaw.plugin.json`.

 Exemplos importantes:

 | Campo                                                             | O que significa                                                                                                                             |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | `openclaw.extensions`                                             | Declara entrypoints nativos de plugin.                                                                                                      |
-| `openclaw.setupEntry`                                             | Entrypoint leve apenas para setup usado durante onboarding e inicialização adiada de canal.                                                 |
-| `openclaw.channel`                                                | Metadados simples de catálogo de canal, como rótulos, caminhos de docs, aliases e texto de seleção.                                        |
-| `openclaw.channel.configuredState`                                | Metadados leves de verificador de estado configurado que podem responder "já existe configuração apenas por env?" sem carregar o runtime completo do canal. |
-| `openclaw.channel.persistedAuthState`                             | Metadados leves de verificador de auth persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath`         | Dicas de instalação/atualização para plugins incluídos e publicados externamente.                                                           |
+| `openclaw.setupEntry`                                             | Entrypoint leve apenas para configuração usado durante o onboarding e a inicialização adiada de canal.                                      |
+| `openclaw.channel`                                                | Metadados leves de catálogo de canal, como rótulos, caminhos de documentação, aliases e texto de seleção.                                  |
+| `openclaw.channel.configuredState`                                | Metadados leves do verificador de estado configurado que podem responder "a configuração apenas por env já existe?" sem carregar o runtime completo do canal. |
+| `openclaw.channel.persistedAuthState`                             | Metadados leves do verificador de autenticação persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath`         | Dicas de instalação/atualização para plugins empacotados e publicados externamente.                                                        |
 | `openclaw.install.defaultChoice`                                  | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis.                                                       |
-| `openclaw.install.minHostVersion`                                 | Versão mínima compatível do host OpenClaw, usando um piso semver como `>=2026.3.22`.                                                       |
-| `openclaw.install.allowInvalidConfigRecovery`                     | Permite um caminho restrito de recuperação por reinstalação de plugin incluído quando a configuração é inválida.                           |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de setup sejam carregadas antes do plugin completo do canal durante a inicialização.               |
+| `openclaw.install.minHostVersion`                                 | Versão mínima compatível do host OpenClaw, usando um piso de semver como `>=2026.3.22`.                                                    |
+| `openclaw.install.allowInvalidConfigRecovery`                     | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida.                         |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração sejam carregadas antes do plugin completo do canal durante a inicialização.        |

-`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro
-de manifestos. Valores inválidos são rejeitados; valores válidos, mas mais novos, ignoram o
-plugin em hosts mais antigos.
+`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro de manifestos. Valores inválidos são rejeitados; valores válidos, porém mais novos, fazem o plugin ser ignorado em hosts mais antigos.

-`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não
-torna configurações quebradas arbitrárias instaláveis. Hoje ele só permite que fluxos de instalação
-se recuperem de falhas específicas e antigas de upgrade de plugin incluído, como um
-caminho ausente de plugin incluído ou uma entrada antiga `channels.<id>` para esse mesmo
-plugin incluído. Erros de configuração não relacionados ainda bloqueiam a instalação e direcionam os
-operadores para `openclaw doctor --fix`.
+`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna configurações arbitrariamente quebradas instaláveis. Hoje ele permite apenas que fluxos de instalação se recuperem de falhas específicas e antigas de upgrade de plugin empacotado, como um caminho ausente de plugin empacotado ou uma entrada `channels.<id>` antiga para esse mesmo plugin empacotado. Erros de configuração não relacionados continuam bloqueando a instalação e encaminham operadores para `openclaw doctor --fix`.

-`openclaw.channel.persistedAuthState` é metadado de pacote para um pequeno módulo
-de verificação:
+`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador mínimo:

 ```json
 {
@ -415,12 +453,9 @@ de verificação:
 }
 ```

-Use-o quando fluxos de setup, doctor ou estado configurado precisarem de uma
-sondagem barata de auth sim/não antes de o plugin completo do canal ser carregado. O export de destino deve ser uma pequena
-função que leia apenas o estado persistido; não o encaminhe pelo barrel completo de runtime do canal.
+Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem de uma verificação barata de autenticação sim/não antes de o plugin completo do canal ser carregado. A exportação de destino deve ser uma função pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo de runtime do canal.

-`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de
-estado configurado apenas por env:
+`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de estado configurado apenas por env:

 ```json
 {
@ -436,64 +471,42 @@ estado configurado apenas por env:
 }
 ```

-Use-o quando um canal puder responder ao estado configurado a partir de env ou de outras entradas pequenas
-não ligadas ao runtime. Se a verificação precisar de resolução completa de configuração ou do
-runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin.
+Use-o quando um canal puder responder ao estado configurado a partir de env ou outras entradas pequenas fora do runtime. Se a verificação precisar da resolução completa da configuração ou do runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin.

 ## Requisitos do JSON Schema

- **Todo plugin deve incluir um JSON Schema**, mesmo que não aceite configuração.
- Um schema vazio é aceitável (por exemplo, `{ "type": "object", "additionalProperties": false }`).
+- **Todo plugin deve fornecer um JSON Schema**, mesmo que não aceite nenhuma configuração.
+- Um schema vazio é aceitável, por exemplo `{ "type": "object", "additionalProperties": false }`.
 - Os schemas são validados no momento de leitura/gravação da configuração, não em runtime.

 ## Comportamento de validação

- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por
-  um manifesto de plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*`
-  devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**.
- Se um plugin estiver instalado, mas tiver um manifesto ou schema quebrado ou ausente,
-  a validação falhará e o Doctor relatará o erro do plugin.
- Se a configuração do plugin existir, mas o plugin estiver **desativado**, a configuração será mantida e
-  um **aviso** será exibido no Doctor + logs.
+- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por um manifesto de plugin.
+- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**.
+- Se um plugin estiver instalado, mas tiver um manifesto ou schema ausente ou com erro, a validação falha e o Doctor informa o erro do plugin.
+- Se a configuração do plugin existir, mas o plugin estiver **desabilitado**, a configuração é mantida e um **aviso** é exibido no Doctor + logs.

-Veja [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`.
+Consulte [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`.

 ## Observações

 - O manifesto é **obrigatório para plugins nativos do OpenClaw**, incluindo carregamentos locais do sistema de arquivos.
- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para
-  descoberta + validação.
- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e
-  chaves sem aspas são aceitos, desde que o valor final continue sendo um objeto.
- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar
-  chaves personalizadas de nível superior aqui.
- `providerAuthEnvVars` é o caminho de metadados simples para sondagens de auth, validação de marcadores de env
-  e superfícies semelhantes de auth de provedor que não devem iniciar o runtime do plugin
-  apenas para inspecionar nomes de env.
- `providerAuthAliases` permite que variantes de provedor reutilizem a auth de outro
-  provedor, incluindo env vars de auth, perfis de auth, auth baseada em configuração e escolha de onboarding por chave de API,
-  sem hardcoding dessa relação no core.
- `channelEnvVars` é o caminho de metadados simples para fallback por shell-env, prompts de setup
-  e superfícies semelhantes de canal que não devem iniciar o runtime do plugin
-  apenas para inspecionar nomes de env.
- `providerAuthChoices` é o caminho de metadados simples para seletores de escolha de auth,
-  resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags de CLI de onboarding
-  antes de o runtime do provedor ser carregado. Para metadados do assistente de runtime
-  que exigem código do provedor, veja
-  [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks).
+- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para descoberta + validação.
+- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto.
+- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior.
+- `providerAuthEnvVars` é o caminho de metadados leve para sondagens de autenticação, validação de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env.
+- `providerAuthAliases` permite que variantes de provedor reutilizem variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding por chave de API de outro provedor sem codificar rigidamente esse relacionamento no core.
+- `channelEnvVars` é o caminho de metadados leve para fallback de env do shell, prompts de configuração e superfícies semelhantes de canal que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env.
+- `providerAuthChoices` é o caminho de metadados leve para seletores de opção de autenticação, resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags da CLI de onboarding antes de o runtime do provedor ser carregado. Para metadados de assistente de runtime que exigem código do provedor, consulte [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks).
 - Tipos exclusivos de plugin são selecionados por meio de `plugins.slots.*`.
  - `kind: "memory"` é selecionado por `plugins.slots.memory`.
-  - `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine`
-    (padrão: `legacy` incluído).
- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um
-  plugin não precisa deles.
- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer
-  requisitos de allowlist do gerenciador de pacotes (por exemplo, `allow-build-scripts` do pnpm
-  - `pnpm rebuild <package>`).
+  - `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine` (padrão: `legacy` interno).
+- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um plugin não precisa deles.
+- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer requisitos de allowlist do gerenciador de pacotes, por exemplo pnpm `allow-build-scripts`
+  - `pnpm rebuild <package>`.

 ## Relacionado

- [Criando plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins
- [Plugin Architecture](/pt-BR/plugins/architecture) — arquitetura interna
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do Plugin SDK
+- [Criando Plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins
+- [Arquitetura de plugins](/pt-BR/plugins/architecture) — arquitetura interna
+- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de plugins
--- a/docs/pt-BR/reference/rich-output-protocol.md
+++ b/docs/pt-BR/reference/rich-output-protocol.md
@ -0,0 +1,60 @@
+---
+x-i18n:
+    generated_at: "2026-04-11T15:15:56Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: 2a8884fc2c304bf96d4675f0c1d1ff781d6dc1ae8c49d92ce08040c9c7709035
+    source_path: reference/rich-output-protocol.md
+    workflow: 15
+---
+
+# Protocolo de Saída Rica
+
+A saída do assistente pode incluir um pequeno conjunto de diretivas de entrega/renderização:
+
+- `MEDIA:` para entrega de anexos
+- `[[audio_as_voice]]` para dicas de apresentação em áudio
+- `[[reply_to_current]]` / `[[reply_to:<id>]]` para metadados de resposta
+- `[embed ...]` para renderização rica na Interface de Controle
+
+Essas diretivas são separadas. `MEDIA:` e as tags de resposta/voz continuam sendo metadados de entrega; `[embed ...]` é o caminho de renderização rica apenas para a web.
+
+## `[embed ...]`
+
+`[embed ...]` é a única sintaxe de renderização rica voltada a agentes para a Interface de Controle.
+
+Exemplo autocontido:
+
+```text
+[embed ref="cv_123" title="Status" /]
+```
+
+Regras:
+
+- `[view ...]` não é mais válido para novas saídas.
+- Os shortcodes de embed são renderizados apenas na superfície de mensagens do assistente.
+- Apenas embeds com URL são renderizados. Use `ref="..."` ou `url="..."`.
+- Shortcodes de embed em HTML inline no formato de bloco não são renderizados.
+- A interface web remove o shortcode do texto visível e renderiza o embed inline.
+- `MEDIA:` não é um alias de embed e não deve ser usado para renderização rica de embeds.
+
+## Forma de Renderização Armazenada
+
+O bloco de conteúdo do assistente normalizado/armazenado é um item `canvas` estruturado:
+
+```json
+{
+  "type": "canvas",
+  "preview": {
+    "kind": "canvas",
+    "surface": "assistant_message",
+    "render": "url",
+    "viewId": "cv_123",
+    "url": "/__openclaw__/canvas/documents/cv_123/index.html",
+    "title": "Status",
+    "preferredHeight": 320
+  }
+}
+```
+
+Blocos ricos armazenados/renderizados usam diretamente esta forma `canvas`. `present_view` não é reconhecido.
--- a/docs/pt-BR/tools/video-generation.md
+++ b/docs/pt-BR/tools/video-generation.md
@ -1,35 +1,34 @@
 ---
 read_when:
-    - Gerando vídeos pelo agente
-    - Configurando provedores e modelos de geração de vídeo
-    - Entendendo os parâmetros da ferramenta video_generate
-summary: Gere vídeos a partir de texto, imagens ou vídeos existentes usando 12 backends de provedor
-title: Geração de vídeo
+    - Gerando vídeos por meio do agente
+    - Configurando provedores e modelos de geração de vídeos
+    - Entendendo os parâmetros da ferramenta `video_generate`
+summary: Gere vídeos a partir de texto, imagens ou vídeos existentes usando 14 backends de provedores
+title: Geração de vídeos
 x-i18n:
-    generated_at: "2026-04-11T02:47:58Z"
+    generated_at: "2026-04-11T15:16:05Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 6848d03ef578181902517d068e8d9fe2f845e572a90481bbdf7bd9f1c591f245
+    source_hash: 0ec159a0bbb6b8a030e68828c0a8bcaf40c8538ecf98bc8ff609dab9d0068263
    source_path: tools/video-generation.md
    workflow: 15
 ---

-# Geração de vídeo
+# Geração de vídeos

-Agentes do OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou vídeos existentes. Há suporte para doze backends de provedor, cada um com diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe automaticamente o provedor correto com base na sua configuração e nas chaves de API disponíveis.
+Agentes OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou vídeos existentes. Há suporte para quatorze backends de provedores, cada um com diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe automaticamente o provedor certo com base na sua configuração e nas chaves de API disponíveis.

 <Note>
-A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo está disponível. Se você não a vir nas ferramentas do seu agente, defina uma chave de API do provedor ou configure `agents.defaults.videoGenerationModel`.
+A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo está disponível. Se você não a vir nas ferramentas do seu agente, defina uma chave de API de provedor ou configure `agents.defaults.videoGenerationModel`.
 </Note>

-O OpenClaw trata a geração de vídeo como três modos de runtime:
+O OpenClaw trata a geração de vídeos como três modos de execução:

 - `generate` para solicitações de texto para vídeo sem mídia de referência
 - `imageToVideo` quando a solicitação inclui uma ou mais imagens de referência
 - `videoToVideo` quando a solicitação inclui um ou mais vídeos de referência

-Os provedores podem oferecer suporte a qualquer subconjunto desses modos. A ferramenta valida o
-modo ativo antes do envio e informa os modos compatíveis em `action=list`.
+Os provedores podem oferecer suporte a qualquer subconjunto desses modos. A ferramenta valida o modo ativo antes do envio e informa os modos compatíveis em `action=list`.

 ## Início rápido

@ -49,20 +48,20 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1

 > Gere um vídeo cinematográfico de 5 segundos de uma lagosta amigável surfando ao pôr do sol.

-O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramenta é necessária.
+O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramentas é necessária.

 ## O que acontece quando você gera um vídeo

-A geração de vídeo é assíncrona. Quando o agente chama `video_generate` em uma sessão:
+A geração de vídeos é assíncrona. Quando o agente chama `video_generate` em uma sessão:

 1. O OpenClaw envia a solicitação ao provedor e retorna imediatamente um ID de tarefa.
-2. O provedor processa o job em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução).
-3. Quando o vídeo fica pronto, o OpenClaw reativa a mesma sessão com um evento interno de conclusão.
+2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução).
+3. Quando o vídeo está pronto, o OpenClaw reativa a mesma sessão com um evento interno de conclusão.
 4. O agente publica o vídeo finalizado de volta na conversa original.

-Enquanto um job estiver em andamento, chamadas duplicadas de `video_generate` na mesma sessão retornam o status atual da tarefa em vez de iniciar outra geração. Use `openclaw tasks list` ou `openclaw tasks show <taskId>` para verificar o progresso pela CLI.
+Enquanto um trabalho está em andamento, chamadas duplicadas de `video_generate` na mesma sessão retornam o status atual da tarefa em vez de iniciar outra geração. Use `openclaw tasks list` ou `openclaw tasks show <taskId>` para verificar o progresso pela CLI.

-Fora de execuções de agente com suporte a sessão (por exemplo, invocações diretas de ferramenta), a ferramenta recorre à geração inline e retorna o caminho final da mídia no mesmo turno.
+Fora de execuções de agente com suporte de sessão (por exemplo, invocações diretas da ferramenta), a ferramenta recorre à geração inline e retorna o caminho final da mídia no mesmo turno.

 ### Ciclo de vida da tarefa

@ -70,8 +69,8 @@ Cada solicitação `video_generate` passa por quatro estados:

 1. **queued** -- tarefa criada, aguardando o provedor aceitá-la.
 2. **running** -- o provedor está processando (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução).
-3. **succeeded** -- vídeo pronto; o agente é reativado e o publica na conversa.
-4. **failed** -- erro do provedor ou timeout; o agente é reativado com detalhes do erro.
+3. **succeeded** -- vídeo pronto; o agente reativa e o publica na conversa.
+4. **failed** -- erro do provedor ou tempo limite; o agente reativa com detalhes do erro.

 Verifique o status pela CLI:

@ -81,118 +80,138 @@ openclaw tasks show <taskId>
 openclaw tasks cancel <taskId>
 ```

-Prevenção de duplicatas: se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual, `video_generate` retornará o status da tarefa existente em vez de iniciar uma nova. Use `action: "status"` para verificar explicitamente sem disparar uma nova geração.
+Prevenção de duplicatas: se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual, `video_generate` retorna o status da tarefa existente em vez de iniciar uma nova. Use `action: "status"` para verificar explicitamente sem acionar uma nova geração.

 ## Provedores compatíveis

-| Provedor | Modelo padrão                  | Texto | Imagem ref        | Vídeo ref        | Chave de API                             |
-| -------- | ------------------------------ | ----- | ----------------- | ---------------- | ---------------------------------------- |
-| Alibaba  | `wan2.6-t2v`                   | Sim   | Sim (URL remota)  | Sim (URL remota) | `MODELSTUDIO_API_KEY`                    |
-| BytePlus | `seedance-1-0-lite-t2v-250428` | Sim   | 1 imagem          | Não              | `BYTEPLUS_API_KEY`                       |
-| ComfyUI  | `workflow`                     | Sim   | 1 imagem          | Não              | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
-| fal      | `fal-ai/minimax/video-01-live` | Sim   | 1 imagem          | Não              | `FAL_KEY`                                |
-| Google   | `veo-3.1-fast-generate-preview`| Sim   | 1 imagem          | 1 vídeo          | `GEMINI_API_KEY`                         |
-| MiniMax  | `MiniMax-Hailuo-2.3`           | Sim   | 1 imagem          | Não              | `MINIMAX_API_KEY`                        |
-| OpenAI   | `sora-2`                       | Sim   | 1 imagem          | 1 vídeo          | `OPENAI_API_KEY`                         |
-| Qwen     | `wan2.6-t2v`                   | Sim   | Sim (URL remota)  | Sim (URL remota) | `QWEN_API_KEY`                           |
-| Runway   | `gen4.5`                       | Sim   | 1 imagem          | 1 vídeo          | `RUNWAYML_API_SECRET`                    |
-| Together | `Wan-AI/Wan2.2-T2V-A14B`       | Sim   | 1 imagem          | Não              | `TOGETHER_API_KEY`                       |
-| Vydra    | `veo3`                         | Sim   | 1 imagem (`kling`)| Não              | `VYDRA_API_KEY`                          |
-| xAI      | `grok-imagine-video`           | Sim   | 1 imagem          | 1 vídeo          | `XAI_API_KEY`                            |
+| Provedor              | Modelo padrão                   | Texto | Imagem de referência                                  | Vídeo de referência | Chave de API                              |
+| --------------------- | ------------------------------- | ----- | ----------------------------------------------------- | ------------------- | ----------------------------------------- |
+| Alibaba               | `wan2.6-t2v`                    | Sim   | Sim (URL remota)                                      | Sim (URL remota)    | `MODELSTUDIO_API_KEY`                     |
+| BytePlus (1.0)        | `seedance-1-0-pro-250528`       | Sim   | Até 2 imagens (apenas modelos I2V; primeiro + último quadro) | Não                 | `BYTEPLUS_API_KEY`                        |
+| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215`       | Sim   | Até 2 imagens (primeiro + último quadro via função)   | Não                 | `BYTEPLUS_API_KEY`                        |
+| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128`  | Sim   | Até 9 imagens de referência                           | Até 3 vídeos        | `BYTEPLUS_API_KEY`                        |
+| ComfyUI               | `workflow`                      | Sim   | 1 imagem                                              | Não                 | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`  |
+| fal                   | `fal-ai/minimax/video-01-live`  | Sim   | 1 imagem                                              | Não                 | `FAL_KEY`                                 |
+| Google                | `veo-3.1-fast-generate-preview` | Sim   | 1 imagem                                              | 1 vídeo             | `GEMINI_API_KEY`                          |
+| MiniMax               | `MiniMax-Hailuo-2.3`            | Sim   | 1 imagem                                              | Não                 | `MINIMAX_API_KEY`                         |
+| OpenAI                | `sora-2`                        | Sim   | 1 imagem                                              | 1 vídeo             | `OPENAI_API_KEY`                          |
+| Qwen                  | `wan2.6-t2v`                    | Sim   | Sim (URL remota)                                      | Sim (URL remota)    | `QWEN_API_KEY`                            |
+| Runway                | `gen4.5`                        | Sim   | 1 imagem                                              | 1 vídeo             | `RUNWAYML_API_SECRET`                     |
+| Together              | `Wan-AI/Wan2.2-T2V-A14B`        | Sim   | 1 imagem                                              | Não                 | `TOGETHER_API_KEY`                        |
+| Vydra                 | `veo3`                          | Sim   | 1 imagem (`kling`)                                    | Não                 | `VYDRA_API_KEY`                           |
+| xAI                   | `grok-imagine-video`            | Sim   | 1 imagem                                              | 1 vídeo             | `XAI_API_KEY`                             |

-Alguns provedores aceitam variáveis de ambiente adicionais ou alternativas para chave de API. Consulte as [páginas de provedor](#related) individuais para obter detalhes.
+Alguns provedores aceitam variáveis de ambiente adicionais ou alternativas para a chave de API. Consulte as [páginas individuais dos provedores](#related) para obter detalhes.

-Execute `video_generate action=list` para inspecionar provedores, modelos e
-modos de runtime disponíveis em tempo de execução.
+Execute `video_generate action=list` para inspecionar os provedores, modelos e modos de execução disponíveis em tempo de execução.

-### Matriz de capacidades declaradas
+### Matriz de capacidades declarada

-Este é o contrato explícito de modo usado por `video_generate`, testes de contrato
-e a varredura live compartilhada.
+Este é o contrato explícito de modo usado por `video_generate`, testes de contrato e a varredura live compartilhada.

-| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Lanes live compartilhadas atualmente                                                                                                     |
-| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Alibaba  | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo remotas `http(s)`                    |
-| BytePlus | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                               |
+| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Lanes live compartilhadas atualmente                                                                                                    |
+| -------- | ---------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Alibaba  | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor exige URLs de vídeo remotas `http(s)`                        |
+| BytePlus | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                              |
 | ComfyUI  | Sim        | Sim            | Não            | Não está na varredura compartilhada; a cobertura específica de workflow fica com os testes do Comfy                                    |
-| fal      | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                               |
+| fal      | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                              |
 | Google   | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura Gemini/Veo atual com buffer não aceita essa entrada |
-| MiniMax  | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                               |
-| OpenAI   | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho atual de organização/entrada precisa de acesso a inpaint/remix do lado do provedor |
-| Qwen     | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo remotas `http(s)`                    |
-| Runway   | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` roda apenas quando o modelo selecionado é `runway/gen4_aleph`                               |
-| Together | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                               |
+| MiniMax  | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                              |
+| OpenAI   | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente exige acesso a inpaint/remix do lado do provedor |
+| Qwen     | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor exige URLs de vídeo remotas `http(s)`                        |
+| Runway   | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` só é executado quando o modelo selecionado é `runway/gen4_aleph`                           |
+| Together | Sim        | Sim            | Não            | `generate`, `imageToVideo`                                                                                                              |
 | Vydra    | Sim        | Sim            | Não            | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL de imagem remota |
-| xAI      | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota                      |
+| xAI      | Sim        | Sim            | Sim            | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente exige uma URL MP4 remota                          |

 ## Parâmetros da ferramenta

-### Obrigatório
+### Obrigatórios

-| Parâmetro | Tipo   | Descrição                                                                     |
-| --------- | ------ | ----------------------------------------------------------------------------- |
-| `prompt`  | string | Descrição em texto do vídeo a ser gerado (obrigatório para `action: "generate"`) |
+| Parâmetro | Tipo   | Descrição                                                                    |
+| --------- | ------ | ---------------------------------------------------------------------------- |
+| `prompt`  | string | Descrição em texto do vídeo a ser gerado (obrigatória para `action: "generate"`) |

 ### Entradas de conteúdo

-| Parâmetro | Tipo     | Descrição                             |
-| --------- | -------- | ------------------------------------- |
-| `image`   | string   | Imagem única de referência (caminho ou URL) |
-| `images`  | string[] | Várias imagens de referência (até 5)  |
-| `video`   | string   | Vídeo único de referência (caminho ou URL) |
-| `videos`  | string[] | Vários vídeos de referência (até 4)   |
+| Parâmetro   | Tipo     | Descrição                                                                                                                              |
+| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `image`     | string   | Imagem de referência única (caminho ou URL)                                                                                            |
+| `images`    | string[] | Múltiplas imagens de referência (até 9)                                                                                                |
+| `imageRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de imagens. Valores canônicos: `first_frame`, `last_frame`, `reference_image` |
+| `video`     | string   | Vídeo de referência único (caminho ou URL)                                                                                             |
+| `videos`    | string[] | Múltiplos vídeos de referência (até 4)                                                                                                 |
+| `videoRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de vídeos. Valor canônico: `reference_video`                        |
+| `audioRef`  | string   | Áudio de referência único (caminho ou URL). Usado, por exemplo, para música de fundo ou referência de voz quando o provedor oferece suporte a entradas de áudio |
+| `audioRefs` | string[] | Múltiplos áudios de referência (até 3)                                                                                                 |
+| `audioRoles`| string[] | Dicas opcionais de função por posição paralelas à lista combinada de áudios. Valor canônico: `reference_audio`                        |
+
+As dicas de função são encaminhadas ao provedor como estão. Os valores canônicos vêm da união `VideoGenerationAssetRole`, mas os provedores podem aceitar strings de função adicionais. Os arrays `*Roles` não devem ter mais entradas do que a lista de referência correspondente; erros de contagem recebem uma mensagem clara. Use uma string vazia para deixar uma posição sem definir.

 ### Controles de estilo

-| Parâmetro        | Tipo    | Descrição                                                                |
-| ---------------- | ------- | ------------------------------------------------------------------------ |
-| `aspectRatio`    | string  | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
-| `resolution`     | string  | `480P`, `720P`, `768P` ou `1080P`                                        |
+| Parâmetro        | Tipo    | Descrição                                                                            |
+| ---------------- | ------- | ------------------------------------------------------------------------------------ |
+| `aspectRatio`    | string  | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` ou `adaptive` |
+| `resolution`     | string  | `480P`, `720P`, `768P` ou `1080P`                                                    |
 | `durationSeconds`| number  | Duração alvo em segundos (arredondada para o valor compatível mais próximo do provedor) |
-| `size`           | string  | Dica de tamanho quando o provedor oferece suporte                        |
-| `audio`          | boolean | Habilita áudio gerado quando houver suporte                              |
-| `watermark`      | boolean | Ativa/desativa marca d'água do provedor quando houver suporte            |
+| `size`           | string  | Dica de tamanho quando o provedor oferece suporte a isso                            |
+| `audio`          | boolean | Ativa o áudio gerado na saída quando compatível. Diferente de `audioRef*` (entradas) |
+| `watermark`      | boolean | Ativa ou desativa a marca d'água do provedor quando compatível                      |
+
+`adaptive` é um valor sentinela específico do provedor: ele é encaminhado como está para provedores que declaram `adaptive` em suas capacidades (por exemplo, o BytePlus Seedance o usa para detectar automaticamente a proporção com base nas dimensões da imagem de entrada). Provedores que não o declaram expõem o valor por meio de `details.ignoredOverrides` no resultado da ferramenta para que a omissão fique visível.

 ### Avançado

-| Parâmetro | Tipo   | Descrição                                          |
-| --------- | ------ | -------------------------------------------------- |
-| `action`  | string | `"generate"` (padrão), `"status"` ou `"list"`      |
-| `model`   | string | Substituição de provedor/modelo (por exemplo, `runway/gen4.5`) |
-| `filename`| string | Dica para nome do arquivo de saída                 |
+| Parâmetro        | Tipo   | Descrição                                                                                                                                                                                                                                                                                                                                          |
+| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`         | string | `"generate"` (padrão), `"status"` ou `"list"`                                                                                                                                                                                                                                                                                                      |
+| `model`          | string | Sobrescrita de provedor/modelo (por exemplo, `runway/gen4.5`)                                                                                                                                                                                                                                                                                     |
+| `filename`       | string | Dica de nome de arquivo de saída                                                                                                                                                                                                                                                                                                                   |
+| `providerOptions`| object | Opções específicas do provedor como um objeto JSON (por exemplo, `{"seed": 42, "draft": true}`). Provedores que declaram um esquema tipado validam as chaves e os tipos; chaves desconhecidas ou incompatibilidades fazem com que o candidato seja ignorado durante o fallback. Provedores sem um esquema declarado recebem as opções como estão. Execute `video_generate action=list` para ver o que cada provedor aceita |

-Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw já normaliza a duração para o valor compatível mais próximo do provedor e também remapeia dicas de geometria traduzidas, como size para aspect ratio, quando um provedor de fallback expõe uma superfície de controle diferente. Substituições realmente sem suporte são ignoradas no melhor esforço e informadas como avisos no resultado da ferramenta. Limites rígidos de capacidade, como entradas de referência em excesso, falham antes do envio.
+Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw já normaliza a duração para o valor compatível mais próximo do provedor e também remapeia dicas de geometria traduzidas, como tamanho para proporção, quando um provedor de fallback expõe uma superfície de controle diferente. Sobrescritas realmente não compatíveis são ignoradas em regime de melhor esforço e relatadas como avisos no resultado da ferramenta. Limites rígidos de capacidade, como entradas de referência demais, falham antes do envio.

-Os resultados da ferramenta informam as configurações aplicadas. Quando o OpenClaw remapeia duração ou geometria durante o fallback de provedor, os valores retornados de `durationSeconds`, `size`, `aspectRatio` e `resolution` refletem o que foi enviado, e `details.normalization` registra a tradução do solicitado para o aplicado.
+Os resultados da ferramenta informam as configurações aplicadas. Quando o OpenClaw remapeia duração ou geometria durante o fallback do provedor, os valores retornados de `durationSeconds`, `size`, `aspectRatio` e `resolution` refletem o que foi enviado, e `details.normalization` captura a tradução do solicitado para o aplicado.

-As entradas de referência também selecionam o modo de runtime:
+As entradas de referência também selecionam o modo de execução:

 - Sem mídia de referência: `generate`
 - Qualquer imagem de referência: `imageToVideo`
 - Qualquer vídeo de referência: `videoToVideo`
+- Entradas de áudio de referência não alteram o modo resolvido; elas se aplicam sobre o modo que as referências de imagem/vídeo selecionarem e só funcionam com provedores que declaram `maxInputAudios`

-Referências mistas de imagem e vídeo não formam uma superfície compartilhada de capacidade estável.
+Referências mistas de imagem e vídeo não são uma superfície de capacidade compartilhada estável.
 Prefira um tipo de referência por solicitação.

+#### Fallback e opções tipadas
+
+Algumas verificações de capacidade são aplicadas na camada de fallback, e não no limite da ferramenta, para que uma solicitação que exceda os limites do provedor principal ainda possa ser executada em um fallback compatível:
+
+- Se o candidato ativo não declarar `maxInputAudios` (ou o declarar como `0`), ele será ignorado quando a solicitação contiver referências de áudio, e o próximo candidato será tentado.
+- Se `maxDurationSeconds` do candidato ativo for menor que `durationSeconds` solicitado e o candidato não declarar uma lista `supportedDurationSeconds`, ele será ignorado.
+- Se a solicitação contiver `providerOptions` e o candidato ativo declarar explicitamente um esquema tipado de `providerOptions`, o candidato será ignorado quando as chaves fornecidas não estiverem no esquema ou quando os tipos dos valores não corresponderem. Provedores que ainda não declararam um esquema recebem as opções como estão (pass-through compatível com versões anteriores). Um provedor pode desativar explicitamente todas as opções de provedor declarando um esquema vazio (`capabilities.providerOptions: {}`), o que causa a mesma omissão que uma incompatibilidade de tipo.
+
+O primeiro motivo de omissão em uma solicitação é registrado em `warn` para que os operadores vejam quando seu provedor principal foi ignorado; omissões posteriores são registradas em `debug` para manter silenciosas cadeias longas de fallback. Se todos os candidatos forem ignorados, o erro agregado inclui o motivo da omissão de cada um.
+
 ## Ações

- **generate** (padrão) -- cria um vídeo a partir do prompt fornecido e entradas de referência opcionais.
- **status** -- verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração.
+- **generate** (padrão) -- cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais.
+- **status** -- verifica o estado da tarefa de vídeo em andamento da sessão atual sem iniciar outra geração.
 - **list** -- mostra provedores, modelos e suas capacidades disponíveis.

 ## Seleção de modelo

 Ao gerar um vídeo, o OpenClaw resolve o modelo nesta ordem:

-1. **Parâmetro `model` da ferramenta** -- se o agente especificar um na chamada.
-2. **`videoGenerationModel.primary`** -- vindo da configuração.
+1. **Parâmetro de ferramenta `model`** -- se o agente especificar um na chamada.
+2. **`videoGenerationModel.primary`** -- da configuração.
 3. **`videoGenerationModel.fallbacks`** -- tentados em ordem.
-4. **Detecção automática** -- usa provedores que têm autenticação válida, começando pelo provedor padrão atual e depois pelos provedores restantes em ordem alfabética.
+4. **Detecção automática** -- usa provedores que têm autenticação válida, começando pelo provedor padrão atual e depois os provedores restantes em ordem alfabética.

 Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos os candidatos falharem, o erro incluirá detalhes de cada tentativa.

-Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` se você quiser
-que a geração de vídeo use apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
+Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` se quiser que a geração de vídeos use apenas as entradas explícitas `model`, `primary` e `fallbacks`.

 ```json5
 {
@ -207,56 +226,28 @@ que a geração de vídeo use apenas as entradas explícitas de `model`, `primar
 }
 ```

-O agente de vídeo da HeyGen no fal pode ser fixado com:
-
-```json5
-{
-  agents: {
-    defaults: {
-      videoGenerationModel: {
-        primary: "fal/fal-ai/heygen/v2/video-agent",
-      },
-    },
-  },
-}
-```
-
-O Seedance 2.0 no fal pode ser fixado com:
-
-```json5
-{
-  agents: {
-    defaults: {
-      videoGenerationModel: {
-        primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
-      },
-    },
-  },
-}
-```
-
 ## Observações sobre provedores

-| Provedor | Observações                                                                                                                                                           |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Alibaba  | Usa o endpoint assíncrono do DashScope/Model Studio. Imagens e vídeos de referência precisam ser URLs remotas `http(s)`.                                           |
-| BytePlus | Apenas uma imagem de referência.                                                                                                                                      |
-| ComfyUI  | Execução local ou em nuvem orientada por workflow. Oferece suporte a texto para vídeo e imagem para vídeo por meio do grafo configurado.                            |
-| fal      | Usa fluxo com fila para jobs de longa duração. Apenas uma imagem de referência. Inclui refs de modelo HeyGen video-agent e Seedance 2.0 para texto para vídeo e imagem para vídeo. |
-| Google   | Usa Gemini/Veo. Oferece suporte a uma imagem ou um vídeo de referência.                                                                                              |
-| MiniMax  | Apenas uma imagem de referência.                                                                                                                                      |
-| OpenAI   | Apenas a substituição de `size` é encaminhada. Outras substituições de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) são ignoradas com um aviso.      |
-| Qwen     | Mesmo backend DashScope do Alibaba. Entradas de referência precisam ser URLs remotas `http(s)`; arquivos locais são rejeitados antecipadamente.                     |
-| Runway   | Oferece suporte a arquivos locais por meio de URIs de dados. Vídeo para vídeo exige `runway/gen4_aleph`. Execuções somente com texto expõem proporções `16:9` e `9:16`. |
-| Together | Apenas uma imagem de referência.                                                                                                                                      |
-| Vydra    | Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos que descartam autenticação. `veo3` é empacotado apenas como texto para vídeo; `kling` exige uma URL remota de imagem. |
-| xAI      | Oferece suporte a fluxos de texto para vídeo, imagem para vídeo e edição/extensão de vídeo remoto.                                                                  |
+| Provedor              | Observações                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Alibaba               | Usa o endpoint assíncrono do DashScope/Model Studio. Imagens e vídeos de referência devem ser URLs remotas `http(s)`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| BytePlus (1.0)        | ID do provedor `byteplus`. Modelos: `seedance-1-0-pro-250528` (padrão), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Modelos T2V (`*-t2v-*`) não aceitam entradas de imagem; modelos I2V e modelos gerais `*-pro-*` oferecem suporte a uma única imagem de referência (primeiro quadro). Passe a imagem posicionalmente ou defina `role: "first_frame"`. IDs de modelo T2V são alternados automaticamente para a variante I2V correspondente quando uma imagem é fornecida. Chaves `providerOptions` compatíveis: `seed` (number), `draft` (boolean, força 480p), `camera_fixed` (boolean). |
+| BytePlus Seedance 1.5 | Requer o plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID do provedor `byteplus-seedance15`. Modelo: `seedance-1-5-pro-251215`. Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens de entrada (`first_frame` + `last_frame`). Todas as entradas devem ser URLs remotas `https://`. Defina `role: "first_frame"` / `"last_frame"` em cada imagem ou passe as imagens posicionalmente. `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. `audio: true` é mapeado para `generate_audio`. `providerOptions.seed` (number) é encaminhado. |
+| BytePlus Seedance 2.0 | Requer o plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID do provedor `byteplus-seedance2`. Modelos: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de referência, 3 vídeos de referência e 3 áudios de referência. Todas as entradas devem ser URLs remotas `https://`. Defina `role` em cada asset — valores compatíveis: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada. `audio: true` é mapeado para `generate_audio`. `providerOptions.seed` (number) é encaminhado. |
+| ComfyUI               | Execução local ou na nuvem orientada por workflow. Oferece suporte a texto para vídeo e imagem para vídeo por meio do grafo configurado.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| fal                   | Usa fluxo com fila para trabalhos de longa duração. Apenas uma única imagem de referência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Google                | Usa Gemini/Veo. Oferece suporte a uma imagem ou um vídeo de referência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| MiniMax               | Apenas uma única imagem de referência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| OpenAI                | Apenas a sobrescrita `size` é encaminhada. Outras sobrescritas de estilo (`aspectRatio`, `resolution`, `audio`, `watermark`) são ignoradas com um aviso.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| Qwen                  | Mesmo backend DashScope do Alibaba. Entradas de referência devem ser URLs remotas `http(s)`; arquivos locais são rejeitados antecipadamente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Runway                | Oferece suporte a arquivos locais por meio de URIs de dados. Vídeo para vídeo requer `runway/gen4_aleph`. Execuções somente com texto expõem proporções `16:9` e `9:16`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Together              | Apenas uma única imagem de referência.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Vydra                 | Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos que descartam a autenticação. `veo3` vem empacotado apenas como texto para vídeo; `kling` exige uma URL de imagem remota.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| xAI                   | Oferece suporte a fluxos de texto para vídeo, imagem para vídeo e edição/extensão de vídeo remoto.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

 ## Modos de capacidade do provedor

-O contrato compartilhado de geração de vídeo agora permite que provedores declarem
-capacidades específicas por modo em vez de apenas limites agregados planos. Novas
-implementações de provedor devem preferir blocos explícitos por modo:
+O contrato compartilhado de geração de vídeos agora permite que os provedores declarem capacidades específicas por modo em vez de apenas limites agregados fixos. Novas implementações de provedores devem preferir blocos de modo explícitos:

 ```typescript
 capabilities: {
@ -280,15 +271,11 @@ capabilities: {
 }
 ```

-Campos agregados planos como `maxInputImages` e `maxInputVideos` não
-são suficientes para anunciar suporte a modo de transformação. Os provedores devem declarar
-`generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes live,
-testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte a modo
-de forma determinística.
+Campos agregados fixos como `maxInputImages` e `maxInputVideos` não são suficientes para anunciar suporte ao modo de transformação. Os provedores devem declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes live, testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte ao modo de forma determinística.

 ## Testes live

-Cobertura live opt-in para os provedores empacotados compartilhados:
+Cobertura live opt-in para os provedores compartilhados empacotados:

 ```bash
 OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -300,22 +287,19 @@ Wrapper do repositório:
 pnpm test:live:media video
 ```

-Este arquivo live carrega variáveis de ambiente ausentes de provedor a partir de `~/.profile`, prioriza
-chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa os
-modos declarados que consegue exercitar com segurança com mídia local:
+Este arquivo live carrega variáveis de ambiente ausentes do provedor a partir de `~/.profile`, prioriza chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa os modos declarados que consegue exercitar com segurança usando mídia local:

- `generate` para todo provedor na varredura
+- `generate` para todos os provedores na varredura
 - `imageToVideo` quando `capabilities.imageToVideo.enabled`
- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo
-  aceita entrada de vídeo local com buffer na varredura compartilhada
+- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo aceita entrada de vídeo local com buffer na varredura compartilhada

-Hoje a lane live compartilhada `videoToVideo` cobre:
+Atualmente, a lane live compartilhada `videoToVideo` cobre:

- `runway` apenas quando você seleciona `runway/gen4_aleph`
+- `runway` somente quando você seleciona `runway/gen4_aleph`

 ## Configuração

-Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw:
+Defina o modelo padrão de geração de vídeos na sua configuração do OpenClaw:

 ```json5
 {
@ -330,7 +314,7 @@ Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw
 }
 ```

-Ou pela CLI:
+Ou via CLI:

 ```bash
 openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
@ -339,7 +323,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
 ## Relacionado

 - [Visão geral das ferramentas](/pt-BR/tools)
- [Tarefas em segundo plano](/pt-BR/automation/tasks) -- rastreamento de tarefas para geração assíncrona de vídeo
+- [Tarefas em segundo plano](/pt-BR/automation/tasks) -- rastreamento de tarefas para geração assíncrona de vídeos
 - [Alibaba Model Studio](/pt-BR/providers/alibaba)
 - [BytePlus](/pt-BR/concepts/model-providers#byteplus-international)
 - [ComfyUI](/pt-BR/providers/comfy)