diff --git a/docs/pt-BR/automation/tasks.md b/docs/pt-BR/automation/tasks.md
index a6fda58ea..cd4e76227 100644
--- a/docs/pt-BR/automation/tasks.md
+++ b/docs/pt-BR/automation/tasks.md
@@ -1,30 +1,30 @@
---
read_when:
- Inspecionando trabalho em segundo plano em andamento ou concluído recentemente
- - Depurando falhas de entrega para execuções destacadas de agentes
+ - Depurando falhas de entrega para execuções de agentes desanexadas
- Entendendo como execuções em segundo plano se relacionam com sessões, cron e heartbeat
-summary: Rastreamento de tarefas em segundo plano para execuções ACP, subagentes, trabalhos cron isolados e operações da CLI
-title: Tarefas em Segundo Plano
+summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, trabalhos cron isolados e operações da CLI
+title: Tarefas em segundo plano
x-i18n:
- generated_at: "2026-04-06T03:06:40Z"
+ generated_at: "2026-04-10T05:34:12Z"
model: gpt-5.4
provider: openai
- source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
+ source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
source_path: automation/tasks.md
workflow: 15
---
-# Tarefas em Segundo Plano
+# Tarefas em segundo plano
-> **Procurando agendamento?** Consulte [Automação e Tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página cobre o **rastreamento** do trabalho em segundo plano, não o agendamento dele.
+> **Está procurando agendamento?** Veja [Automação e Tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página cobre o **rastreamento** de trabalho em segundo plano, não o agendamento.
-As tarefas em segundo plano rastreiam trabalho que é executado **fora da sua sessão principal de conversa**:
-execuções ACP, inicializações de subagentes, execuções isoladas de trabalhos cron e operações iniciadas pela CLI.
+As tarefas em segundo plano rastreiam trabalhos executados **fora da sua sessão principal de conversa**:
+execuções do ACP, inicializações de subagentes, execuções isoladas de trabalhos cron e operações iniciadas pela CLI.
-As tarefas **não** substituem sessões, trabalhos cron ou heartbeats — elas são o **registro de atividade** que registra qual trabalho destacado aconteceu, quando aconteceu e se foi bem-sucedido.
+As tarefas **não** substituem sessões, trabalhos cron ou heartbeats — elas são o **registro de atividade** que documenta que trabalho desanexado aconteceu, quando aconteceu e se foi bem-sucedido.
-Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat interativo normal não criam. Todas as execuções cron, inicializações ACP, inicializações de subagentes e comandos de agente da CLI criam.
+Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat interativo normal não criam. Todas as execuções cron, inicializações do ACP, inicializações de subagentes e comandos de agente da CLI criam.
## Resumo rápido
@@ -32,41 +32,45 @@ Nem toda execução de agente cria uma tarefa. Turnos de heartbeat e chat intera
- Tarefas são **registros**, não agendadores — cron e heartbeat decidem _quando_ o trabalho é executado, as tarefas rastreiam _o que aconteceu_.
- ACP, subagentes, todos os trabalhos cron e operações da CLI criam tarefas. Turnos de heartbeat não criam.
- Cada tarefa passa por `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost).
-- As tarefas cron permanecem ativas enquanto o runtime cron ainda for responsável pelo trabalho; tarefas da CLI com suporte de chat permanecem ativas apenas enquanto seu contexto de execução proprietário ainda estiver ativo.
-- A conclusão é orientada por envio: o trabalho destacado pode notificar diretamente ou despertar a sessão solicitante/heartbeat quando termina, então loops de polling de status geralmente não são o formato correto.
-- Execuções cron isoladas e conclusões de subagentes limpam por melhor esforço abas/processos de navegador rastreados para sua sessão filha antes da contabilidade final de limpeza.
-- A entrega de cron isolado suprime respostas intermediárias obsoletas do pai enquanto o trabalho de subagentes descendentes ainda está sendo drenado, e prefere a saída final descendente quando ela chega antes da entrega.
-- Notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo heartbeat.
+- Tarefas cron permanecem ativas enquanto o runtime do cron ainda possuir o trabalho; tarefas da CLI com suporte de chat permanecem ativas apenas enquanto seu contexto de execução proprietário ainda estiver ativo.
+- A conclusão é orientada por push: o trabalho desanexado pode notificar diretamente ou despertar a
+ sessão/heartbeat solicitante quando terminar, então laços de polling de status
+ geralmente não são o formato certo.
+- Execuções cron isoladas e conclusões de subagentes fazem uma limpeza best-effort de abas/processos rastreados do navegador para sua sessão filha antes da limpeza final de bookkeeping.
+- A entrega de cron isolado suprime respostas intermediárias obsoletas do pai enquanto
+ o trabalho de subagentes descendentes ainda estiver sendo drenado, e prefere a saída final do descendente
+ quando ela chega antes da entrega.
+- As notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo heartbeat.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` exibe problemas.
- Registros terminais são mantidos por 7 dias e depois removidos automaticamente.
## Início rápido
```bash
-# Lista todas as tarefas (mais recentes primeiro)
+# Liste todas as tarefas (mais novas primeiro)
openclaw tasks list
-# Filtra por runtime ou status
+# Filtre por runtime ou status
openclaw tasks list --runtime acp
openclaw tasks list --status running
-# Mostra detalhes de uma tarefa específica (por ID, ID de execução ou chave de sessão)
+# Mostre detalhes de uma tarefa específica (por ID, ID de execução ou chave de sessão)
openclaw tasks show
-# Cancela uma tarefa em execução (mata a sessão filha)
+# Cancele uma tarefa em execução (encerra a sessão filha)
openclaw tasks cancel
-# Altera a política de notificação de uma tarefa
+# Altere a política de notificação de uma tarefa
openclaw tasks notify state_changes
-# Executa uma auditoria de integridade
+# Execute uma auditoria de integridade
openclaw tasks audit
-# Visualiza ou aplica manutenção
+# Visualize ou aplique manutenção
openclaw tasks maintenance
openclaw tasks maintenance --apply
-# Inspeciona o estado do Task Flow
+# Inspecione o estado do TaskFlow
openclaw tasks flow list
openclaw tasks flow show
openclaw tasks flow cancel
@@ -74,23 +78,23 @@ openclaw tasks flow cancel
## O que cria uma tarefa
-| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
+| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
| ---------------------- | --------------- | ----------------------------------------------------- | ------------------------------ |
| Execuções em segundo plano do ACP | `acp` | Ao iniciar uma sessão filha do ACP | `done_only` |
| Orquestração de subagentes | `subagent` | Ao iniciar um subagente via `sessions_spawn` | `done_only` |
-| Trabalhos cron (todos os tipos) | `cron` | Toda execução cron (sessão principal e isolada) | `silent` |
-| Operações da CLI | `cli` | Comandos `openclaw agent` executados por meio do gateway | `silent` |
+| Trabalhos cron (todos os tipos) | `cron` | Em cada execução cron (sessão principal e isolada) | `silent` |
+| Operações da CLI | `cli` | Comandos `openclaw agent` executados pelo gateway | `silent` |
| Trabalhos de mídia do agente | `cli` | Execuções `video_generate` com suporte de sessão | `silent` |
-Tarefas cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam `silent` por padrão, mas são mais visíveis porque são executadas na própria sessão.
+As tarefas cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas cron isoladas também usam `silent` por padrão, mas são mais visíveis porque são executadas na própria sessão.
-Execuções `video_generate` com suporte de sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um wake interno para que o agente possa escrever a mensagem de acompanhamento e anexar ele mesmo o vídeo finalizado. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta ao canal antes de recorrer ao caminho de wake da sessão solicitante.
+Execuções `video_generate` com suporte de sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um despertar interno para que o agente possa escrever a mensagem de acompanhamento e anexar o vídeo concluído por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta ao canal antes de recorrer ao caminho de despertar da sessão solicitante.
-Enquanto uma tarefa `video_generate` com suporte de sessão ainda estiver ativa, a ferramenta também atua como um guardrail: chamadas repetidas de `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status do lado do agente.
+Enquanto uma tarefa `video_generate` com suporte de sessão ainda estiver ativa, a ferramenta também atua como proteção: chamadas repetidas de `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status pelo lado do agente.
**O que não cria tarefas:**
-- Turnos de heartbeat — sessão principal; consulte [Heartbeat](/pt-BR/gateway/heartbeat)
+- Turnos de heartbeat — sessão principal; veja [Heartbeat](/pt-BR/gateway/heartbeat)
- Turnos normais de chat interativo
- Respostas diretas de `/command`
@@ -111,21 +115,21 @@ stateDiagram-v2
| Status | O que significa |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Criada, aguardando o agente iniciar |
-| `running` | O turno do agente está em execução ativa |
+| `running` | O turno do agente está sendo executado ativamente |
| `succeeded` | Concluída com sucesso |
-| `failed` | Concluída com erro |
+| `failed` | Concluída com um erro |
| `timed_out` | Excedeu o tempo limite configurado |
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
-| `lost` | O runtime perdeu o estado de suporte autoritativo após um período de carência de 5 minutos |
+| `lost` | O runtime perdeu o estado de suporte autoritativo após um período de tolerância de 5 minutos |
As transições acontecem automaticamente — quando a execução do agente associada termina, o status da tarefa é atualizado para corresponder.
-`lost` depende do runtime:
+`lost` é sensível ao runtime:
-- Tarefas ACP: os metadados da sessão filha do ACP de suporte desapareceram.
+- Tarefas do ACP: os metadados de suporte da sessão filha do ACP desapareceram.
- Tarefas de subagente: a sessão filha de suporte desapareceu do armazenamento do agente de destino.
-- Tarefas cron: o runtime cron não rastreia mais o trabalho como ativo.
-- Tarefas da CLI: tarefas isoladas de sessão filha usam a sessão filha; tarefas da CLI com suporte de chat usam o contexto de execução ativo em vez disso, então linhas persistentes de sessão de canal/grupo/direta não as mantêm ativas.
+- Tarefas cron: o runtime do cron não rastreia mais o trabalho como ativo.
+- Tarefas da CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas da CLI com suporte de chat usam o contexto de execução ativo no lugar, então linhas persistentes de sessão de canal/grupo/direta não as mantêm ativas.
## Entrega e notificações
@@ -133,23 +137,25 @@ Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois
**Entrega direta** — se a tarefa tiver um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai diretamente para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagentes, o OpenClaw também preserva o roteamento vinculado de thread/tópico quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta.
-**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo heartbeat.
+**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento do sistema na sessão do solicitante e aparece no próximo heartbeat.
-A conclusão da tarefa aciona um wake imediato do heartbeat para que você veja o resultado rapidamente — você não precisa esperar o próximo tick agendado do heartbeat.
+A conclusão da tarefa aciona um despertar imediato do heartbeat para que você veja o resultado rapidamente — você não precisa esperar pelo próximo tick agendado do heartbeat.
-Isso significa que o fluxo de trabalho usual é baseado em envio: inicie o trabalho destacado uma vez e depois deixe o runtime despertar ou notificar você na conclusão. Faça polling do estado da tarefa apenas quando precisar de depuração, intervenção ou uma auditoria explícita.
+Isso significa que o fluxo de trabalho usual é orientado por push: inicie o trabalho desanexado uma vez e depois deixe
+o runtime despertar ou notificar você quando ele terminar. Faça polling do estado da tarefa apenas quando
+precisar de depuração, intervenção ou uma auditoria explícita.
### Políticas de notificação
-Controle o quanto você recebe de informação sobre cada tarefa:
+Controle quanto você quer ouvir sobre cada tarefa:
-| Política | O que é entregue |
-| --------------------- | ------------------------------------------------------------------------ |
+| Política | O que é entregue |
+| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (padrão) | Apenas o estado terminal (succeeded, failed etc.) — **este é o padrão** |
-| `state_changes` | Toda transição de estado e atualização de progresso |
-| `silent` | Nada |
+| `state_changes` | Toda transição de estado e atualização de progresso |
+| `silent` | Nada |
Altere a política enquanto uma tarefa estiver em execução:
@@ -165,7 +171,7 @@ openclaw tasks notify state_changes
openclaw tasks list [--runtime ] [--status ] [--json]
```
-Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID de execução, Sessão filha, Resumo.
+Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID da execução, Sessão filha, Resumo.
### `tasks show`
@@ -173,7 +179,7 @@ Colunas de saída: ID da tarefa, Tipo, Status, Entrega, ID de execução, Sessã
openclaw tasks show
```
-O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo tempo, estado de entrega, erro e resumo terminal.
+O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão. Mostra o registro completo, incluindo tempo, estado da entrega, erro e resumo terminal.
### `tasks cancel`
@@ -181,7 +187,7 @@ O token de lookup aceita um ID de tarefa, ID de execução ou chave de sessão.
openclaw tasks cancel
```
-Para tarefas ACP e de subagente, isso mata a sessão filha. O status passa para `cancelled` e uma notificação de entrega é enviada.
+Para tarefas do ACP e de subagentes, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há um identificador de runtime filho separado). O status muda para `cancelled` e uma notificação de entrega é enviada quando aplicável.
### `tasks notify`
@@ -195,16 +201,16 @@ openclaw tasks notify
openclaw tasks audit [--json]
```
-Exibe problemas operacionais. As descobertas também aparecem em `openclaw status` quando problemas são detectados.
+Exibe problemas operacionais. Os achados também aparecem em `openclaw status` quando problemas são detectados.
-| Descoberta | Severidade | Gatilho |
+| Achado | Severidade | Gatilho |
| ------------------------- | ---------- | ---------------------------------------------------- |
| `stale_queued` | warn | Em fila por mais de 10 minutos |
| `stale_running` | error | Em execução por mais de 30 minutos |
| `lost` | error | A propriedade da tarefa com suporte de runtime desapareceu |
| `delivery_failed` | warn | A entrega falhou e a política de notificação não é `silent` |
-| `missing_cleanup` | warn | Tarefa terminal sem timestamp de limpeza |
-| `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de iniciar) |
+| `missing_cleanup` | warn | Tarefa terminal sem carimbo de data/hora de limpeza |
+| `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de começar) |
### `tasks maintenance`
@@ -213,20 +219,22 @@ openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
-Use isto para visualizar ou aplicar reconciliação, marcação de limpeza e remoção para tarefas e estado do Task Flow.
+Use isso para visualizar ou aplicar reconciliação, marcação de limpeza e remoção para
+tarefas e estado do Task Flow.
-A reconciliação depende do runtime:
+A reconciliação é sensível ao runtime:
-- Tarefas ACP/subagente verificam sua sessão filha de suporte.
-- Tarefas cron verificam se o runtime cron ainda é responsável pelo trabalho.
-- Tarefas da CLI com suporte de chat verificam o contexto de execução ativo proprietário, não apenas a linha de sessão de chat.
+- Tarefas do ACP/subagente verificam sua sessão filha de suporte.
+- Tarefas cron verificam se o runtime do cron ainda possui o trabalho.
+- Tarefas da CLI com suporte de chat verificam o contexto de execução ativo proprietário, não apenas a linha da sessão de chat.
-A limpeza de conclusão também depende do runtime:
+A limpeza de conclusão também é sensível ao runtime:
-- A conclusão de subagente fecha por melhor esforço abas/processos de navegador rastreados para a sessão filha antes de a limpeza do anúncio continuar.
-- A conclusão de cron isolado fecha por melhor esforço abas/processos de navegador rastreados para a sessão cron antes de a execução ser totalmente encerrada.
-- A entrega de cron isolado espera o acompanhamento descendente de subagentes quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
-- A entrega de conclusão de subagente prefere o texto visível mais recente do assistente; se ele estiver vazio, recorre ao texto sanitizado mais recente de tool/toolResult, e execuções de chamada de ferramenta apenas com timeout podem ser reduzidas a um breve resumo de progresso parcial.
+- A conclusão de subagente fecha, em best-effort, abas/processos rastreados do navegador para a sessão filha antes que a limpeza do anúncio continue.
+- A conclusão de cron isolado fecha, em best-effort, abas/processos rastreados do navegador para a sessão cron antes que a execução seja totalmente desmontada.
+- A entrega de cron isolado espera o acompanhamento de subagentes descendentes quando necessário e
+ suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
+- A entrega de conclusão de subagente prefere o texto visível mais recente do assistente; se estiver vazio, recorre ao texto mais recente saneado de tool/toolResult, e execuções apenas com chamada de ferramenta por timeout podem ser condensadas em um resumo curto de progresso parcial.
- Falhas de limpeza não mascaram o resultado real da tarefa.
### `tasks flow list|show|cancel`
@@ -237,19 +245,22 @@ openclaw tasks flow show [--json]
openclaw tasks flow cancel
```
-Use estes comandos quando o Task Flow de orquestração for aquilo com que você se importa, em vez de um registro individual de tarefa em segundo plano.
+Use esses comandos quando o Task Flow de orquestração for a coisa com a qual você se importa
+em vez de um registro individual de tarefa em segundo plano.
## Painel de tarefas no chat (`/tasks`)
-Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O painel mostra tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro.
+Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O painel mostra
+tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro.
-Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente para que você ainda tenha uma visão geral sem expor detalhes de outras sessões.
+Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente
+para que você ainda tenha uma visão geral sem expor detalhes de outras sessões.
Para o registro completo do operador, use a CLI: `openclaw tasks list`.
-## Integração com status (pressão de tarefas)
+## Integração de status (pressão de tarefas)
-`openclaw status` inclui um resumo rápido das tarefas:
+`openclaw status` inclui um resumo rápido de tarefas:
```
Tasks: 3 queued · 2 running · 1 issues
@@ -261,27 +272,29 @@ O resumo informa:
- **failures** — contagem de `failed` + `timed_out` + `lost`
- **byRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli`
-Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas têm prioridade, linhas concluídas obsoletas ficam ocultas, e falhas recentes só aparecem quando não resta trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
+Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas têm
+preferência, linhas concluídas obsoletas são ocultadas e falhas recentes só aparecem quando não resta
+trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
## Armazenamento e manutenção
### Onde as tarefas ficam
-Os registros de tarefas persistem no SQLite em:
+Os registros de tarefa persistem em SQLite em:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
-O registro é carregado na memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
+O registro é carregado em memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
### Manutenção automática
-Um varredor é executado a cada **60 segundos** e cuida de três coisas:
+Um processo de varredura é executado a cada **60 segundos** e lida com três coisas:
-1. **Reconciliação** — verifica se tarefas ativas ainda têm suporte autoritativo de runtime. Tarefas ACP/subagente usam o estado da sessão filha, tarefas cron usam a propriedade do trabalho ativo, e tarefas da CLI com suporte de chat usam o contexto de execução proprietário. Se esse estado de suporte desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
-2. **Marcação de limpeza** — define um timestamp `cleanupAfter` em tarefas terminais (`endedAt` + 7 dias).
-3. **Remoção** — exclui registros que passaram da data `cleanupAfter`.
+1. **Reconciliação** — verifica se tarefas ativas ainda têm suporte autoritativo do runtime. Tarefas do ACP/subagente usam o estado da sessão filha, tarefas cron usam a propriedade do trabalho ativo e tarefas da CLI com suporte de chat usam o contexto de execução proprietário. Se esse estado de suporte desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
+2. **Marcação de limpeza** — define um timestamp `cleanupAfter` em tarefas terminais (`endedAt + 7 days`).
+3. **Remoção** — exclui registros após a data `cleanupAfter`.
**Retenção**: registros de tarefas terminais são mantidos por **7 dias** e depois removidos automaticamente. Nenhuma configuração é necessária.
@@ -289,25 +302,25 @@ Um varredor é executado a cada **60 segundos** e cuida de três coisas:
### Tarefas e Task Flow
-[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxo acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo de orquestração.
+[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo de orquestração.
-Consulte [Task Flow](/pt-BR/automation/taskflow) para mais detalhes.
+Veja [Task Flow](/pt-BR/automation/taskflow) para mais detalhes.
### Tarefas e cron
-Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`. **Toda** execução cron cria um registro de tarefa — tanto principal quanto isolada. Tarefas cron da sessão principal usam a política de notificação `silent` por padrão para rastrear sem gerar notificações.
+Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`. **Toda** execução cron cria um registro de tarefa — tanto na sessão principal quanto em execução isolada. Tarefas cron da sessão principal usam a política de notificação `silent` por padrão, para rastrear sem gerar notificações.
-Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs).
+Veja [Trabalhos cron](/pt-BR/automation/cron-jobs).
### Tarefas e heartbeat
-Execuções de heartbeat são turnos da sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um wake do heartbeat para que você veja o resultado rapidamente.
+Execuções de heartbeat são turnos da sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um despertar do heartbeat para que você veja o resultado prontamente.
-Consulte [Heartbeat](/pt-BR/gateway/heartbeat).
+Veja [Heartbeat](/pt-BR/gateway/heartbeat).
### Tarefas e sessões
-Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem o iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade sobre esse contexto.
+Uma tarefa pode referenciar um `childSessionKey` (onde o trabalho é executado) e um `requesterSessionKey` (quem a iniciou). Sessões são o contexto da conversa; tarefas são o rastreamento de atividade sobre esse contexto.
### Tarefas e execuções de agente
@@ -315,8 +328,8 @@ O `runId` de uma tarefa se vincula à execução do agente que está realizando
## Relacionado
-- [Automação e Tarefas](/pt-BR/automation) — todos os mecanismos de automação em um relance
-- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas
-- [Tarefas Agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
+- [Automação e Tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo
+- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxos acima das tarefas
+- [Tarefas agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal
- [CLI: Tarefas](/cli/index#tasks) — referência de comandos da CLI
diff --git a/docs/pt-BR/concepts/active-memory.md b/docs/pt-BR/concepts/active-memory.md
new file mode 100644
index 000000000..813180e0c
--- /dev/null
+++ b/docs/pt-BR/concepts/active-memory.md
@@ -0,0 +1,616 @@
+---
+read_when:
+ - Você quer entender para que serve a memória ativa
+ - Você quer ativar a memória ativa para um agente conversacional
+ - Você quer ajustar o comportamento da memória ativa sem ativá-la em todos os lugares
+summary: Um subagente de memória de bloqueio, pertencente ao plugin, que injeta memória relevante em sessões de chat interativas
+title: Memória ativa
+x-i18n:
+ generated_at: "2026-04-10T05:34:14Z"
+ model: gpt-5.4
+ provider: openai
+ source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
+ source_path: concepts/active-memory.md
+ workflow: 15
+---
+
+# Memória ativa
+
+A memória ativa é um subagente opcional de memória de bloqueio, pertencente ao plugin, que é executado
+antes da resposta principal em sessões conversacionais qualificadas.
+
+Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem
+do agente principal para decidir quando pesquisar na memória, ou do usuário para dizer coisas
+como "lembre-se disso" ou "pesquise na memória". Nessa altura, o momento em que a memória teria
+feito a resposta parecer natural já passou.
+
+A memória ativa dá ao sistema uma chance limitada de trazer memória relevante
+antes de a resposta principal ser gerada.
+
+## Cole isto no seu agente
+
+Cole isto no seu agente se você quiser habilitar a Memória ativa com uma
+configuração autocontida e segura por padrão:
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ enabled: true,
+ agents: ["main"],
+ allowedChatTypes: ["direct"],
+ modelFallbackPolicy: "default-remote",
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ persistTranscripts: false,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Isso ativa o plugin para o agente `main`, o mantém limitado por padrão a
+sessões no estilo de mensagens diretas, permite que ele herde primeiro o modelo da
+sessão atual e ainda permite o fallback remoto integrado caso nenhum modelo explícito
+ou herdado esteja disponível.
+
+Depois disso, reinicie o gateway:
+
+```bash
+node scripts/run-node.mjs gateway --profile dev
+```
+
+Para inspecioná-lo ao vivo em uma conversa:
+
+```text
+/verbose on
+```
+
+## Ativar a memória ativa
+
+A configuração mais segura é:
+
+1. habilitar o plugin
+2. direcioná-lo para um agente conversacional
+3. manter o logging ativado apenas durante o ajuste fino
+
+Comece com isto em `openclaw.json`:
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ allowedChatTypes: ["direct"],
+ modelFallbackPolicy: "default-remote",
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ persistTranscripts: false,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Depois reinicie o gateway:
+
+```bash
+node scripts/run-node.mjs gateway --profile dev
+```
+
+O que isso significa:
+
+- `plugins.entries.active-memory.enabled: true` ativa o plugin
+- `config.agents: ["main"]` habilita a memória ativa apenas para o agente `main`
+- `config.allowedChatTypes: ["direct"]` mantém a memória ativa habilitada por padrão apenas para sessões no estilo de mensagens diretas
+- se `config.model` não estiver definido, a memória ativa herda primeiro o modelo da sessão atual
+- `config.modelFallbackPolicy: "default-remote"` mantém o fallback remoto integrado como padrão quando nenhum modelo explícito ou herdado está disponível
+- `config.promptStyle: "balanced"` usa o estilo de prompt padrão de uso geral para o modo `recent`
+- a memória ativa ainda é executada apenas em sessões de chat persistentes interativas qualificadas
+
+## Como vê-la
+
+A memória ativa injeta contexto oculto de sistema para o modelo. Ela não expõe
+tags brutas `...` ao cliente.
+
+## Alternância por sessão
+
+Use o comando do plugin quando quiser pausar ou retomar a memória ativa na
+sessão de chat atual sem editar a configuração:
+
+```text
+/active-memory status
+/active-memory off
+/active-memory on
+```
+
+Isso é aplicado no escopo da sessão. Não altera
+`plugins.entries.active-memory.enabled`, o direcionamento por agente nem outras
+configurações globais.
+
+Se você quiser que o comando grave a configuração e pause ou retome a memória ativa para
+todas as sessões, use a forma global explícita:
+
+```text
+/active-memory status --global
+/active-memory off --global
+/active-memory on --global
+```
+
+A forma global grava `plugins.entries.active-memory.config.enabled`. Ela deixa
+`plugins.entries.active-memory.enabled` ativado para que o comando continue disponível
+para reativar a memória ativa depois.
+
+Se você quiser ver o que a memória ativa está fazendo em uma sessão ao vivo, ative o
+modo detalhado para essa sessão:
+
+```text
+/verbose on
+```
+
+Com o modo detalhado ativado, o OpenClaw pode mostrar:
+
+- uma linha de status da memória ativa como `Active Memory: ok 842ms recent 34 chars`
+- um resumo de depuração legível como `Active Memory Debug: Lemon pepper wings with blue cheese.`
+
+Essas linhas são derivadas da mesma passagem de memória ativa que alimenta o contexto
+oculto do sistema, mas são formatadas para humanos em vez de expor marcação bruta
+de prompt.
+
+Por padrão, a transcrição do subagente de memória de bloqueio é temporária e excluída
+após a conclusão da execução.
+
+Fluxo de exemplo:
+
+```text
+/verbose on
+what wings should i order?
+```
+
+Formato de resposta visível esperado:
+
+```text
+...normal assistant reply...
+
+🧩 Active Memory: ok 842ms recent 34 chars
+🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
+```
+
+## Quando ela é executada
+
+A memória ativa usa dois critérios:
+
+1. **Opt-in de configuração**
+ O plugin deve estar habilitado, e o id do agente atual deve aparecer em
+ `plugins.entries.active-memory.config.agents`.
+2. **Qualificação estrita em tempo de execução**
+ Mesmo quando habilitada e direcionada, a memória ativa só é executada em
+ sessões de chat persistentes interativas qualificadas.
+
+A regra real é:
+
+```text
+plugin enabled
++
+agent id targeted
++
+allowed chat type
++
+eligible interactive persistent chat session
+=
+active memory runs
+```
+
+Se qualquer um deles falhar, a memória ativa não será executada.
+
+## Tipos de sessão
+
+`config.allowedChatTypes` controla quais tipos de conversas podem executar a Memória
+ativa de qualquer forma.
+
+O padrão é:
+
+```json5
+allowedChatTypes: ["direct"]
+```
+
+Isso significa que a Memória ativa é executada por padrão em sessões no estilo de
+mensagens diretas, mas não em sessões de grupo ou canal, a menos que você as habilite
+explicitamente.
+
+Exemplos:
+
+```json5
+allowedChatTypes: ["direct"]
+```
+
+```json5
+allowedChatTypes: ["direct", "group"]
+```
+
+```json5
+allowedChatTypes: ["direct", "group", "channel"]
+```
+
+## Onde ela é executada
+
+A memória ativa é um recurso de enriquecimento conversacional, não um recurso de
+inferência para toda a plataforma.
+
+| Superfície | Executa memória ativa? |
+| ------------------------------------------------------------------- | ------------------------------------------------------- |
+| Sessões persistentes da UI de controle / chat web | Sim, se o plugin estiver habilitado e o agente for direcionado |
+| Outras sessões de canal interativas no mesmo caminho de chat persistente | Sim, se o plugin estiver habilitado e o agente for direcionado |
+| Execuções avulsas sem interface | Não |
+| Execuções de heartbeat/background | Não |
+| Caminhos internos genéricos de `agent-command` | Não |
+| Execução interna de subagente/helper | Não |
+
+## Por que usá-la
+
+Use a memória ativa quando:
+
+- a sessão for persistente e voltada ao usuário
+- o agente tiver memória de longo prazo significativa para pesquisar
+- continuidade e personalização importarem mais do que o determinismo bruto do prompt
+
+Ela funciona especialmente bem para:
+
+- preferências estáveis
+- hábitos recorrentes
+- contexto de longo prazo do usuário que deve surgir naturalmente
+
+Ela é pouco adequada para:
+
+- automação
+- workers internos
+- tarefas de API de execução única
+- lugares em que a personalização oculta seria surpreendente
+
+## Como ela funciona
+
+O formato em tempo de execução é:
+
+```mermaid
+flowchart LR
+ U["User Message"] --> Q["Build Memory Query"]
+ Q --> R["Active Memory Blocking Memory Sub-Agent"]
+ R -->|NONE or empty| M["Main Reply"]
+ R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"]
+ I --> M["Main Reply"]
+```
+
+O subagente de memória de bloqueio pode usar apenas:
+
+- `memory_search`
+- `memory_get`
+
+Se a conexão estiver fraca, ele deve retornar `NONE`.
+
+## Modos de consulta
+
+`config.queryMode` controla quanto da conversa o subagente de memória de bloqueio vê.
+
+## Estilos de prompt
+
+`config.promptStyle` controla quão disposto ou rigoroso o subagente de memória de bloqueio é
+ao decidir se deve retornar memória.
+
+Estilos disponíveis:
+
+- `balanced`: padrão de uso geral para o modo `recent`
+- `strict`: menos disposto; melhor quando você quer muito pouca interferência do contexto próximo
+- `contextual`: mais favorável à continuidade; melhor quando o histórico da conversa deve importar mais
+- `recall-heavy`: mais disposto a trazer memória em correspondências mais sutis, mas ainda plausíveis
+- `precision-heavy`: prefere agressivamente `NONE`, a menos que a correspondência seja óbvia
+- `preference-only`: otimizado para favoritos, hábitos, rotinas, gostos e fatos pessoais recorrentes
+
+Mapeamento padrão quando `config.promptStyle` não está definido:
+
+```text
+message -> strict
+recent -> balanced
+full -> contextual
+```
+
+Se você definir `config.promptStyle` explicitamente, essa substituição prevalece.
+
+Exemplo:
+
+```json5
+promptStyle: "preference-only"
+```
+
+## Política de fallback de modelo
+
+Se `config.model` não estiver definido, a Memória ativa tenta resolver um modelo nesta ordem:
+
+```text
+explicit plugin model
+-> current session model
+-> agent primary model
+-> optional built-in remote fallback
+```
+
+`config.modelFallbackPolicy` controla a última etapa.
+
+Padrão:
+
+```json5
+modelFallbackPolicy: "default-remote"
+```
+
+Outra opção:
+
+```json5
+modelFallbackPolicy: "resolved-only"
+```
+
+Use `resolved-only` se quiser que a Memória ativa ignore a recuperação em vez de usar
+o padrão remoto integrado como fallback quando nenhum modelo explícito ou herdado
+estiver disponível.
+
+## Escapes avançados
+
+Essas opções intencionalmente não fazem parte da configuração recomendada.
+
+`config.thinking` pode substituir o nível de raciocínio do subagente de memória de bloqueio:
+
+```json5
+thinking: "medium"
+```
+
+Padrão:
+
+```json5
+thinking: "off"
+```
+
+Não habilite isso por padrão. A Memória ativa é executada no caminho da resposta, então tempo
+extra de raciocínio aumenta diretamente a latência percebida pelo usuário.
+
+`config.promptAppend` adiciona instruções extras do operador após o prompt padrão da
+Memória ativa e antes do contexto da conversa:
+
+```json5
+promptAppend: "Prefer stable long-term preferences over one-off events."
+```
+
+`config.promptOverride` substitui o prompt padrão da Memória ativa. O OpenClaw
+ainda anexa o contexto da conversa em seguida:
+
+```json5
+promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
+```
+
+A personalização do prompt não é recomendada, a menos que você esteja testando
+deliberadamente um contrato de recuperação diferente. O prompt padrão é ajustado para
+retornar `NONE` ou um contexto compacto de fatos do usuário para o modelo principal.
+
+### `message`
+
+Apenas a mensagem mais recente do usuário é enviada.
+
+```text
+Latest user message only
+```
+
+Use isso quando:
+
+- você quiser o comportamento mais rápido
+- você quiser o viés mais forte em direção à recuperação de preferências estáveis
+- turnos de acompanhamento não precisarem de contexto conversacional
+
+Tempo limite recomendado:
+
+- comece em torno de `3000` a `5000` ms
+
+### `recent`
+
+A mensagem mais recente do usuário, mais uma pequena cauda recente da conversa, são enviadas.
+
+```text
+Recent conversation tail:
+user: ...
+assistant: ...
+user: ...
+
+Latest user message:
+...
+```
+
+Use isso quando:
+
+- você quiser um melhor equilíbrio entre velocidade e contextualização conversacional
+- perguntas de acompanhamento frequentemente dependerem dos últimos turnos
+
+Tempo limite recomendado:
+
+- comece em torno de `15000` ms
+
+### `full`
+
+A conversa completa é enviada ao subagente de memória de bloqueio.
+
+```text
+Full conversation context:
+user: ...
+assistant: ...
+user: ...
+...
+```
+
+Use isso quando:
+
+- a melhor qualidade de recuperação for mais importante do que a latência
+- a conversa contiver preparação importante muito antes na thread
+
+Tempo limite recomendado:
+
+- aumente-o substancialmente em comparação com `message` ou `recent`
+- comece em torno de `15000` ms ou mais, dependendo do tamanho da thread
+
+Em geral, o tempo limite deve aumentar com o tamanho do contexto:
+
+```text
+message < recent < full
+```
+
+## Persistência de transcrições
+
+As execuções do subagente de memória de bloqueio da memória ativa criam uma transcrição real
+`session.jsonl` durante a chamada do subagente de memória de bloqueio.
+
+Por padrão, essa transcrição é temporária:
+
+- ela é gravada em um diretório temporário
+- ela é usada apenas para a execução do subagente de memória de bloqueio
+- ela é excluída imediatamente após o término da execução
+
+Se você quiser manter essas transcrições do subagente de memória de bloqueio em disco para depuração ou
+inspeção, ative a persistência explicitamente:
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ persistTranscripts: true,
+ transcriptDir: "active-memory",
+ },
+ },
+ },
+ },
+}
+```
+
+Quando habilitada, a memória ativa armazena transcrições em um diretório separado dentro da
+pasta de sessões do agente de destino, e não no caminho principal da transcrição da conversa
+do usuário.
+
+O layout padrão é conceitualmente:
+
+```text
+agents//sessions/active-memory/.jsonl
+```
+
+Você pode alterar o subdiretório relativo com `config.transcriptDir`.
+
+Use isso com cuidado:
+
+- as transcrições do subagente de memória de bloqueio podem se acumular rapidamente em sessões movimentadas
+- o modo de consulta `full` pode duplicar muito contexto de conversa
+- essas transcrições contêm contexto oculto de prompt e memórias recuperadas
+
+## Configuração
+
+Toda a configuração da memória ativa fica em:
+
+```text
+plugins.entries.active-memory
+```
+
+Os campos mais importantes são:
+
+| Chave | Tipo | Significado |
+| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `enabled` | `boolean` | Habilita o próprio plugin |
+| `config.agents` | `string[]` | IDs de agente que podem usar memória ativa |
+| `config.model` | `string` | Referência opcional de modelo do subagente de memória de bloqueio; quando não definido, a memória ativa usa o modelo atual da sessão |
+| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla quanto da conversa o subagente de memória de bloqueio vê |
+| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla quão disposto ou rigoroso o subagente de memória de bloqueio é ao decidir se deve retornar memória |
+| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada do nível de raciocínio para o subagente de memória de bloqueio; padrão `off` para velocidade |
+| `config.promptOverride` | `string` | Substituição avançada completa do prompt; não recomendada para uso normal |
+| `config.promptAppend` | `string` | Instruções extras avançadas anexadas ao prompt padrão ou substituído |
+| `config.timeoutMs` | `number` | Tempo limite rígido para o subagente de memória de bloqueio |
+| `config.maxSummaryChars` | `number` | Máximo de caracteres totais permitidos no resumo da memória ativa |
+| `config.logging` | `boolean` | Emite logs da memória ativa durante o ajuste fino |
+| `config.persistTranscripts` | `boolean` | Mantém em disco as transcrições do subagente de memória de bloqueio em vez de excluir arquivos temporários |
+| `config.transcriptDir` | `string` | Diretório relativo das transcrições do subagente de memória de bloqueio dentro da pasta de sessões do agente |
+
+Campos úteis para ajuste fino:
+
+| Chave | Tipo | Significado |
+| ----------------------------- | -------- | ------------------------------------------------------------- |
+| `config.maxSummaryChars` | `number` | Máximo de caracteres totais permitidos no resumo da memória ativa |
+| `config.recentUserTurns` | `number` | Turnos anteriores do usuário a incluir quando `queryMode` é `recent` |
+| `config.recentAssistantTurns` | `number` | Turnos anteriores do assistente a incluir quando `queryMode` é `recent` |
+| `config.recentUserChars` | `number` | Máximo de caracteres por turno recente do usuário |
+| `config.recentAssistantChars` | `number` | Máximo de caracteres por turno recente do assistente |
+| `config.cacheTtlMs` | `number` | Reutilização de cache para consultas idênticas repetidas |
+
+## Configuração recomendada
+
+Comece com `recent`.
+
+```json5
+{
+ plugins: {
+ entries: {
+ "active-memory": {
+ enabled: true,
+ config: {
+ agents: ["main"],
+ queryMode: "recent",
+ promptStyle: "balanced",
+ timeoutMs: 15000,
+ maxSummaryChars: 220,
+ logging: true,
+ },
+ },
+ },
+ },
+}
+```
+
+Se você quiser inspecionar o comportamento ao vivo durante o ajuste fino, use `/verbose on` na
+sessão em vez de procurar um comando de depuração separado da memória ativa.
+
+Depois passe para:
+
+- `message` se quiser menor latência
+- `full` se decidir que o contexto extra vale o subagente de memória de bloqueio mais lento
+
+## Depuração
+
+Se a memória ativa não estiver aparecendo onde você espera:
+
+1. Confirme que o plugin está habilitado em `plugins.entries.active-memory.enabled`.
+2. Confirme que o id do agente atual está listado em `config.agents`.
+3. Confirme que você está testando por meio de uma sessão de chat persistente interativa.
+4. Ative `config.logging: true` e observe os logs do gateway.
+5. Verifique se a própria pesquisa de memória funciona com `openclaw memory status --deep`.
+
+Se os resultados de memória estiverem ruidosos, ajuste:
+
+- `maxSummaryChars`
+
+Se a memória ativa estiver lenta demais:
+
+- reduza `queryMode`
+- reduza `timeoutMs`
+- reduza as contagens de turnos recentes
+- reduza os limites de caracteres por turno
+
+## Páginas relacionadas
+
+- [Pesquisa de memória](/pt-BR/concepts/memory-search)
+- [Referência de configuração de memória](/pt-BR/reference/memory-config)
+- [Configuração do Plugin SDK](/pt-BR/plugins/sdk-setup)
diff --git a/docs/pt-BR/concepts/memory-search.md b/docs/pt-BR/concepts/memory-search.md
index e20d5d984..45e201494 100644
--- a/docs/pt-BR/concepts/memory-search.md
+++ b/docs/pt-BR/concepts/memory-search.md
@@ -1,29 +1,26 @@
---
read_when:
- - Você quer entender como o memory_search funciona
+ - Você quer entender como `memory_search` funciona
- Você quer escolher um provedor de embeddings
- Você quer ajustar a qualidade da busca
-summary: Como o Memory Search encontra notas relevantes usando embeddings e recuperação híbrida
-title: Memory Search
+summary: Como a busca de memória encontra notas relevantes usando embeddings e recuperação híbrida
+title: Busca de memória
x-i18n:
- generated_at: "2026-04-06T03:06:33Z"
+ generated_at: "2026-04-10T05:34:13Z"
model: gpt-5.4
provider: openai
- source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
+ source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
source_path: concepts/memory-search.md
workflow: 15
---
-# Memory Search
+# Busca de memória
-`memory_search` encontra notas relevantes nos seus arquivos de memória, mesmo quando a
-redação difere do texto original. Ele funciona indexando a memória em pequenos
-trechos e pesquisando neles usando embeddings, palavras-chave ou ambos.
+`memory_search` encontra notas relevantes dos seus arquivos de memória, mesmo quando a formulação difere do texto original. Ela funciona indexando a memória em pequenos blocos e pesquisando neles usando embeddings, palavras-chave ou ambos.
## Início rápido
-Se você tiver uma chave de API do OpenAI, Gemini, Voyage ou Mistral configurada, o Memory
-Search funciona automaticamente. Para definir um provedor explicitamente:
+Se você tiver uma chave de API da OpenAI, Gemini, Voyage ou Mistral configurada, a busca de memória funciona automaticamente. Para definir um provedor explicitamente:
```json5
{
@@ -37,20 +34,19 @@ Search funciona automaticamente. Para definir um provedor explicitamente:
}
```
-Para embeddings locais sem chave de API, use `provider: "local"` (requer
-node-llama-cpp).
+Para embeddings locais sem chave de API, use `provider: "local"` (requer `node-llama-cpp`).
## Provedores compatíveis
| Provedor | ID | Precisa de chave de API | Observações |
| -------- | --------- | ----------------------- | ----------------------------------------------------- |
| OpenAI | `openai` | Sim | Detectado automaticamente, rápido |
-| Gemini | `gemini` | Sim | Suporta indexação de imagem/áudio |
+| Gemini | `gemini` | Sim | Oferece suporte a indexação de imagem/áudio |
| Voyage | `voyage` | Sim | Detectado automaticamente |
| Mistral | `mistral` | Sim | Detectado automaticamente |
-| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais da AWS é resolvida |
+| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais AWS é resolvida |
| Ollama | `ollama` | Não | Local, deve ser definido explicitamente |
-| Local | `local` | Não | Modelo GGUF, download de ~0.6 GB |
+| Local | `local` | Não | Modelo GGUF, download de ~0,6 GB |
## Como a busca funciona
@@ -67,36 +63,30 @@ flowchart LR
M --> R["Top Results"]
```
-- **Busca vetorial** encontra notas com significado semelhante ("gateway host" corresponde a
- "a máquina que executa o OpenClaw").
-- **Busca por palavra-chave BM25** encontra correspondências exatas (IDs, strings de erro, chaves de
- configuração).
+- **Busca vetorial** encontra notas com significado semelhante ("gateway host" corresponde a "a máquina que executa o OpenClaw").
+- **Busca por palavra-chave com BM25** encontra correspondências exatas (IDs, strings de erro, chaves de configuração).
Se apenas um caminho estiver disponível (sem embeddings ou sem FTS), o outro será executado sozinho.
## Melhorando a qualidade da busca
-Dois recursos opcionais ajudam quando você tem um grande histórico de notas:
+Dois recursos opcionais ajudam quando você tem um histórico grande de notas:
### Decaimento temporal
-Notas antigas perdem gradualmente peso no ranking, para que as informações recentes apareçam primeiro.
-Com a meia-vida padrão de 30 dias, uma nota do mês passado pontua com 50% do
-seu peso original. Arquivos perenes como `MEMORY.md` nunca sofrem decaimento.
+Notas antigas perdem peso gradualmente no ranqueamento para que informações recentes apareçam primeiro.
+Com a meia-vida padrão de 30 dias, uma nota do mês passado recebe 50% do seu peso original. Arquivos permanentes como `MEMORY.md` nunca sofrem decaimento.
-Ative o decaimento temporal se o seu agente tiver meses de notas diárias e informações
-desatualizadas continuarem superando o contexto recente no ranking.
+Ative o decaimento temporal se o seu agente tiver meses de notas diárias e informações desatualizadas continuarem superando o contexto recente.
### MMR (diversidade)
-Reduz resultados redundantes. Se cinco notas mencionarem a mesma configuração de roteador, o MMR
-garante que os principais resultados cubram tópicos diferentes em vez de se repetirem.
+Reduz resultados redundantes. Se cinco notas mencionam a mesma configuração de roteador, o MMR garante que os principais resultados cubram tópicos diferentes em vez de repetir o mesmo conteúdo.
-Ative o MMR se o `memory_search` continuar retornando trechos quase duplicados de
-notas diárias diferentes.
+Ative o MMR se `memory_search` continuar retornando trechos quase duplicados de notas diárias diferentes.
### Ativar ambos
@@ -120,30 +110,22 @@ notas diárias diferentes.
## Memória multimodal
-Com Gemini Embedding 2, você pode indexar imagens e arquivos de áudio junto com
-Markdown. As consultas de busca continuam sendo texto, mas correspondem a conteúdo visual e de áudio.
-Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config) para
-a configuração.
+Com o Gemini Embedding 2, você pode indexar imagens e arquivos de áudio junto com Markdown. As consultas de busca continuam sendo texto, mas correspondem ao conteúdo visual e de áudio. Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config) para saber como configurar.
-## Busca na memória de sessão
+## Busca na memória da sessão
-Opcionalmente, você pode indexar transcrições de sessão para que o `memory_search` possa recuperar
-conversas anteriores. Isso é opt-in via
-`memorySearch.experimental.sessionMemory`. Consulte a
-[referência de configuração](/pt-BR/reference/memory-config) para detalhes.
+Opcionalmente, você pode indexar transcrições de sessão para que `memory_search` consiga recuperar conversas anteriores. Isso é opcional via `memorySearch.experimental.sessionMemory`. Consulte a [referência de configuração](/pt-BR/reference/memory-config) para mais detalhes.
## Solução de problemas
-**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se estiver vazio, execute
-`openclaw memory index --force`.
+**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se estiver vazio, execute `openclaw memory index --force`.
-**Apenas correspondências por palavra-chave?** Seu provedor de embeddings pode não estar configurado. Verifique
-`openclaw memory status --deep`.
+**Apenas correspondências por palavra-chave?** Seu provedor de embeddings pode não estar configurado. Verifique com `openclaw memory status --deep`.
-**Texto CJK não encontrado?** Reconstrua o índice FTS com
-`openclaw memory index --force`.
+**Texto em CJK não encontrado?** Reconstrua o índice FTS com `openclaw memory index --force`.
## Leitura adicional
-- [Memory](/pt-BR/concepts/memory) -- layout de arquivos, backends, ferramentas
-- [referência de configuração de memória](/pt-BR/reference/memory-config) -- todos os parâmetros de configuração
+- [Memória ativa](/pt-BR/concepts/active-memory) -- memória de subagente para sessões de chat interativas
+- [Memória](/pt-BR/concepts/memory) -- layout de arquivos, backends, ferramentas
+- [Referência de configuração de memória](/pt-BR/reference/memory-config) -- todas as opções de configuração
diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md
index 8dc6ae65f..edf4102c6 100644
--- a/docs/pt-BR/concepts/qa-e2e-automation.md
+++ b/docs/pt-BR/concepts/qa-e2e-automation.md
@@ -1,37 +1,37 @@
---
read_when:
- - Ao estender qa-lab ou qa-channel
- - Ao adicionar cenários de QA com suporte do repositório
- - Ao criar uma automação de QA mais realista em torno do Dashboard do Gateway
-summary: Estrutura privada de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
+ - Estendendo qa-lab ou qa-channel
+ - Adicionando cenários de QA com suporte do repositório
+ - Criando automação de QA com maior realismo em torno do painel do Gateway
+summary: Formato privado de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
title: Automação E2E de QA
x-i18n:
- generated_at: "2026-04-09T01:27:38Z"
+ generated_at: "2026-04-10T05:34:12Z"
model: gpt-5.4
provider: openai
- source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
+ source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Automação E2E de QA
-A stack privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista,
-com formato de canal, do que um único teste de unidade consegue.
+A pilha privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista,
+no formato de canal, do que um único teste unitário consegue.
-Componentes atuais:
+Peças atuais:
- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread,
reação, edição e exclusão.
-- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição,
+- `extensions/qa-lab`: interface de depuração e barramento de QA para observar a transcrição,
injetar mensagens de entrada e exportar um relatório em Markdown.
-- `qa/`: recursos seed com suporte do repositório para a tarefa inicial e cenários
+- `qa/`: ativos de seed com suporte do repositório para a tarefa inicial e cenários
básicos de QA.
-O fluxo atual do operador de QA é um site de QA em dois painéis:
+O fluxo atual do operador de QA é um site de QA com dois painéis:
-- Esquerda: Dashboard do Gateway (Control UI) com o agente.
-- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano do cenário.
+- Esquerda: painel do Gateway (Control UI) com o agente.
+- Direita: QA Lab, mostrando a transcrição no estilo do Slack e o plano de cenário.
Execute com:
@@ -39,13 +39,13 @@ Execute com:
pnpm qa:lab:up
```
-Isso compila o site de QA, inicia a lane do gateway com suporte do Docker e expõe a
-página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma
-missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou
+Isso compila o site de QA, inicia a faixa do gateway com suporte do Docker e expõe a
+página do QA Lab onde um operador ou loop de automação pode dar ao agente uma missão
+de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou
permaneceu bloqueado.
Para uma iteração mais rápida na UI do QA Lab sem recompilar a imagem Docker a cada vez,
-inicie a stack com um bundle do QA Lab montado por bind:
+inicie a pilha com um bundle do QA Lab montado por bind:
```bash
pnpm openclaw qa docker-build-image
@@ -56,32 +56,47 @@ pnpm qa:lab:watch
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind-mount de
`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch`
-recompila esse bundle quando há alterações, e o navegador recarrega automaticamente quando o hash
-dos recursos do QA Lab muda.
+recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash
+do ativo do QA Lab muda.
+
+Para uma faixa descartável em VM Linux sem colocar o Docker no caminho do QA, execute:
+
+```bash
+pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
+```
+
+Isso inicializa um guest novo do Multipass, instala as dependências, compila o OpenClaw
+dentro do guest, executa `qa suite` e depois copia o relatório normal de QA e o
+resumo de volta para `.artifacts/qa-e2e/...` no host.
+Ele reutiliza o mesmo comportamento de seleção de cenário que `qa suite` no host.
+Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o
+guest: chaves de provedor baseadas em ambiente, o caminho de configuração do provedor ao vivo de QA e
+`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest
+possa gravar de volta por meio do workspace montado.
## Seeds com suporte do repositório
-Os recursos seed ficam em `qa/`:
+Os ativos de seed ficam em `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
-Eles ficam intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
+Eles estão intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
agente. A lista básica deve permanecer ampla o suficiente para cobrir:
-- conversa por DM e em canal
+- chat em DM e em canal
- comportamento de thread
-- ciclo de vida das ações de mensagem
+- ciclo de vida de ações de mensagem
- callbacks de cron
- recuperação de memória
- troca de modelo
- handoff para subagente
-- leitura do repositório e da documentação
-- uma pequena tarefa de compilação, como Lobster Invaders
+- leitura do repositório e leitura da documentação
+- uma pequena tarefa de build, como Lobster Invaders
## Relatórios
-`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado.
+`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento.
O relatório deve responder:
- O que funcionou
@@ -89,7 +104,7 @@ O relatório deve responder:
- O que permaneceu bloqueado
- Quais cenários de acompanhamento valem a pena adicionar
-Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelo reais
+Para verificações de personalidade e estilo, execute o mesmo cenário em várias refs de modelo ao vivo
e escreva um relatório em Markdown avaliado:
```bash
@@ -109,31 +124,31 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
-O comando executa processos filho locais do gateway de QA, não Docker. Os cenários de avaliação de caráter
+O comando executa processos filhos locais do gateway de QA, não Docker. Os cenários de avaliação de personalidade
devem definir a persona por meio de `SOUL.md` e depois executar turnos normais de usuário,
-como conversa, ajuda no workspace e pequenas tarefas com arquivos. Não se deve dizer ao modelo
-candidato que ele está sendo avaliado. O comando preserva cada transcrição completa,
-registra estatísticas básicas da execução e então pede aos modelos juízes em modo fast com
-raciocínio `xhigh` que classifiquem as execuções por naturalidade, vibe e humor.
-Use `--blind-judge-models` ao comparar providers: o prompt do juiz ainda recebe
-cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos neutros
-como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após o
-parse.
-As execuções dos candidatos usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que
-oferecem suporte a isso. Substitua um candidato específico inline com
+como chat, ajuda com o workspace e pequenas tarefas em arquivos. Não se deve informar ao
+modelo candidato que ele está sendo avaliado. O comando preserva cada transcrição completa,
+registra estatísticas básicas de execução e depois pede aos modelos juízes em modo rápido com
+raciocínio `xhigh` para classificar as execuções por naturalidade, vibe e humor.
+Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe
+cada transcrição e status de execução, mas as refs candidatas são substituídas por rótulos neutros
+como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após a
+análise.
+As execuções candidatas usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que
+o suportam. Substitua um candidato específico inline com
`--model provider/model,thinking=`. `--thinking ` ainda define um
fallback global, e o formato antigo `--model-thinking ` é
mantido por compatibilidade.
-As refs candidatas da OpenAI usam modo fast por padrão para que o processamento prioritário seja usado quando
-o provider oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um
-único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser
-forçar o modo fast para todos os modelos candidatos. As durações dos candidatos e dos juízes são
-registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente para
-não classificar por velocidade.
-As execuções dos modelos candidatos e juízes usam simultaneidade 16 por padrão. Reduza
-`--concurrency` ou `--judge-concurrency` quando limites do provider ou pressão no gateway local
+As refs candidatas da OpenAI usam o modo rápido por padrão para que o processamento prioritário seja usado onde
+o provedor o suportar. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um
+único candidato ou juiz precisar de uma substituição. Passe `--fast` somente quando quiser
+forçar o modo rápido para todos os modelos candidatos. As durações de candidatos e juízes são
+registradas no relatório para análise comparativa, mas os prompts dos juízes dizem explicitamente
+para não classificar por velocidade.
+As execuções de modelos candidatos e juízes usam simultaneidade 16 por padrão. Reduza
+`--concurrency` ou `--judge-concurrency` quando os limites do provedor ou a pressão no gateway local
tornarem uma execução barulhenta demais.
-Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão
+Quando nenhum candidato `--model` é passado, a avaliação de personalidade usa por padrão
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5` e
diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md
index 71914cea3..a80b34fde 100644
--- a/docs/pt-BR/help/testing.md
+++ b/docs/pt-BR/help/testing.md
@@ -1,15 +1,15 @@
---
read_when:
- - Executar testes localmente ou em CI
- - Adicionar regressões para bugs de modelo/provedor
- - Depurar comportamento de gateway + agente
+ - Executando testes localmente ou na CI
+ - Adicionando regressões para bugs de modelo/provedor
+ - Depurando o comportamento do gateway + agente
summary: 'Kit de testes: suítes unit/e2e/live, executores Docker e o que cada teste cobre'
title: Testes
x-i18n:
- generated_at: "2026-04-09T01:30:18Z"
+ generated_at: "2026-04-10T05:34:11Z"
model: gpt-5.4
provider: openai
- source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b
+ source_hash: 21b78e59a5189f4e8e6e1b490d350f4735c0395da31d21fc5d10b825313026b4
source_path: help/testing.md
workflow: 15
---
@@ -21,7 +21,7 @@ O OpenClaw tem três suítes Vitest (unit/integration, e2e, live) e um pequeno c
Este documento é um guia de “como testamos”:
- O que cada suíte cobre (e o que ela deliberadamente _não_ cobre)
-- Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração)
+- Quais comandos executar para fluxos de trabalho comuns (local, antes de enviar, depuração)
- Como os testes live descobrem credenciais e selecionam modelos/provedores
- Como adicionar regressões para problemas reais de modelo/provedor
@@ -29,78 +29,100 @@ Este documento é um guia de “como testamos”:
Na maioria dos dias:
-- Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm test`
-- Execução local mais rápida da suíte completa em uma máquina folgada: `pnpm test:max`
+- Gate completo (esperado antes de enviar): `pnpm build && pnpm check && pnpm test`
+- Execução local mais rápida da suíte completa em uma máquina com bastante recurso: `pnpm test:max`
- Loop direto de watch do Vitest: `pnpm test:watch`
-- O direcionamento direto de arquivos agora também roteia caminhos de extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- Prefira primeiro execuções direcionadas quando estiver iterando em uma única falha.
- Site de QA com suporte de Docker: `pnpm qa:lab:up`
+- Faixa de QA com VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
-Quando você mexe em testes ou quer confiança extra:
+Quando você altera testes ou quer confiança extra:
- Gate de cobertura: `pnpm test:coverage`
- Suíte E2E: `pnpm test:e2e`
-Ao depurar provedores/modelos reais (exige credenciais reais):
+Ao depurar provedores/modelos reais (requer credenciais reais):
-- Suíte live (sondagens de modelos + gateway tool/image): `pnpm test:live`
-- Direcione um único arquivo live silenciosamente: `pnpm test:live -- src/agents/models.profiles.live.test.ts`
+- Suíte live (modelos + sondas de ferramentas/imagens do gateway): `pnpm test:live`
+- Direcionar silenciosamente um arquivo live: `pnpm test:live -- src/agents/models.profiles.live.test.ts`
-Dica: quando você precisa apenas de um caso com falha, prefira restringir os testes live com as variáveis de ambiente de allowlist descritas abaixo.
+Dica: quando você só precisa de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo.
+
+## Executores específicos de QA
+
+Esses comandos ficam ao lado das suítes principais de teste quando você precisa do realismo do qa-lab:
+
+- `pnpm openclaw qa suite`
+ - Executa cenários de QA com suporte do repositório diretamente no host.
+- `pnpm openclaw qa suite --runner multipass`
+ - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável.
+ - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host.
+ - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`.
+ - Execuções live encaminham as entradas de autenticação de QA compatíveis que são práticas para o guest:
+ chaves de provedor baseadas em variáveis de ambiente, o caminho de configuração do provedor live de QA e `CODEX_HOME`
+ quando presente.
+ - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta por meio
+ do workspace montado.
+ - Grava o relatório + resumo normais de QA, além dos logs do Multipass, em
+ `.artifacts/qa-e2e/...`.
+- `pnpm qa:lab:up`
+ - Inicia o site de QA com suporte de Docker para trabalho de QA no estilo de operador.
## Suítes de teste (o que roda onde)
-Pense nas suítes como “realismo crescente” (e flakiness/custo crescentes):
+Pense nas suítes como “realismo crescente” (e aumento de instabilidade/custo):
### Unit / integration (padrão)
- Comando: `pnpm test`
-- Configuração: dez execuções sequenciais de shard (`vitest.full-*.config.ts`) sobre os projetos Vitest escopados já existentes
-- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes node em `ui` permitidos pela allowlist cobertos por `vitest.unit.config.ts`
+- Configuração: dez execuções sequenciais de shards (`vitest.full-*.config.ts`) sobre os projetos Vitest com escopo já existentes
+- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes Node de `ui` permitidos cobertos por `vitest.unit.config.ts`
- Escopo:
- Testes unitários puros
- - Testes de integração in-process (autenticação do gateway, roteamento, ferramentas, parsing, configuração)
+ - Testes de integração em processo (autenticação do gateway, roteamento, ferramentas, parsing, configuração)
- Regressões determinísticas para bugs conhecidos
- Expectativas:
- - Roda em CI
+ - Roda na CI
- Não requer chaves reais
- Deve ser rápido e estável
- Observação sobre projetos:
- - `pnpm test` sem alvo agora executa onze configurações de shard menores (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extension deixe outras suítes sem recursos.
- - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático.
- - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam alvos explícitos de arquivo/diretório primeiro por faixas escopadas, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo completo de inicialização do projeto raiz.
- - `pnpm test:changed` expande caminhos git alterados nas mesmas faixas escopadas quando o diff toca apenas arquivos-fonte/de teste roteáveis; edições de config/setup ainda voltam para a nova execução ampla do projeto raiz.
- - Alguns testes selecionados de `plugin-sdk` e `commands` também são roteados por faixas leves dedicadas que pulam `test/setup-openclaw-runtime.ts`; arquivos stateful/pesados em runtime permanecem nas faixas existentes.
- - Alguns arquivos auxiliares de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas faixas leves, para que edições em helpers evitem reexecutar a suíte pesada completa daquele diretório.
+ - `pnpm test` sem alvo agora executa onze configurações menores de shards (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensões sufoque suítes não relacionadas.
+ - `pnpm test --watch` ainda usa o grafo de projetos raiz nativo de `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático.
+ - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` direcionam primeiro alvos explícitos de arquivo/diretório por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo de inicialização completo do projeto raiz.
+ - `pnpm test:changed` expande caminhos git alterados para as mesmas faixas com escopo quando o diff toca apenas arquivos roteáveis de código-fonte/teste; edições em configuração/setup ainda recorrem à reexecução ampla do projeto raiz.
+ - Alguns testes selecionados de `plugin-sdk` e `commands` também passam por faixas leves dedicadas que pulam `test/setup-openclaw-runtime.ts`; arquivos com estado pesado/em tempo de execução permanecem nas faixas existentes.
+ - Alguns arquivos-fonte auxiliares selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas faixas leves, para que edições em helpers evitem reexecutar a suíte pesada completa desse diretório.
- `auto-reply` agora tem três buckets dedicados: helpers core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token.
- Observação sobre o executor embutido:
- - Quando você altera entradas de descoberta de message-tool ou o contexto de runtime de compactação,
+ - Quando você altera entradas de descoberta de ferramentas de mensagem ou o contexto de tempo de execução de compactação,
mantenha ambos os níveis de cobertura.
- - Adicione regressões focadas em helpers para limites puros de roteamento/normalização.
+ - Adicione regressões focadas de helpers para limites puros de roteamento/normalização.
- Também mantenha saudáveis as suítes de integração do executor embutido:
`src/agents/pi-embedded-runner/compact.hooks.test.ts`,
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`.
- - Essas suítes verificam que ids escopados e o comportamento de compactação ainda fluem
- pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de helper não são um
+ - Essas suítes verificam que ids com escopo e o comportamento de compactação ainda fluem
+ pelos caminhos reais de `run.ts` / `compact.ts`; testes apenas de helper não são um
substituto suficiente para esses caminhos de integração.
- Observação sobre pool:
- A configuração base do Vitest agora usa `threads` por padrão.
- - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos raiz, e2e e live.
- - A faixa UI da raiz mantém sua configuração `jsdom` e otimizador, mas agora também roda no executor compartilhado não isolado.
+ - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos raiz, configurações e2e e live.
+ - A faixa raiz da UI mantém sua configuração `jsdom` e otimizador, mas agora também roda no executor compartilhado não isolado.
- Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest.
- - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão aos processos Node filhos do Vitest para reduzir o churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8.
+ - O iniciador compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest para reduzir o churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8.
- Observação sobre iteração local rápida:
- - `pnpm test:changed` roteia por faixas escopadas quando os caminhos alterados mapeiam claramente para uma suíte menor.
+ - `pnpm test:changed` roteia por faixas com escopo quando os caminhos alterados mapeiam claramente para uma suíte menor.
- `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers.
- - O autoescalonamento local de workers agora é intencionalmente conservador e também reduz quando a média de carga do host já está alta, então múltiplas execuções simultâneas do Vitest causam menos impacto por padrão.
- - A configuração base do Vitest marca os projetos/arquivos de configuração como `forceRerunTriggers` para que novas execuções no modo changed permaneçam corretas quando o encadeamento dos testes muda.
+ - O escalonamento automático local de workers agora é intencionalmente conservador e também recua quando a média de carga do host já está alta, para que várias execuções simultâneas do Vitest causem menos impacto por padrão.
+ - A configuração base do Vitest marca os arquivos de projetos/configuração como `forceRerunTriggers` para que reexecuções em modo changed permaneçam corretas quando o wiring de teste muda.
- A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` ativado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto.
- Observação sobre depuração de desempenho:
- - `pnpm test:perf:imports` ativa relatórios de duração de importação do Vitest mais a saída de detalhamento de importação.
- - `pnpm test:perf:imports:changed` restringe a mesma visão de profiling a arquivos alterados desde `origin/main`.
-- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS.
-- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore local com alterações roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest.
- - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para a sobrecarga de inicialização e transformação do Vitest/Vite.
+ - `pnpm test:perf:imports` ativa relatórios de duração de importação do Vitest, além da saída detalhada de imports.
+ - `pnpm test:perf:imports:changed` restringe a mesma visualização de profiling aos arquivos alterados desde `origin/main`.
+- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para aquele diff com commit e imprime tempo total mais RSS máximo no macOS.
+- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest.
+ - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite.
- `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a suíte unit com paralelismo de arquivos desativado.
### E2E (smoke do gateway)
@@ -108,18 +130,18 @@ Pense nas suítes como “realismo crescente” (e flakiness/custo crescentes):
- Comando: `pnpm test:e2e`
- Configuração: `vitest.e2e.config.ts`
- Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`
-- Padrões de runtime:
- - Usa `threads` do Vitest com `isolate: false`, alinhado ao restante do repositório.
+- Padrões de tempo de execução:
+ - Usa `threads` do Vitest com `isolate: false`, acompanhando o restante do repositório.
- Usa workers adaptativos (CI: até 2, local: 1 por padrão).
- - Roda em modo silencioso por padrão para reduzir a sobrecarga de I/O no console.
-- Overrides úteis:
- - `OPENCLAW_E2E_WORKERS=` para forçar a quantidade de workers (limitada a 16).
+ - Roda em modo silencioso por padrão para reduzir overhead de I/O do console.
+- Substituições úteis:
+ - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16).
- `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada do console.
- Escopo:
- - Comportamento end-to-end de gateway multi-instância
+ - Comportamento end-to-end de gateway com múltiplas instâncias
- Superfícies WebSocket/HTTP, emparelhamento de nós e rede mais pesada
- Expectativas:
- - Roda em CI (quando ativado no pipeline)
+ - Roda na CI (quando habilitado no pipeline)
- Não requer chaves reais
- Tem mais partes móveis do que testes unitários (pode ser mais lento)
@@ -129,15 +151,15 @@ Pense nas suítes como “realismo crescente” (e flakiness/custo crescentes):
- Arquivo: `test/openshell-sandbox.e2e.test.ts`
- Escopo:
- Inicia um gateway OpenShell isolado no host via Docker
- - Cria um sandbox a partir de um Dockerfile local temporário
+ - Cria uma sandbox a partir de um Dockerfile local temporário
- Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` + execução SSH reais
- - Verifica o comportamento canônico do sistema de arquivos remoto por meio da ponte fs do sandbox
+ - Verifica o comportamento canônico remoto do sistema de arquivos por meio da ponte fs da sandbox
- Expectativas:
- - Apenas opt-in; não faz parte da execução padrão de `pnpm test:e2e`
+ - Somente opt-in; não faz parte da execução padrão de `pnpm test:e2e`
- Requer uma CLI `openshell` local e um daemon Docker funcional
- - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o gateway e o sandbox de teste
-- Overrides úteis:
- - `OPENCLAW_E2E_OPENSHELL=1` para ativar o teste ao executar manualmente a suíte e2e mais ampla
+ - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o gateway de teste e a sandbox
+- Substituições úteis:
+ - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper
### Live (provedores reais + modelos reais)
@@ -145,115 +167,115 @@ Pense nas suítes como “realismo crescente” (e flakiness/custo crescentes):
- Comando: `pnpm test:live`
- Configuração: `vitest.live.config.ts`
- Arquivos: `src/**/*.live.test.ts`
-- Padrão: **ativado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`)
+- Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`)
- Escopo:
- “Esse provedor/modelo realmente funciona _hoje_ com credenciais reais?”
- - Detectar mudanças no formato do provedor, peculiaridades de tool-calling, problemas de autenticação e comportamento de limite de taxa
+ - Captura mudanças de formato do provedor, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de limite de taxa
- Expectativas:
- - Não é estável em CI por design (redes reais, políticas reais dos provedores, cotas, indisponibilidades)
+ - Não é estável para CI por definição (redes reais, políticas reais do provedor, cotas, indisponibilidades)
- Custa dinheiro / usa limites de taxa
- - Prefira executar subconjuntos restritos em vez de “tudo”
+ - Prefira executar subconjuntos reduzidos em vez de “tudo”
- Execuções live usam `~/.profile` para obter chaves de API ausentes.
-- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um diretório home temporário de teste, para que fixtures unit não possam modificar seu `~/.openclaw` real.
-- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando você intencionalmente precisar que os testes live usem seu diretório home real.
-- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização.
-- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou override por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de rate limit.
+- Por padrão, execuções live ainda isolam `HOME` e copiam material de configuração/autenticação para um diretório home temporário de teste para que fixtures unit não possam alterar seu `~/.openclaw` real.
+- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando você precisar intencionalmente que os testes live usem seu diretório home real.
+- `pnpm test:live` agora usa um modo mais silencioso por padrão: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra sobre `~/.profile` e silencia logs de bootstrap do gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser os logs completos de inicialização de volta.
+- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou uma substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa.
- Saída de progresso/heartbeat:
- - As suítes live agora emitem linhas de progresso em stderr para que chamadas longas ao provedor permaneçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa.
+ - As suítes live agora emitem linhas de progresso para stderr, para que chamadas longas ao provedor apareçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa.
- `vitest.live.config.ts` desativa a interceptação de console do Vitest para que linhas de progresso do provedor/gateway sejam transmitidas imediatamente durante execuções live.
- Ajuste heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`.
- - Ajuste heartbeats de gateway/probe com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
+ - Ajuste heartbeats de gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
## Qual suíte devo executar?
Use esta tabela de decisão:
-- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa)
+- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você alterou muita coisa)
- Tocando rede do gateway / protocolo WS / emparelhamento: adicione `pnpm test:e2e`
-- Depurando “meu bot caiu” / falhas específicas de provedor / tool calling: execute um `pnpm test:live` restrito
+- Depurando “meu bot caiu” / falhas específicas do provedor / chamada de ferramentas: execute um `pnpm test:live` reduzido
## Live: varredura de capacidades do nó Android
- Teste: `src/gateway/android-node.capabilities.live.test.ts`
- Script: `pnpm android:test:integration`
-- Objetivo: invocar **todo comando anunciado atualmente** por um nó Android conectado e afirmar o comportamento do contrato de comando.
+- Objetivo: invocar **todos os comandos atualmente anunciados** por um nó Android conectado e verificar o comportamento do contrato de comando.
- Escopo:
- - Configuração prévia/manual (a suíte não instala/executa/emparelha o app).
- - Validação `node.invoke` do gateway, comando por comando, para o nó Android selecionado.
+ - Configuração manual/com pré-condições (a suíte não instala/executa/emparelha o app).
+ - Validação `node.invoke` do gateway comando por comando para o nó Android selecionado.
- Pré-configuração obrigatória:
- App Android já conectado + emparelhado ao gateway.
- App mantido em primeiro plano.
- Permissões/consentimento de captura concedidos para as capacidades que você espera que passem.
-- Overrides opcionais de alvo:
+- Substituições opcionais de alvo:
- `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`.
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
-- Detalhes completos de configuração do Android: [App Android](/pt-BR/platforms/android)
+- Detalhes completos da configuração do Android: [App Android](/pt-BR/platforms/android)
## Live: smoke de modelo (chaves de perfil)
Os testes live são divididos em duas camadas para que possamos isolar falhas:
-- “Modelo direto” nos diz se o provedor/modelo consegue responder com a chave informada.
-- “Smoke do gateway” nos diz se o pipeline completo de gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.).
+- “Modelo direto” nos diz se o provedor/modelo consegue responder com a chave fornecida.
+- “Smoke do gateway” nos diz se o pipeline completo gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.).
-### Camada 1: conclusão direta do modelo (sem gateway)
+### Camada 1: conclusão direta de modelo (sem gateway)
- Teste: `src/agents/models.profiles.live.test.ts`
- Objetivo:
- - Enumerar modelos descobertos
- - Usar `getApiKeyForModel` para selecionar modelos para os quais você tem credenciais
- - Executar uma pequena completion por modelo (e regressões direcionadas quando necessário)
-- Como ativar:
- - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar o Vitest diretamente)
-- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias de modern) para realmente executar esta suíte; caso contrário ela é pulada para manter `pnpm test:live` focado no smoke do gateway
+ - Enumerar os modelos descobertos
+ - Usar `getApiKeyForModel` para selecionar os modelos para os quais você tem credenciais
+ - Executar uma pequena conclusão por modelo (e regressões direcionadas quando necessário)
+- Como habilitar:
+ - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente)
+- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no smoke do gateway
- Como selecionar modelos:
- `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
- `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist moderna
- - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgulas)
- - Varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor.
+ - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgula)
+ - As varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor.
- Como selecionar provedores:
- - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgulas)
+ - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgula)
- De onde vêm as chaves:
- - Por padrão: armazenamento de perfis e fallbacks de env
- - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **apenas o armazenamento de perfis**
+ - Por padrão: armazenamento de perfis e fallbacks de ambiente
+ - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **somente o armazenamento de perfis**
- Por que isso existe:
- Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente do gateway está quebrado”
- - Contém regressões pequenas e isoladas (exemplo: OpenAI Responses/Codex Responses reasoning replay + fluxos de tool-call)
+ - Contém regressões pequenas e isoladas (exemplo: fluxos de replay de reasoning + chamada de ferramentas do OpenAI Responses/Codex Responses)
-### Camada 2: smoke do gateway + agente dev (o que `@openclaw` realmente faz)
+### Camada 2: smoke do gateway + agente dev (o que "@openclaw" realmente faz)
- Teste: `src/gateway/gateway-models.profiles.live.test.ts`
- Objetivo:
- - Subir um gateway in-process
- - Criar/aplicar patch em uma sessão `agent:dev:*` (override de modelo por execução)
- - Iterar modelos-com-chaves e afirmar:
+ - Subir um gateway em processo
+ - Criar/aplicar patch em uma sessão `agent:dev:*` (substituição de modelo por execução)
+ - Iterar modelos-com-chaves e verificar:
- resposta “significativa” (sem ferramentas)
- - uma invocação real de ferramenta funciona (read probe)
- - sondagens opcionais extras de ferramenta (exec+read probe)
- - caminhos de regressão do OpenAI (somente tool-call → follow-up) continuam funcionando
-- Detalhes das sondagens (para que você possa explicar falhas rapidamente):
- - Sondagem `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` esse arquivo e ecoar o nonce de volta.
- - Sondagem `exec+read`: o teste pede ao agente para gravar um nonce em um arquivo temporário via `exec` e depois `read` esse arquivo.
- - Sondagem de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `.
+ - uma invocação real de ferramenta funciona (sonda de leitura)
+ - sondas opcionais extras de ferramentas (sonda exec+read)
+ - caminhos de regressão do OpenAI (somente chamada de ferramenta → acompanhamento) continuam funcionando
+- Detalhes das sondas (para que você possa explicar falhas rapidamente):
+ - sonda `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` esse arquivo e retornar o nonce.
+ - sonda `exec+read`: o teste pede ao agente para gravar um nonce via `exec` em um arquivo temporário e depois `read` esse arquivo.
+ - sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `.
- Referência de implementação: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`.
-- Como ativar:
- - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar o Vitest diretamente)
+- Como habilitar:
+ - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente)
- Como selecionar modelos:
- Padrão: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist moderna
- Ou defina `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou lista separada por vírgulas) para restringir
- - Varreduras de gateway modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor.
-- Como selecionar provedores (evite “OpenRouter tudo”):
- - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgulas)
-- As sondagens de ferramenta + imagem estão sempre ativadas neste teste live:
- - sonda `read` + sonda `exec+read` (estresse de ferramenta)
+ - As varreduras de gateway modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor.
+- Como selecionar provedores (evite “tudo do OpenRouter”):
+ - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgula)
+- As sondas de ferramenta + imagem estão sempre ativadas neste teste live:
+ - sonda `read` + sonda `exec+read` (estresse de ferramentas)
- a sonda de imagem roda quando o modelo anuncia suporte a entrada de imagem
- - Fluxo (visão geral):
- - O teste gera um PNG minúsculo com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`)
- - Envia via `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
- - O gateway faz parsing dos attachments em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
- - O agente embutido encaminha uma mensagem multimodal do usuário ao modelo
- - Afirmação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos)
+ - Fluxo (alto nível):
+ - O teste gera um pequeno PNG com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`)
+ - Envia isso via `agent` `attachments: [{ mimeType: "image/png", content: "" }]`
+ - O gateway analisa os anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
+ - O agente embutido encaminha uma mensagem de usuário multimodal ao modelo
+ - Verificação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos)
Dica: para ver o que você pode testar na sua máquina (e os ids exatos de `provider/model`), execute:
@@ -262,26 +284,26 @@ openclaw models list
openclaw models list --json
```
-## Live: smoke do backend CLI (Claude, Codex, Gemini ou outras CLIs locais)
+## Live: smoke de backend CLI (Claude, Codex, Gemini ou outras CLIs locais)
- Teste: `src/gateway/gateway-cli-backend.live.test.ts`
-- Objetivo: validar o pipeline do Gateway + agente usando um backend CLI local, sem tocar na sua configuração padrão.
-- Os padrões de smoke específicos de backend ficam na definição `cli-backend.ts` da extension proprietária.
-- Ativar:
- - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se invocar o Vitest diretamente)
+- Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua configuração padrão.
+- Os padrões de smoke específicos de backend ficam na definição `cli-backend.ts` da extensão proprietária.
+- Habilitar:
+ - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente)
- `OPENCLAW_LIVE_CLI_BACKEND=1`
- Padrões:
- Provedor/modelo padrão: `claude-cli/claude-sonnet-4-6`
- - Comando/args/comportamento de imagem vêm dos metadados do plugin proprietário do backend CLI.
-- Overrides (opcional):
+ - O comportamento de comando/args/imagem vem dos metadados do plugin proprietário do backend CLI.
+- Substituições opcionais:
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um attachment de imagem real (os caminhos são injetados no prompt).
- - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivo de imagem como args da CLI em vez de injeção no prompt.
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um anexo de imagem real (os caminhos são injetados no prompt).
+ - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args da CLI em vez de injeção no prompt.
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como os args de imagem são passados quando `IMAGE_ARG` está definido.
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar um segundo turno e validar o fluxo de retomada.
- - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desativar a sonda padrão de continuidade de mesma sessão Claude Sonnet -> Opus (defina como `1` para forçá-la quando o modelo selecionado suportar um alvo de troca).
+ - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desativar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-la quando o modelo selecionado suportar um alvo de troca).
Exemplo:
@@ -307,37 +329,37 @@ pnpm test:docker:live-cli-backend:gemini
Observações:
-- O executor Docker fica em `scripts/test-live-cli-backend-docker.sh`.
-- Ele executa o smoke live do backend CLI dentro da imagem Docker do repositório como usuário não root `node`.
-- Ele resolve metadados de smoke da CLI a partir da extension proprietária e então instala o pacote CLI Linux correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável em cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`).
-- O smoke live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem, depois chamada de ferramenta MCP `cron` verificada por meio da CLI do gateway.
-- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma anotação anterior.
+- O executor Docker está em `scripts/test-live-cli-backend-docker.sh`.
+- Ele executa o smoke live de backend CLI dentro da imagem Docker do repositório como o usuário não root `node`.
+- Ele resolve os metadados de smoke da CLI a partir da extensão proprietária e então instala o pacote Linux CLI correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável em cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`).
+- O smoke live de backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e depois chamada da ferramenta MCP `cron` verificada pela CLI do gateway.
+- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica se a sessão retomada ainda se lembra de uma observação anterior.
## Live: smoke de bind ACP (`/acp spawn ... --bind here`)
- Teste: `src/gateway/gateway-acp-bind.live.test.ts`
- Objetivo: validar o fluxo real de bind de conversa ACP com um agente ACP live:
- enviar `/acp spawn --bind here`
- - vincular em lugar uma conversa sintética de canal de mensagem
- - enviar um follow-up normal nessa mesma conversa
- - verificar se o follow-up chega à transcrição da sessão ACP vinculada
-- Ativar:
+ - vincular uma conversa sintética de canal de mensagens no lugar
+ - enviar um acompanhamento normal nessa mesma conversa
+ - verificar se o acompanhamento chega à transcrição da sessão ACP vinculada
+- Habilitar:
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
- `OPENCLAW_LIVE_ACP_BIND=1`
- Padrões:
- Agentes ACP em Docker: `claude,codex,gemini`
- Agente ACP para `pnpm test:live ...` direto: `claude`
- - Canal sintético: contexto de conversa estilo DM do Slack
+ - Canal sintético: contexto de conversa no estilo DM do Slack
- Backend ACP: `acpx`
-- Overrides:
+- Substituições:
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
- `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini`
- `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini`
- `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'`
- Observações:
- - Essa faixa usa a superfície `chat.send` do gateway com campos sintéticos de rota de origem somente para admin, para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa.
- - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro interno de agentes do plugin `acpx` embutido para o agente de harness ACP selecionado.
+ - Esta faixa usa a superfície `chat.send` do gateway com campos de rota de origem sintética apenas para admin, para que os testes possam anexar contexto de canal de mensagens sem fingir entrega externa.
+ - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro embutido de agentes do plugin `acpx` para o agente de harness ACP selecionado.
Exemplo:
@@ -361,17 +383,17 @@ pnpm test:docker:live-acp-bind:codex
pnpm test:docker:live-acp-bind:gemini
```
-Observações sobre Docker:
+Observações do Docker:
-- O executor Docker fica em `scripts/test-live-acp-bind-docker.sh`.
-- Por padrão, ele executa o smoke de bind ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex` e depois `gemini`.
+- O executor Docker está em `scripts/test-live-acp-bind-docker.sh`.
+- Por padrão, ele executa o smoke de bind ACP em todos os agentes CLI live compatíveis em sequência: `claude`, `codex` e depois `gemini`.
- Use `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para restringir a matriz.
-- Ele usa `~/.profile` como source, prepara o material de autenticação da CLI correspondente dentro do contêiner, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente.
-- Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que `acpx` mantenha variáveis de ambiente do provedor vindas do profile carregado disponíveis para a CLI filha do harness.
+- Ele usa `~/.profile`, prepara o material de autenticação da CLI correspondente no container, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente.
+- Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente do provedor vindas do profile carregado.
### Receitas live recomendadas
-Allowlists explícitas e restritas são mais rápidas e menos sujeitas a falhas intermitentes:
+Allowlists estreitas e explícitas são mais rápidas e menos instáveis:
- Modelo único, direto (sem gateway):
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
@@ -379,10 +401,10 @@ Allowlists explícitas e restritas são mais rápidas e menos sujeitas a falhas
- Modelo único, smoke do gateway:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-- Tool calling em vários provedores:
+- Chamada de ferramentas em vários provedores:
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-- Foco em Google (chave da API Gemini + Antigravity):
+- Foco em Google (chave de API Gemini + Antigravity):
- Gemini (chave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
- Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
@@ -390,16 +412,16 @@ Observações:
- `google/...` usa a API Gemini (chave de API).
- `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agente no estilo Cloud Code Assist).
-- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (autenticação separada + peculiaridades de tooling).
+- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (autenticação separada + particularidades de tooling).
- API Gemini vs CLI Gemini:
- - API: o OpenClaw chama a API Gemini hospedada pelo Google via HTTP (chave de API / autenticação de perfil); é isso que a maioria dos usuários quer dizer com “Gemini”.
- - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria autenticação e pode se comportar de forma diferente (suporte a streaming/ferramentas/desalinhamento de versão).
+ - API: o OpenClaw chama a API Gemini hospedada pelo Google via HTTP (autenticação por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”.
+ - CLI: o OpenClaw executa um binário `gemini` local; ele tem sua própria autenticação e pode se comportar de forma diferente (streaming/suporte a ferramentas/defasagem de versão).
## Live: matriz de modelos (o que cobrimos)
-Não há uma “lista fixa de modelos de CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves.
+Não existe uma “lista de modelos de CI” fixa (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves.
-### Conjunto smoke moderno (tool calling + imagem)
+### Conjunto moderno de smoke (chamada de ferramentas + imagem)
Esta é a execução de “modelos comuns” que esperamos manter funcionando:
@@ -414,7 +436,7 @@ Esta é a execução de “modelos comuns” que esperamos manter funcionando:
Execute o smoke do gateway com ferramentas + imagem:
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
-### Base: tool calling (Read + Exec opcional)
+### Baseline: chamada de ferramentas (Read + Exec opcional)
Escolha pelo menos um por família de provedores:
@@ -427,78 +449,78 @@ Escolha pelo menos um por família de provedores:
Cobertura adicional opcional (bom ter):
- xAI: `xai/grok-4` (ou a versão mais recente disponível)
-- Mistral: `mistral/`… (escolha um modelo com capacidade de “tools” que você tenha ativado)
+- Mistral: `mistral/`… (escolha um modelo com capacidade de “tools” que você tenha habilitado)
- Cerebras: `cerebras/`… (se você tiver acesso)
-- LM Studio: `lmstudio/`… (local; o tool calling depende do modo da API)
+- LM Studio: `lmstudio/`… (local; a chamada de ferramentas depende do modo da API)
-### Visão: envio de imagem (attachment → mensagem multimodal)
+### Visão: envio de imagem (anexo → mensagem multimodal)
-Inclua pelo menos um modelo com suporte a imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes do OpenAI com capacidade de visão etc.) para exercitar a sonda de imagem.
+Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/variantes do OpenAI com suporte a visão etc.) para exercitar a sonda de imagem.
### Agregadores / gateways alternativos
-Se você tiver chaves ativadas, também oferecemos suporte a testes via:
+Se você tiver chaves habilitadas, também oferecemos suporte a testes via:
-- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de tool+image)
+- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramentas+imagem)
- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (autenticação via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
Mais provedores que você pode incluir na matriz live (se tiver credenciais/configuração):
-- Embutidos: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
+- Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
- Via `models.providers` (endpoints personalizados): `minimax` (nuvem/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.)
-Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é o que `discoverModels(...)` retorna na sua máquina + as chaves disponíveis.
+Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é o que `discoverModels(...)` retorna na sua máquina + quaisquer chaves disponíveis.
## Credenciais (nunca faça commit)
Os testes live descobrem credenciais da mesma forma que a CLI. Implicações práticas:
- Se a CLI funciona, os testes live devem encontrar as mesmas chaves.
-- Se um teste live disser “sem credenciais”, depure da mesma forma que depuraria `openclaw models list` / seleção de modelo.
+- Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria `openclaw models list` / seleção de modelo.
- Perfis de autenticação por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live)
- Configuração: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`)
- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para o home live preparado quando presente, mas não é o armazenamento principal de chaves de perfil)
-- Execuções locais live copiam por padrão a configuração ativa, arquivos `auth-profiles.json` por agente, `credentials/` legado e diretórios de autenticação de CLI externa suportados para um diretório home temporário de teste; homes live preparados pulam `workspace/` e `sandboxes/`, e overrides de caminho `agents.*.workspace` / `agentDir` são removidos para que as sondagens fiquem longe do seu workspace real do host.
+- Execuções live locais copiam por padrão a configuração ativa, os arquivos `auth-profiles.json` por agente, o `credentials/` legado e diretórios compatíveis de autenticação de CLI externa para um home temporário de teste; homes live preparados ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas fiquem fora do seu workspace real no host.
-Se você quiser depender de chaves em env (por exemplo, exportadas no seu `~/.profile`), execute os testes locais após `source ~/.profile` ou use os executores Docker abaixo (eles podem montar `~/.profile` no contêiner).
+Se quiser depender de chaves de ambiente (por exemplo, exportadas no seu `~/.profile`), execute os testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` no container).
-## Deepgram live (transcrição de áudio)
+## Live do Deepgram (transcrição de áudio)
- Teste: `src/media-understanding/providers/deepgram/audio.live.test.ts`
-- Ativar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
+- Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
-## BytePlus coding plan live
+## Live do plano de codificação BytePlus
- Teste: `src/agents/byteplus.live.test.ts`
-- Ativar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
-- Override opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest`
+- Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
+- Substituição opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest`
-## ComfyUI workflow media live
+## Live de mídia de workflow ComfyUI
- Teste: `extensions/comfy/comfy.live.test.ts`
-- Ativar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
+- Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
- Escopo:
- - Exercita os caminhos embutidos de imagem, vídeo e `music_generate` do comfy
- - Pula cada capacidade a menos que `models.providers.comfy.` esteja configurado
- - Útil após mudar envio de workflow do comfy, polling, downloads ou registro de plugin
+ - Exercita os caminhos integrados de imagem, vídeo e `music_generate` do comfy
+ - Ignora cada capacidade, a menos que `models.providers.comfy.` esteja configurado
+ - Útil após alterar envio de workflow do comfy, polling, downloads ou registro do plugin
-## Geração de imagem live
+## Live de geração de imagem
- Teste: `src/image-generation/runtime.live.test.ts`
- Comando: `pnpm test:live src/image-generation/runtime.live.test.ts`
- Harness: `pnpm test:live:media image`
- Escopo:
- - Enumera cada plugin de provedor de geração de imagem registrado
- - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes das sondagens
- - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascararem credenciais reais do shell
- - Pula provedores sem autenticação/perfil/modelo utilizáveis
- - Executa as variantes padrão de geração de imagem por meio da capacidade compartilhada de runtime:
+ - Enumera todos os plugins de provedor de geração de imagem registrados
+ - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes de sondar
+ - Usa chaves de API live/do ambiente antes de perfis de autenticação armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell
+ - Ignora provedores sem autenticação/perfil/modelo utilizável
+ - Executa as variantes padrão de geração de imagem pela capacidade compartilhada de runtime:
- `google:flash-generate`
- `google:pro-generate`
- `google:pro-edit`
- `openai:default-generate`
-- Provedores embutidos atualmente cobertos:
+- Provedores integrados atualmente cobertos:
- `openai`
- `google`
- Restrição opcional:
@@ -506,54 +528,54 @@ Se você quiser depender de chaves em env (por exemplo, exportadas no seu `~/.pr
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"`
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"`
- Comportamento opcional de autenticação:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação pelo armazenamento de perfis e ignorar substituições somente por ambiente
-## Geração de música live
+## Live de geração de música
- Teste: `extensions/music-generation-providers.live.test.ts`
-- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
+- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
- Harness: `pnpm test:live:media music`
- Escopo:
- - Exercita o caminho compartilhado embutido do provedor de geração de música
+ - Exercita o caminho compartilhado integrado de provedor de geração de música
- Atualmente cobre Google e MiniMax
- - Carrega variáveis de ambiente do provedor do seu shell de login (`~/.profile`) antes das sondagens
- - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascararem credenciais reais do shell
- - Pula provedores sem autenticação/perfil/modelo utilizáveis
+ - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar
+ - Usa chaves de API live/do ambiente antes de perfis de autenticação armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell
+ - Ignora provedores sem autenticação/perfil/modelo utilizável
- Executa ambos os modos de runtime declarados quando disponíveis:
- - `generate` com entrada somente de prompt
+ - `generate` com entrada apenas por prompt
- `edit` quando o provedor declara `capabilities.edit.enabled`
- Cobertura atual da faixa compartilhada:
- `google`: `generate`, `edit`
- `minimax`: `generate`
- - `comfy`: arquivo live separado do Comfy, não esta varredura compartilhada
+ - `comfy`: arquivo live do Comfy separado, não esta varredura compartilhada
- Restrição opcional:
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
- Comportamento opcional de autenticação:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação pelo armazenamento de perfis e ignorar substituições somente por ambiente
-## Geração de vídeo live
+## Live de geração de vídeo
- Teste: `extensions/video-generation-providers.live.test.ts`
-- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
+- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
- Harness: `pnpm test:live:media video`
- Escopo:
- - Exercita o caminho compartilhado embutido do provedor de geração de vídeo
- - Carrega variáveis de ambiente do provedor do seu shell de login (`~/.profile`) antes das sondagens
- - Usa por padrão chaves de API live/env antes de perfis de autenticação armazenados, para que chaves de teste obsoletas em `auth-profiles.json` não mascararem credenciais reais do shell
- - Pula provedores sem autenticação/perfil/modelo utilizáveis
+ - Exercita o caminho compartilhado integrado de provedor de geração de vídeo
+ - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes de sondar
+ - Usa chaves de API live/do ambiente antes de perfis de autenticação armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell
+ - Ignora provedores sem autenticação/perfil/modelo utilizável
- Executa ambos os modos de runtime declarados quando disponíveis:
- - `generate` com entrada somente de prompt
- - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local baseada em buffer na varredura compartilhada
- - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local baseada em buffer na varredura compartilhada
- - Provedores `imageToVideo` atualmente declarados, mas pulados, na varredura compartilhada:
- - `vydra` porque o `veo3` embutido é somente texto e o `kling` embutido exige uma URL remota de imagem
+ - `generate` com entrada apenas por prompt
+ - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de imagem baseada em buffer na varredura compartilhada
+ - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada local de vídeo baseada em buffer na varredura compartilhada
+ - Provedores atualmente declarados, mas ignorados, de `imageToVideo` na varredura compartilhada:
+ - `vydra` porque o `veo3` integrado é somente texto e o `kling` integrado exige uma URL de imagem remota
- Cobertura específica do provedor Vydra:
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
- - esse arquivo executa `veo3` text-to-video mais uma faixa `kling` que usa por padrão um fixture remoto de URL de imagem
+ - esse arquivo executa `veo3` text-to-video mais uma faixa `kling` que usa por padrão um fixture de URL de imagem remota
- Cobertura live atual de `videoToVideo`:
- - `runway` apenas quando o modelo selecionado é `runway/gen4_aleph`
- - Provedores `videoToVideo` atualmente declarados, mas pulados, na varredura compartilhada:
+ - `runway` somente quando o modelo selecionado é `runway/gen4_aleph`
+ - Provedores atualmente declarados, mas ignorados, de `videoToVideo` na varredura compartilhada:
- `alibaba`, `qwen`, `xai` porque esses caminhos atualmente exigem URLs de referência remotas `http(s)` / MP4
- `google` porque a faixa compartilhada atual Gemini/Veo usa entrada local baseada em buffer e esse caminho não é aceito na varredura compartilhada
- `openai` porque a faixa compartilhada atual não garante acesso específico da organização a inpaint/remix de vídeo
@@ -561,38 +583,38 @@ Se você quiser depender de chaves em env (por exemplo, exportadas no seu `~/.pr
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
- Comportamento opcional de autenticação:
- - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfis e ignorar overrides somente de env
+ - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação pelo armazenamento de perfis e ignorar substituições somente por ambiente
## Harness live de mídia
- Comando: `pnpm test:live:media`
-- Finalidade:
+- Objetivo:
- Executa as suítes live compartilhadas de imagem, música e vídeo por um único entrypoint nativo do repositório
- Carrega automaticamente variáveis de ambiente de provedor ausentes de `~/.profile`
- - Restringe automaticamente por padrão cada suíte aos provedores que atualmente têm autenticação utilizável
- - Reutiliza `scripts/test-live.mjs`, para que heartbeat e comportamento de modo silencioso permaneçam consistentes
+ - Restringe automaticamente cada suíte por padrão aos provedores que atualmente têm autenticação utilizável
+ - Reutiliza `scripts/test-live.mjs`, para que o comportamento de heartbeat e modo silencioso permaneça consistente
- Exemplos:
- `pnpm test:live:media`
- `pnpm test:live:media image video --providers openai,google,minimax`
- `pnpm test:live:media video --video-providers openai,runway --all-providers`
- `pnpm test:live:media music --quiet`
-## Executores Docker (verificações opcionais de “funciona em Linux”)
+## Executores Docker (verificações opcionais de "funciona no Linux")
Esses executores Docker se dividem em dois grupos:
-- Executores de modelo live: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu respectivo arquivo live de chave de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de configuração e workspace (e usando `~/.profile` como source se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`.
-- Os executores Docker live usam por padrão um limite de smoke menor para que uma varredura Docker completa permaneça prática:
+- Executores de modelo live: `test:docker:live-models` e `test:docker:live-gateway` executam apenas seu arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório de configuração e workspace locais (e carregando `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`.
+- Os executores Docker live usam por padrão um limite de smoke menor para que uma varredura Docker completa continue prática:
`test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e
`test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`,
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`,
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e
- `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando
- quiser explicitamente a varredura exaustiva maior.
-- `test:docker:all` cria a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas Docker live.
-- Executores smoke de contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto.
+ `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando você
+ quiser explicitamente a varredura maior e exaustiva.
+- `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas Docker live.
+- Executores smoke em container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais containers reais e verificam caminhos de integração de nível superior.
-Os executores Docker de modelo live também fazem bind-mount apenas dos diretórios home de autenticação CLI necessários (ou de todos os suportados quando a execução não está restrita), depois os copiam para o home do contêiner antes da execução para que OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host:
+Os executores Docker de modelo live também fazem bind-mount apenas dos homes de autenticação de CLI necessários (ou de todos os compatíveis quando a execução não está restrita), depois os copiam para o home do container antes da execução para que OAuth de CLI externa possa renovar tokens sem alterar o armazenamento de autenticação do host:
- Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`)
- Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`)
@@ -600,161 +622,161 @@ Os executores Docker de modelo live também fazem bind-mount apenas dos diretór
- Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`)
- Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`)
- Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`)
-- Rede do gateway (dois contêineres, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`)
-- Ponte de canal MCP (Gateway preparado + ponte stdio + smoke bruto de frame de notificação Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`)
-- Plugins (smoke de instalação + alias `/plugin` + semântica de reinício de pacote Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`)
+- Rede do gateway (dois containers, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`)
+- Ponte de canal MCP (Gateway semeado + ponte stdio + smoke bruto de frame de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`)
+- Plugins (smoke de instalação + alias `/plugin` + semântica de reinício do bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`)
-Os executores Docker de modelo live também fazem bind-mount do checkout atual somente leitura e
-o preparam em um workdir temporário dentro do contêiner. Isso mantém a imagem de runtime
-enxuta, mas ainda executa o Vitest exatamente sobre seu código/configuração local.
-A etapa de preparação pula caches grandes apenas locais e saídas de build de apps, como
-`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de `.build` ou
-saída do Gradle, para que execuções live no Docker não passem minutos copiando
+Os executores Docker de modelo live também fazem bind-mount do checkout atual como somente leitura e
+o preparam em um workdir temporário dentro do container. Isso mantém a imagem de runtime
+enxuta, enquanto ainda executa o Vitest exatamente sobre seu código-fonte/configuração locais.
+A etapa de preparação ignora grandes caches apenas locais e saídas de build de apps, como
+`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais de saída `.build` ou
+Gradle, para que execuções live no Docker não passem minutos copiando
artefatos específicos da máquina.
-Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que as sondagens live do gateway não iniciem
-workers reais de canais Telegram/Discord/etc. dentro do contêiner.
-`test:docker:live-models` ainda executa `pnpm test:live`, então repasse
-`OPENCLAW_LIVE_GATEWAY_*` também quando precisar restringir ou excluir a cobertura live
-do gateway dessa faixa Docker.
-`test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um
-contêiner de gateway OpenClaw com endpoints HTTP compatíveis com OpenAI ativados,
-inicia um contêiner Open WebUI fixado contra esse gateway, faz login por meio
-do Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma
+Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que as sondas live do gateway não iniciem
+workers reais de canais Telegram/Discord/etc. dentro do container.
+`test:docker:live-models` ainda executa `pnpm test:live`, então também passe
+`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura
+live do gateway dessa faixa Docker.
+`test:docker:openwebui` é um smoke de compatibilidade de nível superior: ele inicia um
+container de gateway OpenClaw com endpoints HTTP compatíveis com OpenAI habilitados,
+inicia um container Open WebUI fixado contra esse gateway, faz login pelo
+Open WebUI, verifica que `/api/models` expõe `openclaw/default` e então envia uma
requisição real de chat pelo proxy `/api/chat/completions` do Open WebUI.
-A primeira execução pode ser perceptivelmente mais lenta porque o Docker pode precisar baixar a
-imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de cold-start.
+A primeira execução pode ser visivelmente mais lenta porque o Docker talvez precise baixar a
+imagem do Open WebUI e o Open WebUI talvez precise concluir sua própria configuração de cold start.
Essa faixa espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE`
-(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções Dockerizadas.
+(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções com Docker.
Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model":
"openclaw/default", ... }`.
`test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma
-conta real de Telegram, Discord ou iMessage. Ele inicializa um contêiner de Gateway
-preparado, inicia um segundo contêiner que sobe `openclaw mcp serve` e então
-verifica descoberta de conversa roteada, leituras de transcrição, metadados de attachment,
-comportamento da fila de eventos live, roteamento de envio de saída e notificações
-de canal + permissão no estilo Claude sobre a ponte stdio MCP real. A verificação de notificação
-inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a
-ponte realmente emite, não apenas o que uma SDK cliente específica por acaso expõe.
+conta real de Telegram, Discord ou iMessage. Ele inicializa um container de Gateway
+semeado, inicia um segundo container que executa `openclaw mcp serve` e então
+verifica descoberta de conversas roteadas, leituras de transcrição, metadados de anexos,
+comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal +
+permissão no estilo Claude pela ponte MCP stdio real. A verificação de notificação
+inspeciona diretamente os frames MCP stdio brutos para que o smoke valide o que a
+ponte realmente emite, não apenas o que um SDK de cliente específico por acaso expõe.
-Smoke manual de thread ACP em linguagem natural (não CI):
+Smoke manual de thread ACP em linguagem simples (não CI):
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...`
-- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua.
+- Mantenha esse script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua.
Variáveis de ambiente úteis:
- `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw`
- `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace`
-- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e usado como source antes de executar os testes
+- `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar os testes
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações de CLI em cache dentro do Docker
-- Diretórios/arquivos de autenticação de CLI externa sob `$HOME` são montados somente leitura sob `/host-auth...` e depois copiados para `/home/node/...` antes do início dos testes
+- Diretórios/arquivos de autenticação de CLI externa sob `$HOME` são montados como somente leitura em `/host-auth...` e depois copiados para `/home/node/...` antes do início dos testes
- Diretórios padrão: `.minimax`
- Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
- Execuções restritas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
- Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução
-- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner
-- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não de env)
+- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do container
+- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não do ambiente)
- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo gateway para o smoke do Open WebUI
- `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI
-- `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI
+- `OPENWEBUI_IMAGE=...` para substituir a tag fixada da imagem Open WebUI
## Sanidade da documentação
-Execute verificações de docs após edições em docs: `pnpm check:docs`.
-Execute a validação completa de âncoras do Mintlify quando também precisar verificar headings na própria página: `pnpm docs:check-links:anchors`.
+Execute verificações da documentação após edições na documentação: `pnpm check:docs`.
+Execute a validação completa de âncoras do Mintlify quando também precisar verificar headings na página: `pnpm docs:check-links:anchors`.
## Regressão offline (segura para CI)
Estas são regressões de “pipeline real” sem provedores reais:
-- Tool calling do gateway (OpenAI simulado, gateway real + loop do agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
-- Assistente do gateway (WS `wizard.start`/`wizard.next`, grava config + auth aplicado): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config")
+- Chamada de ferramentas do gateway (OpenAI simulado, gateway real + loop do agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
+- Assistente do gateway (WS `wizard.start`/`wizard.next`, grava configuração + autenticação aplicada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config")
## Avaliações de confiabilidade do agente (Skills)
Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade do agente”:
-- Tool-calling simulado pelo gateway real + loop do agente (`src/gateway/gateway.test.ts`).
-- Fluxos end-to-end do assistente que validam encadeamento de sessão e efeitos de configuração (`src/gateway/gateway.test.ts`).
+- Chamada simulada de ferramentas pelo gateway real + loop do agente (`src/gateway/gateway.test.ts`).
+- Fluxos end-to-end do assistente que validam wiring de sessão e efeitos de configuração (`src/gateway/gateway.test.ts`).
-O que ainda falta para Skills (consulte [Skills](/pt-BR/tools/skills)):
+O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)):
-- **Tomada de decisão:** quando as Skills são listadas no prompt, o agente escolhe a Skill certa (ou evita as irrelevantes)?
-- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args exigidos?
-- **Contratos de fluxo de trabalho:** cenários multi-turno que afirmam ordem de ferramentas, persistência do histórico da sessão e limites de sandbox.
+- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill certa (ou evita as irrelevantes)?
+- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args obrigatórios?
+- **Contratos de fluxo de trabalho:** cenários de múltiplos turnos que verifiquem ordem de ferramentas, continuidade do histórico da sessão e limites da sandbox.
Avaliações futuras devem permanecer determinísticas primeiro:
-- Um executor de cenários usando provedores simulados para afirmar chamadas de ferramenta + ordem, leituras de arquivo de Skill e encadeamento de sessão.
-- Uma pequena suíte de cenários focados em Skill (usar vs evitar, gating, prompt injection).
-- Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver implementada.
+- Um executor de cenários usando provedores simulados para verificar chamadas de ferramentas + ordem, leituras de arquivos de skill e wiring de sessão.
+- Uma pequena suíte de cenários focados em skill (usar vs evitar, gating, injeção de prompt).
+- Avaliações live opcionais (opt-in, controladas por env) somente depois que a suíte segura para CI estiver pronta.
-## Testes de contrato (forma de plugin e channel)
+## Testes de contrato (formato de plugin e canal)
-Os testes de contrato verificam que todo plugin e channel registrado está em conformidade com seu
+Os testes de contrato verificam que todo plugin e canal registrado está em conformidade com seu
contrato de interface. Eles iteram sobre todos os plugins descobertos e executam uma suíte de
-afirmações de forma e comportamento. A faixa unit padrão de `pnpm test` intencionalmente
-pula esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente
-quando tocar superfícies compartilhadas de channel ou provider.
+verificações de forma e comportamento. A faixa unit padrão de `pnpm test`
+intencionalmente ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente
+quando tocar em superfícies compartilhadas de canal ou provedor.
### Comandos
- Todos os contratos: `pnpm test:contracts`
-- Apenas contratos de channel: `pnpm test:contracts:channels`
-- Apenas contratos de provider: `pnpm test:contracts:plugins`
+- Apenas contratos de canal: `pnpm test:contracts:channels`
+- Apenas contratos de provedor: `pnpm test:contracts:plugins`
-### Contratos de channel
+### Contratos de canal
Localizados em `src/channels/plugins/contracts/*.contract.test.ts`:
-- **plugin** - Forma básica do plugin (id, name, capabilities)
+- **plugin** - Forma básica do plugin (id, nome, capacidades)
- **setup** - Contrato do assistente de configuração
- **session-binding** - Comportamento de vínculo de sessão
-- **outbound-payload** - Estrutura do payload de mensagem
-- **inbound** - Tratamento de mensagem de entrada
-- **actions** - Handlers de ação de channel
-- **threading** - Tratamento de ID de thread
+- **outbound-payload** - Estrutura de payload de mensagem
+- **inbound** - Manipulação de mensagem de entrada
+- **actions** - Manipuladores de ação do canal
+- **threading** - Manipulação de ID de thread
- **directory** - API de diretório/lista
- **group-policy** - Aplicação de política de grupo
-### Contratos de status do provider
+### Contratos de status de provedor
Localizados em `src/plugins/contracts/*.contract.test.ts`.
-- **status** - Sondagens de status de channel
+- **status** - Sondas de status de canal
- **registry** - Forma do registro de plugins
-### Contratos de provider
+### Contratos de provedor
Localizados em `src/plugins/contracts/*.contract.test.ts`:
-- **auth** - Contrato de fluxo de autenticação
+- **auth** - Contrato do fluxo de autenticação
- **auth-choice** - Escolha/seleção de autenticação
- **catalog** - API de catálogo de modelos
- **discovery** - Descoberta de plugin
- **loader** - Carregamento de plugin
-- **runtime** - Runtime do provider
+- **runtime** - Runtime do provedor
- **shape** - Forma/interface do plugin
- **wizard** - Assistente de configuração
### Quando executar
-- Após alterar exportações ou subpaths de plugin-sdk
-- Após adicionar ou modificar um plugin de channel ou provider
+- Após alterar exportações ou subcaminhos do plugin-sdk
+- Após adicionar ou modificar um plugin de canal ou provedor
- Após refatorar registro ou descoberta de plugins
-Os testes de contrato rodam em CI e não exigem chaves de API reais.
+Os testes de contrato rodam na CI e não requerem chaves reais de API.
## Adicionando regressões (orientação)
-Quando você corrige um problema de provider/model descoberto em live:
+Quando você corrige um problema de provedor/modelo descoberto em live:
-- Adicione uma regressão segura para CI, se possível (provider simulado/stub, ou capture a transformação exata do formato da requisição)
-- Se for inerentemente apenas live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in via variáveis de ambiente
-- Prefira mirar a menor camada que detecta o bug:
- - bug de conversão/replay de requisição do provider → teste de modelos diretos
- - bug de pipeline de sessão/histórico/ferramenta do gateway → smoke live do gateway ou teste simulado do gateway seguro para CI
+- Adicione uma regressão segura para CI, se possível (provedor simulado/stub, ou capture a transformação exata do formato da requisição)
+- Se for inerentemente só-live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in por variáveis de ambiente
+- Prefira direcionar a menor camada que detecta o bug:
+ - bug de conversão/replay de requisição do provedor → teste de modelos diretos
+ - bug do pipeline de sessão/histórico/ferramentas do gateway → smoke live do gateway ou teste simulado do gateway seguro para CI
- Guardrail de travessia de SecretRef:
- - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois afirma que ids de exec de segmento de travessia são rejeitados.
- - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não sejam puladas silenciosamente.
+ - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois verifica que ids exec de segmentos de travessia são rejeitados.
+ - Se você adicionar uma nova família de alvos SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente.
diff --git a/docs/pt-BR/reference/memory-config.md b/docs/pt-BR/reference/memory-config.md
index 34a5cea71..a8a0c1653 100644
--- a/docs/pt-BR/reference/memory-config.md
+++ b/docs/pt-BR/reference/memory-config.md
@@ -1,83 +1,94 @@
---
read_when:
- - Você quer configurar provedores de busca em memória ou modelos de embedding
+ - Você quer configurar provedores de pesquisa de memória ou modelos de embedding
- Você quer configurar o backend QMD
- - Você quer ajustar busca híbrida, MMR ou decaimento temporal
- - Você quer ativar indexação de memória multimodal
-summary: Todos os ajustes de configuração para busca em memória, provedores de embedding, QMD, busca híbrida e indexação multimodal
+ - Você quer ajustar a pesquisa híbrida, MMR ou o decaimento temporal
+ - Você quer habilitar a indexação de memória multimodal
+summary: Todos os parâmetros de configuração para pesquisa de memória, provedores de embedding, QMD, pesquisa híbrida e indexação multimodal
title: Referência de configuração de memória
x-i18n:
- generated_at: "2026-04-06T03:12:13Z"
+ generated_at: "2026-04-10T05:34:13Z"
model: gpt-5.4
provider: openai
- source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
+ source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
source_path: reference/memory-config.md
workflow: 15
---
# Referência de configuração de memória
-Esta página lista todos os ajustes de configuração para a busca em memória do OpenClaw. Para
-visões gerais conceituais, consulte:
+Esta página lista todos os parâmetros de configuração para a pesquisa de memória do OpenClaw. Para visões conceituais gerais, consulte:
- [Visão geral da memória](/pt-BR/concepts/memory) -- como a memória funciona
-- [Mecanismo builtin](/pt-BR/concepts/memory-builtin) -- backend SQLite padrão
+- [Mecanismo integrado](/pt-BR/concepts/memory-builtin) -- backend SQLite padrão
- [Mecanismo QMD](/pt-BR/concepts/memory-qmd) -- sidecar local-first
-- [Busca em memória](/pt-BR/concepts/memory-search) -- pipeline de busca e ajuste
+- [Pesquisa de memória](/pt-BR/concepts/memory-search) -- pipeline de pesquisa e ajuste
+- [Memória ativa](/pt-BR/concepts/active-memory) -- como habilitar o subagente de memória para sessões interativas
-Todas as configurações de busca em memória ficam em `agents.defaults.memorySearch` no
-`openclaw.json`, salvo indicação em contrário.
+Todas as configurações de pesquisa de memória ficam em `agents.defaults.memorySearch` no `openclaw.json`, salvo indicação em contrário.
+
+Se você estiver procurando a alternância de recurso de **memória ativa** e a configuração do subagente,
+ela fica em `plugins.entries.active-memory` em vez de `memorySearch`.
+
+A memória ativa usa um modelo de duas etapas:
+
+1. o plugin deve estar habilitado e apontar para o ID do agente atual
+2. a solicitação deve ser uma sessão de chat interativa persistente elegível
+
+Consulte [Memória ativa](/pt-BR/concepts/active-memory) para ver o modelo de ativação,
+a configuração pertencente ao plugin, a persistência de transcrição e o padrão de implantação segura.
---
## Seleção de provedor
-| Chave | Tipo | Padrão | Descrição |
-| ---------- | --------- | -------------- | --------------------------------------------------------------------------------------------- |
+| Chave | Tipo | Padrão | Descrição |
+| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------- |
| `provider` | `string` | detectado automaticamente | ID do adaptador de embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
-| `model` | `string` | padrão do provedor | Nome do modelo de embedding |
-| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o primário falha |
-| `enabled` | `boolean` | `true` | Ativa ou desativa a busca em memória |
+| `model` | `string` | padrão do provedor | Nome do modelo de embedding |
+| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o principal falha |
+| `enabled` | `boolean` | `true` | Habilita ou desabilita a pesquisa de memória |
### Ordem de detecção automática
-Quando `provider` não está definido, o OpenClaw seleciona o primeiro disponível:
+Quando `provider` não é definido, o OpenClaw seleciona o primeiro disponível:
1. `local` -- se `memorySearch.local.modelPath` estiver configurado e o arquivo existir.
2. `openai` -- se uma chave OpenAI puder ser resolvida.
3. `gemini` -- se uma chave Gemini puder ser resolvida.
4. `voyage` -- se uma chave Voyage puder ser resolvida.
5. `mistral` -- se uma chave Mistral puder ser resolvida.
-6. `bedrock` -- se a cadeia de credenciais do SDK da AWS puder ser resolvida (role de instância, chaves de acesso, profile, SSO, web identity ou configuração compartilhada).
+6. `bedrock` -- se a cadeia de credenciais padrão do AWS SDK for resolvida (função da instância, chaves de acesso, perfil, SSO, web identity ou configuração compartilhada).
`ollama` é compatível, mas não é detectado automaticamente (defina-o explicitamente).
### Resolução de chave de API
-Embeddings remotos exigem uma chave de API. O Bedrock usa a cadeia padrão de
-credenciais do SDK da AWS em vez disso (roles de instância, SSO, chaves de acesso).
+Embeddings remotos exigem uma chave de API. O Bedrock usa a cadeia de
+credenciais padrão do AWS SDK no lugar disso (funções de instância, SSO, chaves de acesso).
-| Provedor | Variável env | Chave de configuração |
-| -------- | ----------------------------- | ---------------------------------- |
-| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
-| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
-| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
-| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
-| Bedrock | cadeia de credenciais AWS | Nenhuma chave de API necessária |
-| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
+| Provedor | Variável de ambiente | Chave de configuração |
+| -------- | ----------------------------- | --------------------------------- |
+| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
+| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
+| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
+| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
+| Bedrock | cadeia de credenciais AWS | Nenhuma chave de API necessária |
+| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
-O OAuth do Codex cobre apenas chat/completions e não atende requisições de embedding.
+O OAuth do Codex cobre apenas chat/completions e não atende a solicitações
+de embedding.
---
## Configuração de endpoint remoto
-Para endpoints custom compatíveis com OpenAI ou para substituir padrões do provedor:
+Para endpoints compatíveis com OpenAI personalizados ou para substituir os padrões do provedor:
-| Chave | Tipo | Descrição |
-| ---------------- | -------- | --------------------------------------------------- |
-| `remote.baseUrl` | `string` | Base URL custom da API |
-| `remote.apiKey` | `string` | Substitui a chave de API |
+| Chave | Tipo | Descrição |
+| ---------------- | -------- | ------------------------------------------------- |
+| `remote.baseUrl` | `string` | URL base da API personalizada |
+| `remote.apiKey` | `string` | Substitui a chave de API |
| `remote.headers` | `object` | Cabeçalhos HTTP extras (mesclados com os padrões do provedor) |
```json5
@@ -101,21 +112,21 @@ Para endpoints custom compatíveis com OpenAI ou para substituir padrões do pro
## Configuração específica do Gemini
-| Chave | Tipo | Padrão | Descrição |
-| ---------------------- | -------- | ---------------------- | ------------------------------------------- |
-| `model` | `string` | `gemini-embedding-001` | Também oferece suporte a `gemini-embedding-2-preview` |
-| `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 ou 3072 |
+| Chave | Tipo | Padrão | Descrição |
+| ---------------------- | -------- | ---------------------- | -------------------------------------------- |
+| `model` | `string` | `gemini-embedding-001` | Também é compatível com `gemini-embedding-2-preview` |
+| `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 ou 3072 |
-Alterar `model` ou `outputDimensionality` dispara uma reindexação completa automática.
+Alterar o modelo ou `outputDimensionality` aciona automaticamente uma reindexação completa.
---
## Configuração de embedding do Bedrock
-O Bedrock usa a cadeia padrão de credenciais do SDK da AWS -- nenhuma chave de API é necessária.
-Se o OpenClaw estiver sendo executado no EC2 com uma role de instância habilitada para Bedrock, basta definir o
+O Bedrock usa a cadeia de credenciais padrão do AWS SDK -- nenhuma chave de API é necessária.
+Se o OpenClaw estiver em execução no EC2 com uma função de instância habilitada para Bedrock, basta definir o
provedor e o modelo:
```json5
@@ -131,35 +142,35 @@ provedor e o modelo:
}
```
-| Chave | Tipo | Padrão | Descrição |
-| ---------------------- | -------- | ------------------------------ | ---------------------------------- |
+| Chave | Tipo | Padrão | Descrição |
+| ---------------------- | -------- | ----------------------------- | ------------------------------------ |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualquer ID de modelo de embedding do Bedrock |
-| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
+| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
### Modelos compatíveis
-Os seguintes modelos são compatíveis (com detecção de família e dimensões
-padrão):
+Os modelos a seguir são compatíveis (com detecção de família e padrões de
+dimensão):
-| ID do modelo | Provedor | Dims padrão | Dims configuráveis |
-| ------------------------------------------- | ---------- | ----------- | --------------------- |
-| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
-| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
-| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
-| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
-| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
-| `cohere.embed-english-v3` | Cohere | 1024 | -- |
-| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
-| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
-| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
-| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
+| ID do modelo | Provedor | Dims padrão | Dims configuráveis |
+| ------------------------------------------ | ---------- | ----------- | -------------------- |
+| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
+| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
+| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
+| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
+| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
+| `cohere.embed-english-v3` | Cohere | 1024 | -- |
+| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
+| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
+| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
+| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
Variantes com sufixo de throughput (por exemplo, `amazon.titan-embed-text-v1:2:8k`) herdam
a configuração do modelo base.
### Autenticação
-A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do SDK da AWS:
+A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do AWS SDK:
1. Variáveis de ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
2. Cache de token SSO
@@ -167,12 +178,12 @@ A autenticação do Bedrock usa a ordem padrão de resolução de credenciais do
4. Arquivos compartilhados de credenciais e configuração
5. Credenciais de metadados ECS ou EC2
-A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, da
-`baseUrl` do provedor `amazon-bedrock` ou assume o padrão `us-east-1`.
+A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, do
+`baseUrl` do provedor `amazon-bedrock` ou, por padrão, `us-east-1`.
### Permissões IAM
-A role ou usuário IAM precisa de:
+A função ou o usuário IAM precisa de:
```json
{
@@ -182,7 +193,7 @@ A role ou usuário IAM precisa de:
}
```
-Para privilégio mínimo, limite `InvokeModel` ao modelo específico:
+Para privilégio mínimo, restrinja `InvokeModel` ao modelo específico:
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
@@ -198,33 +209,33 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
| `local.modelCacheDir` | `string` | padrão do node-llama-cpp | Diretório de cache para modelos baixados |
Modelo padrão: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, baixado automaticamente).
-Exige build nativa: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
+Exige build nativo: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
---
-## Configuração de busca híbrida
+## Configuração de pesquisa híbrida
Tudo em `memorySearch.query.hybrid`:
| Chave | Tipo | Padrão | Descrição |
| --------------------- | --------- | ------ | -------------------------------------- |
-| `enabled` | `boolean` | `true` | Ativa a busca híbrida BM25 + vetorial |
+| `enabled` | `boolean` | `true` | Habilita a pesquisa híbrida BM25 + vetorial |
| `vectorWeight` | `number` | `0.7` | Peso para pontuações vetoriais (0-1) |
| `textWeight` | `number` | `0.3` | Peso para pontuações BM25 (0-1) |
-| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do pool de candidatos |
+| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do conjunto de candidatos |
### MMR (diversidade)
| Chave | Tipo | Padrão | Descrição |
| ------------- | --------- | ------ | ---------------------------------------- |
-| `mmr.enabled` | `boolean` | `false` | Ativa reclassificação MMR |
+| `mmr.enabled` | `boolean` | `false` | Habilita a reclassificação MMR |
| `mmr.lambda` | `number` | `0.7` | 0 = diversidade máxima, 1 = relevância máxima |
### Decaimento temporal (recência)
-| Chave | Tipo | Padrão | Descrição |
-| ---------------------------- | --------- | ------ | --------------------------------- |
-| `temporalDecay.enabled` | `boolean` | `false` | Ativa impulso de recência |
+| Chave | Tipo | Padrão | Descrição |
+| ---------------------------- | --------- | ------ | ---------------------------------- |
+| `temporalDecay.enabled` | `boolean` | `false` | Habilita o impulso por recência |
| `temporalDecay.halfLifeDays` | `number` | `30` | A pontuação cai pela metade a cada N dias |
Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem decaimento.
@@ -254,8 +265,8 @@ Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem deca
## Caminhos de memória adicionais
-| Chave | Tipo | Descrição |
-| ------------ | ---------- | ----------------------------------------- |
+| Chave | Tipo | Descrição |
+| ----------- | ---------- | ------------------------------------------- |
| `extraPaths` | `string[]` | Diretórios ou arquivos adicionais para indexar |
```json5
@@ -271,18 +282,18 @@ Arquivos perenes (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem deca
```
Os caminhos podem ser absolutos ou relativos ao workspace. Diretórios são varridos
-recursivamente em busca de arquivos `.md`. O tratamento de symlink depende do backend ativo:
-o mecanismo builtin ignora symlinks, enquanto o QMD segue o comportamento subjacente
-do scanner do QMD.
+recursivamente em busca de arquivos `.md`. O tratamento de symlinks depende do backend ativo:
+o mecanismo integrado ignora symlinks, enquanto o QMD segue o comportamento do scanner
+QMD subjacente.
-Para busca de transcrições entre agentes com escopo de agente, use
+Para pesquisa de transcrições entre agentes com escopo por agente, use
`agents.list[].memorySearch.qmd.extraCollections` em vez de `memory.qmd.paths`.
Essas coleções extras seguem o mesmo formato `{ path, name, pattern? }`, mas
são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho
aponta para fora do workspace atual.
-Se o mesmo caminho resolvido aparecer em `memory.qmd.paths` e
+Se o mesmo caminho resolvido aparecer tanto em `memory.qmd.paths` quanto em
`memorySearch.qmd.extraCollections`, o QMD mantém a primeira entrada e ignora a
-duplicada.
+duplicata.
---
@@ -290,13 +301,13 @@ duplicada.
Indexe imagens e áudio junto com Markdown usando Gemini Embedding 2:
-| Chave | Tipo | Padrão | Descrição |
-| ------------------------- | ---------- | ---------- | ------------------------------------------ |
-| `multimodal.enabled` | `boolean` | `false` | Ativa indexação multimodal |
-| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
-| `multimodal.maxFileBytes` | `number` | `10000000` | Tamanho máximo de arquivo para indexação |
+| Chave | Tipo | Padrão | Descrição |
+| ------------------------- | ---------- | ---------- | -------------------------------------- |
+| `multimodal.enabled` | `boolean` | `false` | Habilita a indexação multimodal |
+| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
+| `multimodal.maxFileBytes` | `number` | `10000000` | Tamanho máximo de arquivo para indexação |
-Aplica-se apenas a arquivos em `extraPaths`. As raízes de memória padrão continuam apenas com Markdown.
+Aplica-se apenas a arquivos em `extraPaths`. As raízes de memória padrão continuam sendo somente Markdown.
Exige `gemini-embedding-2-preview`. `fallback` deve ser `"none"`.
Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
@@ -306,117 +317,117 @@ Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif
## Cache de embedding
-| Chave | Tipo | Padrão | Descrição |
-| ------------------ | --------- | ------ | ---------------------------------- |
-| `cache.enabled` | `boolean` | `false` | Armazena embeddings de chunks em cache no SQLite |
-| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
+| Chave | Tipo | Padrão | Descrição |
+| ------------------ | --------- | ------ | ------------------------------------ |
+| `cache.enabled` | `boolean` | `false` | Armazena em cache embeddings de chunks no SQLite |
+| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
-Evita refazer embeddings de texto inalterado durante reindexação ou atualizações de transcrição.
+Evita recalcular embeddings de texto inalterado durante reindexação ou atualizações de transcrição.
---
## Indexação em lote
-| Chave | Tipo | Padrão | Descrição |
-| ----------------------------- | --------- | ------ | --------------------------- |
-| `remote.batch.enabled` | `boolean` | `false` | Ativa API de embedding em lote |
-| `remote.batch.concurrency` | `number` | `2` | Trabalhos em lote paralelos |
-| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
-| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de polling |
-| `remote.batch.timeoutMinutes` | `number` | -- | Timeout do lote |
+| Chave | Tipo | Padrão | Descrição |
+| ----------------------------- | --------- | ------ | ------------------------------ |
+| `remote.batch.enabled` | `boolean` | `false` | Habilita a API de embedding em lote |
+| `remote.batch.concurrency` | `number` | `2` | Trabalhos em lote paralelos |
+| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
+| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de polling |
+| `remote.batch.timeoutMinutes` | `number` | -- | Tempo limite do lote |
-Disponível para `openai`, `gemini` e `voyage`. O lote do OpenAI normalmente é
-o mais rápido e barato para grandes preenchimentos retroativos.
+Disponível para `openai`, `gemini` e `voyage`. O lote do OpenAI geralmente é o
+mais rápido e barato para grandes preenchimentos retroativos.
---
-## Busca em memória de sessão (experimental)
+## Pesquisa de memória de sessão (experimental)
-Indexe transcrições de sessão e exponha-as via `memory_search`:
+Indexe transcrições de sessão e as exponha via `memory_search`:
-| Chave | Tipo | Padrão | Descrição |
-| --------------------------- | ---------- | ------------ | ------------------------------------------ |
-| `experimental.sessionMemory`| `boolean` | `false` | Ativa indexação de sessão |
-| `sources` | `string[]` | `["memory"]` | Adicione `"sessions"` para incluir transcrições |
-| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
-| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
+| Chave | Tipo | Padrão | Descrição |
+| ----------------------------- | ---------- | ------------ | ---------------------------------------- |
+| `experimental.sessionMemory` | `boolean` | `false` | Habilita a indexação de sessão |
+| `sources` | `string[]` | `["memory"]` | Adicione `"sessions"` para incluir transcrições |
+| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
+| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
-A indexação de sessão é opt-in e é executada de forma assíncrona. Os resultados podem estar
-ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos como o
-limite de confiança.
+A indexação de sessão é opt-in e é executada de forma assíncrona. Os resultados podem ficar
+ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos
+como o limite de confiança.
---
-## Aceleração vetorial SQLite (sqlite-vec)
+## Aceleração vetorial do SQLite (sqlite-vec)
-| Chave | Tipo | Padrão | Descrição |
-| ---------------------------- | --------- | ------- | ---------------------------------- |
-| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
-| `store.vector.extensionPath` | `string` | empacotado | Substitui o caminho do sqlite-vec |
+| Chave | Tipo | Padrão | Descrição |
+| -------------------------- | --------- | ------ | ------------------------------------- |
+| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
+| `store.vector.extensionPath` | `string` | bundled | Substitui o caminho do sqlite-vec |
Quando o sqlite-vec não está disponível, o OpenClaw recorre automaticamente à
similaridade de cosseno em processo.
---
-## Armazenamento do índice
+## Armazenamento de índice
-| Chave | Tipo | Padrão | Descrição |
-| ------------------- | -------- | ------------------------------------ | ---------------------------------------------- |
-| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Localização do índice (oferece suporte ao token `{agentId}`) |
-| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` ou `trigram`) |
+| Chave | Tipo | Padrão | Descrição |
+| --------------------- | -------- | ------------------------------------ | --------------------------------------------- |
+| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Local do índice (compatível com o token `{agentId}`) |
+| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` ou `trigram`) |
---
## Configuração do backend QMD
-Defina `memory.backend = "qmd"` para ativar. Todas as configurações do QMD ficam em
+Defina `memory.backend = "qmd"` para habilitar. Todas as configurações de QMD ficam em
`memory.qmd`:
-| Chave | Tipo | Padrão | Descrição |
-| ------------------------ | --------- | -------- | -------------------------------------------- |
-| `command` | `string` | `qmd` | Caminho do executável QMD |
-| `searchMode` | `string` | `search` | Comando de busca: `search`, `vsearch`, `query` |
+| Chave | Tipo | Padrão | Descrição |
+| ------------------------ | --------- | -------- | ---------------------------------------------- |
+| `command` | `string` | `qmd` | Caminho do executável do QMD |
+| `searchMode` | `string` | `search` | Comando de pesquisa: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | Indexa automaticamente `MEMORY.md` + `memory/**/*.md` |
-| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
-| `sessions.enabled` | `boolean` | `false` | Indexa transcrições de sessão |
-| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
-| `sessions.exportDir` | `string` | -- | Diretório de exportação |
+| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
+| `sessions.enabled` | `boolean` | `false` | Indexa transcrições de sessão |
+| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
+| `sessions.exportDir` | `string` | -- | Diretório de exportação |
-O OpenClaw prefere os formatos atuais de coleção do QMD e de consulta MCP, mas mantém
-releases mais antigos do QMD funcionando ao recorrer às flags legadas de coleção `--mask`
-e a nomes antigos de ferramentas MCP quando necessário.
+O OpenClaw prefere os formatos atuais de coleção QMD e de consulta MCP, mas mantém
+lançamentos mais antigos do QMD funcionando ao recorrer a flags legadas de coleção `--mask`
+e nomes mais antigos de ferramentas MCP quando necessário.
-As substituições de modelo do QMD ficam do lado do QMD, não na configuração do OpenClaw. Se você precisar
+As substituições de modelo do QMD ficam no lado do QMD, não na configuração do OpenClaw. Se você precisar
substituir os modelos do QMD globalmente, defina variáveis de ambiente como
-`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de
-runtime do gateway.
+`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de execução
+do gateway.
-### Agenda de atualização
+### Agendamento de atualização
-| Chave | Tipo | Padrão | Descrição |
-| ------------------------- | --------- | ------- | ---------------------------------------- |
-| `update.interval` | `string` | `5m` | Intervalo de atualização |
-| `update.debounceMs` | `number` | `15000` | Debounce de alterações de arquivo |
-| `update.onBoot` | `boolean` | `true` | Atualiza na inicialização |
-| `update.waitForBootSync` | `boolean` | `false` | Bloqueia a inicialização até a atualização terminar |
-| `update.embedInterval` | `string` | -- | Cadência separada de embeddings |
-| `update.commandTimeoutMs` | `number` | -- | Timeout para comandos QMD |
-| `update.updateTimeoutMs` | `number` | -- | Timeout para operações `qmd update` |
-| `update.embedTimeoutMs` | `number` | -- | Timeout para operações `qmd embed` |
+| Chave | Tipo | Padrão | Descrição |
+| ------------------------- | --------- | ------ | ----------------------------------------- |
+| `update.interval` | `string` | `5m` | Intervalo de atualização |
+| `update.debounceMs` | `number` | `15000` | Debounce para alterações de arquivos |
+| `update.onBoot` | `boolean` | `true` | Atualiza na inicialização |
+| `update.waitForBootSync` | `boolean` | `false` | Bloqueia a inicialização até a atualização ser concluída |
+| `update.embedInterval` | `string` | -- | Cadência separada para embeddings |
+| `update.commandTimeoutMs` | `number` | -- | Tempo limite para comandos QMD |
+| `update.updateTimeoutMs` | `number` | -- | Tempo limite para operações de atualização do QMD |
+| `update.embedTimeoutMs` | `number` | -- | Tempo limite para operações de embedding do QMD |
### Limites
-| Chave | Tipo | Padrão | Descrição |
-| ------------------------- | -------- | ------ | ------------------------------- |
-| `limits.maxResults` | `number` | `6` | Máximo de resultados de busca |
-| `limits.maxSnippetChars` | `number` | -- | Limita o tamanho do trecho |
-| `limits.maxInjectedChars` | `number` | -- | Limita o total de caracteres injetados |
-| `limits.timeoutMs` | `number` | `4000` | Timeout da busca |
+| Chave | Tipo | Padrão | Descrição |
+| ----------------------- | -------- | ------ | ----------------------------------- |
+| `limits.maxResults` | `number` | `6` | Máximo de resultados de pesquisa |
+| `limits.maxSnippetChars`| `number` | -- | Limita o tamanho do trecho |
+| `limits.maxInjectedChars` | `number` | -- | Limita o total de caracteres injetados |
+| `limits.timeoutMs` | `number` | `4000` | Tempo limite de pesquisa |
### Escopo
-Controla quais sessões podem receber resultados de busca do QMD. Mesmo schema de
+Controla quais sessões podem receber resultados de pesquisa do QMD. Mesmo esquema de
[`session.sendPolicy`](/pt-BR/gateway/configuration-reference#session):
```json5
@@ -432,17 +443,17 @@ Controla quais sessões podem receber resultados de busca do QMD. Mesmo schema d
}
```
-O padrão é apenas DM. `match.keyPrefix` corresponde à chave de sessão normalizada;
-`match.rawKeyPrefix` corresponde à chave bruta incluindo `agent::`.
+O padrão é somente DM. `match.keyPrefix` corresponde à chave de sessão normalizada;
+`match.rawKeyPrefix` corresponde à chave bruta, incluindo `agent::`.
### Citações
-`memory.citations` aplica-se a todos os backends:
+`memory.citations` se aplica a todos os backends:
-| Valor | Comportamento |
-| ---------------- | ----------------------------------------------------- |
-| `auto` (padrão) | Inclui rodapé `Source: ` nos trechos |
-| `on` | Sempre inclui o rodapé |
+| Valor | Comportamento |
+| ---------------- | ------------------------------------------------- |
+| `auto` (padrão) | Inclui o rodapé `Source: ` nos trechos |
+| `on` | Sempre inclui o rodapé |
| `off` | Omite o rodapé (o caminho ainda é passado internamente ao agente) |
### Exemplo completo de QMD
@@ -470,20 +481,20 @@ O padrão é apenas DM. `match.keyPrefix` corresponde à chave de sessão normal
## Dreaming (experimental)
-Dreaming é configurado em `plugins.entries.memory-core.config.dreaming`,
+O Dreaming é configurado em `plugins.entries.memory-core.config.dreaming`,
não em `agents.defaults.memorySearch`.
O Dreaming é executado como uma única varredura agendada e usa fases internas light/deep/REM como
-detalhe de implementação.
+um detalhe de implementação.
-Para comportamento conceitual e comandos slash, consulte [Dreaming](/concepts/dreaming).
+Para comportamento conceitual e comandos de barra, consulte [Dreaming](/pt-BR/concepts/dreaming).
### Configurações do usuário
-| Chave | Tipo | Padrão | Descrição |
-| ----------- | --------- | ----------- | ---------------------------------------------- |
-| `enabled` | `boolean` | `false` | Ativa ou desativa totalmente o dreaming |
-| `frequency` | `string` | `0 3 * * *` | Cadência cron opcional para a varredura completa de dreaming |
+| Chave | Tipo | Padrão | Descrição |
+| ----------- | --------- | ----------- | ------------------------------------------------ |
+| `enabled` | `boolean` | `false` | Habilita ou desabilita completamente o Dreaming |
+| `frequency` | `string` | `0 3 * * *` | Cadência cron opcional para a varredura completa do Dreaming |
### Exemplo
@@ -507,5 +518,5 @@ Para comportamento conceitual e comandos slash, consulte [Dreaming](/concepts/dr
Observações:
- O Dreaming grava o estado da máquina em `memory/.dreams/`.
-- O Dreaming grava a saída narrativa legível por humanos em `DREAMS.md` (ou em um `dreams.md` existente).
-- A política e os limites das fases light/deep/REM são comportamento interno, não configuração voltada ao usuário.
+- O Dreaming grava saída narrativa legível por humanos em `DREAMS.md` (ou no `dreams.md` existente).
+- A política de fases light/deep/REM e os limites são comportamentos internos, não configurações voltadas ao usuário.
diff --git a/docs/pt-BR/tools/browser.md b/docs/pt-BR/tools/browser.md
index 9fac400b5..1c7c86864 100644
--- a/docs/pt-BR/tools/browser.md
+++ b/docs/pt-BR/tools/browser.md
@@ -1,15 +1,15 @@
---
read_when:
- - Adicionando automação de navegador controlada pelo agente
+ - Adicionando automação do navegador controlada pelo agente
- Depurando por que o openclaw está interferindo no seu próprio Chrome
- - Implementando configurações + ciclo de vida do navegador no app macOS
-summary: Serviço integrado de controle de navegador + comandos de ação
+ - Implementando configurações e ciclo de vida do navegador no app para macOS
+summary: Serviço integrado de controle do navegador + comandos de ação
title: Navegador (gerenciado pelo OpenClaw)
x-i18n:
- generated_at: "2026-04-05T12:55:29Z"
+ generated_at: "2026-04-10T05:34:15Z"
model: gpt-5.4
provider: openai
- source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
+ source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
source_path: tools/browser.md
workflow: 15
---
@@ -18,24 +18,24 @@ x-i18n:
O OpenClaw pode executar um **perfil dedicado de Chrome/Brave/Edge/Chromium** que o agente controla.
Ele é isolado do seu navegador pessoal e é gerenciado por meio de um pequeno
-serviço local de controle dentro do Gateway (somente loopback).
+serviço local de controle dentro do Gateway (apenas loopback).
Visão para iniciantes:
-- Pense nele como um **navegador separado, só para o agente**.
-- O perfil `openclaw` **não** toca no seu perfil pessoal do navegador.
-- O agente pode **abrir abas, ler páginas, clicar e digitar** em uma faixa segura.
-- O perfil `user` integrado se conecta à sua sessão real do Chrome já autenticada via Chrome MCP.
+- Pense nele como um **navegador separado, apenas para o agente**.
+- O perfil `openclaw` **não** toca no perfil do seu navegador pessoal.
+- O agente pode **abrir abas, ler páginas, clicar e digitar** em um ambiente seguro.
+- O perfil integrado `user` se conecta à sua sessão real do Chrome autenticada por meio do Chrome MCP.
## O que você recebe
-- Um perfil de navegador separado chamado **openclaw** (com destaque laranja por padrão).
+- Um perfil de navegador separado chamado **openclaw** (destaque laranja por padrão).
- Controle determinístico de abas (listar/abrir/focar/fechar).
-- Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela, PDFs.
+- Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela e PDFs.
- Suporte opcional a vários perfis (`openclaw`, `work`, `remote`, ...).
-Este navegador **não** é o seu navegador do dia a dia. É uma superfície segura e isolada para
-automação e verificação por agente.
+Este navegador **não** é o que você usa no dia a dia. Ele é uma superfície segura e isolada para
+automação e verificação pelo agente.
## Início rápido
@@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
-Se aparecer “Browser disabled”, habilite-o na configuração (veja abaixo) e reinicie o
+Se você receber “Navegador desativado”, ative-o na configuração (veja abaixo) e reinicie o
Gateway.
-Se `openclaw browser` estiver completamente ausente, ou se o agente disser que a ferramenta de navegador
-está indisponível, vá para [Missing browser command or tool](/tools/browser#missing-browser-command-or-tool).
+Se `openclaw browser` estiver totalmente ausente, ou se o agente disser que a ferramenta de navegador
+não está disponível, vá para [Comando ou ferramenta de navegador ausente](/pt-BR/tools/browser#missing-browser-command-or-tool).
## Controle por plugin
-A ferramenta padrão `browser` agora é um plugin empacotado que já vem habilitado por
-padrão. Isso significa que você pode desativá-lo ou substituí-lo sem remover o restante do
+A ferramenta `browser` padrão agora é um plugin integrado que é distribuído ativado por
+padrão. Isso significa que você pode desativá-la ou substituí-la sem remover o restante do
sistema de plugins do OpenClaw:
```json5
@@ -70,33 +70,33 @@ sistema de plugins do OpenClaw:
}
```
-Desative o plugin empacotado antes de instalar outro plugin que ofereça o
-mesmo nome de ferramenta `browser`. A experiência padrão de navegador precisa de ambos:
+Desative o plugin integrado antes de instalar outro plugin que forneça o
+mesmo nome de ferramenta `browser`. A experiência padrão do navegador precisa de ambos:
-- `plugins.entries.browser.enabled` não desabilitado
+- `plugins.entries.browser.enabled` não desativado
- `browser.enabled=true`
-Se você desativar apenas o plugin, a CLI de navegador empacotada (`openclaw browser`),
-o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle
-do navegador desaparecem juntos. Sua configuração `browser.*` permanece intacta para que um
+Se você desativar apenas o plugin, a CLI de navegador integrada (`openclaw browser`),
+o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle do navegador
+desaparecem juntos. Sua configuração `browser.*` permanece intacta para que um
plugin substituto a reutilize.
-O plugin empacotado de navegador agora também é dono da implementação de runtime do navegador.
-O núcleo mantém apenas helpers compartilhados do Plugin SDK mais reexports de compatibilidade para
-caminhos internos antigos de importação. Na prática, remover ou substituir o pacote do plugin de navegador
-remove o conjunto de recursos do navegador em vez de deixar um segundo runtime
-pertencente ao núcleo.
+O plugin integrado do navegador também agora é responsável pela implementação de runtime do navegador.
+O núcleo mantém apenas auxiliares compartilhados do Plugin SDK, além de reexports de compatibilidade para
+caminhos de importação internos mais antigos. Na prática, remover ou substituir o pacote do plugin do navegador
+remove o conjunto de recursos do navegador, em vez de deixar um segundo runtime de propriedade do
+núcleo para trás.
-Alterações na configuração do navegador ainda exigem reinício do Gateway para que o plugin empacotado
+Alterações na configuração do navegador ainda exigem reiniciar o Gateway para que o plugin integrado
possa registrar novamente seu serviço de navegador com as novas configurações.
## Comando ou ferramenta de navegador ausente
-Se `openclaw browser` de repente virar um comando desconhecido após uma atualização, ou
-se o agente relatar que a ferramenta de navegador está ausente, a causa mais comum é uma
-lista restritiva `plugins.allow` que não inclui `browser`.
+Se `openclaw browser` de repente se tornar um comando desconhecido após uma atualização, ou
+se o agente informar que a ferramenta de navegador está ausente, a causa mais comum é uma
+lista restritiva em `plugins.allow` que não inclui `browser`.
-Exemplo de configuração quebrada:
+Exemplo de configuração com problema:
```json5
{
@@ -106,7 +106,7 @@ Exemplo de configuração quebrada:
}
```
-Corrija adicionando `browser` à allowlist de plugins:
+Corrija adicionando `browser` à lista de permissões de plugins:
```json5
{
@@ -116,30 +116,30 @@ Corrija adicionando `browser` à allowlist de plugins:
}
```
-Observações importantes:
+Notas importantes:
-- `browser.enabled=true` não basta sozinho quando `plugins.allow` está definido.
-- `plugins.entries.browser.enabled=true` também não basta sozinho quando `plugins.allow` está definido.
-- `tools.alsoAllow: ["browser"]` **não** carrega o plugin empacotado de navegador. Apenas ajusta a política de ferramentas depois que o plugin já foi carregado.
-- Se você não precisa de uma allowlist restritiva de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador empacotado.
+- `browser.enabled=true` não é suficiente por si só quando `plugins.allow` está definido.
+- `plugins.entries.browser.enabled=true` também não é suficiente por si só quando `plugins.allow` está definido.
+- `tools.alsoAllow: ["browser"]` **não** carrega o plugin integrado do navegador. Ele apenas ajusta a política da ferramenta depois que o plugin já foi carregado.
+- Se você não precisa de uma lista restritiva de permissões de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador integrado.
Sintomas típicos:
- `openclaw browser` é um comando desconhecido.
- `browser.request` está ausente.
-- O agente relata a ferramenta de navegador como indisponível ou ausente.
+- O agente informa que a ferramenta de navegador está indisponível ou ausente.
## Perfis: `openclaw` vs `user`
-- `openclaw`: navegador gerenciado e isolado (não requer extensão).
-- `user`: perfil embutido de conexão Chrome MCP para sua **sessão real do Chrome já autenticada**.
+- `openclaw`: navegador gerenciado e isolado (nenhuma extensão necessária).
+- `user`: perfil integrado de conexão via Chrome MCP para sua **sessão real do Chrome autenticada**.
-Para chamadas da ferramenta de navegador pelo agente:
+Para chamadas da ferramenta de navegador do agente:
- Padrão: use o navegador isolado `openclaw`.
-- Prefira `profile="user"` quando sessões já autenticadas existentes importarem e o usuário
+- Prefira `profile="user"` quando sessões autenticadas já existentes importarem e o usuário
estiver no computador para clicar/aprovar qualquer prompt de conexão.
-- `profile` é o override explícito quando você quer um modo específico de navegador.
+- `profile` é a substituição explícita quando você quer um modo de navegador específico.
Defina `browser.defaultProfile: "openclaw"` se quiser o modo gerenciado por padrão.
@@ -152,14 +152,14 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
browser: {
enabled: true, // padrão: true
ssrfPolicy: {
- dangerouslyAllowPrivateNetwork: true, // modo padrão de rede confiável
+ dangerouslyAllowPrivateNetwork: true, // modo trusted-network padrão
// allowPrivateNetwork: true, // alias legado
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
- // cdpUrl: "http://127.0.0.1:18792", // override legado de perfil único
- remoteCdpTimeoutMs: 1500, // timeout HTTP remoto do CDP (ms)
- remoteCdpHandshakeTimeoutMs: 3000, // timeout do handshake WebSocket remoto do CDP (ms)
+ // cdpUrl: "http://127.0.0.1:18792", // substituição legada de perfil único
+ remoteCdpTimeoutMs: 1500, // tempo limite de HTTP do CDP remoto (ms)
+ remoteCdpHandshakeTimeoutMs: 3000, // tempo limite do handshake WebSocket do CDP remoto (ms)
defaultProfile: "openclaw",
color: "#FF4500",
headless: false,
@@ -186,36 +186,36 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`.
}
```
-Observações:
+Notas:
-- O serviço de controle do navegador faz bind em loopback em uma porta derivada de `gateway.port`
+- O serviço de controle do navegador se vincula ao loopback em uma porta derivada de `gateway.port`
(padrão: `18791`, que é gateway + 2).
-- Se você sobrescrever a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
+- Se você substituir a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`),
as portas derivadas do navegador mudam para permanecer na mesma “família”.
-- `cdpUrl` assume por padrão a porta CDP local gerenciada quando não definido.
-- `remoteCdpTimeoutMs` se aplica a verificações de alcance de CDP remoto (não loopback).
+- `cdpUrl` usa por padrão a porta CDP local gerenciada quando não está definido.
+- `remoteCdpTimeoutMs` se aplica a verificações de alcance do CDP remoto (não loopback).
- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcance do handshake WebSocket do CDP remoto.
-- Navegação/abertura de aba no navegador é protegida contra SSRF antes da navegação e verificada novamente, no melhor esforço, na URL final `http(s)` após a navegação.
-- No modo estrito de SSRF, descoberta/sondas de endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também são verificadas.
-- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tem padrão `true` (modelo de rede confiável). Defina como `false` para navegação pública estrita.
-- `browser.ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado para compatibilidade.
-- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução.”
-- `color` + `color` por perfil tingem a UI do navegador para que você veja qual perfil está ativo.
+- A navegação/abertura de aba do navegador é protegida contra SSRF antes da navegação e verificada novamente, no melhor esforço, na URL final `http(s)` após a navegação.
+- No modo SSRF estrito, a descoberta/sondagem de endpoints CDP remotos (`cdpUrl`, incluindo buscas em `/json/version`) também é verificada.
+- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa `true` por padrão (modelo de rede confiável). Defina como `false` para navegação estrita apenas pública.
+- `browser.ssrfPolicy.allowPrivateNetwork` continua com suporte como alias legado por compatibilidade.
+- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução”.
+- `color` + `color` por perfil tingem a interface do navegador para que você possa ver qual perfil está ativo.
- O perfil padrão é `openclaw` (navegador independente gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador autenticado do usuário.
- Ordem de autodetecção: navegador padrão do sistema se for baseado em Chromium; caso contrário Chrome → Brave → Edge → Chromium → Chrome Canary.
-- Perfis locais `openclaw` atribuem automaticamente `cdpPort`/`cdpUrl` — defina-os apenas para CDP remoto.
+- Perfis `openclaw` locais atribuem automaticamente `cdpPort`/`cdpUrl` — defina esses valores apenas para CDP remoto.
- `driver: "existing-session"` usa Chrome DevTools MCP em vez de CDP bruto. Não
defina `cdpUrl` para esse driver.
- Defina `browser.profiles..userDataDir` quando um perfil existing-session
deve se conectar a um perfil de usuário Chromium não padrão, como Brave ou Edge.
-## Use Brave (ou outro navegador baseado em Chromium)
+## Usar Brave (ou outro navegador baseado em Chromium)
Se o seu navegador **padrão do sistema** for baseado em Chromium (Chrome/Brave/Edge/etc),
-o OpenClaw o usa automaticamente. Defina `browser.executablePath` para sobrescrever a
+o OpenClaw o usa automaticamente. Defina `browser.executablePath` para substituir a
autodetecção:
-Exemplo via CLI:
+Exemplo na CLI:
```bash
openclaw config set browser.executablePath "/usr/bin/google-chrome"
@@ -247,48 +247,48 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
## Controle local vs remoto
- **Controle local (padrão):** o Gateway inicia o serviço de controle em loopback e pode iniciar um navegador local.
-- **Controle remoto (node host):** execute um node host na máquina que tem o navegador; o Gateway faz proxy das ações do navegador para ele.
+- **Controle remoto (host de nó):** execute um host de nó na máquina que tem o navegador; o Gateway encaminha as ações do navegador para ele.
- **CDP remoto:** defina `browser.profiles..cdpUrl` (ou `browser.cdpUrl`) para
se conectar a um navegador remoto baseado em Chromium. Nesse caso, o OpenClaw não iniciará um navegador local.
-O comportamento ao parar difere por modo de perfil:
+O comportamento de parada difere por modo de perfil:
-- perfis gerenciados locais: `openclaw browser stop` para o processo do navegador que
+- perfis locais gerenciados: `openclaw browser stop` interrompe o processo do navegador que
o OpenClaw iniciou
-- perfis attach-only e CDP remoto: `openclaw browser stop` fecha a sessão ativa de
- controle e libera overrides de emulação Playwright/CDP (viewport,
+- perfis somente de conexão e CDP remoto: `openclaw browser stop` fecha a sessão de controle ativa
+ e libera as substituições de emulação do Playwright/CDP (viewport,
esquema de cores, localidade, fuso horário, modo offline e estado semelhante), mesmo
que nenhum processo de navegador tenha sido iniciado pelo OpenClaw
-URLs CDP remotas podem incluir autenticação:
+URLs de CDP remoto podem incluir autenticação:
-- Tokens em query (por exemplo, `https://provider.example?token=`)
+- Tokens de query (por exemplo, `https://provider.example?token=`)
- Autenticação HTTP Basic (por exemplo, `https://user:pass@provider.example`)
O OpenClaw preserva a autenticação ao chamar endpoints `/json/*` e ao se conectar
-ao WebSocket CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para
-tokens em vez de gravá-los em arquivos de configuração.
+ao WebSocket do CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para
+tokens em vez de confirmá-los em arquivos de configuração.
-## Proxy de navegador por node (padrão zero-config)
+## Proxy de navegador do nó (padrão sem configuração)
-Se você executar um **node host** na máquina que tem seu navegador, o OpenClaw pode
-rotear automaticamente chamadas da ferramenta de navegador para esse node sem nenhuma configuração extra de navegador.
-Esse é o caminho padrão para gateways remotos.
+Se você executar um **host de nó** na máquina que tem o navegador, o OpenClaw pode
+rotear automaticamente chamadas da ferramenta de navegador para esse nó sem nenhuma configuração extra de navegador.
+Este é o caminho padrão para gateways remotos.
-Observações:
+Notas:
-- O node host expõe seu servidor local de controle de navegador por meio de um **comando proxy**.
-- Os perfis vêm da própria configuração `browser.profiles` do node (igual ao local).
-- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados continuam acessíveis pelo proxy, incluindo rotas de criação/exclusão de perfil.
-- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw o trata como um limite de menor privilégio: apenas perfis na allowlist podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy.
+- O host de nó expõe seu servidor local de controle de navegador por meio de um **comando proxy**.
+- Os perfis vêm da própria configuração `browser.profiles` do nó (igual à local).
+- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados permanecem acessíveis por meio do proxy, incluindo rotas de criação/exclusão de perfil.
+- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw trata isso como um limite de menor privilégio: apenas perfis na lista de permissões podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy.
- Desative se não quiser isso:
- - No node: `nodeHost.browserProxy.enabled=false`
+ - No nó: `nodeHost.browserProxy.enabled=false`
- No gateway: `gateway.nodes.browser.mode="off"`
## Browserless (CDP remoto hospedado)
-[Browserless](https://browserless.io) é um serviço Chromium hospedado que expõe
-URLs de conexão CDP por HTTPS e WebSocket. O OpenClaw pode usar qualquer formato, mas
+[Browserless](https://browserless.io) é um serviço hospedado de Chromium que expõe
+URLs de conexão CDP por HTTPS e WebSocket. O OpenClaw pode usar qualquer uma das formas, mas
para um perfil de navegador remoto a opção mais simples é a URL WebSocket direta
da documentação de conexão do Browserless.
@@ -311,21 +311,21 @@ Exemplo:
}
```
-Observações:
+Notas:
- Substitua `` pelo seu token real do Browserless.
-- Escolha o endpoint de região que corresponda à sua conta Browserless (veja a documentação deles).
+- Escolha o endpoint de região que corresponda à sua conta do Browserless (veja a documentação deles).
- Se o Browserless fornecer uma URL base HTTPS, você pode convertê-la para
- `wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar que o OpenClaw
- descubra `/json/version`.
+ `wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar o OpenClaw
+ descobrir `/json/version`.
## Provedores CDP WebSocket diretos
-Alguns serviços de navegador hospedado expõem um endpoint **WebSocket direto** em vez de
-descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw suporta ambos:
+Alguns serviços hospedados de navegador expõem um endpoint **WebSocket direto** em vez da
+descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece suporte a ambos:
- **Endpoints HTTP(S)** — o OpenClaw chama `/json/version` para descobrir a
- URL WebSocket do depurador e então se conecta.
+ URL do depurador WebSocket e então se conecta.
- **Endpoints WebSocket** (`ws://` / `wss://`) — o OpenClaw se conecta diretamente,
ignorando `/json/version`. Use isso para serviços como
[Browserless](https://browserless.io),
@@ -335,7 +335,7 @@ descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw suporta amb
### Browserbase
[Browserbase](https://www.browserbase.com) é uma plataforma em nuvem para executar
-navegadores headless com resolução de CAPTCHA integrada, modo stealth e
+navegadores headless com resolução de CAPTCHA integrada, modo furtivo e
proxies residenciais.
```json5
@@ -355,59 +355,59 @@ proxies residenciais.
}
```
-Observações:
+Notas:
- [Cadastre-se](https://www.browserbase.com/sign-up) e copie sua **API Key**
- do [dashboard Overview](https://www.browserbase.com/overview).
-- Substitua `` pela sua chave de API real do Browserbase.
-- O Browserbase cria automaticamente uma sessão de navegador ao conectar o WebSocket, então
- não é necessária nenhuma etapa manual de criação de sessão.
-- O nível gratuito permite uma sessão concorrente e uma hora de navegador por mês.
- Consulte [pricing](https://www.browserbase.com/pricing) para limites dos planos pagos.
-- Consulte a [documentação do Browserbase](https://docs.browserbase.com) para a
+ do [painel Overview](https://www.browserbase.com/overview).
+- Substitua `` pela sua API key real do Browserbase.
+- O Browserbase cria automaticamente uma sessão de navegador na conexão WebSocket, portanto
+ nenhuma etapa manual de criação de sessão é necessária.
+- O plano gratuito permite uma sessão simultânea e uma hora de navegador por mês.
+ Veja os [preços](https://www.browserbase.com/pricing) para os limites dos planos pagos.
+- Veja a [documentação do Browserbase](https://docs.browserbase.com) para a
referência completa da API, guias de SDK e exemplos de integração.
## Segurança
Ideias principais:
-- O controle do navegador é somente loopback; o acesso flui pela autenticação do Gateway ou pelo pareamento do node.
-- A API HTTP independente de navegador em loopback usa **somente autenticação por segredo compartilhado**:
- autenticação bearer do token do gateway, `x-openclaw-password`, ou HTTP Basic auth com a
+- O controle do navegador é apenas por loopback; o acesso flui pela autenticação do Gateway ou pelo emparelhamento de nó.
+- A API HTTP independente do navegador em loopback usa **apenas autenticação por segredo compartilhado**:
+ bearer auth com token do gateway, `x-openclaw-password`, ou autenticação HTTP Basic com a
senha configurada do gateway.
- Cabeçalhos de identidade do Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **não**
- autenticam essa API independente de navegador em loopback.
-- Se o controle do navegador estiver habilitado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
+ autenticam esta API independente do navegador em loopback.
+- Se o controle do navegador estiver ativado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw
gera automaticamente `gateway.auth.token` na inicialização e o persiste na configuração.
-- O OpenClaw **não** gera automaticamente esse token quando `gateway.auth.mode` já for
+- O OpenClaw **não** gera automaticamente esse token quando `gateway.auth.mode` já é
`password`, `none` ou `trusted-proxy`.
-- Mantenha o Gateway e quaisquer node hosts em uma rede privada (Tailscale); evite exposição pública.
-- Trate URLs/tokens CDP remotos como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
+- Mantenha o Gateway e quaisquer hosts de nó em uma rede privada (Tailscale); evite exposição pública.
+- Trate URLs/tokens remotos de CDP como segredos; prefira variáveis de ambiente ou um gerenciador de segredos.
Dicas para CDP remoto:
-- Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração sempre que possível.
+- Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração quando possível.
- Evite incorporar tokens de longa duração diretamente em arquivos de configuração.
-## Perfis (múltiplos navegadores)
+## Perfis (vários navegadores)
O OpenClaw oferece suporte a vários perfis nomeados (configurações de roteamento). Os perfis podem ser:
- **gerenciados pelo openclaw**: uma instância dedicada de navegador baseado em Chromium com seu próprio diretório de dados de usuário + porta CDP
-- **remotos**: uma URL CDP explícita (navegador baseado em Chromium rodando em outro lugar)
-- **sessão existente**: seu perfil existente do Chrome por conexão automática do Chrome DevTools MCP
+- **remoto**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar)
+- **sessão existente**: seu perfil atual do Chrome via conexão automática do Chrome DevTools MCP
Padrões:
- O perfil `openclaw` é criado automaticamente se estiver ausente.
-- O perfil `user` é embutido para conexão existing-session do Chrome MCP.
-- Perfis existing-session são opt-in além do `user`; crie-os com `--driver existing-session`.
-- Portas CDP locais são alocadas por padrão em **18800–18899**.
+- O perfil `user` é integrado para conexão de sessão existente do Chrome MCP.
+- Perfis de sessão existente são opt-in além de `user`; crie-os com `--driver existing-session`.
+- As portas CDP locais são alocadas de **18800–18899** por padrão.
- Excluir um perfil move seu diretório de dados local para a Lixeira.
Todos os endpoints de controle aceitam `?profile=`; a CLI usa `--browser-profile`.
-## Existing-session via Chrome DevTools MCP
+## Sessão existente via Chrome DevTools MCP
O OpenClaw também pode se conectar a um perfil de navegador baseado em Chromium já em execução por meio do
servidor oficial Chrome DevTools MCP. Isso reutiliza as abas e o estado de login
@@ -418,19 +418,19 @@ Referências oficiais de contexto e configuração:
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
-Perfil embutido:
+Perfil integrado:
- `user`
-Opcional: crie seu próprio perfil existing-session personalizado se quiser um
-nome, cor ou diretório de dados do navegador diferentes.
+Opcional: crie seu próprio perfil personalizado de sessão existente se quiser um
+nome, cor ou diretório de dados do navegador diferente.
Comportamento padrão:
-- O perfil `user` embutido usa conexão automática Chrome MCP, que mira o
+- O perfil integrado `user` usa conexão automática do Chrome MCP, que mira o
perfil local padrão do Google Chrome.
-Use `userDataDir` para Brave, Edge, Chromium ou um perfil não padrão do Chrome:
+Use `userDataDir` para Brave, Edge, Chromium ou um perfil Chrome não padrão:
```json5
{
@@ -450,16 +450,16 @@ Use `userDataDir` para Brave, Edge, Chromium ou um perfil não padrão do Chrome
Então, no navegador correspondente:
1. Abra a página de inspeção desse navegador para depuração remota.
-2. Habilite a depuração remota.
+2. Ative a depuração remota.
3. Mantenha o navegador em execução e aprove o prompt de conexão quando o OpenClaw se conectar.
-Páginas de inspeção comuns:
+Páginas comuns de inspeção:
- Chrome: `chrome://inspect/#remote-debugging`
- Brave: `brave://inspect/#remote-debugging`
- Edge: `edge://inspect/#remote-debugging`
-Teste rápido de conexão ativa:
+Teste rápido de conexão ao vivo:
```bash
openclaw browser --browser-profile user start
@@ -473,63 +473,64 @@ Como é o sucesso:
- `status` mostra `driver: existing-session`
- `status` mostra `transport: chrome-mcp`
- `status` mostra `running: true`
-- `tabs` lista suas abas já abertas no navegador
+- `tabs` lista as abas do navegador que já estavam abertas
- `snapshot` retorna refs da aba ativa selecionada
O que verificar se a conexão não funcionar:
-- o navegador-alvo baseado em Chromium está na versão `144+`
-- a depuração remota está habilitada na página de inspeção desse navegador
-- o navegador mostrou e você aceitou o prompt de consentimento da conexão
-- `openclaw doctor` migra configuração antiga de navegador baseada em extensão e verifica se
- o Chrome está instalado localmente para perfis padrão de conexão automática, mas ele não consegue
- habilitar a depuração remota no lado do navegador para você
+- o navegador baseado em Chromium de destino está na versão `144+`
+- a depuração remota está ativada na página de inspeção desse navegador
+- o navegador exibiu o prompt de consentimento de conexão e você o aceitou
+- `openclaw doctor` migra a configuração antiga de navegador baseada em extensão e verifica se
+ o Chrome está instalado localmente para perfis padrão de conexão automática, mas não pode
+ ativar a depuração remota no lado do navegador para você
Uso pelo agente:
- Use `profile="user"` quando precisar do estado do navegador autenticado do usuário.
-- Se você usa um perfil existing-session personalizado, passe esse nome de perfil explícito.
-- Escolha esse modo apenas quando o usuário estiver no computador para aprovar o
+- Se você usa um perfil personalizado de sessão existente, passe esse nome de perfil explícito.
+- Só escolha esse modo quando o usuário estiver no computador para aprovar o
prompt de conexão.
-- o Gateway ou node host pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
+- o Gateway ou host de nó pode iniciar `npx chrome-devtools-mcp@latest --autoConnect`
-Observações:
+Notas:
-- Esse caminho é de risco mais alto do que o perfil isolado `openclaw`, porque ele pode
+- Esse caminho tem mais risco do que o perfil isolado `openclaw` porque pode
agir dentro da sua sessão autenticada do navegador.
- O OpenClaw não inicia o navegador para esse driver; ele se conecta apenas a uma
sessão existente.
- O OpenClaw usa aqui o fluxo oficial `--autoConnect` do Chrome DevTools MCP. Se
- `userDataDir` estiver definido, o OpenClaw o repassa para mirar esse diretório
- explícito de dados de usuário do Chromium.
-- Capturas de tela em existing-session suportam capturas da página e capturas de elemento com `--ref`
- a partir de snapshots, mas não seletores CSS `--element`.
-- Capturas de tela de página em existing-session funcionam sem Playwright via Chrome MCP.
+ `userDataDir` estiver definido, o OpenClaw o repassa para mirar esse diretório explícito
+ de dados de usuário Chromium.
+- Capturas de tela de sessão existente oferecem suporte a capturas de página e capturas de elemento com `--ref`
+ a partir de snapshots, mas não a seletores CSS `--element`.
+- Capturas de tela de página de sessão existente funcionam sem Playwright por meio do Chrome MCP.
Capturas de elemento baseadas em ref (`--ref`) também funcionam ali, mas `--full-page`
- não pode ser combinado com `--ref` nem com `--element`.
-- Ações em existing-session ainda são mais limitadas do que no caminho de navegador gerenciado:
+ não pode ser combinado com `--ref` ou `--element`.
+- Ações de sessão existente ainda são mais limitadas do que no caminho do navegador
+ gerenciado:
- `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` exigem
refs de snapshot em vez de seletores CSS
- - `click` é somente com botão esquerdo (sem overrides de botão ou modificadores)
- - `type` não suporta `slowly=true`; use `fill` ou `press`
- - `press` não suporta `delayMs`
+ - `click` é apenas com botão esquerdo (sem substituições de botão ou modificadores)
+ - `type` não oferece suporte a `slowly=true`; use `fill` ou `press`
+ - `press` não oferece suporte a `delayMs`
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` e `evaluate` não
- suportam overrides de timeout por chamada
- - `select` atualmente suporta apenas um único valor
-- Existing-session `wait --url` suporta padrões exatos, substring e glob
+ oferecem suporte a substituições de tempo limite por chamada
+ - `select` atualmente oferece suporte apenas a um único valor
+- `wait --url` para sessão existente oferece suporte a padrões exatos, de substring e glob
como outros drivers de navegador. `wait --load networkidle` ainda não é compatível.
-- Hooks de upload em existing-session exigem `ref` ou `inputRef`, suportam um arquivo
- por vez e não suportam direcionamento CSS `element`.
-- Hooks de diálogo em existing-session não suportam overrides de timeout.
-- Alguns recursos ainda exigem o caminho de navegador gerenciado, incluindo
- ações em lote, exportação de PDF, interceptação de download e `responsebody`.
-- Existing-session é local ao host. Se o Chrome estiver em outra máquina ou em outro
- namespace de rede, use CDP remoto ou um node host.
+- Hooks de upload em sessão existente exigem `ref` ou `inputRef`, oferecem suporte a um arquivo
+ por vez e não oferecem suporte ao direcionamento por `element` CSS.
+- Hooks de diálogo em sessão existente não oferecem suporte a substituições de tempo limite.
+- Alguns recursos ainda exigem o caminho de navegador gerenciado, incluindo ações em lote,
+ exportação em PDF, interceptação de download e `responsebody`.
+- Sessão existente é local ao host. Se o Chrome estiver em outra máquina ou em um
+ namespace de rede diferente, use CDP remoto ou um host de nó.
## Garantias de isolamento
-- **Diretório de dados de usuário dedicado**: nunca toca no seu perfil pessoal do navegador.
-- **Portas dedicadas**: evita `9222` para impedir colisões com fluxos de desenvolvimento.
+- **Diretório de dados de usuário dedicado**: nunca toca no perfil do seu navegador pessoal.
+- **Portas dedicadas**: evita `9222` para prevenir colisões com fluxos de trabalho de desenvolvimento.
- **Controle determinístico de abas**: mira abas por `targetId`, não pela “última aba”.
## Seleção do navegador
@@ -542,21 +543,21 @@ Ao iniciar localmente, o OpenClaw escolhe o primeiro disponível:
4. Chromium
5. Chrome Canary
-Você pode sobrescrever com `browser.executablePath`.
+Você pode substituir isso com `browser.executablePath`.
Plataformas:
- macOS: verifica `/Applications` e `~/Applications`.
-- Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium` etc.
+- Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium`, etc.
- Windows: verifica locais comuns de instalação.
## API de controle (opcional)
Apenas para integrações locais, o Gateway expõe uma pequena API HTTP em loopback:
-- Status/start/stop: `GET /`, `POST /start`, `POST /stop`
+- Status/iniciar/parar: `GET /`, `POST /start`, `POST /stop`
- Abas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
-- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot`
+- Snapshot/captura de tela: `GET /snapshot`, `POST /screenshot`
- Ações: `POST /navigate`, `POST /act`
- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog`
- Downloads: `POST /download`, `POST /wait/download`
@@ -569,21 +570,42 @@ Apenas para integrações locais, o Gateway expõe uma pequena API HTTP em loopb
Todos os endpoints aceitam `?profile=`.
-Se a autenticação por segredo compartilhado do gateway estiver configurada, as rotas HTTP do navegador também exigirão autenticação:
+Se a autenticação do gateway por segredo compartilhado estiver configurada, as rotas HTTP do navegador também exigirão autenticação:
- `Authorization: Bearer `
-- `x-openclaw-password: ` ou HTTP Basic auth com essa senha
+- `x-openclaw-password: ` ou autenticação HTTP Basic com essa senha
-Observações:
+Notas:
-- Esta API independente de navegador em loopback **não** consome cabeçalhos de identidade de trusted-proxy nem
- de Tailscale Serve.
-- Se `gateway.auth.mode` for `none` ou `trusted-proxy`, estas rotas de navegador em loopback
- não herdam esses modos com identidade; mantenha-as somente em loopback.
+- Esta API independente do navegador em loopback **não** consome cabeçalhos de identidade de trusted-proxy ou
+ Tailscale Serve.
+- Se `gateway.auth.mode` for `none` ou `trusted-proxy`, essas rotas de navegador em loopback
+ não herdam esses modos com identidade; mantenha-as apenas em loopback.
-### Exigência do Playwright
+### Contrato de erro de `/act`
-Alguns recursos (`navigate`/`act`/snapshot AI/role snapshot, screenshots de elemento,
+`POST /act` usa uma resposta de erro estruturada para validação no nível da rota e
+falhas de política:
+
+```json
+{ "error": "", "code": "ACT_*" }
+```
+
+Valores atuais de `code`:
+
+- `ACT_KIND_REQUIRED` (HTTP 400): `kind` está ausente ou não é reconhecido.
+- `ACT_INVALID_REQUEST` (HTTP 400): a carga da ação falhou na normalização ou validação.
+- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` foi usado com um tipo de ação não compatível.
+- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desativado por configuração.
+- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nível superior ou em lote entra em conflito com o alvo da solicitação.
+- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis de sessão existente.
+
+Outras falhas de runtime ainda podem retornar `{ "error": "" }` sem um
+campo `code`.
+
+### Requisito do Playwright
+
+Alguns recursos (navigate/act/AI snapshot/role snapshot, capturas de tela de elementos,
PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornam
um erro 501 claro.
@@ -591,58 +613,58 @@ O que ainda funciona sem Playwright:
- Snapshots ARIA
- Capturas de tela de página para o navegador gerenciado `openclaw` quando um WebSocket
- CDP por aba estiver disponível
+ CDP por aba está disponível
- Capturas de tela de página para perfis `existing-session` / Chrome MCP
-- Capturas de tela `--ref` baseadas em existing-session a partir da saída de snapshot
+- Capturas de tela baseadas em ref (`--ref`) para `existing-session` a partir da saída de snapshot
-O que ainda precisa do Playwright:
+O que ainda exige Playwright:
- `navigate`
- `act`
-- Snapshots AI / role snapshots
+- Snapshots AI / snapshots de função
- Capturas de tela de elemento por seletor CSS (`--element`)
- Exportação completa de PDF do navegador
Capturas de tela de elemento também rejeitam `--full-page`; a rota retorna `fullPage is
not supported for element screenshots`.
-Se você vir `Playwright is not available in this gateway build`, instale o pacote
-completo do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale
-o OpenClaw com suporte a navegador.
+Se você vir `Playwright is not available in this gateway build`, instale o pacote completo
+do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o
+OpenClaw com suporte a navegador.
#### Instalação do Playwright no Docker
-Se o Gateway estiver rodando em Docker, evite `npx playwright` (conflitos de override do npm).
-Use a CLI empacotada em vez disso:
+Se o seu Gateway roda em Docker, evite `npx playwright` (conflitos de override do npm).
+Use a CLI incluída em vez disso:
```bash
docker compose run --rm openclaw-cli \
node /app/node_modules/playwright-core/cli.js install chromium
```
-Para persistir downloads de navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
-`/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido via
-`OPENCLAW_HOME_VOLUME` ou um bind mount. Consulte [Docker](/pt-BR/install/docker).
+Para persistir downloads do navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo,
+`/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido por meio de
+`OPENCLAW_HOME_VOLUME` ou de um bind mount. Veja [Docker](/pt-BR/install/docker).
## Como funciona (internamente)
Fluxo de alto nível:
- Um pequeno **servidor de controle** aceita requisições HTTP.
-- Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) via **CDP**.
-- Para ações avançadas (clicar/digitar/snapshot/PDF), usa **Playwright** por cima
- do CDP.
-- Quando o Playwright está ausente, apenas operações sem Playwright ficam disponíveis.
+- Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) por meio de **CDP**.
+- Para ações avançadas (clicar/digitar/snapshot/PDF), ele usa **Playwright** sobre
+ o CDP.
+- Quando o Playwright está ausente, apenas operações que não usam Playwright ficam disponíveis.
-Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo que permite
-trocar navegadores/perfis locais ou remotos.
+Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo em que permite
+trocar navegadores e perfis locais/remotos.
## Referência rápida da CLI
-Todos os comandos aceitam `--browser-profile ` para mirar um perfil específico.
+Todos os comandos aceitam `--browser-profile ` para direcionar um perfil específico.
Todos os comandos também aceitam `--json` para saída legível por máquina (payloads estáveis).
-Noções básicas:
+Básico:
- `openclaw browser status`
- `openclaw browser start`
@@ -671,11 +693,11 @@ Inspeção:
- `openclaw browser snapshot --frame "iframe#main" --interactive`
- `openclaw browser console --level error`
-Observação sobre ciclo de vida:
+Observação sobre o ciclo de vida:
-- Para perfis attach-only e CDP remoto, `openclaw browser stop` ainda é o
- comando correto de limpeza após testes. Ele fecha a sessão ativa de controle e
- limpa overrides temporários de emulação em vez de encerrar o navegador
+- Para perfis somente de conexão e CDP remoto, `openclaw browser stop` continua sendo o
+ comando de limpeza correto após os testes. Ele fecha a sessão de controle ativa e
+ limpa substituições temporárias de emulação em vez de encerrar o navegador
subjacente.
- `openclaw browser errors --clear`
- `openclaw browser requests --filter api --clear`
@@ -725,62 +747,62 @@ Estado:
- `openclaw browser set locale en-US`
- `openclaw browser set device "iPhone 14"`
-Observações:
+Notas:
-- `upload` e `dialog` são chamadas de **preparo**; execute-as antes do click/press
- que dispara o seletor/diálogo.
-- Caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
+- `upload` e `dialog` são chamadas de **preparação**; execute-as antes do clique/tecla
+ que aciona o seletor de arquivos/caixa de diálogo.
+- Os caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw:
- traces: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
- downloads: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
-- Caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
+- Os caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw:
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
-- `upload` também pode definir inputs de arquivo diretamente via `--input-ref` ou `--element`.
+- `upload` também pode definir diretamente entradas de arquivo por meio de `--input-ref` ou `--element`.
- `snapshot`:
- `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot AI com refs numéricos (`aria-ref=""`).
- `--format aria`: retorna a árvore de acessibilidade (sem refs; apenas inspeção).
- - `--efficient` (ou `--mode efficient`): preset compacto de role snapshot (interactive + compact + depth + maxChars menor).
- - Padrão de configuração (somente ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando o chamador não passar um modo (consulte [Gateway configuration](/pt-BR/gateway/configuration-reference#browser)).
- - Opções de role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em papel com refs como `ref=e12`.
- - `--frame "