openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh pt-BR translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:52:35 +00:00
parent 6b43efae95
commit b4b8d72122
37 changed files with 4842 additions and 4326 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
docs/pt-BR/automation/tasks.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Inspecionando trabalhos em segundo plano em andamento ou concluídos recentemente
- Depuração de falhas de entrega em execuções de agente desanexadas
- Entendendo como as execuções em segundo plano se relacionam com sessões, Cron e Heartbeat
- Depuração de falhas de entrega em execuções de agentes desanexadas
- Entendendo como execuções em segundo plano se relacionam a sessões, Cron e Heartbeat
sidebarTitle: Background tasks
summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, tarefas Cron isoladas e operações da CLI
summary: Rastreamento de tarefas em segundo plano para execuções de ACP, subagentes, trabalhos Cron isolados e operações da CLI
title: Tarefas em segundo plano
x-i18n:
generated_at: "2026-05-01T05:55:21Z"
generated_at: "2026-05-05T01:44:37Z"
model: gpt-5.5
provider: openai
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991
source_path: automation/tasks.md
workflow: 16
---
@ -19,29 +19,29 @@ x-i18n:
Procurando agendamento? Consulte [Automação e tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página é o registro de atividades do trabalho em segundo plano, não o agendador.
</Note>
Tarefas em segundo plano rastreiam o trabalho executado **fora da sua sessão principal de conversa**: execuções ACP, criação de subagentes, execuções isoladas de tarefas Cron e operações iniciadas pela CLI.
Tarefas em segundo plano rastreiam trabalhos executados **fora da sua sessão principal de conversa**: execuções ACP, criação de subagentes, execuções isoladas de tarefas cron e operações iniciadas pela CLI.
Tarefas **não** substituem sessões, tarefas Cron nem Heartbeats — elas são o **registro de atividades** que registra qual trabalho destacado aconteceu, quando e se ele teve sucesso.
Tarefas **não** substituem sessões, tarefas cron ou heartbeats — elas são o **registro de atividades** que registra qual trabalho separado aconteceu, quando, e se foi bem-sucedido.
<Note>
Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat interativo normal não criam. Todas as execuções Cron, criações ACP, criações de subagentes e comandos de agente pela 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, criações ACP, criações de subagentes e comandos de agente pela CLI criam.
</Note>
## TL;DR
- Tarefas são **registros**, não agendadores — Cron e Heartbeat decidem _quando_ o trabalho é executado, tarefas rastreiam _o que aconteceu_.
- ACP, subagentes, todas as tarefas Cron e operações da CLI criam tarefas. Turnos de Heartbeat não criam.
- Tarefas são **registros**, não agendadores — cron e heartbeat decidem _quando_ o trabalho executa, tarefas rastreiam _o que aconteceu_.
- ACP, subagentes, todas as tarefas 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).
- Tarefas Cron permanecem ativas enquanto o runtime Cron ainda controla o job; se o
estado do runtime em memória desapareceu, a manutenção de tarefas primeiro verifica o histórico durável de execuções Cron
- Tarefas cron permanecem ativas enquanto o runtime cron ainda é dono do job; se o
estado do runtime em memória se foi, a manutenção de tarefas primeiro verifica o histórico durável de execuções cron
antes de marcar uma tarefa como perdida.
- A conclusão é orientada por push: trabalho destacado pode notificar diretamente ou acordar a
sessão/Heartbeat solicitante quando termina, então loops de sondagem de status
- A conclusão é orientada por push: trabalho separado pode notificar diretamente ou acordar a
sessão/heartbeat solicitante quando termina, então loops de consulta de status
geralmente têm o formato errado.
- Execuções Cron isoladas e conclusões de subagentes fazem a melhor tentativa de limpar abas/processos de navegador rastreados para a sessão filha antes da escrituração final de limpeza.
- A entrega Cron isolada suprime respostas intermediárias obsoletas do pai enquanto trabalho de subagente descendente ainda está escoando, e prefere a saída final do 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.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` expõe problemas.
- Execuções cron isoladas e conclusões de subagentes tentam, em melhor esforço, limpar abas/processos de navegador rastreados para a sessão filha antes da escrituração 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 do 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.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` destaca problemas.
- Registros terminais são mantidos por 7 dias e depois removidos automaticamente.
## Início rápido
@ -97,28 +97,28 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
## O que cria uma tarefa
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política padrão de notificação |
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Execuções em segundo plano ACP | `acp` | Ao criar uma sessão ACP filha | `done_only` |
| Execuções ACP em segundo plano | `acp` | Ao criar uma sessão ACP filha | `done_only` |
| Orquestração de subagentes | `subagent` | Ao criar um subagente via `sessions_spawn` | `done_only` |
| Tarefas Cron (todos os tipos) | `cron` | Toda execução Cron (sessão principal e isolada) | `silent` |
| Operações da CLI | `cli` | Comandos `openclaw agent` que executam pelo Gateway | `silent` |
| Tarefas cron (todos os tipos) | `cron` | A cada execução cron (sessão principal e isolada) | `silent` |
| Operações da CLI | `cli` | Comandos `openclaw agent` que executam pelo gateway | `silent` |
| Jobs de mídia do agente | `cli` | Execuções `music_generate`/`video_generate` apoiadas por sessão | `silent` |
<AccordionGroup>
<Accordion title="Padrões de notificação para Cron e mídia">
Tarefas Cron de 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 executam em sua própria sessão.
<Accordion title="Padrões de notificação para cron e mídia">
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 executam em sua própria sessão.
Execuções `music_generate` e `video_generate` apoiadas por 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 a mídia finalizada por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `video_generate` podem tentar primeiro a entrega direta no canal; conclusões assíncronas de `music_generate` permanecem no caminho de despertar da sessão solicitante.
Execuções `music_generate` e `video_generate` apoiadas por 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 acionamento interno para que o agente possa escrever a mensagem de acompanhamento e anexar a mídia finalizada por conta própria. Conclusões em grupo/canal seguem a política normal de resposta visível, então o agente usa a ferramenta de mensagem quando a entrega de origem exige isso.
</Accordion>
<Accordion title="Proteção contra video_generate concorrente">
Enquanto uma tarefa `video_generate` apoiada por sessão ainda está ativa, a ferramenta também atua como uma 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.
<Accordion title="Proteção para video_generate concorrente">
Enquanto uma tarefa `video_generate` apoiada por sessão ainda está ativa, a ferramenta também atua como uma proteção: chamadas repetidas a `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.
</Accordion>
<Accordion title="O que não cria tarefas">
- Turnos de Heartbeat — sessão principal; consulte [Heartbeat](/pt-BR/gateway/heartbeat)
- Turnos de chat interativo normal
- Respostas diretas de `/command`
- Turnos normais de chat interativo
- Respostas diretas a `/command`
</Accordion>
</AccordionGroup>
@ -137,55 +137,55 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | O que significa |
| Status | O que significa |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Criada, aguardando o agente iniciar |
| `running` | O turno do agente está executando ativamente |
| `succeeded` | Concluída com sucesso |
| `queued` | Criada, aguardando o agente iniciar |
| `running` | O turno do agente está executando ativamente |
| `succeeded` | Concluída com sucesso |
| `failed` | Concluída com erro |
| `timed_out` | Excedeu o timeout configurado |
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de tolerância de 5 minutos |
| `timed_out` | Excedeu o tempo limite configurado |
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de carência de 5 minutos |
As transições acontecem automaticamente — quando a execução de agente associada termina, o status da tarefa é atualizado para corresponder.
A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução destacada bem-sucedida finaliza como `succeeded`, erros comuns de execução finalizam como `failed`, e resultados de timeout ou abortamento finalizam como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como `failed`, `timed_out` ou `lost`, um sinal posterior de sucesso não rebaixa esse status terminal.
A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução separada bem-sucedida finaliza como `succeeded`, erros comuns de execução finalizam como `failed`, e resultados de timeout ou abortamento finalizam como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como `failed`, `timed_out` ou `lost`, um sinal posterior de sucesso não rebaixa esse status terminal.
`lost` é ciente do runtime:
- Tarefas ACP: os metadados da sessão ACP filha de apoio desapareceram.
- Tarefas de subagente: a sessão filha de apoio desapareceu do armazenamento do agente de destino.
- Tarefas Cron: o runtime Cron não rastreia mais o job como ativo e o histórico durável de execuções Cron
não mostra um resultado terminal para essa execução. A auditoria offline da CLI
não trata seu próprio estado vazio de runtime Cron em processo como autoridade.
- Tarefas CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas CLI
apoiadas por chat usam o contexto de execução ao vivo, então linhas persistentes
de sessão de canal/grupo/direta não as mantêm vivas. Execuções
`openclaw agent` apoiadas pelo Gateway também finalizam pelo resultado da execução, então execuções concluídas
não ficam ativas até que o varredor as marque como `lost`.
- Tarefas cron: o runtime cron não rastreia mais o job como ativo e o histórico durável
de execuções cron não mostra um resultado terminal para essa execução. A auditoria offline da CLI
não trata seu próprio estado vazio de runtime cron em processo como autoridade.
- Tarefas da CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas da CLI
apoiadas por chat usam o contexto de execução ativo, então linhas persistentes de sessão
de canal/grupo/direta não as mantêm vivas. Execuções `openclaw agent` apoiadas pelo Gateway
também finalizam a partir do resultado da execução, então execuções concluídas
não ficam ativas até o varredor marcá-las como `lost`.
## Entrega e notificações
Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
Quando uma tarefa alcança um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
**Entrega direta** — se a tarefa tem um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai direto para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagente, o OpenClaw também preserva o roteamento de thread/tópico vinculado 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 direta** — se a tarefa tem 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 de thread/tópico vinculado 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 falha ou nenhuma origem está 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 de sistema na sessão do solicitante e aparece no próximo heartbeat.
<Tip>
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 de Heartbeat agendado.
A conclusão de tarefa aciona um acionamento imediato de heartbeat para que você veja o resultado rapidamente — você não precisa esperar o próximo tique de heartbeat agendado.
</Tip>
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho destacado uma vez e depois deixe o runtime acordar ou notificar você na conclusão. Sonde o estado da tarefa somente quando precisar de depuração, intervenção ou uma auditoria explícita.
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho separado uma vez e deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa somente quando precisar depurar, intervir ou fazer uma auditoria explícita.
### Políticas de notificação
Controle quanto você ouve sobre cada tarefa:
| Política | O que é entregue |
| Política | O que é entregue |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (padrão) | Somente estado terminal (succeeded, failed etc.) — **este é o padrão** |
| `state_changes` | Toda transição de estado e atualização de progresso |
| `state_changes` | Toda transição de estado e atualização de progresso |
| `silent` | Nada |
Altere a política enquanto uma tarefa está em execução:
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Para tarefas ACP e de subagente, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há handle separado de runtime filho). O status transita para `cancelled` e uma notificação de entrega é enviada quando aplicável.
Para tarefas ACP e de subagente, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há identificador de runtime filho separado). O status transiciona para `cancelled` e uma notificação de entrega é enviada quando aplicável.
</Accordion>
<Accordion title="tasks notify">
@ -231,16 +231,16 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks audit [--json]
```
Expõe problemas operacionais. Constatações também aparecem em `openclaw status` quando problemas são detectados.
Destaca problemas operacionais. Achados também aparecem em `openclaw status` quando problemas são detectados.
| Constatação | Severidade | Acionador |
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | warn | Em fila por mais de 10 minutos |
| `stale_running` | error | Em execução por mais de 30 minutos |
| `lost` | warn/error | A propriedade da tarefa respaldada por runtime desapareceu; tarefas perdidas retidas emitem aviso até `cleanupAfter`, depois viram erros |
| `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 começar) |
| Descoberta | Severidade | Gatilho |
| ------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | warn | Na fila há mais de 10 minutos |
| `stale_running` | error | Em execução há mais de 30 minutos |
| `lost` | warn/error | A propriedade da tarefa apoiada pelo runtime desapareceu; tarefas perdidas retidas avisam até `cleanupAfter`, depois viram erros |
| `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 começar) |
</Accordion>
<Accordion title="manutenção de tarefas">
@ -249,21 +249,21 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Use isto para visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e estado do TaskFlow.
Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e o estado do Task Flow.
A reconciliação é ciente de runtime:
A reconciliação é ciente do runtime:
- Tarefas ACP/subagente verificam sua sessão filha de apoio.
- Tarefas de ACP/subagente verificam sua sessão filha de apoio.
- Tarefas de subagente cuja sessão filha tem uma lápide de recuperação de reinicialização são marcadas como perdidas em vez de serem tratadas como sessões de apoio recuperáveis.
- Tarefas Cron verificam se o runtime do cron ainda possui o job, depois recuperam o status terminal de logs de execução de cron/estado de job persistidos antes de recorrer a `lost`. Apenas o processo Gateway é autoritativo para o conjunto de jobs ativos de cron em memória; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa de cron como perdida somente porque esse Set local está vazio.
- Tarefas da CLI respaldadas por chat verificam o contexto de execução ao vivo proprietário, não apenas a linha da sessão de chat.
- Tarefas de Cron verificam se o runtime de cron ainda possui o trabalho, depois recuperam o status terminal de logs de execução cron/estado de trabalho persistidos antes de recorrer a `lost`. Somente o processo Gateway é autoritativo para o conjunto em memória de trabalhos ativos de cron; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa cron como perdida apenas porque esse Set local está vazio.
- Tarefas da CLI apoiadas por chat verificam o contexto de execução ao vivo proprietário, não apenas a linha da sessão de chat.
A limpeza de conclusão também é ciente de runtime:
A limpeza de conclusão também é ciente do runtime:
- A conclusão de subagente tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão filha antes que a limpeza de anúncio continue.
- A conclusão de cron isolado tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão de cron antes que a execução seja totalmente encerrada.
- A entrega de cron isolado aguarda acompanhamento de subagente descendente 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 de assistente visível mais recente; se ele estiver vazio, recorre ao texto sanitizado mais recente de tool/toolResult, e execuções de chamadas de ferramenta apenas por timeout podem ser reduzidas a um breve resumo de progresso parcial. Execuções terminais com falha anunciam o status de falha sem repetir o texto de resposta capturado.
- A conclusão de subagente fecha, por melhor esforço, abas/processos de navegador rastreados para a sessão filha antes de a limpeza de 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 desmontada.
- A entrega de cron isolado aguarda o acompanhamento de subagente descendente 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 de assistente visível mais recente; se estiver vazio, recorre ao texto mais recente higienizado de ferramenta/toolResult, e execuções de chamadas de ferramenta apenas por timeout podem ser reduzidas a um breve resumo de progresso parcial. Execuções terminais com falha anunciam o status de falha sem reproduzir o texto de resposta capturado.
- Falhas de limpeza não mascaram o resultado real da tarefa.
</Accordion>
@ -274,65 +274,65 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks flow cancel <lookup>
```
Use estes quando o TaskFlow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano.
Use estes quando o Task Flow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano.
</Accordion>
</AccordionGroup>
## Quadro de tarefas do chat (`/tasks`)
Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O quadro 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 quadro mostra tarefas ativas e concluídas recentemente com runtime, status, temporização e detalhes de progresso ou erro.
Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre às contagens de tarefas locais do agente, para que você ainda tenha uma visão geral sem vazar 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 vazar detalhes de outras sessões.
Para o livro-razão completo do operador, use a CLI: `openclaw tasks list`.
Para o registro completo do operador, use a CLI: `openclaw tasks list`.
## Integração de status (pressão de tarefas)
`openclaw status` inclui um resumo rápido de tarefas:
`openclaw status` inclui um resumo de tarefas em uma olhada:
```
Tasks: 3 queued · 2 running · 1 issues
```
O resumo informa:
O resumo relata:
- **active** — contagem de `queued` + `running`
- **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 ciente de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas são ocultadas e falhas recentes só aparecem quando nenhum trabalho ativo permanece. Isso mantém o cartão de status focado no que importa agora.
Tanto `/status` quanto a ferramenta `session_status` usam um instantâneo de tarefas ciente de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas ficam ocultas, e falhas recentes só aparecem quando não resta nenhum trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
## Armazenamento e manutenção
### Onde as tarefas ficam
Registros de tarefas persistem no SQLite em:
Registros de tarefa persistem no 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 Gateway mantém o log de gravação antecipada do SQLite limitado usando o limite padrão de
O registro é carregado na memória na inicialização do gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
O Gateway mantém o log write-ahead do SQLite limitado usando o limite padrão de
autocheckpoint do SQLite mais checkpoints `TRUNCATE` periódicos e no desligamento.
### Manutenção automática
Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
Um varredor roda a cada **60 segundos** e cuida de quatro coisas:
<Steps>
<Step title="Reconciliação">
Verifica se tarefas ativas ainda têm respaldo autoritativo de runtime. Tarefas ACP/subagente usam o estado da sessão filha, tarefas de cron usam a propriedade de jobs ativos, e tarefas da CLI respaldadas por chat usam o contexto de execução proprietário. Se esse estado de apoio desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
Verifica se tarefas ativas ainda têm apoio autoritativo de runtime. Tarefas de ACP/subagente usam o estado da sessão filha, tarefas de cron usam a propriedade do trabalho ativo, e tarefas da CLI apoiadas por chat usam o contexto de execução proprietário. Se esse estado de apoio desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
</Step>
<Step title="Reparo de sessão ACP">
Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs somente quando não resta nenhum vínculo de conversa ativo.
Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs apenas quando não resta nenhuma vinculação de conversa ativa.
</Step>
<Step title="Marcação de limpeza">
Define um timestamp `cleanupAfter` em tarefas terminais (endedAt + 7 dias). Durante a retenção, tarefas perdidas ainda aparecem na auditoria como avisos; depois que `cleanupAfter` expira ou quando metadados de limpeza estão ausentes, elas são erros.
</Step>
<Step title="Poda">
Exclui registros após sua data `cleanupAfter`.
Exclui registros após a data `cleanupAfter`.
</Step>
</Steps>
@ -343,36 +343,36 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
## Como as tarefas se relacionam com outros sistemas
<AccordionGroup>
<Accordion title="Tarefas e TaskFlow">
[TaskFlow](/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 orquestrador.
<Accordion title="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 tarefa e `openclaw tasks flow` para inspecionar o fluxo orquestrador.
Consulte [TaskFlow](/pt-BR/automation/taskflow) para detalhes.
Consulte [Task Flow](/pt-BR/automation/taskflow) para obter detalhes.
</Accordion>
<Accordion title="Tarefas e cron">
Uma **definição** de job de cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução em runtime fica ao lado dela em `~/.openclaw/cron/jobs-state.json`. **Toda** execução de cron cria um registro de tarefa — tanto de sessão principal quanto isolada. Tarefas de cron de sessão principal usam por padrão a política de notificação `silent`, de modo que são rastreadas sem gerar notificações.
Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução do runtime fica ao lado dela em `~/.openclaw/cron/jobs-state.json`. **Toda** execução de cron cria um registro de tarefa — tanto de sessão principal quanto isolada. Tarefas cron de sessão principal usam a política de notificação `silent` por padrão, para que sejam rastreadas sem gerar notificações.
Consulte [Cron Jobs](/pt-BR/automation/cron-jobs).
Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs).
</Accordion>
<Accordion title="Tarefas e Heartbeat">
Execuções de Heartbeat são turnos de sessão principal — elas não criam registros de tarefas. Quando uma tarefa é concluída, ela pode acionar um despertar de Heartbeat para que você veja o resultado prontamente.
<Accordion title="Tarefas e heartbeat">
Execuções de Heartbeat são turnos de sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode disparar um despertar de Heartbeat para que você veja o resultado prontamente.
Consulte [Heartbeat](/pt-BR/gateway/heartbeat).
</Accordion>
<Accordion title="Tarefas e sessões">
Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade sobre isso.
Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade por cima disso.
</Accordion>
<Accordion title="Tarefas e execuções de agente">
O `runId` de uma tarefa aponta para a execução do agente que realiza o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa — você não precisa gerenciar o ciclo de vida manualmente.
O `runId` de uma tarefa vincula à execução de agente que faz o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa — você não precisa gerenciar o ciclo de vida manualmente.
</Accordion>
</AccordionGroup>
## Relacionados
## Relacionado
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em uma olhada
- [CLI: Tarefas](/pt-BR/cli/tasks) — referência de comandos da CLI
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos de sessão principal
- [Tarefas agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
- [TaskFlow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas
- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas

696
docs/pt-BR/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

417
docs/pt-BR/ci.md
View File

@ -1,71 +1,71 @@
---
read_when:
- Você precisa entender por que um job de CI foi executado ou não
- Você está depurando uma verificação do GitHub Actions que está falhando
- Você está coordenando uma execução ou reexecução da validação de lançamento
- Você precisa entender por que uma tarefa de CI foi ou não executada
- Você está depurando uma verificação com falha do GitHub Actions
- Você está coordenando uma execução ou reexecução de validação de lançamento
- Você está alterando o acionamento do ClawSweeper ou o encaminhamento de atividades do GitHub
summary: Grafo de tarefas de CI, controles de escopo, guarda-chuvas de lançamento e equivalentes de comandos locais
summary: Grafo de tarefas de CI, critérios de escopo, abrangências de lançamento e equivalentes de comandos locais
title: Pipeline de CI
x-i18n:
generated_at: "2026-05-04T05:52:15Z"
generated_at: "2026-05-05T01:44:48Z"
model: gpt-5.5
provider: openai
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66
source_path: ci.md
workflow: 16
---
A CI do OpenClaw é executada em cada push para `main` e em cada pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais de `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android continuam opcionais por meio de `include_android`. A cobertura de Plugins somente de release fica no workflow separado [`Plugin Prerelease`](#plugin-prerelease) e só é executada a partir de [`Full Release Validation`](#full-release-validation) ou de um disparo manual explícito.
OpenClaw CI é executado em cada push para `main` e em cada pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais por `workflow_dispatch` ignoram intencionalmente o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android continuam opt-in por meio de `include_android`. A cobertura de plugins exclusiva de release fica no workflow separado [`Pré-lançamento de Plugin`](#plugin-prerelease) e só é executada a partir de [`Validação Completa de Release`](#full-release-validation) ou de um disparo manual explícito.
## Visão geral do pipeline
| Job | Finalidade | Quando é executado |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Detecta alterações somente de docs, escopos alterados, extensions alteradas e constrói o manifesto de CI | Sempre em pushes e PRs não rascunho |
| `security-scm-fast` | Detecção de chaves privadas e auditoria de workflow via `zizmor` | Sempre em pushes e PRs não rascunho |
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs não rascunho |
| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não rascunho |
| `check-dependencies` | Passagem do Knip somente para dependências de produção mais a guarda da lista de permissões de arquivos não usados | Alterações relevantes para Node |
| `build-artifacts` | Compila `dist/`, Control UI, verificações de artefatos compilados e artefatos downstream reutilizáveis | Alterações relevantes para Node |
| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de Plugins empacotados/contratos de Plugin/protocolo | Alterações relevantes para Node |
| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canais com um resultado agregado estável | Alterações relevantes para Node |
| `checks-node-core-test` | Fragmentos de testes do Node principal, excluindo lanes de canais, Plugins empacotados, contratos e extensions | Alterações relevantes para Node |
| `check` | Equivalente fragmentado do gate local principal: tipos de produção, lint, guardas, tipos de teste e smoke estrito | Alterações relevantes para Node |
| `check-additional` | Arquitetura, drift fragmentado de limites/prompts, guardas de extensions, limite de pacote e Gateway watch | Alterações relevantes para Node |
| `build-smoke` | Testes smoke da CLI compilada e smoke de memória de inicialização | Alterações relevantes para Node |
| `checks` | Verificador para testes de canal de artefatos compilados | Alterações relevantes para Node |
| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para releases |
| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas |
| `skills-python` | Ruff + pytest para Skills apoiadas por Python | Alterações relevantes para Skills em Python |
| `checks-windows` | Testes específicos de processo/caminho no Windows mais regressões compartilhadas de especificadores de importação em runtime | Alterações relevantes para Windows |
| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Alterações relevantes para macOS |
| `macos-swift` | Lint, build e testes Swift para o app macOS | Alterações relevantes para macOS |
| `android` | Testes unitários de Android para ambos os flavors mais um build de APK de debug | Alterações relevantes para Android |
| `test-performance-agent` | Otimização diária de testes lentos pelo Codex após atividade confiável | Sucesso da CI principal ou disparo manual |
| `openclaw-performance` | Relatórios diários/sob demanda de performance do runtime Kova com lanes de mock-provider, deep-profile e GPT 5.4 ao vivo | Disparo agendado e manual |
| Job | Finalidade | Quando é executado |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `preflight` | Detecta mudanças apenas em docs, escopos alterados, extensões alteradas e cria o manifesto de CI | Sempre em pushes e PRs não rascunho |
| `security-scm-fast` | Detecção de chave privada e auditoria de workflows via `zizmor` | Sempre em pushes e PRs não rascunho |
| `security-dependency-audit` | Auditoria do lockfile de produção, sem dependências, contra avisos do npm | Sempre em pushes e PRs não rascunho |
| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs não rascunho |
| `check-dependencies` | Passo Knip de produção apenas para dependências mais a guarda da allowlist de arquivos não usados | Mudanças relevantes para Node |
| `build-artifacts` | Cria `dist/`, Control UI, verificações de artefatos criados e artefatos reutilizáveis downstream | Mudanças relevantes para Node |
| `checks-fast-core` | Lanes rápidas de correção no Linux, como verificações de bundled/contrato de plugin/protocolo | Mudanças relevantes para Node |
| `checks-fast-contracts-channels` | Verificações fragmentadas de contratos de canais com um resultado de verificação agregado estável | Mudanças relevantes para Node |
| `checks-node-core-test` | Shards de testes principais de Node, excluindo lanes de canal, bundled, contrato e extensão | Mudanças relevantes para Node |
| `check` | Equivalente fragmentado do gate local principal: tipos de prod, lint, guardas, tipos de teste e smoke estrito | Mudanças relevantes para Node |
| `check-additional` | Arquitetura, drift fragmentado de boundary/prompt, guardas de extensão, package boundary e gateway watch | Mudanças relevantes para Node |
| `build-smoke` | Testes smoke da CLI criada e smoke de memória de inicialização | Mudanças relevantes para Node |
| `checks` | Verificador para testes de canais com artefatos criados | Mudanças relevantes para Node |
| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Disparo manual de CI para releases |
| `check-docs` | Formatação, lint e verificações de links quebrados da documentação | Docs alteradas |
| `skills-python` | Ruff + pytest para skills baseadas em Python | Mudanças relevantes para skills Python |
| `checks-windows` | Testes específicos do Windows para processos/caminhos mais regressões compartilhadas de especificadores de importação em runtime | Mudanças relevantes para Windows |
| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos criados compartilhados | Mudanças relevantes para macOS |
| `macos-swift` | Lint, build e testes Swift para o app macOS | Mudanças relevantes para macOS |
| `android` | Testes unitários Android para ambos os flavors mais um build de APK debug | Mudanças relevantes para Android |
| `test-performance-agent` | Otimização diária de testes lentos do Codex após atividade confiável | Sucesso do CI principal ou disparo manual |
| `openclaw-performance` | Relatórios diários/sob demanda de performance do runtime Kova com mock-provider, deep-profile e lanes live GPT 5.4 | Disparo agendado e manual |
## Ordem de falha rápida
## Ordem de fail-fast
1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro deste job, não jobs independentes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de matriz de artefatos e plataformas.
1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` são etapas dentro desse job, não jobs independentes.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falham rapidamente sem esperar pelos jobs mais pesados de artefatos e matriz de plataformas.
3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto.
4. Lanes mais pesadas de plataforma e runtime se expandem depois disso: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
4. Depois disso, lanes mais pesadas de plataforma e runtime se expandem: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega ao mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais nova para a mesma ref também esteja falhando. Verificações agregadas de fragmentos usam `!cancelled() && always()` para que ainda relatem falhas normais de fragmentos, mas não entrem na fila depois que o workflow inteiro já tiver sido substituído. A chave de concorrência automática da CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas da main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento.
O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais recente chega ao mesmo PR ou ref `main`. Trate isso como ruído de CI, a menos que a execução mais recente para a mesma ref também esteja falhando. Verificações agregadas de shards usam `!cancelled() && always()` para ainda relatar falhas normais de shard, mas não entrar na fila depois que o workflow inteiro já foi substituído. A chave automática de concorrência do CI é versionada (`CI-v7-*`) para que um zumbi do lado do GitHub em um grupo de fila antigo não possa bloquear indefinidamente execuções mais novas de main. Execuções manuais da suíte completa usam `CI-manual-v1-*` e não cancelam execuções em andamento.
## Escopo e roteamento
A lógica de escopo fica em `scripts/ci-changed-scope.mjs` e é coberta por testes unitários em `src/scripts/ci-changed-scope.test.ts`. O disparo manual pula a detecção de escopo alterado e faz o manifesto de preflight agir como se todas as áreas com escopo tivessem mudado.
- **Edições de workflow de CI** validam o grafo de CI do Node mais linting de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma permanecem escopadas a alterações de código-fonte de plataforma.
- **Edições apenas de roteamento de CI, edições selecionadas de fixtures baratas de testes do núcleo e edições estreitas de helpers/roteamento de testes de contrato de Plugin** usam um caminho rápido de manifesto somente Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canais, fragmentos completos do núcleo, fragmentos de Plugins empacotados e matrizes adicionais de guardas quando a alteração se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente.
- **Verificações de Node no Windows** são escopadas a wrappers específicos de processo/caminho do Windows, helpers de execução npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; alterações não relacionadas de código-fonte, Plugin, smoke de instalação e somente testes permanecem nas lanes de Node no Linux.
- **Edições no workflow de CI** validam o grafo de CI do Node mais o lint de workflow, mas não forçam builds nativos de Windows, Android ou macOS por si só; essas lanes de plataforma continuam limitadas ao escopo de mudanças no código-fonte da plataforma.
- **Edições apenas de roteamento de CI, edições selecionadas baratas de fixtures de testes principais e edições estreitas de helpers/test-routing de contrato de plugin** usam um caminho rápido de manifesto apenas para Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canais, shards principais completos, shards de bundled-plugin e matrizes adicionais de guardas quando a mudança se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente.
- **Verificações de Node no Windows** têm escopo limitado a wrappers de processos/caminhos específicos do Windows, helpers de runner npm/pnpm/UI, configuração do gerenciador de pacotes e superfícies do workflow de CI que executam essa lane; mudanças não relacionadas em código-fonte, plugin, install-smoke e apenas testes ficam nas lanes de Node do Linux.
As famílias mais lentas de testes Node são divididas ou balanceadas para que cada job continue pequeno sem reservar runners em excesso: contratos de canais rodam como três fragmentos ponderados, lanes rápidas/de suporte de unidade do núcleo rodam separadamente, a infraestrutura de runtime do núcleo é dividida entre fragmentos de estado e processo/configuração, auto-reply roda como workers balanceados (com a subárvore de respostas dividida em fragmentos de agent-runner, dispatch e commands/state-routing), e configurações agentic de Gateway/servidor são divididas entre lanes de chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos compilados. Testes amplos de navegador, QA, mídia e Plugins diversos usam suas configurações Vitest dedicadas em vez do catch-all compartilhado de Plugins. Fragmentos com padrão de inclusão registram entradas de tempo usando o nome do fragmento de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma configuração inteira de um fragmento filtrado. `check-additional` mantém juntos o trabalho de compilação/canário de limite de pacote e separa a arquitetura de topologia de runtime da cobertura de Gateway watch; a lista de guardas de limite é distribuída em quatro fragmentos de matriz, cada um executando guardas independentes selecionadas em paralelo e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que drift de prompt do caminho feliz do runtime Codex fique preso ao PR que o causou. Gateway watch, testes de canais e o fragmento de limite de suporte do núcleo rodam em paralelo dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados.
As famílias de testes Node mais lentas são divididas ou balanceadas para que cada job permaneça pequeno sem reservar runners em excesso: contratos de canais rodam como três shards ponderados, lanes fast/support de unidades do core rodam separadamente, a infraestrutura de runtime do core é dividida entre shards de estado e processo/config, auto-reply roda como workers balanceados (com a subárvore de reply dividida em shards de agent-runner, dispatch e commands/state-routing), e configs agentic de gateway/server são divididas entre lanes de chat/auth/model/http-plugin/runtime/startup em vez de esperar por artefatos criados. Testes amplos de navegador, QA, mídia e plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de plugins. Shards de include-pattern registram entradas de tempo usando o nome do shard de CI, para que `.artifacts/vitest-shard-timings.json` possa distinguir uma config inteira de um shard filtrado. `check-additional` mantém o trabalho de compile/canary de package-boundary junto e separa arquitetura de topologia de runtime da cobertura de gateway watch; a lista de guardas de boundary é distribuída em quatro shards de matriz, cada um executando guardas independentes selecionadas em paralelo e imprimindo tempos por verificação, incluindo `pnpm prompt:snapshots:check`, para que o drift de prompt do caminho feliz do runtime Codex fique fixado ao PR que o causou. Gateway watch, testes de canais e o shard de support-boundary do core rodam em paralelo dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram criados.
A CI de Android executa `testPlayDebugUnitTest` e `testThirdPartyDebugUnitTest` e depois compila o APK de debug Play. O flavor third-party não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo um job duplicado de empacotamento de APK de debug em cada push relevante para Android.
O CI de Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest` e depois cria o APK debug Play. O flavor third-party não tem source set ou manifesto separado; sua lane de testes unitários ainda compila o flavor com as flags BuildConfig de SMS/call-log, evitando ao mesmo tempo um job duplicado de empacotamento de APK debug em todo push relevante para Android.
O fragmento `check-dependencies` executa `pnpm deadcode:dependencies` (uma passagem do Knip somente para dependências de produção fixada na versão mais recente do Knip, com a idade mínima de release do pnpm desativada para a instalação `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na lista de permissões, preservando superfícies intencionais de Plugins dinâmicos, geradas, de build, testes ao vivo e pontes de pacote que o Knip não consegue resolver estaticamente.
O shard `check-dependencies` executa `pnpm deadcode:dependencies` (um passo Knip de produção apenas para dependências, fixado na versão mais recente do Knip, com a idade mínima de release do pnpm desativada para a instalação `dlx`) e `pnpm deadcode:unused-files`, que compara as descobertas de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. A guarda de arquivos não usados falha quando um PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na allowlist, preservando ao mesmo tempo superfícies intencionais de plugin dinâmico, geradas, de build, live-test e bridge de pacote que o Knip não consegue resolver estaticamente.
## Encaminhamento de atividade do ClawSweeper
@ -75,20 +75,20 @@ O workflow tem quatro lanes:
- `clawsweeper_item` para solicitações exatas de revisão de issues e pull requests;
- `clawsweeper_comment` para comandos explícitos do ClawSweeper em comentários de issues;
- `clawsweeper_commit_review` para solicitações de revisão no nível de commit em pushes para `main`;
- `clawsweeper_commit_review` para solicitações de revisão em nível de commit em pushes para `main`;
- `github_activity` para atividade geral do GitHub que o agente ClawSweeper pode inspecionar.
A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos de comentários ou revisões quando presentes. Ela evita intencionalmente encaminhar o corpo completo do Webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper.
A lane `github_activity` encaminha apenas metadados normalizados: tipo de evento, ação, ator, repositório, número do item, URL, título, estado e trechos curtos para comentários ou reviews quando presentes. Ela evita intencionalmente encaminhar o corpo completo do webhook. O workflow receptor em `openclaw/clawsweeper` é `.github/workflows/github-activity.yml`, que publica o evento normalizado no hook do OpenClaw Gateway para o agente ClawSweeper.
Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino do Discord no prompt e deve publicar em `#clawsweeper` somente quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, atividade repetitiva de bots, ruído de Webhook duplicado e tráfego normal de revisão devem resultar em `NO_REPLY`.
Atividade geral é observação, não entrega por padrão. O agente ClawSweeper recebe o destino Discord em seu prompt e deve publicar em `#clawsweeper` apenas quando o evento for surpreendente, acionável, arriscado ou operacionalmente útil. Aberturas rotineiras, edições, ruído de bots, ruído duplicado de webhook e tráfego normal de reviews devem resultar em `NO_REPLY`.
Trate títulos, comentários, corpos, texto de revisão, nomes de branches e mensagens de commit do GitHub como dados não confiáveis em todo este caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou o runtime do agente.
Trate títulos, comentários, corpos, texto de reviews, nomes de branches e mensagens de commit do GitHub como dados não confiáveis ao longo de todo esse caminho. Eles são entrada para sumarização e triagem, não instruções para o workflow ou runtime do agente.
## Disparos manuais
Os dispatches manuais de CI executam o mesmo grafo de jobs que a CI normal, mas forçam a ativação de toda lane com escopo não Android: shards Linux Node, shards de plugins agrupados, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de documentação, Skills Python, Windows, macOS e i18n da Control UI. Dispatches manuais independentes de CI executam apenas Android com `include_android=true`; o guarda-chuva completo de release habilita Android passando `include_android=true`. Verificações estáticas de pré-release de Plugin, o shard exclusivo de release `agentic-plugins`, a varredura completa em lote de extensions e as lanes Docker de pré-release de Plugin ficam excluídos da CI. A suíte Docker de pré-release é executada somente quando `Full Release Validation` dispara o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado.
Os despachos manuais de CI executam o mesmo grafo de jobs da CI normal, mas forçam todos os lanes com escopo não Android: shards Linux Node, shards de plugins agrupados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS e i18n da Control UI. Despachos manuais independentes de CI executam apenas Android com `include_android=true`; o guarda-chuva de release completo habilita Android passando `include_android=true`. Verificações estáticas de pré-lançamento de Plugin, o shard exclusivo de release `agentic-plugins`, a varredura completa em lote de plugins e lanes Docker de pré-lançamento de Plugin são excluídos da CI. A suíte Docker de pré-lançamento é executada apenas quando `Full Release Validation` despacha o workflow separado `Plugin Prerelease` com o gate de validação de release habilitado.
Execuções manuais usam um grupo de concorrência único para que uma suíte completa de candidato a release não seja cancelada por outra execução de push ou PR na mesma ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA completo de commit usando o arquivo de workflow da ref de dispatch selecionada.
Execuções manuais usam um grupo de concorrência exclusivo para que uma suíte completa de candidato a release não seja cancelada por outra execução de push ou PR no mesmo ref. A entrada opcional `target_ref` permite que um chamador confiável execute esse grafo contra uma branch, tag ou SHA de commit completo enquanto usa o arquivo de workflow do ref de despacho selecionado.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -96,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
## Executores
## Runners
| Executor | Jobs |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, jobs rápidos de segurança e agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/plugins agrupados, verificações fragmentadas de contratos de canal, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de documentação, Skills Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado pelo GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensions mais leves, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de plugins agrupados, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU a ponto de 8 vCPU custar mais do que economizou); builds Docker de install-smoke (o tempo de fila de 32 vCPU custou mais do que economizou) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks voltam para `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks voltam para `macos-latest` |
| Runner | Jobs |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, jobs e agregados de segurança rápidos (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/agrupados, verificações de contrato de canal em shards, shards de `check` exceto lint, shards e agregados de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills Python, workflow-sanity, labeler, auto-response; o preflight de install-smoke também usa Ubuntu hospedado no GitHub para que a matriz do Blacksmith possa entrar na fila mais cedo |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shards de extensão mais leves, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shards de testes Linux Node, shards de testes de Plugin agrupado, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU o bastante para que 8 vCPU custassem mais do que economizavam); builds Docker de install-smoke (o tempo de fila de 32 vCPU custou mais do que economizou) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` em `openclaw/openclaw`; forks usam `macos-latest` como fallback |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` em `openclaw/openclaw`; forks usam `macos-latest` como fallback |
## Equivalentes locais
@ -135,9 +135,9 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md
```
## Desempenho do OpenClaw
## Performance do OpenClaw
`OpenClaw Performance` é o workflow de desempenho de produto/runtime. Ele é executado diariamente em `main` e pode ser disparado manualmente:
`OpenClaw Performance` é o workflow de performance do produto/runtime. Ele é executado diariamente em `main` e pode ser despachado manualmente:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,25 +145,32 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
O dispatch manual normalmente mede a ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Os caminhos de relatórios publicados e ponteiros mais recentes são indexados pela ref testada, e cada `index.md` registra a ref/SHA testada, a ref/SHA do workflow, a ref do Kova, perfil, modo de autenticação da lane, modelo, contagem de repetições e filtros de cenário.
O despacho manual normalmente mede o ref do workflow. Defina `target_ref` para medir uma tag de release ou outra branch com a implementação atual do workflow. Caminhos de relatórios publicados e ponteiros mais recentes são indexados pelo ref testado, e cada `index.md` registra o ref/SHA testado, ref/SHA do workflow, ref do Kova, perfil, modo de autenticação do lane, modelo, contagem de repetições e filtros de cenário.
O workflow instala OCM a partir de uma release fixada e Kova a partir de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes:
O workflow instala o OCM a partir de uma release fixada e o Kova a partir de `openclaw/Kova` na entrada fixada `kova_ref`, depois executa três lanes:
- `mock-provider`: cenários diagnósticos do Kova contra um runtime de build local com autenticação fake determinística compatível com OpenAI.
- `mock-deep-profile`: profiling de CPU/heap/trace para pontos críticos de inicialização, Gateway e turnos de agente.
- `mock-provider`: cenários diagnósticos do Kova contra um runtime de build local com autenticação falsa determinística compatível com OpenAI.
- `mock-deep-profile`: profiling de CPU/heap/trace para hotspots de inicialização, Gateway e turno de agente.
- `live-gpt54`: um turno real de agente OpenAI `openai/gpt-5.4`, ignorado quando `OPENAI_API_KEY` não está disponível.
A lane mock-provider também executa sondagens de origem nativas do OpenClaw após a passagem do Kova: tempo de inicialização e memória do Gateway nos casos de inicialização padrão, com hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock-OpenAI; e comandos de inicialização da CLI contra o Gateway iniciado. O resumo Markdown da sondagem de origem fica em `source/index.md` no pacote de relatório, com JSON bruto ao lado.
O lane mock-provider também executa sondagens de origem nativas do OpenClaw após a passagem do Kova: tempo de boot e memória do Gateway em casos de inicialização padrão, com hook e com 50 plugins; loops repetidos de hello `channel-chat-baseline` com mock-OpenAI; e comandos de inicialização da CLI contra o Gateway inicializado. O resumo Markdown da sondagem de origem fica em `source/index.md` no pacote do relatório, com JSON bruto ao lado.
Cada lane envia artefatos do GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também faz commit de `report.json`, `report.md`, pacotes, `index.md` e artefatos de sondagem de origem em `openclaw/clawgrit-reports` sob `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. O ponteiro atual da ref testada é gravado como `openclaw-performance/<tested-ref>/latest-<lane>.json`.
Cada lane envia artefatos do GitHub. Quando `CLAWGRIT_REPORTS_TOKEN` está configurado, o workflow também faz commit de `report.json`, `report.md`, pacotes, `index.md` e artefatos de sondagem de origem em `openclaw/clawgrit-reports` sob `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. O ponteiro atual do ref testado é escrito como `openclaw-performance/<tested-ref>/latest-<lane>.json`.
## Validação Completa de Release
## Full Release Validation
`Full Release Validation` é o workflow manual guarda-chuva para "executar tudo antes da release." Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para comprovação exclusiva de release de plugin/pacote/estática/Docker e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release Docker, live/E2E, OpenWebUI, paridade QA Lab, Matrix e lanes Telegram. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Depois da publicação, passe `npm_telegram_package_spec` para reexecutar a mesma lane de pacote Telegram contra o pacote npm publicado.
`Full Release Validation` é o workflow guarda-chuva manual para "executar tudo antes da release". Ele aceita uma branch, tag ou SHA de commit completo, despacha o workflow manual `CI` com esse alvo, despacha `Plugin Prerelease` para prova exclusiva de release de plugin/pacote/estática/Docker e despacha `OpenClaw Release Checks` para install smoke, aceitação de pacote, verificações de pacote entre sistemas operacionais, paridade do QA Lab, Matrix e lanes do Telegram. Execuções estáveis/padrão mantêm cobertura exaustiva live/E2E e de caminho de release Docker atrás de `run_release_soak=true`; `release_profile=full` força essa cobertura de soak para que validações amplas de advisory continuem amplas. Com `rerun_group=all` e `release_profile=full`, ele também executa `NPM Telegram Beta E2E` contra o artefato `release-package-under-test` das verificações de release. Após publicar, passe `npm_telegram_package_spec` para reexecutar o mesmo lane de pacote Telegram contra o pacote npm publicado.
Consulte [validação completa de release](/pt-BR/reference/full-release-validation) para a matriz de estágios, nomes exatos de jobs do workflow, diferenças de perfil, artefatos e identificadores de reexecução focada.
Consulte [Validação completa de release](/pt-BR/reference/full-release-validation) para a
matriz de estágios, nomes exatos dos jobs de workflow, diferenças de perfil, artefatos e
identificadores de reexecução focada.
`OpenClaw Release Publish` é o workflow manual mutável de release. Dispare-o de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o preflight npm do OpenClaw tiver sido concluído com sucesso. Ele verifica `pnpm plugins:sync:check`, dispara `Plugin NPM Release` para todos os pacotes de Plugin publicáveis, dispara `Plugin ClawHub Release` para o mesmo SHA de release e só então dispara `OpenClaw NPM Release` com o `preflight_run_id` salvo.
`OpenClaw Release Publish` é o workflow manual mutável de release. Despache-o
a partir de `release/YYYY.M.D` ou `main` depois que a tag de release existir e depois que o
preflight npm do OpenClaw tiver sido bem-sucedido. Ele verifica `pnpm plugins:sync:check`,
despacha `Plugin NPM Release` para todos os pacotes de Plugin publicáveis, despacha
`Plugin ClawHub Release` para o mesmo SHA de release e só então despacha
`OpenClaw NPM Release` com o `preflight_run_id` salvo.
```bash
gh workflow run openclaw-release-publish.yml \
@ -173,35 +180,45 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Para comprovação de commit fixado em uma branch que se move rápido, use o helper em vez de `gh workflow run ... --ref main -f ref=<sha>`:
Para prova de commit fixado em uma branch que muda rapidamente, use o helper em vez de
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
pnpm ci:full-release --sha <full-sha>
```
Refs de dispatch de workflow do GitHub devem ser branches ou tags, não SHAs brutos de commit. O helper envia uma branch temporária `release-ci/<sha>-...` no SHA alvo, dispara `Full Release Validation` a partir dessa ref fixada, verifica se cada `headSha` de workflow filho corresponde ao alvo e exclui a branch temporária quando a execução termina. O verificador guarda-chuva também falha se qualquer workflow filho tiver executado em um SHA diferente.
Refs de despacho de workflow do GitHub devem ser branches ou tags, não SHAs de commit brutos. O
helper envia uma branch temporária `release-ci/<sha>-...` no SHA de destino,
despacha `Full Release Validation` a partir desse ref fixado, verifica se cada `headSha`
de workflow filho corresponde ao alvo e exclui a branch temporária quando a
execução termina. O verificador guarda-chuva também falha se qualquer workflow filho for executado em um
SHA diferente.
`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os fluxos de trabalho manuais de lançamento usam `stable` por padrão; use `full` somente quando você intencionalmente quiser a matriz ampla consultiva de provedores/mídia.
`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os fluxos de trabalho manuais de lançamento usam `stable` por padrão; use `full` apenas quando você intencionalmente quiser a ampla matriz consultiva de provedores/mídia. `run_release_soak` controla se as verificações de lançamento estáveis/padrão executam o soak exaustivo live/E2E e do caminho de lançamento do Docker; `full` força o soak.
- `minimum` mantém as linhas OpenAI/núcleo críticas para lançamento mais rápidas.
- `minimum` mantém as lanes críticas de lançamento mais rápidas de OpenAI/core.
- `stable` adiciona o conjunto estável de provedores/backends.
- `full` executa a matriz ampla consultiva de provedores/mídia.
- `full` executa a ampla matriz consultiva de provedores/mídia.
O guarda-chuva registra os ids das execuções filhas disparadas, e o trabalho final `Verify full validation` verifica novamente as conclusões atuais das execuções filhas e acrescenta tabelas dos trabalhos mais lentos de cada execução filha. Se um fluxo de trabalho filho for reexecutado e ficar verde, reexecute apenas o trabalho verificador pai para atualizar o resultado guarda-chuva e o resumo de tempos.
O guarda-chuva registra os ids das execuções filhas despachadas, e o job final `Verify full validation` verifica novamente as conclusões atuais das execuções filhas e acrescenta tabelas dos jobs mais lentos para cada execução filha. Se um fluxo de trabalho filho for reexecutado e ficar verde, reexecute apenas o job verificador pai para atualizar o resultado do guarda-chuva e o resumo de tempos.
Para recuperação, tanto `Full Release Validation` quanto `OpenClaw Release Checks` aceitam `rerun_group`. Use `all` para um candidato a lançamento, `ci` apenas para o filho de CI completo normal, `plugin-prerelease` apenas para o filho de pré-lançamento de plugins, `release-checks` para todos os filhos de lançamento, ou um grupo mais estreito: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` no guarda-chuva. Isso mantém limitada a reexecução de uma caixa de lançamento com falha após uma correção focada.
Para recuperação, tanto `Full Release Validation` quanto `OpenClaw Release Checks` aceitam `rerun_group`. Use `all` para um candidato a lançamento, `ci` somente para o filho normal de CI completo, `plugin-prerelease` somente para o filho de pré-lançamento de plugin, `release-checks` para todos os filhos de lançamento, ou um grupo mais estreito: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` ou `npm-telegram` no guarda-chuva. Isso mantém limitada a reexecução de uma caixa de lançamento com falha após uma correção focada. Para uma lane cross-OS com falha, combine `rerun_group=cross-os` com `cross_os_suite_filter`, por exemplo `windows/packaged-upgrade`; comandos cross-OS longos emitem linhas de heartbeat, e resumos packaged-upgrade incluem tempos por fase. Lanes de verificação de lançamento de QA são consultivas, então falhas somente de QA avisam, mas não bloqueiam o verificador de release-check.
`OpenClaw Release Checks` usa a ref confiável do fluxo de trabalho para resolver a ref selecionada uma vez em um tarball `release-package-under-test`, depois passa esse artefato tanto para o fluxo de trabalho Docker live/E2E do caminho de lançamento quanto para o shard de aceitação de pacote. Isso mantém os bytes do pacote consistentes entre as caixas de lançamento e evita reempacotar o mesmo candidato em vários trabalhos filhos.
`OpenClaw Release Checks` usa a referência confiável do fluxo de trabalho para resolver a ref selecionada uma vez em um tarball `release-package-under-test`, depois passa esse artefato para verificações cross-OS e Package Acceptance, além do fluxo de trabalho Docker live/E2E do caminho de lançamento quando a cobertura de soak é executada. Isso mantém os bytes do pacote consistentes entre caixas de lançamento e evita reempacotar o mesmo candidato em vários jobs filhos.
Execuções duplicadas de `Full Release Validation` para `ref=main` e `rerun_group=all` substituem o guarda-chuva mais antigo. O monitor pai cancela qualquer fluxo de trabalho filho que já tenha disparado quando o pai é cancelado, então a validação mais nova da main não fica atrás de uma execução obsoleta de duas horas de verificações de lançamento. A validação de branch/tag de lançamento e grupos de reexecução focados mantêm `cancel-in-progress: false`.
Execuções duplicadas de `Full Release Validation` para `ref=main` e `rerun_group=all`
substituem o guarda-chuva mais antigo. O monitor pai cancela qualquer fluxo de trabalho filho que
já tenha despachado quando o pai é cancelado, então a validação mais nova de main
não fica atrás de uma execução obsoleta de duas horas de release-check. Validações de branch/tag
de lançamento e grupos de reexecução focada mantêm `cancel-in-progress: false`.
## Shards live e E2E
## Fragmentos live e E2E
O filho live/E2E de lançamento mantém cobertura ampla nativa de `pnpm test:live`, mas a executa como shards nomeados por meio de `scripts/test-live-shard.mjs` em vez de um trabalho serial:
O filho live/E2E de lançamento mantém ampla cobertura nativa de `pnpm test:live`, mas a executa como fragmentos nomeados por meio de `scripts/test-live-shard.mjs` em vez de um job serial:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- trabalhos `native-live-src-gateway-profiles` filtrados por provedor
- jobs `native-live-src-gateway-profiles` filtrados por provedor
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -209,57 +226,59 @@ O filho live/E2E de lançamento mantém cobertura ampla nativa de `pnpm test:liv
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- shards de áudio/vídeo de mídia divididos e shards de música filtrados por provedor
- fragmentos separados de mídia de áudio/vídeo e fragmentos de música filtrados por provedor
Isso mantém a mesma cobertura de arquivos enquanto torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes de shard agregados `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` continuam válidos para reexecuções manuais únicas.
Isso mantém a mesma cobertura de arquivos e torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes agregados de fragmentos `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` continuam válidos para reexecuções manuais únicas.
Os shards nativos de mídia live executam em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo fluxo de trabalho `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; os trabalhos de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners Blacksmith normais — trabalhos em contêiner são o lugar errado para iniciar testes Docker aninhados.
Os fragmentos nativos de mídia live são executados em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo fluxo de trabalho `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; jobs de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners normais da Blacksmith — jobs em contêiner são o lugar errado para iniciar testes Docker aninhados.
Shards live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:<sha>` por commit selecionado. O fluxo de trabalho live de lançamento cria e envia essa imagem uma vez, depois os shards de modelo live Docker, Gateway divididos por provedor, backend CLI, vínculo ACP e harness Codex executam com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shards Docker do Gateway carregam limites explícitos de `timeout` em nível de script abaixo do timeout do trabalho do fluxo de trabalho, para que um contêiner travado ou caminho de limpeza falhe rápido em vez de consumir todo o orçamento das verificações de lançamento. Se esses shards recriarem o alvo Docker de código-fonte completo independentemente, a execução de lançamento está mal configurada e desperdiçará tempo de relógio com builds duplicados de imagem.
Fragmentos live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:<sha>` por commit selecionado. O fluxo de trabalho live de lançamento cria e envia essa imagem uma vez, depois os fragmentos de modelo live Docker, Gateway dividido por provedor, backend de CLI, vínculo ACP e harness Codex executam com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Fragmentos Docker de Gateway carregam limites explícitos de `timeout` no nível do script abaixo do timeout do job do fluxo de trabalho para que um contêiner travado ou caminho de limpeza falhe rápido em vez de consumir todo o orçamento de release-check. Se esses fragmentos reconstruírem independentemente o alvo Docker completo do código-fonte, a execução de lançamento está configurada incorretamente e desperdiçará tempo de relógio em builds duplicados de imagem.
## Aceitação de Pacote
## Package Acceptance
Use `Package Acceptance` quando a pergunta for "este pacote OpenClaw instalável funciona como produto?" Ela é diferente da CI normal: a CI normal valida a árvore de código-fonte, enquanto a aceitação de pacote valida um único tarball pelo mesmo harness Docker E2E que os usuários exercitam após instalar ou atualizar.
Use `Package Acceptance` quando a pergunta for “este pacote instalável do OpenClaw funciona como produto?”. Ele é diferente do CI normal: o CI normal valida a árvore de código-fonte, enquanto o package acceptance valida um único tarball pelo mesmo harness Docker E2E que usuários exercitam após instalar ou atualizar.
### Trabalhos
### Jobs
1. `resolve_package` faz checkout de `workflow_ref`, resolve um candidato de pacote, grava `.artifacts/docker-e2e-package/openclaw-current.tgz`, grava `.artifacts/docker-e2e-package/package-candidate.json`, envia ambos como o artefato `package-under-test` e imprime a origem, ref do fluxo de trabalho, ref do pacote, versão, SHA-256 e perfil no resumo da etapa do GitHub.
2. `docker_acceptance` chama `openclaw-live-and-e2e-checks-reusable.yml` com `ref=workflow_ref` e `package_artifact_name=package-under-test`. O fluxo de trabalho reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker de resumo de pacote quando necessário e executa as linhas Docker selecionadas contra esse pacote em vez de empacotar o checkout do fluxo de trabalho. Quando um perfil seleciona vários `docker_lanes` direcionados, o fluxo de trabalho reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas linhas como trabalhos Docker direcionados paralelos com artefatos únicos.
3. `package_telegram` opcionalmente chama `NPM Telegram Beta E2E`. Ele executa quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando Package Acceptance resolveu um; um disparo autônomo do Telegram ainda pode instalar uma especificação npm publicada.
4. `summary` falha o fluxo de trabalho se a resolução do pacote, a aceitação Docker ou a linha opcional do Telegram falhar.
1. `resolve_package` faz checkout de `workflow_ref`, resolve um candidato de pacote, escreve `.artifacts/docker-e2e-package/openclaw-current.tgz`, escreve `.artifacts/docker-e2e-package/package-candidate.json`, envia ambos como o artefato `package-under-test` e imprime a fonte, a ref do fluxo de trabalho, a ref do pacote, a versão, o SHA-256 e o perfil no resumo de etapa do GitHub.
2. `docker_acceptance` chama `openclaw-live-and-e2e-checks-reusable.yml` com `ref=workflow_ref` e `package_artifact_name=package-under-test`. O fluxo de trabalho reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker com digest do pacote quando necessário e executa as lanes Docker selecionadas contra esse pacote em vez de empacotar o checkout do fluxo de trabalho. Quando um perfil seleciona vários `docker_lanes` direcionados, o fluxo de trabalho reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas lanes como jobs Docker direcionados paralelos com artefatos únicos.
3. `package_telegram` opcionalmente chama `NPM Telegram Beta E2E`. Ele é executado quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando Package Acceptance resolveu um; um despacho autônomo do Telegram ainda pode instalar uma especificação npm publicada.
4. `summary` falha o fluxo de trabalho se a resolução do pacote, a aceitação Docker ou a lane opcional do Telegram falhar.
### Origens de candidatos
### Fontes de candidatos
- `source=npm` aceita somente `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isso para aceitação de pré-lançamento/estável publicado.
- `source=ref` empacota um branch, tag ou SHA completo de commit confiável em `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável pelo histórico de branches do repositório ou por uma tag de lançamento, instala dependências em uma árvore de trabalho destacada e o empacota com `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` aceita apenas `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isto para aceitação de pré-lançamento/estável publicado.
- `source=ref` empacota uma branch, tag ou SHA completo de commit confiável de `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável pelo histórico de branches do repositório ou por uma tag de lançamento, instala dependências em uma worktree destacada e o empacota com `scripts/package-openclaw-for-docker.mjs`.
- `source=url` baixa um `.tgz` HTTPS; `package_sha256` é obrigatório.
- `source=artifact` baixa um `.tgz` de `artifact_run_id` e `artifact_name`; `package_sha256` é opcional, mas deve ser fornecido para artefatos compartilhados externamente.
Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código confiável de fluxo de trabalho/harness que executa o teste. `package_ref` é o commit de origem que é empacotado quando `source=ref`. Isso permite que o harness de teste atual valide commits de origem confiáveis mais antigos sem executar lógica antiga de fluxo de trabalho.
Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código confiável do fluxo de trabalho/harness que executa o teste. `package_ref` é o commit de origem que é empacotado quando `source=ref`. Isso permite que o harness de teste atual valide commits de origem confiáveis mais antigos sem executar lógica antiga de fluxo de trabalho.
### Perfis de suíte
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
- `product` — `package` mais `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — blocos completos Docker do caminho de lançamento com OpenWebUI
- `full` — blocos completos do caminho de lançamento Docker com OpenWebUI
- `custom` — `docker_lanes` exatos; obrigatório quando `suite_profile=custom`
O perfil `package` usa cobertura offline de plugins para que a validação de pacote publicado não dependa da disponibilidade live do ClawHub. A linha opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho de especificação npm publicada para disparos autônomos.
O perfil `package` usa cobertura offline de plugins para que a validação de pacote publicado não dependa da disponibilidade live do ClawHub. A lane opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho de especificação npm publicada para despachos autônomos.
Para a política dedicada de testes de atualização e plugins, incluindo comandos locais, linhas Docker, entradas de Package Acceptance, padrões de lançamento e triagem de falhas, consulte [Testar atualizações e plugins](/pt-BR/help/testing-updates-plugins).
Para a política dedicada de testes de atualização e plugin, incluindo comandos locais,
lanes Docker, entradas de Package Acceptance, padrões de lançamento e triagem de falhas,
consulte [Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins).
As verificações de lançamento chamam Package Acceptance com `source=artifact`, o artefato de pacote de lançamento preparado, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues` e `telegram_mode=mock-openai`. Isso mantém a prova de migração de pacote, atualização, limpeza de dependência obsoleta de plugin, reparo de instalação de plugin configurado, plugin offline, atualização de plugin e Telegram no mesmo tarball de pacote resolvido. Defina `package_acceptance_package_spec` em Full Release Validation ou OpenClaw Release Checks para executar essa mesma matriz contra um pacote npm enviado em vez do artefato criado a partir do SHA. As verificações de lançamento entre sistemas operacionais ainda cobrem integração inicial específica de SO, instalador e comportamento de plataforma; a validação de produto de pacote/atualização deve começar com Package Acceptance. A linha Docker `published-upgrade-survivor` valida uma linha de base de pacote publicado por execução. Em Package Acceptance, o tarball `package-under-test` resolvido é sempre o candidato, e `published_upgrade_survivor_baseline` seleciona a linha de base publicada de fallback, com padrão `openclaw@latest`; comandos de reexecução de linha com falha preservam essa linha de base. Defina `published_upgrade_survivor_baselines=all-since-2026.4.23` para expandir a CI de Full Release por todos os lançamentos npm estáveis de `2026.4.23` até `latest`; `release-history` continua disponível para amostragem manual mais ampla com a âncora pré-data mais antiga. Defina `published_upgrade_survivor_scenarios=reported-issues` para expandir as mesmas linhas de base por fixtures em formato de issues para configuração do Feishu, arquivos bootstrap/persona preservados, instalações configuradas de plugin OpenClaw, caminhos de log com til e raízes obsoletas de dependência de plugins legados. O fluxo de trabalho separado `Update Migration` usa a linha Docker `update-migration` com `all-since-2026.4.23` e `plugin-deps-cleanup` quando a pergunta é limpeza exaustiva de atualização publicada, não a amplitude normal da CI de Full Release. Execuções agregadas locais podem passar especificações exatas de pacote com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, manter uma única linha com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, como `openclaw@2026.4.15`, ou definir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` para a matriz de cenários. A linha publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, registra etapas da receita em `summary.json` e sonda `/healthz`, `/readyz`, além do status RPC após o início do Gateway. As linhas frescas empacotadas e de instalador do Windows também verificam que um pacote instalado consegue importar uma substituição de controle de navegador de um caminho Windows absoluto bruto. O smoke de turno de agente OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, `openai/gpt-5.4`, para que a prova de instalação e Gateway permaneça em um modelo de teste GPT-5 enquanto evita padrões GPT-4.x.
As verificações de lançamento chamam Package Acceptance com `source=artifact`, o artefato de pacote de lançamento preparado, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'` e `telegram_mode=mock-openai`. Isso mantém a prova de migração de pacote, atualização, limpeza de dependência obsoleta de plugin, reparo de instalação de plugin configurado, plugin offline, atualização de plugin e Telegram no mesmo tarball de pacote resolvido. Defina `package_acceptance_package_spec` em Full Release Validation ou OpenClaw Release Checks para executar essa mesma matriz contra um pacote npm enviado em vez do artefato criado a partir do SHA. Verificações de lançamento cross-OS ainda cobrem onboarding, instalador e comportamento de plataforma específicos de SO; a validação de produto de pacote/atualização deve começar com Package Acceptance. A lane Docker `published-upgrade-survivor` valida uma linha de base de pacote publicado por execução no caminho de lançamento bloqueante. Em Package Acceptance, o tarball `package-under-test` resolvido é sempre o candidato, e `published_upgrade_survivor_baseline` seleciona a linha de base publicada alternativa, com padrão `openclaw@latest`; comandos de reexecução de lane com falha preservam essa linha de base. Full Release Validation com `run_release_soak=true` ou `release_profile=full` define `published_upgrade_survivor_baselines=all-since-2026.4.23` e `published_upgrade_survivor_scenarios=reported-issues` para expandir por todos os lançamentos npm estáveis de `2026.4.23` até `latest` e fixtures com formato de issues para configuração do Feishu, arquivos bootstrap/persona preservados, instalações configuradas de plugins OpenClaw, caminhos de log com til e raízes obsoletas de dependências legadas de plugins. O fluxo de trabalho separado `Update Migration` usa a lane Docker `update-migration` com `all-since-2026.4.23` e `plugin-deps-cleanup` quando a pergunta é limpeza exaustiva de atualização publicada, não a amplitude normal do Full Release CI. Execuções agregadas locais podem passar especificações exatas de pacote com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, manter uma única lane com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, como `openclaw@2026.4.15`, ou definir `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` para a matriz de cenários. A lane publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, registra etapas da receita em `summary.json` e sonda `/healthz`, `/readyz`, além do status RPC após o início do Gateway. As lanes fresh empacotada e de instalador do Windows também verificam se um pacote instalado consegue importar uma substituição de controle de navegador de um caminho absoluto bruto do Windows. O smoke cross-OS de turno de agente OpenAI usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, `openai/gpt-5.4`, para que a prova de instalação e Gateway permaneça em um modelo de teste GPT-5 evitando padrões GPT-4.x.
### Janelas de compatibilidade legada
Package Acceptance tem janelas limitadas de compatibilidade legada para pacotes já publicados. Pacotes até `2026.4.25`, incluindo `2026.4.25-beta.*`, podem usar o caminho de compatibilidade:
- entradas QA privadas conhecidas em `dist/postinstall-inventory.json` podem apontar para arquivos omitidos do tarball;
- `doctor-switch` pode pular o subcaso de persistência de `gateway install --wrapper` quando o pacote não expõe essa flag;
- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes da fixture git falsa derivada do tarball e pode registrar `update.channel` persistido ausente;
- entradas privadas de QA conhecidas em `dist/postinstall-inventory.json` podem apontar para arquivos omitidos do tarball;
- `doctor-switch` pode pular o subcaso de persistência `gateway install --wrapper` quando o pacote não expõe essa flag;
- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes do fixture git falso derivado do tarball e pode registrar `update.channel` persistido ausente;
- smokes de plugin podem ler locais legados de registro de instalação ou aceitar persistência ausente de registro de instalação do marketplace;
- `plugin-update` pode permitir migração de metadados de configuração enquanto ainda exige que o registro de instalação e o comportamento de não reinstalação permaneçam inalterados.
- `plugin-update` pode permitir migração de metadados de configuração enquanto ainda exige que o registro de instalação e o comportamento de não reinstalar permaneçam inalterados.
O pacote publicado `2026.4.26` também pode avisar sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores devem satisfazer os contratos modernos; as mesmas condições falham em vez de avisar ou pular.
@ -304,110 +323,110 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo de `resolve_package` para confirmar a origem do pacote, a versão e o SHA-256. Em seguida, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de reexecução. Prefira reexecutar o perfil de pacote com falha ou as lanes Docker exatas em vez de reexecutar a validação completa de lançamento.
Ao depurar uma execução de aceitação de pacote com falha, comece pelo resumo `resolve_package` para confirmar a origem, a versão e o SHA-256 do pacote. Em seguida, inspecione a execução filha `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lanes, tempos de fase e comandos de reexecução. Prefira reexecutar o perfil de pacote com falha ou as lanes Docker exatas em vez de reexecutar a validação completa de release.
## Smoke de instalação
O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio do próprio job `preflight`. Ele divide a cobertura smoke em `run_fast_install_smoke` e `run_full_install_smoke`.
O workflow separado `Install Smoke` reutiliza o mesmo script de escopo por meio de seu próprio job `preflight`. Ele divide a cobertura de smoke em `run_fast_install_smoke` e `run_full_install_smoke`.
- **Caminho rápido** é executado para pull requests que tocam superfícies Docker/pacote, alterações em pacote/manifesto de Plugin empacotado ou superfícies centrais de Plugin/canal/Gateway/Plugin SDK exercitadas pelos jobs de smoke Docker. Alterações somente de código-fonte em Plugin empacotado, edições somente de teste e edições somente de documentação não reservam workers Docker. O caminho rápido cria a imagem do Dockerfile raiz uma vez, verifica a CLI, executa o smoke de CLI de exclusão de agentes em workspace compartilhado, executa o E2E de rede do Gateway em contêiner, verifica um argumento de build de extensão empacotada e executa o perfil Docker limitado de Plugin empacotado sob um timeout agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente).
- **Caminho completo** mantém a cobertura de instalação de pacote QR e Docker/atualização do instalador para execuções agendadas noturnas, disparos manuais, verificações de lançamento por chamada de workflow e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, o install-smoke prepara ou reutiliza uma imagem smoke GHCR do Dockerfile raiz para o SHA de destino e, então, executa a instalação de pacote QR, smokes do Dockerfile raiz/Gateway, smokes de instalador/atualização e o E2E Docker rápido de Plugin empacotado como jobs separados para que o trabalho de instalador não espere atrás dos smokes da imagem raiz.
- **Caminho rápido** é executado para pull requests que tocam superfícies Docker/pacote, alterações em pacote/manifesto de plugin incluído ou superfícies principais de plugin/canal/gateway/Plugin SDK que os jobs de smoke Docker exercitam. Alterações apenas em código-fonte de plugins incluídos, edições apenas de testes e edições apenas de documentação não reservam workers Docker. O caminho rápido compila a imagem do Dockerfile raiz uma vez, verifica a CLI, executa o smoke da CLI de exclusão de agents em workspace compartilhado, executa o e2e de gateway-network do contêiner, verifica um argumento de build de extensão incluída e executa o perfil Docker limitado de plugin incluído sob um timeout agregado de comando de 240 segundos (cada execução Docker de cenário é limitada separadamente).
- **Caminho completo** mantém a instalação de pacote QR e a cobertura Docker/de atualização do instalador para execuções noturnas agendadas, dispatches manuais, verificações de release por workflow-call e pull requests que realmente tocam superfícies de instalador/pacote/Docker. No modo completo, install-smoke prepara ou reutiliza uma imagem de smoke GHCR do Dockerfile raiz para o SHA de destino, depois executa instalação de pacote QR, smokes do Dockerfile raiz/gateway, smokes de instalador/atualização e o Docker E2E rápido de plugin incluído como jobs separados, para que o trabalho do instalador não espere atrás dos smokes da imagem raiz.
Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de alterações solicitaria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke completo de instalação para a validação noturna ou de lançamento.
Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo de alterações pediria cobertura completa em um push, o workflow mantém o smoke Docker rápido e deixa o smoke completo de instalação para a validação noturna ou de release.
O smoke lento de provedor de imagem com instalação global via Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele é executado na agenda noturna e a partir do workflow de verificações de lançamento, e disparos manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação.
O smoke lento do provedor de imagens com instalação global Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele é executado na agenda noturna e a partir do workflow de verificações de release, e dispatches manuais de `Install Smoke` podem optar por incluí-lo, mas pull requests e pushes para `main` não. Testes Docker de QR e instalador mantêm seus próprios Dockerfiles focados em instalação.
## E2E Docker local
## Docker E2E local
`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e cria duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e compila duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
- um runner básico Node/Git para lanes de instalador/atualização/dependência de Plugin;
- uma imagem funcional que instala o mesmo tarball em `/app` para lanes de funcionalidade normal.
- um runner Node/Git básico para lanes de instalador/atualização/dependência de plugin;
- uma imagem funcional que instala o mesmo tarball em `/app` para lanes de funcionalidade normais.
As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois executa as lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`.
As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica do planejador fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O agendador seleciona a imagem por lane com `OPENCLAW_DOCKER_E2E_BARE_IMAGE` e `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, depois executa lanes com `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Parâmetros ajustáveis
### Ajustes
| Variável | Padrão | Finalidade |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live concorrentes para que provedores não apliquem throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes concorrentes de instalação npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes concorrentes com múltiplos serviços. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo escalonado entre inícios de lanes para evitar tempestades de criação no daemon Docker; defina `0` para sem escalonamento. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais estritos. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista separada por vírgulas de lanes exatas; pula o smoke de limpeza para que agentes possam reproduzir uma lane com falha. |
| Variável | Padrão | Finalidade |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Contagem de slots do pool principal para lanes normais. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Contagem de slots do pool final sensível a provedores. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes live simultâneas para que os provedores não façam throttle. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Limite de lanes simultâneas de instalação npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Limite de lanes simultâneas com múltiplos serviços. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Intervalo entre inícios de lanes para evitar tempestades de criação no daemon Docker; defina `0` para não escalonar. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout de fallback por lane (120 minutos); lanes live/finais selecionadas usam limites mais rígidos. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do agendador sem executar lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista de lanes exatas separadas por vírgulas; pula o smoke de limpeza para que agents possam reproduzir uma lane com falha. |
Uma lane mais pesada que seu limite efetivo ainda pode começar de um pool vazio e, então, roda sozinha até liberar capacidade. Os preflights agregados locais verificam o Docker, removem contêineres E2E obsoletos do OpenClaw, emitem status de lanes ativas, persistem tempos de lanes para ordenação da mais longa para a mais curta e param de agendar novas lanes em pool após a primeira falha por padrão.
Uma lane mais pesada do que seu limite efetivo ainda pode iniciar a partir de um pool vazio, depois roda sozinha até liberar capacidade. Os preflights agregados locais verificam o Docker, removem contêineres OpenClaw E2E obsoletos, emitem status de lanes ativas, persistem tempos de lanes para ordenação pelas mais longas primeiro e, por padrão, param de agendar novas lanes em pool após a primeira falha.
### Workflow live/E2E reutilizável
O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual pacote, tipo de imagem, imagem live, lane e cobertura de credenciais são necessários. `scripts/docker-e2e.mjs` então converte esse plano em saídas e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; cria e envia imagens Docker E2E bare/funcionais GHCR marcadas com digest de pacote por meio do cache de camadas Docker do Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidas ou imagens existentes com digest de pacote em vez de reconstruir. Pulls de imagens Docker são repetidos com um timeout limitado de 180 segundos por tentativa para que um fluxo travado de registro/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico da CI.
O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` qual pacote, tipo de imagem, imagem live, lane e cobertura de credenciais são necessários. `scripts/docker-e2e.mjs` então converte esse plano em outputs e resumos do GitHub. Ele empacota o OpenClaw por meio de `scripts/package-openclaw-for-docker.mjs`, baixa um artefato de pacote da execução atual ou baixa um artefato de pacote de `package_artifact_run_id`; valida o inventário do tarball; compila e envia imagens Docker E2E GHCR básicas/funcionais marcadas pelo digest do pacote por meio do cache de camadas Docker da Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas `docker_e2e_bare_image`/`docker_e2e_functional_image` fornecidas ou imagens existentes por digest de pacote em vez de recompilar. Pulls de imagens Docker são repetidos com um timeout limitado de 180 segundos por tentativa, para que um stream preso de registry/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico da CI.
### Fragmentos do caminho de lançamento
### Chunks do caminho de release
A cobertura Docker de lançamento executa jobs menores em fragmentos com `OPENCLAW_SKIP_DOCKER_BUILD=1`, de modo que cada fragmento puxe apenas o tipo de imagem de que precisa e execute várias lanes pelo mesmo agendador ponderado:
A cobertura Docker de release executa jobs menores em chunks com `OPENCLAW_SKIP_DOCKER_BUILD=1`, para que cada chunk puxe apenas o tipo de imagem de que precisa e execute várias lanes pelo mesmo agendador ponderado:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Os fragmentos Docker de lançamento atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` permanecem aliases agregados de Plugin/runtime. O alias de lane `install-e2e` permanece o alias agregado de reexecução manual para ambas as lanes de instalador de provedor.
Os chunks Docker de release atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` e `plugins-runtime-install-a` até `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` permanecem aliases agregados de plugin/runtime. O alias de lane `install-e2e` permanece o alias agregado de reexecução manual para ambas as lanes de instalador de provedor.
OpenWebUI é incorporado em `plugins-runtime-services` quando a cobertura completa de release-path o solicita, e mantém um fragmento independente `openwebui` apenas para disparos somente do OpenWebUI. Lanes de atualização de canais empacotados tentam novamente uma vez em caso de falhas transitórias de rede npm.
OpenWebUI é incorporado a `plugins-runtime-services` quando a cobertura completa do caminho de release o solicita, e mantém um chunk autônomo `openwebui` apenas para dispatches somente de OpenWebUI. Lanes de atualização de canais incluídos tentam novamente uma vez em caso de falhas transitórias de rede npm.
Cada fragmento faz upload de `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do workflow executa lanes selecionadas contra as imagens preparadas em vez dos jobs de fragmento, o que mantém a depuração de lane com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado cria a imagem de teste live localmente para essa reexecução. Comandos gerados de reexecução por lane no GitHub incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagem preparadas quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha.
Cada chunk envia `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do agendador, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do workflow executa lanes selecionadas contra as imagens preparadas em vez dos jobs de chunk, o que mantém a depuração de lanes com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma lane selecionada for uma lane Docker live, o job direcionado compila a imagem de teste live localmente para essa reexecução. Comandos de reexecução do GitHub gerados por lane incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagens preparadas quando esses valores existem, para que uma lane com falha possa reutilizar o pacote e as imagens exatos da execução com falha.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
O workflow live/E2E agendado executa diariamente a suíte Docker completa de release-path.
O workflow live/E2E agendado executa diariamente a suíte Docker completa do caminho de release.
## Pré-lançamento de Plugin
## Pré-release de Plugin
`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, portanto é um workflow separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e disparos manuais independentes de CI mantêm essa suíte desativada. Ele balanceia testes de Plugins empacotados entre oito workers de extensão; esses jobs de shard de extensão executam até dois grupos de configuração de Plugin por vez, com um worker Vitest por grupo e um heap Node maior para que lotes de Plugins pesados em importação não criem jobs extras de CI. O caminho Docker de pré-lançamento exclusivo de lançamento agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos.
`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, portanto é um workflow separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes para `main` e dispatches manuais autônomos de CI mantêm essa suíte desativada. Ele balanceia testes de plugins incluídos entre oito workers de extensão; esses jobs de shards de extensão executam até dois grupos de configuração de plugin por vez, com um worker Vitest por grupo e um heap Node maior, para que lotes de plugins pesados em imports não criem jobs extras de CI. O caminho Docker de pré-release somente para release agrupa lanes Docker direcionadas em pequenos grupos para evitar reservar dezenas de runners para jobs de um a três minutos.
## QA Lab
O QA Lab tem lanes dedicadas de CI fora do workflow principal com escopo inteligente. A paridade agêntica fica aninhada sob os harnesses amplos de QA e lançamento, não como um workflow autônomo de PR. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação.
QA Lab tem lanes de CI dedicadas fora do workflow principal com escopo inteligente. A paridade agentic fica aninhada nos harnesses amplos de QA e release, não em um workflow autônomo de PR. Use `Full Release Validation` com `rerun_group=qa-parity` quando a paridade deve acompanhar uma execução ampla de validação.
- O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e por disparo manual; ele distribui a lane de paridade mock, a lane live Matrix e as lanes live Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases Convex.
- O workflow `QA-Lab - All Lanes` é executado todas as noites em `main` e em dispatch manual; ele distribui em leque a lane de paridade mock, a lane live Matrix e as lanes live Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases Convex.
As verificações de lançamento executam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`) para que o contrato do canal fique isolado da latência de modelos live e da inicialização normal de Plugin de provedor. O Gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
As verificações de release executam lanes de transporte live Matrix e Telegram com o provedor mock determinístico e modelos qualificados por mock (`mock-openai/gpt-5.5` e `mock-openai/gpt-5.5-alt`), para que o contrato de canal fique isolado da latência de modelo live e da inicialização normal de plugin de provedor. O gateway de transporte live desativa a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedores é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
Matrix usa `--profile fast` para gates agendados e de lançamento, adicionando `--fail-fast` apenas quando a CLI em checkout oferece suporte a isso. O padrão da CLI e a entrada manual do workflow permanecem `all`; o disparo manual `matrix_profile=all` sempre fragmenta a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
Matrix usa `--profile fast` para gates agendados e de release, adicionando `--fail-fast` apenas quando a CLI com checkout dá suporte a isso. O padrão da CLI e a entrada manual do workflow permanecem `all`; dispatch manual `matrix_profile=all` sempre fragmenta a cobertura Matrix completa em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
`OpenClaw Release Checks` também executa as lanes críticas de lançamento do QA Lab antes da aprovação de lançamento; seu gate de paridade de QA executa os pacotes candidato e baseline como jobs de lanes paralelos e, então, baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade.
`OpenClaw Release Checks` também executa as lanes críticas de release do QA Lab antes da aprovação de release; seu gate de paridade de QA executa os pacotes candidato e baseline como jobs de lane paralelos, depois baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade.
Para PRs normais, siga evidências de CI/verificações com escopo em vez de tratar a paridade como um status obrigatório.
Para PRs normais, siga evidências de CI/check com escopo em vez de tratar a paridade como um status obrigatório.
## CodeQL
O fluxo de trabalho `CodeQL` é intencionalmente um verificador de segurança inicial e estreito, não uma varredura completa do repositório. Execuções de proteção diárias, manuais e de solicitações de pull não rascunho verificam o código de fluxos de trabalho do Actions, além das superfícies JavaScript/TypeScript de maior risco, com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica.
O workflow `CodeQL` é intencionalmente um scanner de segurança inicial restrito, não uma varredura completa do repositório. Execuções diárias, manuais e de proteção de pull requests que não são rascunho escaneiam código de workflows do Actions e as superfícies JavaScript/TypeScript de maior risco com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica.
A proteção de solicitação de pull permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança do fluxo de trabalho agendado. CodeQL para Android e macOS fica fora dos padrões de PR.
A proteção de pull request permanece leve: ela só inicia para alterações em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança do workflow agendado. O CodeQL de Android e macOS fica fora dos padrões de PR.
### Categorias de segurança
| Categoria | Superfície |
| Categoria | Superfície |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, cron e Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do núcleo, além do runtime do plugin de canal, Gateway, Plugin SDK, segredos e pontos de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do núcleo, análise de IP, proteção de rede, busca web e política de SSRF do Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, auxiliares de execução de processo, entrega de saída e proteções de execução de ferramentas de agentes |
| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, carregador, manifesto, registro, instalação do gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK |
| `/codeql-security-high/core-auth-secrets` | Linha de base de autenticação, segredos, sandbox, Cron e Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canal do core mais o runtime de Plugin de canal, Gateway, Plugin SDK, segredos e pontos de contato de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies de SSRF do core, parsing de IP, proteção de rede, web-fetch e política de SSRF do Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, helpers de execução de processos, entrega de saída e gates de execução de ferramentas de agentes |
| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, loader, manifesto, registro, instalação por gerenciador de pacotes, carregamento de código-fonte e contrato de pacote do Plugin SDK |
### Shards de segurança específicos de plataforma
### Shards de segurança específicos por plataforma
- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o aplicativo Android manualmente para o CodeQL no menor executor Linux do Blacksmith aceito pela sanidade do fluxo de trabalho. Envia em `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o aplicativo macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de compilação de dependências fora do SARIF enviado e envia em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque a compilação do macOS domina o tempo de execução mesmo quando está limpa.
- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Compila o app Android manualmente para o CodeQL no menor runner Blacksmith Linux aceito pela sanidade do workflow. Faz upload em `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard semanal/manual de segurança do macOS. Compila o app macOS manualmente para o CodeQL no Blacksmith macOS, filtra resultados de build de dependências do SARIF enviado e faz upload em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque o build do macOS domina o tempo de execução mesmo quando está limpo.
### Categorias de qualidade crítica
`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript sem segurança e com severidade de erro sobre superfícies estreitas de alto valor no executor Linux menor do Blacksmith. Sua proteção de solicitação de pull é intencionalmente menor que o perfil agendado: PRs não rascunho executam apenas os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de respostas, código de esquema/migração/IO de configuração, código de autenticação/segredos/sandbox/segurança, canal do núcleo e runtime de plugin de canal empacotado, protocolo/método de servidor do Gateway, cola de runtime/SDK de memória, MCP/processo/entrega de saída, catálogo de runtime/modelos de provedores, diagnósticos de sessão/filas de entrega, carregador de Plugin, contrato de Plugin SDK/pacote ou runtime de respostas do Plugin SDK. Alterações na configuração do CodeQL e no fluxo de trabalho de qualidade executam todos os doze shards de qualidade de PR.
`CodeQL Critical Quality` é o shard não relacionado a segurança correspondente. Ele executa apenas consultas de qualidade JavaScript/TypeScript de severidade de erro e não relacionadas a segurança sobre superfícies restritas de alto valor no runner Blacksmith Linux menor. Sua proteção de pull request é intencionalmente menor que o perfil agendado: PRs que não são rascunho executam apenas os shards correspondentes `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` e `plugin-sdk-reply-runtime` para alterações em código de execução de comando/modelo/ferramenta de agente e despacho de resposta, código de schema/migração/IO de config, código de autenticação/segredos/sandbox/segurança, runtime de canal do core e Plugin de canal incluído, protocolo/método de servidor do Gateway, runtime de memória/cola do SDK, MCP/processo/entrega de saída, catálogo de runtime/modelo de provedor, diagnósticos de sessão/filas de entrega, loader de Plugin, contrato de Plugin SDK/pacote ou runtime de resposta do Plugin SDK. Alterações de configuração do CodeQL e workflow de qualidade executam todos os doze shards de qualidade de PR.
O despacho manual aceita:
@ -415,40 +434,40 @@ O despacho manual aceita:
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Os perfis estreitos são ganchos de ensino/iteração para executar um shard de qualidade isoladamente.
Os perfis restritos são ganchos de ensino/iteração para executar um shard de qualidade isoladamente.
| Categoria | Superfície |
| Categoria | Superfície |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, cron e Gateway |
| `/codeql-critical-quality/config-boundary` | Contratos de esquema, migração, normalização e IO de configuração |
| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas do protocolo do Gateway e contratos de métodos de servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do núcleo e de plugin de canal empacotado |
| `/codeql-critical-quality/agent-runtime-boundary` | Execução de comandos, despacho de modelo/provedor, despacho e filas de resposta automática e contratos de runtime do plano de controle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e pontes de ferramentas, auxiliares de supervisão de processo e contratos de entrega de saída |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK de host de memória, fachadas de runtime de memória, aliases de memória do Plugin SDK, cola de ativação de runtime de memória e comandos doctor de memória |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internos de fila de resposta, filas de entrega de sessão, auxiliares de vinculação/entrega de sessão de saída, superfícies de evento diagnóstico/pacote de logs e contratos de CLI doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do Plugin SDK, auxiliares de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e auxiliares de vinculação de sessão/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de provedores, registro de runtime de provedores, padrões/catálogos de provedores e registros de web/pesquisa/busca/embedding |
| `/codeql-critical-quality/ui-control-plane` | Inicialização da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Busca/pesquisa web do núcleo, IO de mídia, compreensão de mídia, geração de imagens e contratos de runtime de geração de mídia |
| `/codeql-critical-quality/plugin-boundary` | Contratos de carregador, registro, superfície pública e pontos de entrada do Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK do lado do pacote publicado e auxiliares de contrato de pacote de plugin |
| `/codeql-critical-quality/core-auth-secrets` | Código de fronteira de segurança de autenticação, segredos, sandbox, Cron e Gateway |
| `/codeql-critical-quality/config-boundary` | Schema de configuração, migração, normalização e contratos de IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Schemas de protocolo do Gateway e contratos de método de servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canal do core e Plugin de canal incluído |
| `/codeql-critical-quality/agent-runtime-boundary` | Execução de comandos, despacho de modelo/provedor, despacho e filas de resposta automática, e contratos de runtime do plano de controle ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Servidores MCP e bridges de ferramentas, helpers de supervisão de processos e contratos de entrega de saída |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK do host de memória, facades de runtime de memória, aliases de Plugin SDK de memória, cola de ativação de runtime de memória e comandos doctor de memória |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internos da fila de respostas, filas de entrega de sessão, helpers de vinculação/entrega de sessão de saída, superfícies de eventos diagnósticos/pacote de logs e contratos de CLI de doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do Plugin SDK, helpers de payload/fragmentação/runtime de resposta, opções de resposta de canal, filas de entrega e helpers de vinculação de sessão/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalização de catálogo de modelos, autenticação e descoberta de provedores, registro de runtime de provedor, padrões/catálogos de provedor e registros de web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap da UI de controle, persistência local, fluxos de controle do Gateway e contratos de runtime do plano de controle de tarefas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Fetch/search web do core, IO de mídia, entendimento de mídia, geração de imagens e contratos de runtime de geração de mídia |
| `/codeql-critical-quality/plugin-boundary` | Contratos de loader, registro, superfície pública e ponto de entrada do Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do Plugin SDK do lado do pacote publicado e helpers de contrato de pacote de Plugin |
Qualidade fica separada de segurança para que achados de qualidade possam ser agendados, medidos, desativados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e plugins empacotados deve ser adicionada de volta como trabalho de acompanhamento com escopo ou sharding apenas depois que os perfis estreitos tiverem runtime e sinal estáveis.
A qualidade fica separada da segurança para que achados de qualidade possam ser agendados, medidos, desabilitados ou expandidos sem obscurecer o sinal de segurança. A expansão do CodeQL para Swift, Python e Plugins incluídos deve ser adicionada novamente como trabalho de acompanhamento escopado ou fragmentado apenas depois que os perfis restritos tiverem tempo de execução e sinal estáveis.
## Fluxos de trabalho de manutenção
## Workflows de manutenção
### Docs Agent
O fluxo de trabalho `Docs Agent` é uma via de manutenção do Codex orientada por eventos para manter a documentação existente alinhada com alterações recém-integradas. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` já avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando ele executa, revisa o intervalo de commits desde o SHA de origem anterior não ignorado do Docs Agent até o `main` atual, então uma execução horária pode cobrir todas as alterações em main acumuladas desde a última passagem de documentação.
O workflow `Docs Agent` é uma faixa de manutenção Codex orientada a eventos para manter a documentação existente alinhada com alterações aterrissadas recentemente. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, e o despacho manual pode executá-lo diretamente. Invocações por workflow-run são ignoradas quando `main` já avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando executado, ele revisa o intervalo de commits do SHA de origem anterior não ignorado do Docs Agent até o `main` atual, então uma execução horária pode cobrir todas as alterações em main acumuladas desde a última passada de documentação.
### Test Performance Agent
O fluxo de trabalho `Test Performance Agent` é uma via de manutenção do Codex orientada por eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, mas ele é ignorado se outra invocação por workflow-run já foi executada ou está em execução naquele dia UTC. O despacho manual ignora essa proteção de atividade diária. A via cria um relatório de desempenho agrupado de Vitest da suíte completa, permite que o Codex faça apenas pequenas correções de desempenho de testes que preservem a cobertura, em vez de refatorações amplas, depois reexecuta o relatório da suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias, e o relatório da suíte completa pós-agente deve passar antes de qualquer coisa ser commitada. Quando `main` avança antes que o push do bot seja integrado, a via faz rebase do patch validado, reexecuta `pnpm check:changed` e tenta o push novamente; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado no GitHub para que a ação do Codex possa manter a mesma postura de segurança drop-sudo do agente de documentação.
O workflow `Test Performance Agent` é uma faixa de manutenção Codex orientada a eventos para testes lentos. Ele não tem agendamento puro: uma execução de CI bem-sucedida de push não bot em `main` pode acioná-lo, mas ele ignora se outra invocação por workflow-run já executou ou está executando naquele dia UTC. O despacho manual contorna esse gate de atividade diária. A faixa gera um relatório agrupado de performance do Vitest para a suíte completa, permite que o Codex faça apenas pequenas correções de performance de testes que preservem cobertura em vez de refatorações amplas, depois reexecuta o relatório da suíte completa e rejeita alterações que reduzam a contagem de testes aprovados da linha de base. Se a linha de base tiver testes falhando, o Codex pode corrigir apenas falhas óbvias e o relatório da suíte completa após o agente deve passar antes que qualquer coisa seja commitada. Quando `main` avança antes do push do bot aterrissar, a faixa faz rebase do patch validado, reexecuta `pnpm check:changed` e tenta o push novamente; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado pelo GitHub para que a ação Codex possa manter a mesma postura de segurança sem sudo do agente de documentação.
### PRs duplicados após merge
O fluxo de trabalho `Duplicate PRs After Merge` é um fluxo de trabalho manual de mantenedor para limpeza de duplicatas pós-integração. Ele usa dry-run por padrão e só fecha PRs explicitamente listados quando `apply=true`. Antes de alterar o GitHub, ele verifica se o PR integrado foi mesclado e se cada duplicata tem um problema referenciado compartilhado ou hunks alterados sobrepostos.
O workflow `Duplicate PRs After Merge` é um workflow manual de mantenedor para limpeza de duplicatas pós-aterrissagem. Ele usa dry-run por padrão e só fecha PRs listados explicitamente quando `apply=true`. Antes de alterar o GitHub, ele verifica se o PR aterrissado foi mesclado e se cada duplicata tem uma issue referenciada compartilhada ou hunks alterados sobrepostos.
```bash
gh workflow run duplicate-after-merge.yml \
@ -457,29 +476,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Proteções de verificação local e roteamento de alterações
## Gates de verificação local e roteamento de alterações
A lógica local de changed-lane vive em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Essa proteção de verificação local é mais estrita sobre fronteiras de arquitetura do que o escopo amplo da plataforma de CI:
A lógica local de changed-lane vive em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate de verificação local é mais rigoroso sobre fronteiras de arquitetura do que o escopo amplo da plataforma de CI:
- alterações de produção do núcleo executam typecheck de produção do núcleo e de testes do núcleo, além de lint/proteções do núcleo;
- alterações apenas em testes do núcleo executam somente typecheck de testes do núcleo, além de lint do núcleo;
- alterações de produção de extensão executam typecheck de produção e de testes de extensão, além de lint de extensão;
- alterações apenas em testes de extensão executam typecheck de testes de extensão, além de lint de extensão;
- alterações no Plugin SDK público ou no contrato de plugins expandem para typecheck de extensões porque extensões dependem desses contratos do núcleo (varreduras de extensão do Vitest continuam sendo trabalho explícito de teste);
- bumps de versão somente de metadados de release executam verificações direcionadas de versão/configuração/dependência raiz;
- alterações desconhecidas de raiz/configuração falham de modo seguro para todas as vias de verificação.
- alterações de produção do core executam typecheck de core prod e core test mais lint/guards do core;
- alterações apenas de teste do core executam apenas typecheck de core test mais lint do core;
- alterações de produção de extensão executam typecheck de extension prod e extension test mais lint de extension;
- alterações apenas de teste de extensão executam typecheck de extension test mais lint de extension;
- alterações públicas do Plugin SDK ou contrato de Plugin expandem para typecheck de extension porque extensões dependem desses contratos do core (varreduras de extensão do Vitest continuam sendo trabalho de teste explícito);
- aumentos de versão apenas de metadados de release executam verificações direcionadas de versão/config/dependência raiz;
- alterações desconhecidas em root/config falham com segurança para todas as faixas de verificação.
O roteamento local de changed-test vive em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de testes executam a si mesmas, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de importação. A configuração compartilhada de entrega em salas de grupo é um dos mapeamentos explícitos: alterações na configuração de resposta visível de grupo, no modo de entrega de resposta de origem ou no prompt de sistema da ferramenta de mensagens passam pelos testes de resposta do núcleo, além de regressões de entrega do Discord e Slack, para que uma alteração de padrão compartilhado falhe antes do primeiro push de PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável.
O roteamento local de changed-test vive em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de teste executam os próprios testes, edições de código-fonte preferem mapeamentos explícitos, depois testes irmãos e dependentes do grafo de imports. A configuração de entrega de sala de grupo compartilhada é um dos mapeamentos explícitos: alterações na configuração de resposta visível de grupo, no modo de entrega de resposta de origem ou no prompt de sistema da ferramenta de mensagens passam pelos testes de resposta do core mais regressões de entrega do Discord e Slack para que uma alteração de padrão compartilhado falhe antes do primeiro push do PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` apenas quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável.
## Validação Testbox
Execute o Testbox a partir da raiz do repositório e prefira uma box recém-aquecida para comprovação ampla. Antes de gastar um gate lento em uma box que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da box primeiro.
Execute o Testbox a partir da raiz do repositório e prefira uma máquina recém-aquecida para comprovação ampla. Antes de gastar um gate lento em uma máquina que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute `pnpm testbox:sanity` dentro da máquina primeiro.
A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desapareceram ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso normalmente significa que o estado da sincronização remota não é uma cópia confiável do PR; pare essa box e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs com grandes exclusões intencionais, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade.
A verificação de sanidade falha rapidamente quando arquivos obrigatórios da raiz, como `pnpm-lock.yaml`, desapareceram ou quando `git status --short` mostra pelo menos 200 exclusões rastreadas. Isso geralmente significa que o estado de sincronização remoto não é uma cópia confiável do PR; pare essa máquina e aqueça uma nova em vez de depurar a falha do teste do produto. Para PRs intencionais com grandes exclusões, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade.
`pnpm testbox:run` também encerra uma invocação local da CLI do Blacksmith que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desativar essa proteção, ou use um valor maior em milissegundos para diffs locais incomumente grandes.
`pnpm testbox:run` também encerra uma invocação local da CLI do Blacksmith que permanece na fase de sincronização por mais de cinco minutos sem saída pós-sincronização. Defina `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` para desabilitar essa proteção ou use um valor maior em milissegundos para diffs locais incomumente grandes.
Crabbox é o wrapper de box remota mantido pelo repositório para comprovação Linux de mantenedores. Use-o quando uma verificação for ampla demais para um ciclo local de edição, quando a paridade com CI for importante ou quando a comprovação precisar de segredos, Docker, lanes de pacote, boxes reutilizáveis ou logs remotos. O backend normal do OpenClaw é `blacksmith-testbox`; a capacidade própria em AWS/Hetzner é uma alternativa para indisponibilidades do Blacksmith, problemas de cota ou testes explícitos em capacidade própria.
Crabbox é o wrapper de máquina remota pertencente ao repositório para comprovação Linux de mantenedores. Use-o quando uma verificação for ampla demais para um ciclo local de edição, quando a paridade com CI importar ou quando a comprovação precisar de segredos, Docker, lanes de pacote, máquinas reutilizáveis ou logs remotos. O backend normal do OpenClaw é `blacksmith-testbox`; capacidade própria em AWS/Hetzner é um fallback para indisponibilidades do Blacksmith, problemas de cota ou testes explícitos de capacidade própria.
Antes de uma primeira execução, verifique o wrapper a partir da raiz do repositório:
@ -487,7 +506,7 @@ Antes de uma primeira execução, verifique o wrapper a partir da raiz do reposi
pnpm crabbox:run -- --help | sed -n '1,120p'
```
O wrapper do repositório recusa um binário Crabbox obsoleto que não anuncia `blacksmith-testbox`. Passe o provider explicitamente, mesmo que `.crabbox.yaml` tenha padrões de nuvem própria.
O wrapper do repositório recusa um binário obsoleto do Crabbox que não anuncia `blacksmith-testbox`. Passe o provedor explicitamente, mesmo que `.crabbox.yaml` tenha padrões de nuvem própria.
Gate de alterações:
@ -504,7 +523,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
```
Reexecução de teste focado:
Reexecução de teste focada:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -534,21 +553,21 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Leia o resumo JSON final. Os campos úteis são `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` e `totalMs`. Execuções Crabbox únicas com suporte do Blacksmith devem parar o Testbox automaticamente; se uma execução for interrompida ou a limpeza não estiver clara, inspecione as boxes ativas e pare somente as boxes que você criou:
Leia o resumo JSON final. Os campos úteis são `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs` e `totalMs`. Execuções únicas do Crabbox com suporte do Blacksmith devem parar o Testbox automaticamente; se uma execução for interrompida ou a limpeza não estiver clara, inspecione as máquinas ativas e pare apenas as máquinas que você criou:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
Use reutilização somente quando você precisar intencionalmente de vários comandos na mesma box hidratada:
Use reutilização somente quando precisar intencionalmente de vários comandos na mesma máquina hidratada:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
pnpm crabbox:stop -- <tbx_id>
```
Se o Crabbox for a camada quebrada, mas o próprio Blacksmith funcionar, use o Blacksmith direto como alternativa restrita:
Se o Crabbox for a camada quebrada, mas o próprio Blacksmith funcionar, use o Blacksmith direto como um fallback restrito:
```bash
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
@ -556,7 +575,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_id>
```
Escalone para capacidade própria do Crabbox somente quando o Blacksmith estiver indisponível, limitado por cota, sem o ambiente necessário ou quando a capacidade própria for explicitamente o objetivo:
Escale para capacidade própria do Crabbox somente quando o Blacksmith estiver fora do ar, limitado por cota, sem o ambiente necessário ou quando a capacidade própria for explicitamente o objetivo:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@ -565,9 +584,9 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` controla os padrões de provider, sincronização e hidratação do GitHub Actions para lanes de nuvem própria. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados Git remotos em vez de sincronizar remotos e armazenamentos de objetos locais dos mantenedores, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla o checkout, a configuração do Node/pnpm, o fetch de `origin/main` e a transferência de ambiente sem segredos para comandos `crabbox run --id <cbx_id>` em nuvem própria.
`.crabbox.yaml` controla os padrões de provedor, sincronização e hidratação do GitHub Actions para lanes de nuvem própria. Ele exclui o `.git` local para que o checkout hidratado do Actions mantenha seus próprios metadados remotos do Git em vez de sincronizar remotos e armazenamentos de objetos locais do mantenedor, e exclui artefatos locais de runtime/build que nunca devem ser transferidos. `.github/workflows/crabbox-hydrate.yml` controla checkout, configuração de Node/pnpm, busca de `origin/main` e repasse de ambiente não secreto para comandos `crabbox run --id <cbx_id>` em nuvem própria.
## Relacionados
## Relacionado
- [Visão geral da instalação](/pt-BR/install)
- [Canais de desenvolvimento](/pt-BR/install/development-channels)

29
docs/pt-BR/cli/dashboard.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Você quer abrir a Control UI com seu token atual
- Você quer exibir a URL sem abrir um navegador
summary: Referência de CLI para `openclaw dashboard` (abre a Control UI)
- Você quer abrir a UI de Controle com seu token atual
- Você quer imprimir a URL sem abrir um navegador
summary: Referência da CLI para `openclaw dashboard` (abrir a interface de controle)
title: Painel
x-i18n:
generated_at: "2026-04-25T13:43:35Z"
model: gpt-5.4
generated_at: "2026-05-05T01:44:32Z"
model: gpt-5.5
provider: openai
source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c
source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f
source_path: cli/dashboard.md
workflow: 15
workflow: 16
---
# `openclaw dashboard`
Abre a Control UI usando sua autenticação atual.
Abra a UI de Controle usando sua autenticação atual.
```bash
openclaw dashboard
@ -24,11 +24,14 @@ openclaw dashboard --no-open
Observações:
- `dashboard` resolve SecretRefs configurados em `gateway.auth.token` quando possível.
- `dashboard` segue `gateway.tls.enabled`: Gateways com TLS habilitado exibem/abrem
URLs da Control UI com `https://` e se conectam via `wss://`.
- Para tokens gerenciados por SecretRef (resolvidos ou não resolvidos), `dashboard` exibe/copia/abre uma URL sem token para evitar expor segredos externos na saída do terminal, no histórico da área de transferência ou em argumentos de inicialização do navegador.
- Se `gateway.auth.token` for gerenciado por SecretRef, mas não estiver resolvido neste caminho de comando, o comando exibirá uma URL sem token e orientações explícitas de correção em vez de incorporar um placeholder de token inválido.
- `dashboard` resolve SecretRefs de `gateway.auth.token` configuradas quando possível.
- `dashboard` segue `gateway.tls.enabled`: instâncias de Gateway com TLS habilitado imprimem/abrem URLs da UI de Controle com
`https://` e se conectam por `wss://`.
- Se a entrega pela área de transferência/navegador falhar para uma URL do painel autenticada por token,
`dashboard` registra uma dica segura de autenticação manual nomeando `OPENCLAW_GATEWAY_TOKEN`,
`gateway.auth.token` e a chave de fragmento `token` sem imprimir o valor do token.
- Para tokens gerenciados por SecretRef (resolvidos ou não resolvidos), `dashboard` imprime/copia/abre uma URL sem token para evitar expor segredos externos na saída do terminal, no histórico da área de transferência ou nos argumentos de inicialização do navegador.
- Se `gateway.auth.token` for gerenciado por SecretRef, mas não for resolvido neste caminho de comando, o comando imprime uma URL sem token e orientações explícitas de correção em vez de incorporar um placeholder de token inválido.
## Relacionado

68
docs/pt-BR/cli/doctor.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Você tem problemas de conectividade/autenticação e deseja correções guiadas
- Você atualizou e quer uma verificação rápida
- Você está com problemas de conectividade/autenticação e quer correções guiadas
- Você atualizou e quer uma verificação de sanidade
summary: Referência da CLI para `openclaw doctor` (verificações de integridade + reparos guiados)
title: Diagnóstico
x-i18n:
generated_at: "2026-05-04T02:22:18Z"
generated_at: "2026-05-05T01:44:26Z"
model: gpt-5.5
provider: openai
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Verificações de integridade + correções rápidas para o Gateway e canais.
Verificações de integridade + correções rápidas para o Gateway e os canais.
Relacionado:
@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token
## Opções
- `--no-workspace-suggestions`: desativa sugestões de memória/pesquisa do workspace
- `--no-workspace-suggestions`: desabilita sugestões de memória/pesquisa do workspace
- `--yes`: aceita os padrões sem solicitar confirmação
- `--repair`: aplica reparos recomendados que não envolvem serviço sem solicitar confirmação; instalações e reescritas do serviço do Gateway ainda exigem confirmação interativa ou comandos explícitos do Gateway
- `--repair`: aplica reparos recomendados que não sejam de serviço sem solicitar confirmação; instalações e regravações do serviço de Gateway ainda exigem confirmação interativa ou comandos explícitos de Gateway
- `--fix`: alias para `--repair`
- `--force`: aplica reparos agressivos, incluindo sobrescrever configuração personalizada de serviço quando necessário
- `--non-interactive`: executa sem prompts; apenas migrações seguras e reparos que não envolvem serviço
- `--generate-gateway-token`: gera e configura um token do Gateway
- `--deep`: verifica serviços do sistema em busca de instalações extras do Gateway
- `--non-interactive`: executa sem prompts; somente migrações seguras e reparos que não sejam de serviço
- `--generate-gateway-token`: gera e configura um token de Gateway
- `--deep`: examina os serviços do sistema em busca de instalações extras do Gateway
Observações:
- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções sem interface (cron, Telegram, sem terminal) ignorarão prompts.
- Desempenho: execuções não interativas de `doctor` ignoram o carregamento antecipado de plugins para manter verificações de integridade sem interface rápidas. Sessões interativas ainda carregam plugins completamente quando uma verificação precisa da contribuição deles.
- Prompts interativos (como correções de keychain/OAuth) só são executados quando stdin é um TTY e `--non-interactive` **não** está definido. Execuções headless (cron, Telegram, sem terminal) ignorarão os prompts.
- Desempenho: execuções não interativas de `doctor` ignoram o carregamento antecipado de Plugin para que as verificações de integridade headless permaneçam rápidas. Sessões interativas ainda carregam Plugins por completo quando uma verificação precisa da contribuição deles.
- `--fix` (alias para `--repair`) grava um backup em `~/.openclaw/openclaw.json.bak` e remove chaves de configuração desconhecidas, listando cada remoção.
- `doctor --fix --non-interactive` relata definições de serviço do Gateway ausentes ou obsoletas, mas não as instala nem reescreve fora do modo de reparo de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher.
- As verificações de integridade de estado agora detectam arquivos de transcrição órfãos no diretório de sessões. Arquivá-los como `.deleted.<timestamp>` exige uma confirmação interativa; `--fix`, `--yes` e execuções sem interface os deixam no lugar.
- Doctor também verifica `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de tarefas cron e pode reescrevê-los no lugar antes que o agendador precise normalizá-los automaticamente em tempo de execução.
- No Linux, Doctor avisa quando o crontab do usuário ainda executa o legado `~/.openclaw/bin/ensure-whatsapp.sh`; esse script não é mais mantido e pode registrar falsas indisponibilidades do Gateway do WhatsApp quando o cron não tem o ambiente do barramento de usuário do systemd.
- Doctor limpa estado legado de preparação de dependências de plugins criado por versões antigas do OpenClaw. Ele também repara plugins baixáveis configurados ausentes quando o registro consegue resolvê-los, e a passagem de Doctor 2026.5.2 instala automaticamente plugins baixáveis que uma configuração antiga já usa antes de marcar a configuração como tocada para essa versão. Se o download falhar, Doctor relata o erro de instalação e preserva a entrada de plugin configurada para a próxima tentativa de reparo.
- Doctor repara configuração obsoleta de plugins removendo ids de plugins ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal pendente correspondente, alvos de Heartbeat e substituições de modelo de canal quando a descoberta de plugins está íntegra.
- Doctor coloca configuração inválida de plugins em quarentena desativando a entrada `plugins.entries.<id>` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já ignora apenas esse plugin problemático, para que outros plugins e canais possam continuar em execução.
- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerencia o ciclo de vida do Gateway. Doctor ainda relata a integridade do Gateway/serviço e aplica reparos que não envolvem serviço, mas ignora instalação/início/reinício/bootstrap do serviço e limpeza de serviço legado.
- No Linux, Doctor ignora unidades systemd extras semelhantes ao Gateway que estejam inativas e não reescreve metadados de comando/entrypoint para um serviço systemd do Gateway em execução durante o reparo. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você intencionalmente quiser substituir o launcher ativo.
- Doctor migra automaticamente configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e relacionados) para `talk.provider` + `talk.providers.<provider>`.
- Execuções repetidas de `doctor --fix` não relatam/aplicam mais normalização do Talk quando a única diferença é a ordem das chaves do objeto.
- Doctor inclui uma verificação de prontidão de pesquisa de memória e pode recomendar `openclaw configure --section model` quando credenciais de embeddings estão ausentes.
- Doctor avisa quando nenhum proprietário de comandos está configurado. O proprietário de comandos é a conta do operador humano autorizada a executar comandos exclusivos de proprietário e aprovar ações perigosas. O pareamento por DM apenas permite que alguém fale com o bot; se você aprovou um remetente antes de existir o bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente.
- Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais do Codex CLI existem no diretório inicial Codex do operador. Inicializações locais do servidor de app do Codex usam diretórios iniciais isolados por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente.
- Doctor avisa quando Skills permitidas para o agente padrão estão indisponíveis no ambiente de execução atual porque bins, variáveis de ambiente, configuração ou requisitos de SO estão ausentes. `doctor --fix` pode desativar essas skills indisponíveis com `skills.entries.<skill>.enabled=false`; instale/configure o requisito ausente em vez disso quando quiser manter a skill ativa.
- Se o modo sandbox estiver ativado mas o Docker estiver indisponível, Doctor relata um aviso de alto sinal com correção (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`).
- Se arquivos legados do registro do sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, Doctor os relata; `openclaw doctor --fix` migra entradas válidas para diretórios de registro particionados e coloca arquivos legados inválidos em quarentena.
- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho do comando atual, Doctor relata um aviso somente leitura e não grava credenciais fallback em texto simples.
- Se a inspeção de SecretRef do canal falhar em um caminho de correção, Doctor continua e relata um aviso em vez de sair antecipadamente.
- Após migrações de diretório de estado, Doctor avisa quando contas padrão ativadas do Telegram ou Discord dependem de fallback por env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo do Doctor.
- A resolução automática de nome de usuário `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho do comando atual. Se a inspeção do token estiver indisponível, Doctor relata um aviso e ignora a resolução automática nessa passagem.
- `doctor --fix --non-interactive` informa definições de serviço de Gateway ausentes ou obsoletas, mas não as instala nem regrava fora do modo de reparo de atualização. Execute `openclaw gateway install` para um serviço ausente, ou `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador.
- As verificações de integridade de estado agora detectam arquivos órfãos de transcrição no diretório de sessões. Arquivá-los como `.deleted.<timestamp>` exige uma confirmação interativa; `--fix`, `--yes` e execuções headless os deixam no lugar.
- Doctor também examina `~/.openclaw/cron/jobs.json` (ou `cron.store`) em busca de formatos legados de trabalhos Cron e pode regravá-los no local antes que o agendador precise normalizá-los automaticamente em tempo de execução.
- No Linux, doctor avisa quando o crontab do usuário ainda executa o legado `~/.openclaw/bin/ensure-whatsapp.sh`; esse script não é mais mantido e pode registrar falsas indisponibilidades do Gateway do WhatsApp quando Cron não tem o ambiente de barramento de usuário do systemd.
- Doctor limpa o estado legado de preparação de dependências de Plugin criado por versões antigas do OpenClaw. Ele também repara Plugins baixáveis ausentes que são referenciados pela configuração, como `plugins.entries`, canais configurados, configurações de provedor/pesquisa configuradas ou runtimes de agente configurados. Durante atualizações de pacote, doctor ignora o reparo de Plugin pelo gerenciador de pacotes até que a troca de pacote seja concluída; execute novamente `openclaw doctor --fix` depois se um Plugin configurado ainda precisar de recuperação. Se o download falhar, doctor relata o erro de instalação e preserva a entrada de Plugin configurada para a próxima tentativa de reparo.
- Doctor repara configuração obsoleta de Plugin removendo ids de Plugin ausentes de `plugins.allow`/`plugins.entries`, além da configuração de canal pendente correspondente, alvos de Heartbeat e substituições de modelo de canal quando a descoberta de Plugin está íntegra.
- Doctor coloca em quarentena configuração inválida de Plugin desabilitando a entrada `plugins.entries.<id>` afetada e removendo seu payload `config` inválido. A inicialização do Gateway já ignora apenas esse Plugin problemático para que outros Plugins e canais possam continuar em execução.
- Defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando outro supervisor gerenciar o ciclo de vida do Gateway. Doctor ainda relata a integridade do Gateway/serviço e aplica reparos que não sejam de serviço, mas ignora instalação/início/reinício/bootstrap de serviço e limpeza de serviço legado.
- No Linux, doctor ignora unidades systemd extras semelhantes a Gateway que estejam inativas e não regrava metadados de comando/entrypoint para um serviço systemd de Gateway em execução durante o reparo. Pare o serviço primeiro ou use `openclaw gateway install --force` quando você quiser substituir intencionalmente o inicializador ativo.
- Doctor migra automaticamente a configuração plana legada do Talk (`talk.voiceId`, `talk.modelId` e afins) para `talk.provider` + `talk.providers.<provider>`.
- Execuções repetidas de `doctor --fix` não relatam/aplicam mais a normalização do Talk quando a única diferença é a ordem das chaves do objeto.
- Doctor inclui uma verificação de prontidão de pesquisa em memória e pode recomendar `openclaw configure --section model` quando as credenciais de embedding estão ausentes.
- Doctor avisa quando nenhum proprietário de comandos está configurado. O proprietário de comandos é a conta de operador humano autorizada a executar comandos exclusivos do proprietário e aprovar ações perigosas. O pareamento por DM apenas permite que alguém fale com o bot; se você aprovou um remetente antes da existência do bootstrap do primeiro proprietário, defina `commands.ownerAllowFrom` explicitamente.
- Doctor avisa quando agentes em modo Codex estão configurados e ativos pessoais da CLI do Codex existem na home Codex do operador. Inicializações locais do app-server do Codex usam homes isoladas por agente, então use `openclaw migrate codex --dry-run` para inventariar ativos que devem ser promovidos deliberadamente.
- Doctor avisa quando Skills permitidas para o agente padrão estão indisponíveis no ambiente de runtime atual porque bins, env vars, configuração ou requisitos de SO estão ausentes. `doctor --fix` pode desabilitar essas Skills indisponíveis com `skills.entries.<skill>.enabled=false`; instale/configure o requisito ausente em vez disso quando quiser manter a skill ativa.
- Se o modo sandbox estiver habilitado, mas o Docker estiver indisponível, doctor relata um aviso de alto sinal com remediação (`install Docker` ou `openclaw config set agents.defaults.sandbox.mode off`).
- Se arquivos legados de registro de sandbox (`~/.openclaw/sandbox/containers.json` ou `~/.openclaw/sandbox/browsers.json`) estiverem presentes, doctor os relata; `openclaw doctor --fix` migra entradas válidas para diretórios de registro fragmentados e coloca arquivos legados inválidos em quarentena.
- Se `gateway.auth.token`/`gateway.auth.password` forem gerenciados por SecretRef e estiverem indisponíveis no caminho de comando atual, doctor relata um aviso somente leitura e não grava credenciais fallback em texto simples.
- Se a inspeção de SecretRef do canal falhar em um caminho de correção, doctor continua e relata um aviso em vez de sair antecipadamente.
- Após migrações do diretório de estado, doctor avisa quando contas padrão habilitadas do Telegram ou Discord dependem de fallback de env e `TELEGRAM_BOT_TOKEN` ou `DISCORD_BOT_TOKEN` está indisponível para o processo doctor.
- A resolução automática de nome de usuário `allowFrom` do Telegram (`doctor --fix`) exige um token do Telegram resolvível no caminho de comando atual. Se a inspeção do token estiver indisponível, doctor relata um aviso e ignora a resolução automática nessa passagem.
## macOS: substituições de env do `launchctl`
Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor sobrescreve seu arquivo de configuração e pode causar erros persistentes de “não autorizado”.
Se você executou anteriormente `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (ou `...PASSWORD`), esse valor substitui seu arquivo de configuração e pode causar erros persistentes de “não autorizado”.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN

219
docs/pt-BR/cli/gateway.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Executando o Gateway pela CLI (desenvolvimento ou servidores)
- Depuração de autenticação do Gateway, modos de vinculação e conectividade
- Descoberta de Gateways via Bonjour (DNS-SD local + de área ampla)
- Depuração da autenticação do Gateway, dos modos de bind e da conectividade
- Descobrindo Gateways via Bonjour (DNS-SD local + de área ampla)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — execute, consulte e descubra Gateways
title: Gateway
x-i18n:
generated_at: "2026-05-04T18:23:47Z"
generated_at: "2026-05-05T01:44:36Z"
model: gpt-5.5
provider: openai
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_path: cli/gateway.md
workflow: 16
---
@ -19,13 +19,13 @@ O Gateway é o servidor WebSocket do OpenClaw (canais, nós, sessões, hooks). O
<CardGroup cols={3}>
<Card title="Descoberta Bonjour" href="/pt-BR/gateway/bonjour">
Configuração de mDNS local + DNS-SD de área ampla.
Configuração local de mDNS + DNS-SD de área ampla.
</Card>
<Card title="Visão geral da descoberta" href="/pt-BR/gateway/discovery">
<Card title="Visão geral de descoberta" href="/pt-BR/gateway/discovery">
Como o OpenClaw anuncia e encontra gateways.
</Card>
<Card title="Configuração" href="/pt-BR/gateway/configuration">
Chaves de configuração de nível superior do gateway.
Chaves de configuração de Gateway de nível superior.
</Card>
</CardGroup>
@ -46,11 +46,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Comportamento de inicialização">
- Por padrão, o Gateway se recusa a iniciar a menos que `gateway.mode=local` esteja definido em `~/.openclaw/openclaw.json`. Use `--allow-unconfigured` para execuções ad-hoc/de desenvolvimento.
- Espera-se que `openclaw onboard --mode local` e `openclaw setup` gravem `gateway.mode=local`. Se o arquivo existir, mas `gateway.mode` estiver ausente, trate isso como uma configuração quebrada ou sobrescrita e repare-a em vez de assumir implicitamente o modo local.
- Se o arquivo existir e `gateway.mode` estiver ausente, o Gateway trata isso como dano suspeito na configuração e se recusa a "adivinhar local" para você.
- Vincular além do loopback sem autenticação é bloqueado (barreira de segurança).
- `SIGUSR1` aciona uma reinicialização dentro do processo quando autorizado (`commands.restart` é habilitado por padrão; defina `commands.restart: false` para bloquear a reinicialização manual, enquanto aplicação/atualização da ferramenta/configuração do gateway continuam permitidas).
- Os manipuladores de `SIGINT`/`SIGTERM` interrompem o processo do gateway, mas não restauram nenhum estado personalizado do terminal. Se você encapsular a CLI com uma TUI ou entrada em modo bruto, restaure o terminal antes de sair.
- Espera-se que `openclaw onboard --mode local` e `openclaw setup` gravem `gateway.mode=local`. Se o arquivo existir, mas `gateway.mode` estiver ausente, trate isso como uma configuração quebrada ou sobrescrita e repare-a em vez de presumir implicitamente o modo local.
- Se o arquivo existir e `gateway.mode` estiver ausente, o Gateway trata isso como dano suspeito à configuração e se recusa a "adivinhar local" por você.
- Vinculação além de loopback sem autenticação é bloqueada (barreira de segurança).
- `SIGUSR1` aciona uma reinicialização em processo quando autorizado (`commands.restart` é habilitado por padrão; defina `commands.restart: false` para bloquear reinicialização manual, enquanto aplicação/atualização de ferramenta/configuração do Gateway continuam permitidas).
- Manipuladores de `SIGINT`/`SIGTERM` param o processo do gateway, mas não restauram nenhum estado personalizado do terminal. Se você encapsular a CLI com uma TUI ou entrada em modo bruto, restaure o terminal antes de sair.
</Accordion>
</AccordionGroup>
@ -58,19 +58,19 @@ openclaw gateway run
### Opções
<ParamField path="--port <port>" type="number">
Porta WebSocket (o padrão vem da configuração/env; geralmente `18789`).
Porta WebSocket (o padrão vem de config/env; geralmente `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Modo de bind do listener.
Modo de vinculação do listener.
</ParamField>
<ParamField path="--auth <token|password>" type="string">
Substituição do modo de autenticação.
</ParamField>
<ParamField path="--token <token>" type="string">
Substituição do token (também define `OPENCLAW_GATEWAY_TOKEN` para o processo).
Substituição de token (também define `OPENCLAW_GATEWAY_TOKEN` para o processo).
</ParamField>
<ParamField path="--password <password>" type="string">
Substituição da senha.
Substituição de senha.
</ParamField>
<ParamField path="--password-file <path>" type="string">
Leia a senha do gateway de um arquivo.
@ -79,16 +79,16 @@ openclaw gateway run
Exponha o Gateway via Tailscale.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
Redefina a configuração serve/funnel do Tailscale ao encerrar.
Redefina a configuração de serve/funnel do Tailscale no encerramento.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Permita que o gateway inicie sem `gateway.mode=local` na configuração. Ignora a proteção de inicialização apenas para bootstrap ad-hoc/de desenvolvimento; não grava nem repara o arquivo de configuração.
Permite iniciar o gateway sem `gateway.mode=local` na configuração. Ignora a proteção de inicialização apenas para bootstrap ad-hoc/de desenvolvimento; não grava nem repara o arquivo de configuração.
</ParamField>
<ParamField path="--dev" type="boolean">
Crie uma configuração de desenvolvimento + workspace se ausentes (ignora BOOTSTRAP.md).
Crie uma configuração de desenvolvimento + workspace se estiver ausente (ignora BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Redefina configuração de desenvolvimento + credenciais + sessões + workspace (requer `--dev`).
Redefina a configuração de desenvolvimento + credenciais + sessões + workspace (requer `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Encerre qualquer listener existente na porta selecionada antes de iniciar.
@ -100,7 +100,7 @@ openclaw gateway run
Mostre apenas logs do backend da CLI no console (e habilite stdout/stderr).
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Estilo de log do WebSocket.
Estilo de log Websocket.
</ParamField>
<ParamField path="--compact" type="boolean">
Alias para `--ws-log compact`.
@ -109,7 +109,7 @@ openclaw gateway run
Registre eventos brutos de stream do modelo em jsonl.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
Caminho jsonl do stream bruto.
Caminho do jsonl de stream bruto.
</ParamField>
## Reiniciar o Gateway
@ -120,21 +120,21 @@ openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` pede ao Gateway em execução que faça uma pré-verificação do trabalho ativo do OpenClaw antes de reiniciar. Se operações em fila, entrega de respostas, execuções incorporadas ou execuções de tarefas estiverem ativas, o Gateway relata os bloqueadores, agrupa solicitações duplicadas de reinicialização segura e reinicia quando o trabalho ativo é escoado. `restart` simples mantém o comportamento existente do gerenciador de serviço para compatibilidade. Use `--force` somente quando você quiser explicitamente o caminho de substituição imediata.
`openclaw gateway restart --safe` solicita ao Gateway em execução que faça um preflight do trabalho ativo do OpenClaw antes de reiniciar. Se operações enfileiradas, entrega de respostas, execuções incorporadas ou execuções de tarefas estiverem ativas, o Gateway relata os bloqueadores, consolida solicitações duplicadas de reinicialização segura e reinicia quando o trabalho ativo esvazia. `restart` simples mantém o comportamento existente do gerenciador de serviço por compatibilidade. Use `--force` apenas quando você quiser explicitamente o caminho de substituição imediata.
<Warning>
`--password` inline pode ser exposto em listagens de processos locais. Prefira `--password-file`, env ou um `gateway.auth.password` baseado em SecretRef.
</Warning>
### Perfilamento da inicialização
### Perfil de inicialização
- Defina `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar tempos de fases durante a inicialização do Gateway, incluindo atraso `eventLoopMax` por fase e tempos de tabelas de consulta de plugins para índice instalado, registro de manifestos, planejamento de inicialização e trabalho de mapa de proprietários.
- Defina `OPENCLAW_DIAGNOSTICS=timeline` com `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` para gravar uma timeline de diagnósticos de inicialização JSONL de melhor esforço para harnesses externos de QA. Você também pode habilitar a flag com `diagnostics.flags: ["timeline"]` na configuração; o caminho ainda é fornecido por env. Adicione `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir amostras do loop de eventos.
- Execute `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir a inicialização do Gateway. O benchmark registra a primeira saída do processo, `/healthz`, `/readyz`, tempos do trace de inicialização, atraso do loop de eventos e detalhes de tempo das tabelas de consulta de plugins.
- Defina `OPENCLAW_GATEWAY_STARTUP_TRACE=1` para registrar tempos de fase durante a inicialização do Gateway, incluindo atraso `eventLoopMax` por fase e tempos de tabela de lookup de Plugin para índice instalado, registro de manifestos, planejamento de inicialização e trabalho de mapa de proprietários.
- Defina `OPENCLAW_DIAGNOSTICS=timeline` com `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` para gravar uma linha do tempo de diagnósticos de inicialização JSONL de melhor esforço para harnesses externos de QA. Você também pode habilitar a flag com `diagnostics.flags: ["timeline"]` na configuração; o caminho ainda é fornecido via env. Adicione `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` para incluir amostras do loop de eventos.
- Execute `pnpm test:startup:gateway -- --runs 5 --warmup 1` para medir o desempenho da inicialização do Gateway. O benchmark registra a primeira saída do processo, `/healthz`, `/readyz`, tempos de trace de inicialização, atraso do loop de eventos e detalhes de tempo da tabela de lookup de Plugin.
## Consultar um Gateway em execução
Todos os comandos de consulta usam RPC por WebSocket.
Todos os comandos de consulta usam RPC via WebSocket.
<Tabs>
<Tab title="Modos de saída">
@ -154,7 +154,7 @@ Todos os comandos de consulta usam RPC por WebSocket.
</Tabs>
<Note>
Quando você define `--url`, a CLI não recorre a credenciais da configuração ou do ambiente. Passe `--token` ou `--password` explicitamente. Credenciais explícitas ausentes são um erro.
Quando você define `--url`, a CLI não faz fallback para credenciais de configuração ou ambiente. Passe `--token` ou `--password` explicitamente. A ausência de credenciais explícitas é um erro.
</Note>
### `gateway health`
@ -163,11 +163,11 @@ Quando você define `--url`, a CLI não recorre a credenciais da configuração
openclaw gateway health --url ws://127.0.0.1:18789
```
O endpoint HTTP `/healthz` é uma sonda de vitalidade: ele retorna quando o servidor consegue responder por HTTP. O endpoint HTTP `/readyz` é mais rigoroso e permanece vermelho enquanto sidecars de plugins de inicialização, canais ou hooks configurados ainda estão se acomodando. Respostas detalhadas de prontidão locais ou autenticadas incluem um bloco de diagnóstico `eventLoop` com atraso do loop de eventos, utilização do loop de eventos, proporção de núcleos de CPU e uma flag `degraded`.
O endpoint HTTP `/healthz` é uma sonda de atividade: ele retorna quando o servidor consegue responder HTTP. O endpoint HTTP `/readyz` é mais estrito e permanece vermelho enquanto sidecars de Plugin de inicialização, canais ou hooks configurados ainda estão se estabilizando. Respostas detalhadas de prontidão locais ou autenticadas incluem um bloco de diagnóstico `eventLoop` com atraso do loop de eventos, utilização do loop de eventos, razão de núcleos de CPU e uma flag `degraded`.
### `gateway usage-cost`
Busca resumos de custo de uso dos logs de sessão.
Busque resumos de custo de uso dos logs de sessão.
```bash
openclaw gateway usage-cost
@ -181,7 +181,7 @@ openclaw gateway usage-cost --json
### `gateway stability`
Busca o gravador recente de estabilidade de diagnóstico de um Gateway em execução.
Busque o gravador recente de estabilidade de diagnóstico de um Gateway em execução.
```bash
openclaw gateway stability
@ -201,10 +201,10 @@ openclaw gateway stability --json
Inclua apenas eventos após um número de sequência de diagnóstico.
</ParamField>
<ParamField path="--bundle [path]" type="string">
Leia um pacote de estabilidade persistido em vez de chamar o Gateway em execução. Use `--bundle latest` (ou apenas `--bundle`) para o pacote mais novo no diretório de estado, ou passe diretamente um caminho JSON do pacote.
Leia um pacote de estabilidade persistido em vez de chamar o Gateway em execução. Use `--bundle latest` (ou apenas `--bundle`) para o pacote mais novo no diretório de estado, ou passe diretamente um caminho JSON de pacote.
</ParamField>
<ParamField path="--export" type="boolean">
Grave um zip de diagnósticos de suporte compartilhável em vez de imprimir detalhes de estabilidade.
Grave um zip compartilhável de diagnósticos de suporte em vez de imprimir detalhes de estabilidade.
</ParamField>
<ParamField path="--output <path>" type="string">
Caminho de saída para `--export`.
@ -212,15 +212,15 @@ openclaw gateway stability --json
<AccordionGroup>
<Accordion title="Privacidade e comportamento do pacote">
- Os registros mantêm metadados operacionais: nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de filas/sessões, nomes de canais/plugins e resumos de sessão redigidos. Eles não mantêm texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies, valores secretos, nomes de host ou ids brutos de sessão. Defina `diagnostics.enabled: false` para desabilitar o gravador totalmente.
- Em encerramentos fatais do Gateway, timeouts de desligamento e falhas de inicialização após reinicialização, o OpenClaw grava o mesmo snapshot de diagnóstico em `~/.openclaw/logs/stability/openclaw-stability-*.json` quando o gravador tem eventos. Inspecione o pacote mais novo com `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` também se aplicam à saída do pacote.
- Os registros mantêm metadados operacionais: nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de fila/sessão, nomes de canais/plugins e resumos de sessão redigidos. Eles não mantêm texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies, valores secretos, nomes de host ou ids brutos de sessão. Defina `diagnostics.enabled: false` para desabilitar completamente o gravador.
- Em saídas fatais do Gateway, timeouts de encerramento e falhas de inicialização de reinício, o OpenClaw grava o mesmo snapshot de diagnóstico em `~/.openclaw/logs/stability/openclaw-stability-*.json` quando o gravador tem eventos. Inspecione o pacote mais novo com `openclaw gateway stability --bundle latest`; `--limit`, `--type` e `--since-seq` também se aplicam à saída do pacote.
</Accordion>
</AccordionGroup>
### `gateway diagnostics export`
Grava um zip de diagnósticos local projetado para anexar a relatórios de bugs. Para o modelo de privacidade e o conteúdo do pacote, consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics).
Grave um zip local de diagnósticos projetado para anexar a relatórios de bugs. Para o modelo de privacidade e o conteúdo do pacote, consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics).
```bash
openclaw gateway diagnostics export
@ -232,7 +232,7 @@ openclaw gateway diagnostics export --json
Caminho do zip de saída. O padrão é uma exportação de suporte no diretório de estado.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Máximo de linhas de log sanitizadas a incluir.
Número máximo de linhas de log sanitizadas a incluir.
</ParamField>
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
Máximo de bytes de log a inspecionar.
@ -256,13 +256,13 @@ openclaw gateway diagnostics export --json
Imprima o caminho gravado, o tamanho e o manifesto como JSON.
</ParamField>
A exportação contém um manifesto, um resumo em Markdown, formato da configuração, detalhes sanitizados da configuração, resumos sanitizados de logs, snapshots sanitizados de status/integridade do Gateway e o pacote de estabilidade mais novo quando existir.
A exportação contém um manifesto, um resumo em Markdown, formato de configuração, detalhes de configuração sanitizados, resumos de log sanitizados, snapshots sanitizados de status/integridade do Gateway e o pacote de estabilidade mais novo quando houver um.
Ela foi feita para ser compartilhada. Mantém detalhes operacionais que ajudam na depuração, como campos seguros de log do OpenClaw, nomes de subsistemas, códigos de status, durações, modos configurados, portas, ids de plugins, ids de provedores, configurações de recursos não secretas e mensagens de log operacional redigidas. Omite ou redige texto de chat, corpos de webhook, saídas de ferramentas, credenciais, cookies, identificadores de contas/mensagens, texto de prompts/instruções, nomes de host e valores secretos. Quando uma mensagem no estilo LogTape parece texto de payload de usuário/chat/ferramenta, a exportação mantém apenas que uma mensagem foi omitida, além de sua contagem de bytes.
Ela foi feita para ser compartilhada. Mantém detalhes operacionais que ajudam na depuração, como campos seguros de log do OpenClaw, nomes de subsistemas, códigos de status, durações, modos configurados, portas, ids de Plugin, ids de provedores, configurações de recursos não secretas e mensagens de log operacional redigidas. Ela omite ou redige texto de chat, corpos de webhook, saídas de ferramentas, credenciais, cookies, identificadores de conta/mensagem, texto de prompt/instrução, nomes de host e valores secretos. Quando uma mensagem no estilo LogTape parece texto de payload de usuário/chat/ferramenta, a exportação mantém apenas que uma mensagem foi omitida e sua contagem de bytes.
### `gateway status`
`gateway status` mostra o serviço do Gateway (launchd/systemd/schtasks) mais uma sonda opcional de capacidade de conectividade/autenticação.
`gateway status` mostra o serviço do Gateway (launchd/systemd/schtasks) mais uma sonda opcional de conectividade/capacidade de autenticação.
```bash
openclaw gateway status
@ -271,7 +271,7 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Adicione um destino de sondagem explícito. O remoto configurado + localhost ainda são sondados.
Adicione um alvo de sondagem explícito. O remoto configurado + localhost ainda são sondados.
</ParamField>
<ParamField path="--token <token>" type="string">
Autenticação por token para a sondagem.
@ -283,32 +283,32 @@ openclaw gateway status --require-rpc
Tempo limite da sondagem.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Pule a sondagem de conectividade (visão apenas do serviço).
Ignore a sondagem de conectividade (visualização somente do serviço).
</ParamField>
<ParamField path="--deep" type="boolean">
Examine também serviços em nível de sistema.
Verifique também serviços em nível de sistema.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Atualize a sondagem de conectividade padrão para uma sondagem de leitura e saia com código diferente de zero quando essa sondagem de leitura falhar. Não pode ser combinado com `--no-probe`.
Promova a sondagem de conectividade padrão para uma sondagem de leitura e saia com código diferente de zero quando essa sondagem de leitura falhar. Não pode ser combinado com `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Semântica de status">
- `gateway status` permanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou é inválida.
- `gateway status` permanece disponível para diagnósticos mesmo quando a configuração local da CLI está ausente ou inválida.
- O `gateway status` padrão comprova o estado do serviço, a conexão WebSocket e a capacidade de autenticação visível no momento do handshake. Ele não comprova operações de leitura/gravação/administração.
- As sondagens de diagnóstico não fazem mutações para autenticação de dispositivo de primeira vez: elas reutilizam um token de dispositivo existente em cache quando ele existe, mas não criam uma nova identidade de dispositivo da CLI nem um registro de pareamento de dispositivo somente leitura apenas para verificar o status.
- As sondagens de diagnóstico não fazem mutações na autenticação de dispositivos de primeiro uso: elas reutilizam um token de dispositivo em cache existente quando houver um, mas não criam uma nova identidade de dispositivo da CLI nem um registro de pareamento de dispositivo somente leitura apenas para verificar o status.
- `gateway status` resolve SecretRefs de autenticação configurados para autenticação da sondagem quando possível.
- Se um SecretRef de autenticação obrigatório não for resolvido nesse caminho de comando, `gateway status --json` relatará `rpc.authWarning` quando a conectividade/autenticação da sondagem falhar; passe `--token`/`--password` explicitamente ou resolva a origem do segredo primeiro.
- Se a sondagem for bem-sucedida, avisos de referências de autenticação não resolvidas serão suprimidos para evitar falsos positivos.
- Use `--require-rpc` em scripts e automação quando um serviço em escuta não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam íntegras.
- `--deep` adiciona uma verificação de melhor esforço por instalações extras de launchd/systemd/schtasks. Quando vários serviços semelhantes ao Gateway são detectados, a saída humana imprime dicas de limpeza e avisa que a maioria das configurações deve executar um Gateway por máquina.
- A saída humana inclui o caminho resolvido do log em arquivo mais um instantâneo dos caminhos/validade da configuração CLI-vs-serviço para ajudar a diagnosticar desvios de perfil ou diretório de estado.
- Se uma SecretRef de autenticação obrigatória não for resolvida neste caminho de comando, `gateway status --json` relata `rpc.authWarning` quando a conectividade/autenticação da sondagem falha; passe `--token`/`--password` explicitamente ou resolva a origem do segredo primeiro.
- Se a sondagem for bem-sucedida, avisos de referência de autenticação não resolvida serão suprimidos para evitar falsos positivos.
- Use `--require-rpc` em scripts e automação quando um serviço escutando não for suficiente e você também precisar que chamadas RPC com escopo de leitura estejam íntegras.
- `--deep` adiciona uma verificação de melhor esforço por instalações launchd/systemd/schtasks extras. Quando vários serviços semelhantes ao Gateway são detectados, a saída humana mostra dicas de limpeza e avisa que a maioria das configurações deve executar um Gateway por máquina.
- A saída humana inclui o caminho resolvido do arquivo de log, além de um instantâneo dos caminhos/validade da configuração da CLI versus serviço para ajudar a diagnosticar desvio de perfil ou diretório de estado.
</Accordion>
<Accordion title="Verificações de desvio de autenticação do systemd no Linux">
- Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores `Environment=` e `EnvironmentFile=` da unidade (incluindo `%h`, caminhos entre aspas, múltiplos arquivos e arquivos opcionais com `-`).
- As verificações de desvio resolvem SecretRefs de `gateway.auth.token` usando o ambiente de runtime mesclado (primeiro o ambiente do comando do serviço, depois fallback para o ambiente do processo).
- Se a autenticação por token não estiver efetivamente ativa (`gateway.auth.mode` explícito de `password`/`none`/`trusted-proxy`, ou modo não definido em que a senha pode prevalecer e nenhum candidato a token pode prevalecer), as verificações de desvio de token pulam a resolução do token de configuração.
- Em instalações Linux systemd, as verificações de desvio de autenticação do serviço leem valores de `Environment=` e `EnvironmentFile=` da unidade (incluindo `%h`, caminhos entre aspas, vários arquivos e arquivos opcionais com `-`).
- As verificações de desvio resolvem SecretRefs de `gateway.auth.token` usando o ambiente de runtime mesclado (primeiro o ambiente do comando de serviço, depois o ambiente do processo como fallback).
- Se a autenticação por token não estiver efetivamente ativa (`gateway.auth.mode` explícito como `password`/`none`/`trusted-proxy`, ou modo não definido quando a senha pode prevalecer e nenhum candidato a token pode prevalecer), as verificações de desvio de token ignoram a resolução do token de configuração.
</Accordion>
</AccordionGroup>
@ -317,17 +317,17 @@ openclaw gateway status --require-rpc
`gateway probe` é o comando de "depurar tudo". Ele sempre sonda:
- seu Gateway remoto configurado (se definido), e
- localhost (loopback) **mesmo se o remoto estiver configurado**.
- seu gateway remoto configurado (se definido), e
- localhost (loopback) **mesmo que o remoto esteja configurado**.
Se você passar `--url`, esse destino explícito será adicionado antes de ambos. A saída humana rotula os destinos como:
Se você passar `--url`, esse alvo explícito será adicionado antes de ambos. A saída humana rotula os alvos como:
- `URL (explicit)`
- `Remote (configured)` ou `Remote (configured, inactive)`
- `Local loopback`
<Note>
Se vários Gateways estiverem acessíveis, ele imprime todos. Múltiplos Gateways têm suporte quando você usa perfis/portas isolados (por exemplo, um bot de resgate), mas a maioria das instalações ainda executa um único Gateway.
Se vários gateways estiverem acessíveis, ele mostra todos. Vários gateways têm suporte quando você usa perfis/portas isolados (por exemplo, um bot de resgate), mas a maioria das instalações ainda executa um único gateway.
</Note>
```bash
@ -337,51 +337,51 @@ openclaw gateway probe --json
<AccordionGroup>
<Accordion title="Interpretação">
- `Reachable: yes` significa que pelo menos um destino aceitou uma conexão WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` relata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da alcançabilidade.
- `Read probe: ok` significa que chamadas RPC detalhadas com escopo de leitura (`health`/`status`/`system-presence`/`config.get`) também foram bem-sucedidas.
- `Read probe: limited - missing scope: operator.read` significa que a conexão foi bem-sucedida, mas o RPC com escopo de leitura está limitado. Isso é relatado como alcançabilidade **degradada**, não falha total.
- `Read probe: failed` após `Connect: ok` significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura subsequentes atingiram o tempo limite ou falharam. Isso também é alcançabilidade **degradada**, não um Gateway inalcançável.
- Assim como `gateway status`, a sondagem reutiliza a autenticação de dispositivo em cache existente, mas não cria identidade de dispositivo de primeira vez nem estado de pareamento.
- O código de saída é diferente de zero apenas quando nenhum destino sondado está acessível.
- `Reachable: yes` significa que pelo menos um alvo aceitou uma conexão WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` relata o que a sondagem conseguiu comprovar sobre autenticação. Isso é separado da acessibilidade.
- `Read probe: ok` significa que chamadas RPC de detalhe com escopo de leitura (`health`/`status`/`system-presence`/`config.get`) também foram bem-sucedidas.
- `Read probe: limited - missing scope: operator.read` significa que a conexão foi bem-sucedida, mas o RPC com escopo de leitura está limitado. Isso é relatado como acessibilidade **degradada**, não falha total.
- `Read probe: failed` após `Connect: ok` significa que o Gateway aceitou a conexão WebSocket, mas os diagnósticos de leitura seguintes atingiram o tempo limite ou falharam. Isso também é acessibilidade **degradada**, não um Gateway inacessível.
- Como `gateway status`, a sondagem reutiliza a autenticação de dispositivo em cache existente, mas não cria identidade de dispositivo de primeiro uso nem estado de pareamento.
- O código de saída é diferente de zero somente quando nenhum alvo sondado está acessível.
</Accordion>
<Accordion title="Saída JSON">
Nível superior:
- `ok`: pelo menos um destino está acessível.
- `degraded`: pelo menos um destino aceitou uma conexão, mas não concluiu todos os diagnósticos RPC detalhados.
- `capability`: melhor capacidade vista entre destinos acessíveis (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` ou `unknown`).
- `primaryTargetId`: melhor destino a tratar como vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e depois local loopback.
- `ok`: pelo menos um alvo está acessível.
- `degraded`: pelo menos um alvo aceitou uma conexão, mas não concluiu todos os diagnósticos RPC detalhados.
- `capability`: melhor capacidade observada entre alvos acessíveis (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` ou `unknown`).
- `primaryTargetId`: melhor alvo a tratar como vencedor ativo nesta ordem: URL explícita, túnel SSH, remoto configurado e, depois, local loopback.
- `warnings[]`: registros de aviso de melhor esforço com `code`, `message` e `targetIds` opcionais.
- `network`: dicas de URL de local loopback/tailnet derivadas da configuração atual e da rede do host.
- `discovery.timeoutMs` e `discovery.count`: o orçamento/contagem de resultados de descoberta reais usados nesta passagem de sondagem.
- `discovery.timeoutMs` e `discovery.count`: o orçamento/contagem de resultados real de descoberta usado nesta passada de sondagem.
Por destino (`targets[].connect`):
Por alvo (`targets[].connect`):
- `ok`: alcançabilidade após conexão + classificação degradada.
- `rpcOk`: sucesso total do RPC detalhado.
- `scopeLimited`: RPC detalhado falhou devido à ausência de escopo de operador.
- `ok`: acessibilidade após conexão + classificação degradada.
- `rpcOk`: sucesso completo de RPC detalhado.
- `scopeLimited`: o RPC detalhado falhou devido à ausência de escopo de operador.
Por destino (`targets[].auth`):
Por alvo (`targets[].auth`):
- `role`: função de autenticação relatada em `hello-ok` quando disponível.
- `scopes`: escopos concedidos relatados em `hello-ok` quando disponíveis.
- `capability`: a classificação de capacidade de autenticação exposta para esse destino.
- `capability`: a classificação de capacidade de autenticação exibida para esse alvo.
</Accordion>
<Accordion title="Códigos de aviso comuns">
- `ssh_tunnel_failed`: a configuração do túnel SSH falhou; o comando recorreu a sondagens diretas.
- `multiple_gateways`: mais de um destino estava acessível; isso é incomum, a menos que você execute intencionalmente perfis isolados, como um bot de resgate.
- `auth_secretref_unresolved`: um SecretRef de autenticação configurado não pôde ser resolvido para um destino com falha.
- `ssh_tunnel_failed`: a configuração do túnel SSH falhou; o comando voltou para sondagens diretas.
- `multiple_gateways`: mais de um alvo estava acessível; isso é incomum, a menos que você execute perfis isolados intencionalmente, como um bot de resgate.
- `auth_secretref_unresolved`: uma SecretRef de autenticação configurada não pôde ser resolvida para um alvo com falha.
- `probe_scope_limited`: a conexão WebSocket foi bem-sucedida, mas a sondagem de leitura foi limitada pela ausência de `operator.read`.
</Accordion>
</AccordionGroup>
#### Remoto via SSH (paridade com o app para Mac)
#### Remoto via SSH (paridade do app Mac)
O modo "Remote over SSH" do app macOS usa um encaminhamento de porta local para que o Gateway remoto (que pode estar vinculado apenas ao loopback) fique acessível em `ws://127.0.0.1:<port>`.
O modo "Remote over SSH" do app macOS usa um encaminhamento de porta local para que o gateway remoto (que pode estar vinculado apenas ao loopback) fique acessível em `ws://127.0.0.1:<port>`.
Equivalente na CLI:
@ -396,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host
Arquivo de identidade.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Escolha o primeiro host de Gateway descoberto como destino SSH a partir do endpoint de descoberta resolvido (`local.` mais o domínio de longa distância configurado, se houver). Dicas somente TXT são ignoradas.
Escolha o primeiro host de Gateway descoberto como alvo SSH a partir do endpoint de descoberta resolvido (`local.` mais o domínio de longa distância configurado, se houver). Dicas somente TXT são ignoradas.
</ParamField>
Configuração (opcional, usada como padrão):
@ -429,7 +429,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Orçamento de tempo limite.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Principalmente para RPCs no estilo agente que transmitem eventos intermediários antes de um payload final.
Principalmente para RPCs no estilo de agente que transmitem eventos intermediários antes de um payload final.
</ParamField>
<ParamField path="--json" type="boolean">
Saída JSON legível por máquina.
@ -439,7 +439,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
`--params` deve ser JSON válido.
</Note>
## Gerencie o serviço Gateway
## Gerenciar o serviço Gateway
```bash
openclaw gateway install
@ -452,8 +452,8 @@ openclaw gateway uninstall
### Instalar com um wrapper
Use `--wrapper` quando o serviço gerenciado precisar iniciar por meio de outro executável, por exemplo um
shim de gerenciador de segredos ou um auxiliar run-as. O wrapper recebe os argumentos normais do Gateway e é
responsável por eventualmente executar `openclaw` ou Node com esses argumentos via exec.
shim de gerenciador de segredos ou um auxiliar de execução como outro usuário. O wrapper recebe os argumentos normais do Gateway e é
responsável por eventualmente executar `openclaw` ou Node com esses argumentos.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -477,7 +477,7 @@ OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --
openclaw doctor
```
Para remover um wrapper persistido, limpe `OPENCLAW_WRAPPER` durante a reinstalação:
Para remover um wrapper persistido, limpe `OPENCLAW_WRAPPER` ao reinstalar:
```bash
OPENCLAW_WRAPPER= openclaw gateway install --force
@ -488,43 +488,44 @@ openclaw gateway restart
<Accordion title="Opções de comando">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Comportamento do ciclo de vida">
- Use `gateway restart` para reiniciar um serviço gerenciado. Não encadeie `gateway stop` e `gateway start` como substituto de reinicialização; no macOS, `gateway stop` desativa intencionalmente o LaunchAgent antes de pará-lo.
- `gateway restart --safe` solicita ao Gateway em execução que faça uma pré-verificação do trabalho ativo do OpenClaw e adie a reinicialização até que a entrega de respostas, execuções incorporadas e execuções de tarefas sejam drenadas. `--safe` não pode ser combinado com `--force` ou `--wait`.
- `gateway restart --wait 30s` substitui o orçamento configurado de drenagem de reinicialização para essa reinicialização. Números sem unidade são milissegundos; unidades como `s`, `m` e `h` são aceitas. `--wait 0` aguarda indefinidamente.
- `gateway restart --force` pula a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já tiver inspecionado os bloqueadores de tarefas listados e quiser o Gateway de volta agora.
- Comandos de ciclo de vida aceitam `--json` para scripts.
- `gateway restart --force` ignora a drenagem de trabalho ativo e reinicia imediatamente. Use quando um operador já inspecionou os bloqueadores de tarefas listados e quer o gateway de volta agora.
- Os comandos de ciclo de vida aceitam `--json` para scripts.
</Accordion>
<Accordion title="Autenticação e SecretRefs no momento da instalação">
- Quando a autenticação por token requer um token e `gateway.auth.token` é gerenciado por SecretRef, `gateway install` valida que o SecretRef pode ser resolvido, mas não persiste o token resolvido nos metadados de ambiente do serviço.
- Se a autenticação por token requer um token e o SecretRef de token configurado não é resolvido, a instalação falha de forma fechada em vez de persistir fallback em texto claro.
- Para autenticação por senha em `gateway run`, prefira `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` ou um `gateway.auth.password` com suporte de SecretRef em vez de `--password` inline.
- No modo de autenticação inferido, `OPENCLAW_GATEWAY_PASSWORD` apenas no shell não relaxa os requisitos de token de instalação; use configuração durável (`gateway.auth.password` ou `env` de configuração) ao instalar um serviço gerenciado.
<Accordion title="Auth and SecretRefs at install time">
- Quando a autenticação por token exige um token e `gateway.auth.token` é gerenciado por SecretRef, `gateway install` valida que o SecretRef pode ser resolvido, mas não persiste o token resolvido nos metadados de ambiente do serviço.
- Se a autenticação por token exige um token e o SecretRef do token configurado não é resolvido, a instalação falha de modo fechado em vez de persistir texto simples de fallback.
- Para autenticação por senha em `gateway run`, prefira `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` ou um `gateway.auth.password` apoiado por SecretRef em vez de `--password` inline.
- No modo de autenticação inferido, `OPENCLAW_GATEWAY_PASSWORD` disponível apenas no shell não flexibiliza os requisitos de token da instalação; use configuração durável (`gateway.auth.password` ou `env` de configuração) ao instalar um serviço gerenciado.
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, a instalação será bloqueada até que o modo seja definido explicitamente.
</Accordion>
</AccordionGroup>
## Descobrir Gateways (Bonjour)
## Descobrir gateways (Bonjour)
`gateway discover` verifica beacons do Gateway (`_openclaw-gw._tcp`).
`gateway discover` verifica beacons de Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Bonjour de área ampla): escolha um domínio (exemplo: `openclaw.internal.`) e configure DNS dividido + um servidor DNS; consulte [Bonjour](/pt-BR/gateway/bonjour).
- DNS-SD multicast: `local.`
- DNS-SD unicast (Bonjour de área ampla): escolha um domínio (exemplo: `openclaw.internal.`) e configure DNS dividido + um servidor DNS; consulte [Bonjour](/pt-BR/gateway/bonjour).
Somente gateways com descoberta Bonjour habilitada (padrão) anunciam o sinalizador.
Somente gateways com descoberta Bonjour habilitada (padrão) anunciam o beacon.
Registros de descoberta de área ampla incluem (TXT):
- `role` (dica de função do gateway)
- `transport` (dica de transporte, por exemplo, `gateway`)
- `gatewayPort` (porta WebSocket, geralmente `18789`)
- `sshPort` (opcional; clientes usam `22` como destino SSH padrão quando ausente)
- `tailnetDns` (nome de host MagicDNS, quando disponível)
- `sshPort` (opcional; clientes usam `22` como padrão para destinos SSH quando ausente)
- `tailnetDns` (nome do host MagicDNS, quando disponível)
- `gatewayTls` / `gatewayTlsSha256` (TLS habilitado + impressão digital do certificado)
- `cliPath` (dica de instalação remota gravada na zona de área ampla)
@ -535,10 +536,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
Tempo limite por comando (busca/resolução).
Tempo limite por comando (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
Saída legível por máquina (também desabilita estilo/spinner).
Saída legível por máquina (também desativa estilo/spinner).
</ParamField>
Exemplos:
@ -549,13 +550,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- A CLI examina `local.` mais o domínio de área ampla configurado quando um está habilitado.
- `wsUrl` na saída JSON é derivado do endpoint de serviço resolvido, não de dicas apenas em TXT, como `lanHost` ou `tailnetDns`.
- Em mDNS `local.`, `sshPort` e `cliPath` só são transmitidos quando `discovery.mdns.mode` é `full`. DNS-SD de área ampla ainda grava `cliPath`; `sshPort` também permanece opcional lá.
- A CLI verifica `local.` mais o domínio de área ampla configurado quando algum está habilitado.
- `wsUrl` na saída JSON é derivado do endpoint de serviço resolvido, não de dicas apenas de TXT, como `lanHost` ou `tailnetDns`.
- No mDNS `local.`, `sshPort` e `cliPath` só são transmitidos quando `discovery.mdns.mode` é `full`. DNS-SD de área ampla ainda grava `cliPath`; `sshPort` também continua opcional ali.
</Note>
## Relacionados
## Relacionado
- [Referência da CLI](/pt-BR/cli)
- [Runbook do Gateway](/pt-BR/gateway)

185
docs/pt-BR/cli/plugins.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Você deseja instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
- Você quer depurar falhas de carregamento de Plugin
- Você quer instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
- Você quer depurar falhas no carregamento de Plugin
sidebarTitle: Plugins
summary: Referência da CLI para `openclaw plugins` (listar, instalar, marketplace, desinstalar, habilitar/desabilitar, doctor)
summary: Referência da CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Plugins
x-i18n:
generated_at: "2026-05-04T09:37:13Z"
generated_at: "2026-05-05T01:44:32Z"
model: gpt-5.5
provider: openai
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
source_path: cli/plugins.md
workflow: 16
---
@ -63,15 +63,15 @@ openclaw plugins marketplace list <marketplace> --json
```
Para investigar instalações, inspeções, desinstalações ou atualizações de registro lentas, execute o
comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava os tempos das fases
comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava tempos das fases
em stderr e mantém a saída JSON analisável. Consulte [Depuração](/pt-BR/help/debugging#plugin-lifecycle-trace).
<Note>
Plugins empacotados são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelo empacotados, provedores de fala empacotados e o Plugin de navegador empacotado); outros exigem `plugins enable`.
Plugins incluídos são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelos incluídos, provedores de fala incluídos e o plugin de navegador incluído); outros exigem `plugins enable`.
Plugins nativos do OpenClaw devem incluir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
Plugins nativos do OpenClaw devem distribuir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo do bundle (`codex`, `claude` ou `cursor`) além das capacidades de bundle detectadas.
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo do bundle (`codex`, `claude` ou `cursor`) mais as capacidades de bundle detectadas.
</Note>
### Instalar
@ -93,17 +93,17 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
Nomes de pacote simples são instalados a partir do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para o ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
Nomes de pacotes sem prefixo são instalados a partir do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
</Warning>
`plugins search` consulta o ClawHub em busca de pacotes de plugins instaláveis e imprime
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de Plugin de código e Plugin de bundle,
não Skills. Use `openclaw skills search` para Skills do ClawHub.
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de plugins de código e de plugins de bundle,
não skills. Use `openclaw skills search` para Skills do ClawHub.
<Note>
ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. O npm
continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de Plugin
`@openclaw/*` mantidos pelo OpenClaw foram publicados novamente no npm; veja a lista atual
ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. Npm
continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de plugins
`@openclaw/*` de propriedade do OpenClaw voltaram a ser publicados no npm; veja a lista atual
em [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou no
[inventário de plugins](/pt-BR/plugins/plugin-inventory). Instalações estáveis usam `latest`.
Instalações e atualizações do canal beta preferem a dist-tag `beta` do npm quando essa tag
@ -112,50 +112,50 @@ está disponível, depois recorrem a `latest`.
<AccordionGroup>
<Accordion title="Includes de configuração e reparo de configuração inválida">
Se sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de includes e includes com substituições irmãs falham de forma fechada em vez de serem achatados. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
Se a sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` gravam nesse arquivo incluído e deixam `openclaw.json` intocado. Includes raiz, arrays de include e includes com sobrescritas irmãs falham de forma fechada em vez de serem achatados. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e orienta você a executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração de Plugin inválida falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar a entrada inválida do Plugin em quarentena. A única exceção documentada em tempo de instalação é um caminho estreito de recuperação de Plugin empacotado para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e orienta você a executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração inválida de plugin falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar em quarentena a entrada inválida do plugin. A única exceção documentada no momento da instalação é um caminho restrito de recuperação de plugin incluído para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
</Accordion>
<Accordion title="--force e reinstalação versus atualização">
`--force` reutiliza o destino de instalação existente e sobrescreve um Plugin ou pacote de hooks já instalado no lugar. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para upgrades rotineiros de um Plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force e reinstalação vs atualização">
`--force` reutiliza o destino de instalação existente e sobrescreve no local um plugin ou pacote de hooks já instalado. Use quando estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para upgrades rotineiros de um plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
Se você executar `plugins install` para um id de Plugin que já está instalado, o OpenClaw interrompe e aponta para `plugins update <id-or-npm-spec>` para um upgrade normal, ou para `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
Se você executar `plugins install` para um id de plugin que já está instalado, o OpenClaw para e aponta para `plugins update <id-or-npm-spec>` para um upgrade normal, ou para `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
</Accordion>
<Accordion title="Escopo de --pin">
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de fonte do marketplace em vez de uma especificação npm.
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados da fonte do marketplace em vez de uma especificação npm.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no verificador integrado de código perigoso. Ela permite que a instalação continue mesmo quando o verificador integrado relata achados `critical`, mas **não** ignora bloqueios de política de hook `before_install` do Plugin e **não** ignora falhas de varredura.
`--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no scanner integrado de código perigoso. Ela permite que a instalação continue mesmo quando o scanner integrado relata achados `critical`, mas **não** contorna bloqueios de política de hook `before_install` do plugin e **não** contorna falhas de varredura.
Essa flag da CLI se aplica a fluxos de instalação/atualização de Plugin. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
Essa flag de CLI se aplica a fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de requisição correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
Se um Plugin que você publicou no ClawHub for bloqueado por uma varredura de registro, use as etapas para publicadores em [ClawHub](/pt-BR/tools/clawhub).
Se um plugin que você publicou no ClawHub for bloqueado por uma varredura do registro, use as etapas de publicador em [ClawHub](/pt-BR/tools/clawhub).
</Accordion>
<Accordion title="Pacotes de hooks e especificações npm">
`plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacote.
`plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacotes.
Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências rodam localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm.
Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências são executadas localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação do npm.
Use `npm:<package>` quando quiser explicitar a resolução npm. Especificações de pacote simples também instalam diretamente do npm durante a transição de lançamento.
Use `npm:<package>` quando quiser tornar a resolução npm explícita. Especificações de pacote sem prefixo também instalam diretamente do npm durante a transição de lançamento.
Especificações simples e `@latest` permanecem na faixa estável. Versões de correção datadas do OpenClaw, como `2026.5.3-1`, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você aceite explicitamente com uma tag de pré-versão, como `@beta`/`@rc`, ou uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
Especificações sem prefixo e `@latest` permanecem na trilha estável. Versões de correção do OpenClaw com carimbo de data, como `2026.5.3-1`, são lançamentos estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw para e pede que você opte explicitamente por uma tag de pré-versão, como `@beta`/`@rc`, ou por uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
Se uma especificação de instalação simples corresponder a um id oficial de Plugin (por exemplo, `diffs`), o OpenClaw instala a entrada do catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícito (por exemplo, `@scope/diffs`).
Se uma especificação de instalação sem prefixo corresponder a um id oficial de plugin (por exemplo, `diffs`), o OpenClaw instala a entrada do catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícito (por exemplo, `@scope/diffs`).
</Accordion>
<Accordion title="Repositórios Git">
Use `git:<repo>` para instalar diretamente de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completas `https://`, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git` de clone. Adicione `@<ref>` ou `#<ref>` para fazer checkout de um branch, tag ou commit antes da instalação.
Use `git:<repo>` para instalar diretamente a partir de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completos `https://`, `ssh://`, `git://`, `file://` e URLs de clone `git@host:owner/repo.git`. Adicione `@<ref>` ou `#<ref>` para fazer checkout de uma branch, tag ou commit antes da instalação.
Instalações Git clonam para um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de Plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a fonte mais tarde.
Instalações Git clonam em um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a fonte depois.
Depois de instalar a partir de git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos da CLI. Se o Plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
Depois de instalar a partir de git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos de CLI. Se o plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Arquivos">
Arquivos compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos de Plugin nativo do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do Plugin; arquivos que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
Arquivos compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos de plugins nativos do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do plugin; arquivos que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
Instalações do marketplace Claude também são compatíveis.
@ -169,25 +169,25 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Especificações de Plugin simples seguras para npm instalam a partir do npm por padrão durante a transição de lançamento:
Especificações de plugin seguras para npm sem prefixo são instaladas a partir do npm por padrão durante a transição de lançamento:
```bash
openclaw plugins install openclaw-codex-app-server
```
Use `npm:` para explicitar a resolução somente por npm:
Use `npm:` para tornar a resolução somente npm explícita:
```bash
openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
O OpenClaw verifica a API de Plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo. Versões antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações posteriores.
Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que `openclaw plugins update` possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor.
O OpenClaw verifica a API de plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo. Versões antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações futuras.
Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que `openclaw plugins update` possa acompanhar lançamentos mais novos do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados a esse seletor.
#### Atalho de marketplace
#### Abreviação de marketplace
Use o atalho `plugin@marketplace` quando o nome do marketplace existir no cache de registro local do Claude em `~/.claude/plugins/known_marketplaces.json`:
Use a abreviação `plugin@marketplace` quando o nome do marketplace existir no cache local de registro do Claude em `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
@ -204,28 +204,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
<Tabs>
<Tab title="Marketplace sources">
<Tab title="Fontes de marketplace">
- um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json`
- uma raiz de marketplace local ou um caminho `marketplace.json`
- um atalho de repositório do GitHub, como `owner/repo`
- uma URL de repositório do GitHub, como `https://github.com/owner/repo`
- uma raiz de marketplace local ou caminho de `marketplace.json`
- um atalho de repositório GitHub, como `owner/repo`
- uma URL de repositório GitHub, como `https://github.com/owner/repo`
- uma URL git
</Tab>
<Tab title="Remote marketplace rules">
Para marketplaces remotos carregados do GitHub ou git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras fontes de Plugin que não sejam caminhos em manifests remotos.
<Tab title="Regras de marketplace remoto">
Para marketplaces remotos carregados do GitHub ou git, as entradas de plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras fontes de plugin que não sejam caminhos em manifestos remotos.
</Tab>
</Tabs>
Para caminhos locais e arquivos compactados, o OpenClaw detecta automaticamente:
Para caminhos locais e arquivos, o OpenClaw detecta automaticamente:
- Plugins nativos do OpenClaw (`openclaw.plugin.json`)
- plugins nativos do OpenClaw (`openclaw.plugin.json`)
- pacotes compatíveis com Codex (`.codex-plugin/plugin.json`)
- pacotes compatíveis com Claude (`.claude-plugin/plugin.json` ou o layout padrão de componentes do Claude)
- pacotes compatíveis com Cursor (`.cursor-plugin/plugin.json`)
<Note>
Pacotes compatíveis são instalados na raiz normal de Plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifest, Skills de comando do Cursor e diretórios de hooks compatíveis do Codex; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
Pacotes compatíveis são instalados na raiz normal de plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifesto, Skills de comando do Cursor e diretórios de hooks Codex compatíveis; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
</Note>
### Listar
@ -241,28 +241,29 @@ openclaw plugins search <query> --json
```
<ParamField path="--enabled" type="boolean">
Mostra apenas Plugins habilitados.
Mostra apenas plugins habilitados.
</ParamField>
<ParamField path="--verbose" type="boolean">
Alterna da visualização em tabela para linhas detalhadas por Plugin com metadados de fonte/origem/versão/ativação.
Alterna da visualização em tabela para linhas de detalhes por plugin com metadados de fonte/origem/versão/ativação.
</ParamField>
<ParamField path="--json" type="boolean">
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacote.
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências do pacote.
</ParamField>
<Note>
`plugins list` lê primeiro o registro local persistido de Plugins, com um fallback derivado apenas de manifest quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime em tempo real de um processo Gateway já em execução. Depois de alterar código de Plugin, habilitação, política de hooks ou `plugins.load.paths`, reinicie o Gateway que atende o canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper.
`plugins list` lê primeiro o registro de plugins local persistido, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um plugin está instalado, habilitado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime ativa de um processo Gateway já em execução. Depois de alterar o código do plugin, a habilitação, a política de hooks ou `plugins.load.paths`, reinicie o Gateway que atende ao canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper.
`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` de `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de busca `node_modules` do Node do Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
`plugins list --json` inclui o `dependencyStatus` de cada plugin a partir de
`dependencies` e `optionalDependencies` em `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de consulta de `node_modules` do Node do plugin; ele não importa código de runtime do plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
</Note>
`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados da busca incluem o nome do pacote no ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:<package>`.
`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera a configuração, não instala pacotes nem carrega código de runtime de plugin. Os resultados da busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:<package>`.
Para trabalho com Plugin incluído dentro de uma imagem Docker empacotada, monte o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, de modo que instalações empacotadas normais continuam usando o dist compilado.
Para trabalho com plugin incluído em uma imagem Docker empacotada, monte com bind o diretório de origem do plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, para que instalações empacotadas normais ainda usem o dist compilado.
Para depuração de hooks em runtime:
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou instalar Plugins baixáveis configurados que estejam ausentes.
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou recuperar plugins baixáveis ausentes referenciados pela configuração.
- `openclaw gateway status --deep --require-rpc` confirma o Gateway acessível, dicas de serviço/processo, caminho de configuração e integridade de RPC.
- Hooks de conversa não incluídos (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigem `plugins.entries.<id>.hooks.allowConversationAccess=true`.
@ -275,14 +276,14 @@ openclaw plugins install -l ./my-plugin
<Note>
`--force` não é compatível com `--link` porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.
Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de Plugins gerenciado, mantendo o comportamento padrão sem fixação.
Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de plugins gerenciado, mantendo o comportamento padrão sem fixação.
</Note>
### Índice de Plugins
### Índice de plugins
Metadados de instalação de Plugin são estado gerenciado pela máquina, não configuração do usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros de manifests de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado de manifest. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e o registro frio de Plugins.
Metadados de instalação de plugins são estado gerenciado por máquina, não configuração de usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável dos metadados de instalação, incluindo registros de manifestos de plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado do manifesto. O arquivo inclui um aviso para não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e pelo registro frio de plugins.
Quando o OpenClaw vê registros legados enviados de `plugins.installs` na configuração, ele os move para o índice de Plugins e remove a chave de configuração; se qualquer uma das gravações falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.
Quando o OpenClaw encontra registros legados enviados em `plugins.installs` na configuração, ele os move para o índice de plugins e remove a chave de configuração; se qualquer gravação falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.
### Desinstalar
@ -292,10 +293,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de Plugins, de entradas de lista de permissão/negação de Plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de Plugins do OpenClaw. Para Plugins de Active Memory, o slot de memória é redefinido para `memory-core`.
`uninstall` remove registros de plugin de `plugins.entries`, do índice de plugins persistido, de entradas de lista de permissão/bloqueio de plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de plugins do OpenClaw. Para plugins de memória ativa, o slot de memória é redefinido para `memory-core`.
<Note>
`--keep-config` é compatível como um alias obsoleto de `--keep-files`.
`--keep-config` é compatível como alias obsoleto de `--keep-files`.
</Note>
### Atualizar
@ -308,29 +309,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Atualizações se aplicam a instalações de Plugin rastreadas no índice de Plugins gerenciado e a instalações de pacotes de hooks rastreadas em `hooks.internal.installs`.
Atualizações se aplicam a instalações de plugin rastreadas no índice de plugins gerenciado e a instalações de pacotes de hooks rastreadas em `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Resolving plugin id vs npm spec">
Quando você passa um id de Plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam sendo usadas em execuções posteriores de `update <id>`.
<Accordion title="Resolução de id de plugin vs especificação npm">
Quando você passa um id de plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam sendo usadas em execuções posteriores de `update <id>`.
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id.
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de plugin rastreado, atualiza esse plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id.
Passar o nome do pacote npm sem versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin tiver sido fixado a uma versão exata e você quiser movê-lo de volta para a linha de lançamento padrão do registro.
Passar o nome do pacote npm sem uma versão ou tag também resolve de volta para o registro de plugin rastreado. Use isso quando um plugin foi fixado em uma versão exata e você quer movê-lo de volta para a linha de lançamento padrão do registro.
</Accordion>
<Accordion title="Beta channel updates">
`openclaw plugins update` reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e, em seguida, fazem fallback para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor.
<Accordion title="Atualizações do canal beta">
`openclaw plugins update` reutiliza a especificação de plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e depois retornam para a especificação padrão/latest registrada se não existir uma versão beta do plugin. Versões exatas e tags explícitas permanecem fixadas a esse seletor.
</Accordion>
<Accordion title="Version checks and integrity drift">
Antes de uma atualização npm em tempo real, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
<Accordion title="Verificações de versão e desvio de integridade">
Antes de uma atualização npm ativa, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já correspondem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de continuar. Auxiliares de atualização não interativos falham em modo fechado, a menos que o chamador forneça uma política de continuação explícita.
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e solicita confirmação antes de continuar. Auxiliares de atualização não interativos falham de forma fechada, a menos que o chamador forneça uma política explícita de continuação.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição de emergência para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não contorna bloqueios de política `before_install` do Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de pacotes de hooks.
<Accordion title="--dangerously-force-unsafe-install na atualização">
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição de emergência para falsos positivos da verificação integrada de código perigoso durante atualizações de plugins. Ele ainda não contorna bloqueios de política `before_install` de plugin nem bloqueios por falha de verificação, e se aplica apenas a atualizações de plugins, não a atualizações de pacotes de hooks.
</Accordion>
</AccordionGroup>
@ -342,21 +343,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
A inspeção mostra identidade, estado de carregamento, fonte, recursos do manifest, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidores MCP ou LSP sem importar o runtime do Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção de runtime relata dependências ausentes do Plugin diretamente; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
Inspecionar mostra identidade, status de carregamento, fonte, capacidades do manifesto, sinalizadores de política, diagnósticos, metadados de instalação, capacidades de pacote e qualquer suporte detectado a servidor MCP ou LSP sem importar o runtime do plugin por padrão. Adicione `--runtime` para carregar o módulo do plugin e incluir hooks, ferramentas, comandos, serviços, métodos de gateway e rotas HTTP registrados. A inspeção de runtime relata dependências de plugin ausentes diretamente; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
Comandos de CLI pertencentes a Plugins são instalados como grupos de comandos raiz `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
Comandos de CLI pertencentes a plugins são instalados como grupos de comandos raiz de `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
Cada Plugin é classificado pelo que ele realmente registra em runtime:
Cada plugin é classificado pelo que ele realmente registra em runtime:
- **plain-capability** — um tipo de recurso (por exemplo, um Plugin apenas de provedor)
- **hybrid-capability** — vários tipos de recurso (por exemplo, texto + fala + imagens)
- **hook-only** — apenas hooks, sem recursos ou superfícies
- **non-capability** — ferramentas/comandos/serviços, mas sem recursos
- **plain-capability** — um tipo de capacidade (por exemplo, um plugin somente de provedor)
- **hybrid-capability** — vários tipos de capacidade (por exemplo, texto + fala + imagens)
- **hook-only** — apenas hooks, sem capacidades ou superfícies
- **non-capability** — ferramentas/comandos/serviços, mas sem capacidades
Consulte [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de recursos.
Consulte [Formatos de plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de capacidades.
<Note>
A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de recurso, avisos de compatibilidade, recursos de pacote e resumo de hooks. `info` é um alias de `inspect`.
A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de capacidade, avisos de compatibilidade, capacidades de pacote e resumo de hooks. `info` é um alias de `inspect`.
</Note>
### Doctor
@ -365,11 +366,11 @@ A flag `--json` gera um relatório legível por máquina adequado para scripts e
openclaw plugins doctor
```
`doctor` relata erros de carregamento de Plugin, diagnósticos de manifest/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
`doctor` relata erros de carregamento de plugins, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
Se um Plugin configurado estiver presente no disco, mas bloqueado pelas verificações de segurança de caminho do loader, a validação de configuração mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade de caminho ou permissões graváveis pelo mundo, em vez de remover a configuração `plugins.entries.<id>` ou `plugins.allow`.
Se um plugin configurado está presente no disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação de configuração mantém a entrada do plugin e a relata como `present but blocked`. Corrija o diagnóstico de plugin bloqueado anterior, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a configuração `plugins.entries.<id>` ou `plugins.allow`.
Para falhas de formato de módulo, como exports `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato dos exports na saída de diagnóstico.
Para falhas de formato de módulo, como exportações `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato de exportação na saída de diagnóstico.
### Registro
@ -379,14 +380,14 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
O registro local de Plugins é o modelo persistido de leitura fria do OpenClaw para identidade de Plugins instalados, habilitação, metadados de fonte e propriedade de contribuição. A inicialização normal, a busca de proprietário de provedor, a classificação de configuração de canal e o inventário de Plugins podem lê-lo sem importar módulos de runtime de Plugin.
O registro local de plugins é o modelo de leitura fria persistido do OpenClaw para identidade de plugins instalados, habilitação, metadados de fonte e propriedade de contribuições. Inicialização normal, consulta de proprietário de provedor, classificação de configuração de canal e inventário de plugins podem lê-lo sem importar módulos de runtime de plugins.
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice persistido de Plugins, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice de Plugin persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
`openclaw doctor --fix` também repara desvios de npm gerenciado adjacentes ao registro: se um pacote `@openclaw/*` órfão ou recuperado sob a raiz npm de Plugins gerenciados sombrear um Plugin incluído, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto incluído.
`openclaw doctor --fix` também repara desvios de npm gerenciado adjacentes ao registro: se um pacote `@openclaw/*` órfão ou recuperado sob a raiz npm de Plugin gerenciado sombrear um Plugin incluído, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto incluído.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma chave de compatibilidade emergencial obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por env é apenas para recuperação emergencial de inicialização enquanto a migração é distribuída.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma opção de compatibilidade emergencial obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por env é apenas para recuperação emergencial de inicialização enquanto a migração é implantada.
</Warning>
### Mercado
@ -396,10 +397,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
A listagem do mercado aceita um caminho local de mercado, um caminho `marketplace.json`, um atalho do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da fonte resolvida, além do manifesto de mercado analisado e das entradas de Plugin.
A listagem do mercado aceita um caminho de mercado local, um caminho `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório GitHub ou uma URL git. `--json` imprime o rótulo da fonte resolvida mais o manifesto de mercado analisado e as entradas de Plugin.
## Relacionado
- [Criando Plugins](/pt-BR/plugins/building-plugins)
- [Criação de Plugins](/pt-BR/plugins/building-plugins)
- [Referência da CLI](/pt-BR/cli)
- [Plugins da comunidade](/pt-BR/plugins/community)

43
docs/pt-BR/cli/sessions.md
View File

@ -1,30 +1,31 @@
---
read_when:
- Você quer listar as sessões armazenadas e ver a atividade recente
- Você quer listar sessões armazenadas e ver a atividade recente
summary: Referência da CLI para `openclaw sessions` (listar sessões armazenadas + uso)
title: Sessões
x-i18n:
generated_at: "2026-05-04T07:02:44Z"
generated_at: "2026-05-05T01:44:15Z"
model: gpt-5.5
provider: openai
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
Liste sessões de conversa armazenadas.
Liste as sessões de conversa armazenadas.
Listas de sessões não são verificações de disponibilidade de canal/provedor. Elas mostram linhas de conversa persistidas dos armazenamentos de sessões. Um Discord, Slack, Telegram ou outro canal silencioso pode se reconectar com sucesso sem criar uma nova linha de sessão até que uma mensagem seja processada. Use `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` quando precisar de conectividade de canal ao vivo.
Listas de sessões não são verificações de conectividade de canal/provedor. Elas mostram linhas de conversa persistidas dos armazenamentos de sessão. Um Discord, Slack, Telegram ou outro canal silencioso pode se reconectar com sucesso sem criar uma nova linha de sessão até que uma mensagem seja processada. Use `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` quando precisar de conectividade de canal ao vivo.
As respostas `sessions.list` do Gateway são limitadas por padrão para que armazenamentos grandes e de longa duração não monopolizem o loop de eventos do Gateway. Passe um `limit` positivo explícito de clientes RPC quando uma janela de resultados diferente for necessária; as respostas incluem `totalCount`, `limitApplied` e `hasMore` quando os chamadores precisam mostrar que existem mais linhas.
As respostas de `openclaw sessions` e Gateway `sessions.list` são limitadas por padrão para que armazenamentos grandes e de longa duração não monopolizem o processo da CLI ou o loop de eventos do Gateway. A CLI retorna as 100 sessões mais recentes por padrão; passe `--limit <n>` para uma janela menor/maior ou `--limit all` quando você precisar intencionalmente do armazenamento completo. Respostas JSON incluem `totalCount`, `limitApplied` e `hasMore` quando chamadores precisam mostrar que existem mais linhas.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json
```
@ -35,7 +36,8 @@ Seleção de escopo:
- `--verbose`: registro em log detalhado
- `--agent <id>`: um armazenamento de agente configurado
- `--all-agents`: agrega todos os armazenamentos de agentes configurados
- `--store <path>`: caminho explícito do armazenamento (não pode ser combinado com `--agent` ou `--all-agents`)
- `--store <path>`: caminho de armazenamento explícito (não pode ser combinado com `--agent` ou `--all-agents`)
- `--limit <n|all>`: máximo de linhas a gerar na saída (padrão `100`; `all` restaura a saída completa)
Exporte um pacote de trajetória para uma sessão armazenada:
@ -44,9 +46,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de exec. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no workspace selecionado.
Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de execução. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no workspace selecionado.
`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` com modelo. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; symlinks e caminhos fora da raiz são ignorados.
`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` modelada. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; links simbólicos e caminhos fora da raiz são ignorados.
Exemplos JSON:
@ -61,6 +63,9 @@ Exemplos JSON:
],
"allAgents": true,
"count": 2,
"totalCount": 2,
"limitApplied": 100,
"hasMore": false,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
@ -82,21 +87,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123
openclaw sessions cleanup --json
```
`openclaw sessions cleanup` usa as configurações `session.maintenance` da configuração:
`openclaw sessions cleanup` usa as configurações de `session.maintenance` da configuração:
- Observação de escopo: `openclaw sessions cleanup` faz manutenção de armazenamentos de sessões, transcrições e sidecars de trajetória. Ele não remove logs de execução de Cron (`cron/runs/<jobId>.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance).
- Observação de escopo: `openclaw sessions cleanup` mantém armazenamentos de sessão, transcrições e sidecars de trajetória. Ele não poda logs de execução de Cron (`cron/runs/<jobId>.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance).
- `--dry-run`: visualiza quantas entradas seriam removidas/limitadas sem gravar.
- No modo de texto, dry-run imprime uma tabela de ações por sessão (`Action`, `Key`, `Age`, `Model`, `Flags`) para que você veja o que seria mantido ou removido.
- `--enforce`: aplica manutenção mesmo quando `session.maintenance.mode` é `warn`.
- `--dry-run`: visualize quantas entradas seriam podadas/limitadas sem gravar.
- No modo de texto, dry-run imprime uma tabela de ações por sessão (`Action`, `Key`, `Age`, `Model`, `Flags`) para que você possa ver o que seria mantido vs removido.
- `--enforce`: aplica a manutenção mesmo quando `session.maintenance.mode` é `warn`.
- `--fix-missing`: remove entradas cujos arquivos de transcrição estão ausentes, mesmo que elas normalmente ainda não fossem removidas por idade/contagem.
- `--active-key <key>`: protege uma chave ativa específica da remoção por orçamento de disco. Ponteiros duráveis de conversas externas, como sessões de grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção de idade/contagem/orçamento de disco.
- `--active-key <key>`: protege uma chave ativa específica contra remoção por orçamento de disco. Ponteiros duráveis de conversas externas, como sessões de grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção por idade/contagem/orçamento de disco.
- `--agent <id>`: executa a limpeza para um armazenamento de agente configurado.
- `--all-agents`: executa a limpeza para todos os armazenamentos de agentes configurados.
- `--store <path>`: executa contra um arquivo `sessions.json` específico.
- `--json`: imprime um resumo JSON. Com `--all-agents`, a saída inclui um resumo por armazenamento.
Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada pelo Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões que o tráfego de runtime. Use `--store <path>` para reparo offline explícito de um arquivo de armazenamento.
Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada por meio do Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões do tráfego de runtime. Use `--store <path>` para reparo offline explícito de um arquivo de armazenamento.
`openclaw sessions cleanup --all-agents --dry-run --json`:
@ -128,9 +133,9 @@ Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de
Relacionado:
- Configuração de sessão: [Referência de configuração](/pt-BR/gateway/config-agents#session)
- Configuração de sessão: [referência de configuração](/pt-BR/gateway/config-agents#session)
## Relacionado
- [Referência da CLI](/pt-BR/cli)
- [Gerenciamento de sessões](/pt-BR/concepts/session)
- [referência da CLI](/pt-BR/cli)
- [gerenciamento de sessões](/pt-BR/concepts/session)

142
docs/pt-BR/cli/update.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Você quer atualizar um checkout do código-fonte com segurança
- Você quer atualizar um checkout de código-fonte com segurança
- Você está depurando a saída ou as opções de `openclaw update`
- Você precisa entender o comportamento da forma abreviada `--update`
summary: Referência da CLI para `openclaw update` (atualização do código-fonte relativamente segura + reinicialização automática do Gateway)
- Você precisa entender o comportamento abreviado de `--update`
summary: Referência da CLI para `openclaw update` (atualização de origem relativamente segura + reinício automático do Gateway)
title: Atualizar
x-i18n:
generated_at: "2026-05-03T21:29:30Z"
generated_at: "2026-05-05T01:45:10Z"
model: gpt-5.5
provider: openai
source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
source_path: cli/update.md
workflow: 16
---
@ -18,7 +18,7 @@ x-i18n:
Atualize o OpenClaw com segurança e alterne entre os canais stable/beta/dev.
Se você instalou via **npm/pnpm/bun** (instalação global, sem metadados git),
Se você instalou via **npm/pnpm/bun** (instalação global, sem metadados do git),
as atualizações acontecem pelo fluxo do gerenciador de pacotes em [Atualização](/pt-BR/install/updating).
## Uso
@ -40,23 +40,24 @@ openclaw --update
## Opções
- `--no-restart`: ignora a reinicialização do serviço Gateway após uma atualização bem-sucedida. Atualizações por gerenciador de pacotes que reiniciam o Gateway verificam se o serviço reiniciado informa a versão atualizada esperada antes de o comando ser concluído com sucesso.
- `--channel <stable|beta|dev>`: define o canal de atualização (git + npm; persistido na configuração).
- `--tag <dist-tag|version|spec>`: substitui o destino do pacote somente para esta atualização. Para instalações de pacote, `main` é mapeado para `github:openclaw/openclaw#main`.
- `--dry-run`: pré-visualiza as ações de atualização planejadas (fluxo de canal/tag/destino/reinicialização) sem gravar configuração, instalar, sincronizar plugins ou reiniciar.
- `--json`: imprime JSON `UpdateRunResult` legível por máquina, incluindo
`postUpdate.plugins.integrityDrifts` quando divergência de artefato de plugin npm é
detectada durante a sincronização de plugins pós-atualização.
- `--no-restart`: pule a reinicialização do serviço Gateway após uma atualização bem-sucedida. Atualizações por gerenciador de pacotes que reiniciam o Gateway verificam se o serviço reiniciado informa a versão atualizada esperada antes de o comando ser concluído com sucesso.
- `--channel <stable|beta|dev>`: defina o canal de atualização (git + npm; persistido na configuração).
- `--tag <dist-tag|version|spec>`: substitua o pacote de destino somente para esta atualização. Para instalações por pacote, `main` mapeia para `github:openclaw/openclaw#main`.
- `--dry-run`: visualize as ações de atualização planejadas (fluxo de canal/tag/destino/reinicialização) sem gravar configuração, instalar, sincronizar plugins ou reiniciar.
- `--json`: imprima JSON `UpdateRunResult` legível por máquina, incluindo
`postUpdate.plugins.integrityDrifts` quando desvio de artefato de Plugin npm for
detectado durante a sincronização de plugins pós-atualização.
- `--timeout <seconds>`: tempo limite por etapa (o padrão é 1800s).
- `--yes`: ignora prompts de confirmação (por exemplo, confirmação de downgrade).
- `--yes`: pule prompts de confirmação (por exemplo, confirmação de downgrade).
`openclaw update` não tem uma flag `--verbose`. Use `--dry-run` para pré-visualizar
as ações planejadas de canal/tag/instalação/reinicialização, `--json` para resultados
legíveis por máquina e `openclaw update status --json` quando você só precisar dos
detalhes de canal e disponibilidade. Se você estiver depurando logs do Gateway em torno de uma atualização,
a verbosidade do console e o nível de log em arquivo são separados: `--verbose` do Gateway afeta
a saída de terminal/WebSocket, enquanto logs em arquivo exigem `logging.level: "debug"` ou
`"trace"` na configuração. Veja [Logs do Gateway](/pt-BR/gateway/logging).
`openclaw update` não tem uma flag `--verbose`. Use `--dry-run` para visualizar
as ações planejadas de canal/tag/instalação/reinicialização, `--json` para
resultados legíveis por máquina, e `openclaw update status --json` quando você
só precisar de detalhes de canal e disponibilidade. Se você estiver depurando
logs do Gateway durante uma atualização, a verbosidade do console e o nível de
log em arquivo são separados: Gateway `--verbose` afeta a saída
terminal/WebSocket, enquanto logs em arquivo exigem `logging.level: "debug"` ou
`"trace"` na configuração. Consulte [logs do Gateway](/pt-BR/gateway/logging).
<Warning>
Downgrades exigem confirmação porque versões mais antigas podem quebrar a configuração.
@ -64,7 +65,7 @@ Downgrades exigem confirmação porque versões mais antigas podem quebrar a con
## `update status`
Mostra o canal de atualização ativo + tag/branch/SHA do git (para checkouts de origem), além da disponibilidade de atualização.
Mostre o canal de atualização ativo + tag/branch/SHA do git (para checkouts de código-fonte), além da disponibilidade de atualização.
```bash
openclaw update status
@ -74,13 +75,13 @@ openclaw update status --timeout 10
Opções:
- `--json`: imprime JSON de status legível por máquina.
- `--json`: imprima JSON de status legível por máquina.
- `--timeout <seconds>`: tempo limite para verificações (o padrão é 3s).
## `update wizard`
Fluxo interativo para escolher um canal de atualização e confirmar se o Gateway deve ser reiniciado
após a atualização (o padrão é reiniciar). Se você selecionar `dev` sem um checkout git, ele
Fluxo interativo para escolher um canal de atualização e confirmar se deve reiniciar o Gateway
após atualizar (o padrão é reiniciar). Se você selecionar `dev` sem um checkout git, ele
oferece criar um.
Opções:
@ -89,114 +90,115 @@ Opções:
## O que ele faz
Quando você troca de canal explicitamente (`--channel ...`), o OpenClaw também mantém o
Quando você alterna canais explicitamente (`--channel ...`), o OpenClaw também mantém o
método de instalação alinhado:
- `dev` → garante um checkout git (padrão: `~/openclaw`, substitua com `OPENCLAW_GIT_DIR`),
atualiza-o e instala a CLI global a partir desse checkout.
- `stable` → instala do npm usando `latest`.
- `beta` → prefere a dist-tag npm `beta`, mas recua para `latest` quando beta está
- `beta` → prefere a dist-tag npm `beta`, mas recorre a `latest` quando beta está
ausente ou é mais antiga que a versão stable atual.
O atualizador automático do núcleo do Gateway (quando habilitado via configuração) inicia o caminho de atualização da CLI
fora do manipulador de requisições ativo do Gateway. Atualizações de gerenciador de pacotes
`update.run` do plano de controle forçam uma reinicialização de atualização não adiada e sem cooldown após a troca do pacote,
porque o processo antigo do Gateway ainda pode ter partes em memória apontando para
fora do manipulador de requisições ativo do Gateway. Atualizações por gerenciador de pacotes
`update.run` do plano de controle forçam uma reinicialização de atualização sem adiamento e sem cooldown após a troca do pacote,
porque o processo antigo do Gateway ainda pode ter chunks em memória que apontam para
arquivos removidos pelo novo pacote.
Para instalações por gerenciador de pacotes, `openclaw update` resolve a versão
do pacote de destino antes de invocar o gerenciador de pacotes. Instalações globais npm usam uma instalação
em estágio: o OpenClaw instala o novo pacote em um prefixo npm temporário, verifica
o inventário `dist` empacotado ali e então troca essa árvore limpa de pacote para o
prefixo global real. Se a verificação falhar, o doctor pós-atualização, a sincronização de plugins e
o trabalho de reinicialização não rodam a partir da árvore suspeita. Mesmo quando a versão instalada
já corresponde ao destino, o comando atualiza a instalação global do pacote,
depois executa a sincronização de plugins, uma atualização de conclusão de comando principal e o trabalho de reinicialização. Isso
mantém sidecars empacotados e registros de plugins pertencentes ao canal alinhados com a
build instalada do OpenClaw, deixando reconstruções completas de conclusão de comandos de plugins para
do pacote de destino antes de invocar o gerenciador de pacotes. Instalações globais npm usam uma instalação em estágio:
o OpenClaw instala o novo pacote em um prefixo npm temporário, verifica
o inventário `dist` empacotado ali e então troca essa árvore de pacote limpa para o
prefixo global real. Se a verificação falhar, doctor pós-atualização, sincronização de plugins e
reinicialização não são executados a partir da árvore suspeita. Mesmo quando a versão instalada
já corresponde ao destino, o comando atualiza a instalação do pacote global,
depois executa sincronização de plugins, uma atualização de completions de comandos principais e a reinicialização. Isso
mantém sidecars empacotados e registros de Plugin pertencentes ao canal alinhados com a
build do OpenClaw instalada, deixando reconstruções completas de completions de comandos de Plugin para
execuções explícitas de `openclaw completion --write-state`.
Quando um serviço Gateway gerenciado local está instalado e a reinicialização está habilitada,
atualizações por gerenciador de pacotes param o serviço em execução antes de substituir a árvore
do pacote, depois atualizam os metadados do serviço a partir da instalação atualizada, reiniciam o
do pacote, então atualizam os metadados do serviço a partir da instalação atualizada, reiniciam o
serviço e verificam se o Gateway reiniciado informa a versão esperada antes de
relatar sucesso. No macOS, a verificação pós-atualização também verifica se o LaunchAgent
está carregado/em execução para o perfil ativo e se a porta de local loopback configurada está
saudável. Se o plist está instalado, mas o launchd não o supervisiona, o OpenClaw
reexecuta o bootstrap do LaunchAgent automaticamente, depois executa novamente as
verificações de prontidão de saúde/versão/canal. Um bootstrap novo carrega o job RunAtLoad
informar sucesso. No macOS, a verificação pós-atualização também verifica se o LaunchAgent
está carregado/em execução para o perfil ativo e se a porta de loopback configurada está
saudável. Se o plist estiver instalado, mas o launchd não estiver supervisionando-o, o OpenClaw
reinicializa o LaunchAgent automaticamente e então executa novamente as verificações de
saúde/versão/prontidão de canal. Um bootstrap novo carrega o job RunAtLoad
diretamente, então a recuperação de atualização não executa imediatamente `kickstart -k` no Gateway
recém-iniciado. Se o Gateway ainda não ficar saudável, o comando sai
com código diferente de zero e imprime o caminho do log de reinicialização mais instruções explícitas de reinicialização, reinstalação e
rollback de pacote. Com `--no-restart`,
recém-criado. Se o Gateway ainda não ficar saudável, o comando sai
com código diferente de zero e imprime o caminho do log de reinicialização, além de instruções explícitas de reinicialização, reinstalação e
rollback do pacote. Com `--no-restart`,
a substituição do pacote ainda é executada, mas o serviço gerenciado não é parado nem
reiniciado, então o Gateway em execução pode manter código antigo até que você o reinicie
reiniciado, então o Gateway em execução pode manter o código antigo até que você o reinicie
manualmente.
## Fluxo de checkout git
### Seleção de canal
- `stable`: faz checkout da tag não beta mais recente, depois compila e executa o doctor.
- `beta`: prefere a tag `-beta` mais recente, mas recua para a tag stable mais recente quando beta está ausente ou é mais antiga.
- `dev`: faz checkout de `main`, depois busca e faz rebase.
- `stable`: faz checkout da tag não beta mais recente, depois faz build e executa doctor.
- `beta`: prefere a tag `-beta` mais recente, mas recorre à tag stable mais recente quando beta está ausente ou é mais antiga.
- `dev`: faz checkout de `main`, depois faz fetch e rebase.
### Etapas de atualização
<Steps>
<Step title="Verificar worktree limpa">
Exige ausência de alterações não commitadas.
Exige nenhuma alteração não commitada.
</Step>
<Step title="Trocar canal">
Troca para o canal selecionado (tag ou branch).
<Step title="Alternar canal">
Alterna para o canal selecionado (tag ou branch).
</Step>
<Step title="Buscar upstream">
Somente dev.
</Step>
<Step title="Build de preflight (somente dev)">
Executa lint e build TypeScript em uma worktree temporária. Se a ponta falhar, volta até 10 commits para encontrar a build limpa mais nova.
Executa lint e build TypeScript em uma worktree temporária. Se a ponta falhar, retrocede até 10 commits para encontrar a build limpa mais recente.
</Step>
<Step title="Rebase">
Faz rebase para o commit selecionado (somente dev).
Faz rebase no commit selecionado (somente dev).
</Step>
<Step title="Instalar dependências">
Usa o gerenciador de pacotes do repo. Para checkouts pnpm, o atualizador inicializa `pnpm` sob demanda (via `corepack` primeiro, depois um fallback temporário `npm install pnpm@10`) em vez de executar `npm run build` dentro de um workspace pnpm.
Usa o gerenciador de pacotes do repositório. Para checkouts pnpm, o atualizador inicializa `pnpm` sob demanda (via `corepack` primeiro, depois um fallback temporário `npm install pnpm@10`) em vez de executar `npm run build` dentro de um workspace pnpm.
</Step>
<Step title="Compilar a Control UI">
Compila o gateway e a Control UI.
<Step title="Build da Control UI">
Faz build do gateway e da Control UI.
</Step>
<Step title="Executar doctor">
`openclaw doctor` é executado como a verificação final de atualização segura.
</Step>
<Step title="Sincronizar plugins">
Sincroniza plugins com o canal ativo. Dev usa plugins empacotados; stable e beta usam npm. Atualiza instalações de plugins rastreadas.
Sincroniza plugins com o canal ativo. Dev usa plugins incluídos; stable e beta usam npm. Atualiza instalações de Plugin rastreadas.
</Step>
</Steps>
No canal de atualização beta, instalações rastreadas de plugins npm e ClawHub que seguem
a linha padrão/latest tentam primeiro uma versão `@beta` do plugin. Se o plugin não tiver
versão beta, o OpenClaw recua para a spec padrão/latest registrada. Versões
exatas e tags explícitas não são reescritas.
a linha padrão/latest tentam primeiro uma versão `@beta` do Plugin. Se o Plugin não tiver
versão beta, o OpenClaw recorre à spec padrão/latest registrada. Para
plugins npm, o OpenClaw também recorre quando o pacote beta existe, mas falha na
validação de instalação. Versões exatas e tags explícitas não são reescritas.
<Warning>
Se uma atualização de plugin npm fixada exata resolver para um artefato cuja integridade difere do registro de instalação armazenado, `openclaw update` aborta essa atualização de artefato de plugin em vez de instalá-la. Reinstale ou atualize o plugin explicitamente somente depois de verificar que você confia no novo artefato.
Se uma atualização de Plugin npm fixada exatamente resolver para um artefato cuja integridade difere do registro de instalação armazenado, `openclaw update` aborta essa atualização de artefato de Plugin em vez de instalá-lo. Reinstale ou atualize o Plugin explicitamente somente após verificar que você confia no novo artefato.
</Warning>
<Note>
Falhas de sincronização de plugins pós-atualização fazem o resultado da atualização falhar e interrompem o trabalho subsequente de reinicialização. Corrija a instalação do plugin ou o erro de atualização, depois execute novamente `openclaw update`.
Falhas de sincronização de plugins pós-atualização fazem o resultado da atualização falhar e interrompem o trabalho de reinicialização subsequente. Corrija o erro de instalação ou atualização do Plugin e execute novamente `openclaw update`.
Quando o Gateway atualizado inicia, o carregamento de plugins é somente verificação: a inicialização não executa gerenciadores de pacotes nem altera árvores de dependências. Reinicializações `update.run` por gerenciador de pacotes ignoram o adiamento ocioso normal e o cooldown de reinicialização depois que a árvore do pacote foi trocada, para que o processo antigo não possa continuar carregando de forma preguiçosa partes removidas.
Quando o Gateway atualizado inicia, o carregamento de plugins é apenas de verificação: a inicialização não executa gerenciadores de pacotes nem altera árvores de dependências. Reinicializações `update.run` por gerenciador de pacotes ignoram o adiamento ocioso normal e o cooldown de reinicialização depois que a árvore de pacotes foi trocada, para que o processo antigo não possa continuar carregando lentamente chunks removidos.
Se o bootstrap do pnpm ainda falhar, o atualizador para cedo com um erro específico do gerenciador de pacotes em vez de tentar `npm run build` dentro do checkout.
</Note>
## Atalho `--update`
## Abreviação `--update`
`openclaw --update` é reescrito para `openclaw update` (útil para shells e scripts de inicialização).
## Relacionado
## Relacionados
- `openclaw doctor` (oferece executar a atualização primeiro em checkouts git)
- `openclaw doctor` (oferece executar update primeiro em checkouts git)
- [Canais de desenvolvimento](/pt-BR/install/development-channels)
- [Atualização](/pt-BR/install/updating)
- [Referência da CLI](/pt-BR/cli)

155
docs/pt-BR/concepts/models.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Adicionar ou modificar a CLI de modelos (models list/set/scan/aliases/fallbacks)
- Alteração do comportamento de fallback do modelo ou da UX de seleção
- Adicionando ou modificando a CLI de modelos (models list/set/scan/aliases/fallbacks)
- Alterando o comportamento alternativo do modelo ou a experiência do usuário na seleção
- Atualizando sondas de varredura de modelos (ferramentas/imagens)
sidebarTitle: Models CLI
summary: 'CLI de modelos: listar, definir, aliases, fallbacks, verificar, status'
title: CLI de modelos
title: CLI de Modelos
x-i18n:
generated_at: "2026-05-02T20:45:29Z"
generated_at: "2026-05-05T01:45:19Z"
model: gpt-5.5
provider: openai
source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f
source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="Failover de modelos" href="/pt-BR/concepts/model-failover">
<Card title="Failover de modelo" href="/pt-BR/concepts/model-failover">
Rotação de perfis de autenticação, cooldowns e como isso interage com fallbacks.
</Card>
<Card title="Provedores de modelos" href="/pt-BR/concepts/model-providers">
Visão geral rápida de provedores e exemplos.
<Card title="Provedores de modelo" href="/pt-BR/concepts/model-providers">
Visão geral rápida dos provedores e exemplos.
</Card>
<Card title="Runtimes de agentes" href="/pt-BR/concepts/agent-runtimes">
PI, Codex e outros runtimes de loop de agente.
@ -30,14 +30,14 @@ x-i18n:
</Card>
</CardGroup>
Refs de modelo escolhem um provedor e um modelo. Normalmente, elas não escolhem o runtime de agente de baixo nível. Por exemplo, `openai/gpt-5.5` pode ser executado pelo caminho normal do provedor OpenAI ou pelo runtime do servidor de app do Codex, dependendo de `agents.defaults.agentRuntime.id`. No modo de runtime do Codex, a ref `openai/gpt-*` não implica cobrança por chave de API; a autenticação pode vir de uma conta Codex ou do perfil de autenticação `openai-codex`. Consulte [Runtimes de agentes](/pt-BR/concepts/agent-runtimes).
Refs de modelo escolhem um provedor e um modelo. Normalmente, eles não escolhem o runtime de agente de baixo nível. Por exemplo, `openai/gpt-5.5` pode executar pelo caminho normal do provedor OpenAI ou pelo runtime do app-server do Codex, dependendo de `agents.defaults.agentRuntime.id`. No modo de runtime Codex, a ref `openai/gpt-*` não implica cobrança por chave de API; a autenticação pode vir de uma conta Codex ou do perfil de autenticação `openai-codex`. Veja [Runtimes de agentes](/pt-BR/concepts/agent-runtimes).
## Como a seleção de modelo funciona
OpenClaw seleciona modelos nesta ordem:
O OpenClaw seleciona modelos nesta ordem:
<Steps>
<Step title="Modelo principal">
<Step title="Modelo primário">
`agents.defaults.model.primary` (ou `agents.defaults.model`).
</Step>
<Step title="Fallbacks">
@ -50,33 +50,33 @@ OpenClaw seleciona modelos nesta ordem:
<AccordionGroup>
<Accordion title="Superfícies de modelo relacionadas">
- `agents.defaults.models` é a allowlist/catálogo de modelos que o OpenClaw pode usar (além de aliases).
- `agents.defaults.imageModel` é usado **somente quando** o modelo principal não consegue aceitar imagens.
- `agents.defaults.pdfModel` é usado pela ferramenta `pdf`. Se omitido, a ferramenta faz fallback para `agents.defaults.imageModel` e depois para o modelo resolvido da sessão/padrão.
- `agents.defaults.imageGenerationModel` é usado pela capacidade compartilhada de geração de imagens. Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de imagens registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- `agents.defaults.musicGenerationModel` é usado pela capacidade compartilhada de geração de música. Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de música registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- `agents.defaults.videoGenerationModel` é usado pela capacidade compartilhada de geração de vídeo. Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os provedores de geração de vídeo registrados restantes em ordem de ID de provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- Padrões por agente podem substituir `agents.defaults.model` via `agents.list[].model` mais associações (consulte [Roteamento multiagente](/pt-BR/concepts/multi-agent)).
- `agents.defaults.models` é a allowlist/catálogo de modelos que o OpenClaw pode usar (mais aliases).
- `agents.defaults.imageModel` é usado **somente quando** o modelo primário não aceita imagens.
- `agents.defaults.pdfModel` é usado pela ferramenta `pdf`. Se omitido, a ferramenta recorre a `agents.defaults.imageModel` e depois ao modelo resolvido da sessão/padrão.
- `agents.defaults.imageGenerationModel` é usado pela capacidade compartilhada de geração de imagens. Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagens em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- `agents.defaults.musicGenerationModel` é usado pela capacidade compartilhada de geração de música. Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- `agents.defaults.videoGenerationModel` é usado pela capacidade compartilhada de geração de vídeo. Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo em ordem de ID do provedor. Se você definir um provedor/modelo específico, configure também a autenticação/chave de API desse provedor.
- Padrões por agente podem substituir `agents.defaults.model` via `agents.list[].model` mais vinculações (veja [Roteamento multiagente](/pt-BR/concepts/multi-agent)).
</Accordion>
</AccordionGroup>
## Origem da seleção e comportamento de fallback
## Fonte da seleção e comportamento de fallback
O mesmo `provider/model` pode significar coisas diferentes dependendo de onde veio:
- Padrões configurados (`agents.defaults.model.primary` e modelos principais específicos do agente) são o ponto de partida normal e usam `agents.defaults.model.fallbacks`.
- Seleções automáticas de fallback são estado temporário de recuperação. Elas são armazenadas com `modelOverrideSource: "auto"` para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar primeiro um modelo principal sabidamente ruim.
- Seleções de sessão do usuário são exatas. `/model`, o seletor de modelos, `session_status(model=...)` e `sessions.patch` armazenam `modelOverrideSource: "user"`; se esse provedor/modelo selecionado estiver inacessível, o OpenClaw falha de forma visível em vez de passar para outro modelo configurado.
- `--model` de Cron / `model` do payload é um modelo principal por job. Ele ainda usa fallbacks configurados, a menos que o job forneça `fallbacks` explícitos no payload (use `fallbacks: []` para uma execução de cron estrita).
- Seletores de modelo padrão e de allowlist da CLI respeitam `models.mode: "replace"` listando `models.providers.*.models` explícitos em vez de carregar todo o catálogo integrado completo.
- O seletor de modelos da UI de Controle pede ao Gateway sua visão de modelos configurada: `agents.defaults.models` quando presente; caso contrário, `models.providers.*.models` explícitos mais provedores com autenticação utilizável. O catálogo integrado completo fica reservado para visualizações explícitas de navegação, como `models.list` com `view: "all"` ou `openclaw models list --all`.
- Padrões configurados (`agents.defaults.model.primary` e primários específicos de agente) são o ponto de partida normal e usam `agents.defaults.model.fallbacks`.
- Seleções de fallback automáticas são estado temporário de recuperação. Elas são armazenadas com `modelOverrideSource: "auto"` para que turnos posteriores possam continuar usando a cadeia de fallback sem sondar primeiro um primário sabidamente ruim.
- Seleções de sessão do usuário são exatas. `/model`, o seletor de modelos, `session_status(model=...)` e `sessions.patch` armazenam `modelOverrideSource: "user"`; se esse provedor/modelo selecionado estiver inacessível, o OpenClaw falha de forma visível em vez de cair para outro modelo configurado.
- Cron `--model` / payload `model` é um primário por job. Ele ainda usa fallbacks configurados, a menos que o job forneça `fallbacks` explícitos no payload (use `fallbacks: []` para uma execução de cron estrita).
- Os seletores de modelo padrão e allowlist da CLI respeitam `models.mode: "replace"` listando `models.providers.*.models` explícitos em vez de carregar todo o catálogo integrado.
- O seletor de modelos da Control UI pede ao Gateway a visão configurada de modelos: `agents.defaults.models` quando presente; caso contrário, `models.providers.*.models` explícitos mais provedores com autenticação utilizável. O catálogo integrado completo é reservado para visões de navegação explícitas, como `models.list` com `view: "all"` ou `openclaw models list --all`.
## Política rápida de modelos
- Defina seu principal como o modelo de geração mais recente e mais forte disponível para você.
- Use fallbacks para tarefas sensíveis a custo/latência e chat de menor risco.
- Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelos mais antigas/mais fracas.
- Defina seu primário como o modelo de geração mais recente mais forte disponível para você.
- Use fallbacks para tarefas sensíveis a custo/latência e chats de menor risco.
- Para agentes com ferramentas habilitadas ou entradas não confiáveis, evite camadas de modelo mais antigas/fracas.
## Onboarding (recomendado)
@ -99,7 +99,7 @@ Ele pode configurar modelo + autenticação para provedores comuns, incluindo **
- `models.providers` (provedores personalizados gravados em `models.json`)
<Note>
Refs de modelo são normalizadas para minúsculas. Aliases de provedor como `z.ai/*` são normalizados para `zai/*`.
Refs de modelo são normalizadas para minúsculas. Aliases de provedor como `z.ai/*` normalizam para `zai/*`.
Exemplos de configuração de provedor (incluindo OpenCode) ficam em [OpenCode](/pt-BR/providers/opencode).
</Note>
@ -114,9 +114,9 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
<AccordionGroup>
<Accordion title="Regras de proteção contra sobrescrita">
`openclaw config set` protege mapas de modelo/provedor contra sobrescritas acidentais. Uma atribuição de objeto simples a `agents.defaults.models`, `models.providers` ou `models.providers.<id>.models` é rejeitada quando removeria entradas existentes. Use `--merge` para alterações aditivas; use `--replace` somente quando o valor fornecido deve se tornar o valor alvo completo.
`openclaw config set` protege mapas de modelo/provedor contra sobrescritas acidentais. Uma atribuição simples de objeto para `agents.defaults.models`, `models.providers` ou `models.providers.<id>.models` é rejeitada quando removeria entradas existentes. Use `--merge` para alterações aditivas; use `--replace` somente quando o valor fornecido deve se tornar o valor completo do alvo.
A configuração interativa de provedor e `openclaw configure --section model` também mesclam seleções com escopo de provedor na allowlist existente, então adicionar Codex, Ollama ou outro provedor não remove entradas de modelo não relacionadas. Configure preserva um `agents.defaults.model.primary` existente quando a autenticação do provedor é reaplicada. Comandos explícitos de definição de padrão, como `openclaw models auth login --provider <id> --set-default` e `openclaw models set <model>`, ainda substituem `agents.defaults.model.primary`.
A configuração interativa de provedor e `openclaw configure --section model` também mesclam seleções no escopo do provedor à allowlist existente, então adicionar Codex, Ollama ou outro provedor não remove entradas de modelo não relacionadas. A configuração preserva um `agents.defaults.model.primary` existente quando a autenticação do provedor é reaplicada. Comandos explícitos de definição de padrão, como `openclaw models auth login --provider <id> --set-default` e `openclaw models set <model>`, ainda substituem `agents.defaults.model.primary`.
</Accordion>
</AccordionGroup>
@ -126,11 +126,12 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
Se `agents.defaults.models` estiver definido, ele se torna a **allowlist** para `/model` e para substituições de sessão. Quando um usuário seleciona um modelo que não está nessa allowlist, o OpenClaw retorna:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
Isso acontece **antes** que uma resposta normal seja gerada, então a mensagem pode parecer que "não respondeu". A correção é:
Isso acontece **antes** de uma resposta normal ser gerada, então a mensagem pode parecer que "não respondeu". A correção é:
- Adicionar o modelo a `agents.defaults.models`, ou
- Limpar a allowlist (remover `agents.defaults.models`), ou
@ -138,9 +139,11 @@ Isso acontece **antes** que uma resposta normal seja gerada, então a mensagem p
</Warning>
Para modelos locais/GGUF, armazene a ref completa com prefixo do provedor na allowlist,
Quando o comando rejeitado incluía uma substituição de runtime, como `/model openai/gpt-5.5 --runtime codex`, corrija primeiro a allowlist e depois tente novamente o mesmo comando `/model ... --runtime ...`. Para execução nativa do Codex, o modelo selecionado ainda é `openai/gpt-5.5`; o runtime `codex` seleciona o harness e usa a autenticação do Codex separadamente.
Para modelos locais/GGUF, armazene a ref completa com prefixo de provedor na allowlist,
por exemplo `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf` ou o
`provider/model` exato mostrado por `openclaw models list --provider <provider>`.
provedor/modelo exato mostrado por `openclaw models list --provider <provider>`.
Nomes de arquivos locais simples ou nomes de exibição não são suficientes quando a allowlist está
ativa.
@ -173,32 +176,32 @@ Você pode alternar modelos para a sessão atual sem reiniciar:
<AccordionGroup>
<Accordion title="Comportamento do seletor">
- `/model` (e `/model list`) é um seletor compacto e numerado (família de modelo + provedores disponíveis).
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa Submit.
- No Telegram, as seleções do seletor `/models` têm escopo de sessão; elas não alteram o padrão persistente do agente em `openclaw.json`.
- `/models add` está obsoleto e agora retorna uma mensagem de obsolescência em vez de registrar modelos pelo chat.
- No Discord, `/model` e `/models` abrem um seletor interativo com dropdowns de provedor e modelo, além de uma etapa de envio.
- No Telegram, as seleções do seletor `/models` são no escopo da sessão; elas não alteram o padrão persistente do agente em `openclaw.json`.
- `/models add` está obsoleto e agora retorna uma mensagem de descontinuação em vez de registrar modelos pelo chat.
- `/model <#>` seleciona a partir desse seletor.
</Accordion>
<Accordion title="Persistência e alternância ao vivo">
- `/model` persiste imediatamente a nova seleção de sessão.
- `/model` persiste a nova seleção de sessão imediatamente.
- Se o agente estiver ocioso, a próxima execução usa o novo modelo imediatamente.
- Se uma execução já estiver ativa, o OpenClaw marca uma alternância ao vivo como pendente e só reinicia no novo modelo em um ponto limpo de nova tentativa.
- Se a atividade de ferramenta ou a saída da resposta já tiver começado, a alternância pendente pode ficar na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário.
- Uma ref `/model` selecionada pelo usuário é estrita para essa sessão: se o provedor/modelo selecionado estiver inacessível, a resposta falha de forma visível em vez de responder silenciosamente a partir de `agents.defaults.model.fallbacks`. Isso é diferente de padrões configurados e modelos principais de jobs cron, que ainda podem usar cadeias de fallback.
- `/model status` é a visualização detalhada (candidatos de autenticação e, quando configurado, `baseUrl` do endpoint do provedor + modo `api`).
- Se uma execução já estiver ativa, o OpenClaw marca uma alternância ao vivo como pendente e só reinicia no novo modelo em um ponto de nova tentativa limpo.
- Se a atividade de ferramentas ou a saída da resposta já tiver começado, a alternância pendente pode ficar enfileirada até uma oportunidade de nova tentativa posterior ou o próximo turno do usuário.
- Uma ref `/model` selecionada pelo usuário é estrita para essa sessão: se o provedor/modelo selecionado estiver inacessível, a resposta falha de forma visível em vez de responder silenciosamente a partir de `agents.defaults.model.fallbacks`. Isso é diferente dos padrões configurados e dos primários de jobs cron, que ainda podem usar cadeias de fallback.
- `/model status` é a visão detalhada (candidatos de autenticação e, quando configurado, endpoint do provedor `baseUrl` + modo `api`).
</Accordion>
<Accordion title="Análise de refs">
<Accordion title="Análise de ref">
- Refs de modelo são analisadas dividindo na **primeira** `/`. Use `provider/model` ao digitar `/model <ref>`.
- Se o próprio ID do modelo contiver `/` (estilo OpenRouter), você deve incluir o prefixo do provedor (exemplo: `/model openrouter/moonshotai/kimi-k2`).
- Se você omitir o provedor, o OpenClaw resolve a entrada nesta ordem:
1. correspondência de alias
2. correspondência única de provedor configurado para esse ID de modelo exato sem prefixo
3. fallback obsoleto para o provedor padrão configurado — se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw, em vez disso, faz fallback para o primeiro provedor/modelo configurado para evitar exibir um padrão obsoleto de provedor removido.
3. fallback obsoleto para o provedor padrão configurado — se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado para evitar expor um padrão obsoleto de provedor removido.
</Accordion>
</AccordionGroup>
Comportamento/configuração completa dos comandos: [Comandos de barra](/pt-BR/tools/slash-commands).
Comportamento/configuração completa do comando: [Comandos de barra](/pt-BR/tools/slash-commands).
## Comandos da CLI
@ -227,10 +230,10 @@ openclaw models image-fallbacks clear
### `models list`
Mostra modelos configurados/disponíveis por autenticação por padrão. Flags úteis:
Mostra modelos configurados/com autenticação disponível por padrão. Flags úteis:
<ParamField path="--all" type="boolean">
Catálogo completo. Inclui linhas de catálogo estático agrupadas e pertencentes ao provedor antes da configuração da autenticação, para que visualizações apenas de descoberta possam mostrar modelos que ficam indisponíveis até você adicionar credenciais correspondentes do provedor.
Catálogo completo. Inclui linhas de catálogo estático pertencentes a provedores incluídos antes de a autenticação ser configurada, para que visualizações apenas de descoberta possam mostrar modelos indisponíveis até você adicionar credenciais de provedor correspondentes.
</ParamField>
<ParamField path="--local" type="boolean">
Apenas provedores locais.
@ -247,21 +250,21 @@ Mostra modelos configurados/disponíveis por autenticação por padrão. Flags
### `models status`
Mostra o modelo primário resolvido, fallbacks, modelo de imagem e uma visão geral de autenticação dos provedores configurados. Também exibe o status de expiração OAuth para perfis encontrados no armazenamento de autenticação (avisa com 24h de antecedência por padrão). `--plain` imprime apenas o modelo primário resolvido.
Mostra o modelo primário resolvido, fallbacks, modelo de imagem e uma visão geral de autenticação dos provedores configurados. Também exibe o status de expiração OAuth para perfis encontrados no armazenamento de autenticação (avisa dentro de 24h por padrão). `--plain` imprime apenas o modelo primário resolvido.
<AccordionGroup>
<Accordion title="Comportamento de autenticação e sondagem">
- O status OAuth é sempre mostrado (e incluído na saída `--json`). Se um provedor configurado não tiver credenciais, `models status` imprime uma seção **Autenticação ausente**.
- JSON inclui `auth.oauth` (janela de aviso + perfis) e `auth.providers` (autenticação efetiva por provedor, incluindo credenciais baseadas em env). `auth.oauth` é apenas a integridade de perfis do armazenamento de autenticação; provedores somente por env não aparecem ali.
- Use `--check` para automação (sai com `1` quando ausente/expirado, `2` quando expirando).
- Use `--probe` para verificações de autenticação ao vivo; linhas de sondagem podem vir de perfis de autenticação, credenciais de env ou `models.json`.
- O status OAuth é sempre mostrado (e incluído na saída de `--json`). Se um provedor configurado não tiver credenciais, `models status` imprime uma seção **Autenticação ausente**.
- JSON inclui `auth.oauth` (janela de aviso + perfis) e `auth.providers` (autenticação efetiva por provedor, incluindo credenciais vindas do ambiente). `auth.oauth` é apenas a integridade de perfis do armazenamento de autenticação; provedores somente de ambiente não aparecem ali.
- Use `--check` para automação (saída `1` quando ausente/expirado, `2` quando estiver prestes a expirar).
- Use `--probe` para verificações de autenticação ao vivo; linhas de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`.
- Se `auth.order.<provider>` explícito omitir um perfil armazenado, a sondagem relata `excluded_by_auth_order` em vez de tentar usá-lo. Se houver autenticação, mas nenhum modelo sondável puder ser resolvido para esse provedor, a sondagem relata `status: no_model`.
</Accordion>
</AccordionGroup>
<Note>
A escolha de autenticação depende do provedor/conta. Para hosts de gateway sempre ativos, chaves de API geralmente são as mais previsíveis; a reutilização do Claude CLI e perfis OAuth/token existentes da Anthropic também são compatíveis.
A escolha de autenticação depende do provedor/conta. Para hosts de Gateway sempre ativos, chaves de API costumam ser as mais previsíveis; reutilização da Claude CLI e perfis OAuth/token existentes da Anthropic também são compatíveis.
</Note>
Exemplo (Claude CLI):
@ -273,7 +276,7 @@ openclaw models status
## Varredura (modelos gratuitos do OpenRouter)
`openclaw models scan` inspeciona o **catálogo de modelos gratuitos** do OpenRouter e pode, opcionalmente, sondar modelos para suporte a ferramentas e imagens.
`openclaw models scan` inspeciona o **catálogo de modelos gratuitos** do OpenRouter e pode opcionalmente sondar modelos quanto a suporte a ferramentas e imagens.
<ParamField path="--no-probe" type="boolean">
Pule sondagens ao vivo (somente metadados).
@ -285,66 +288,66 @@ openclaw models status
Pule modelos mais antigos.
</ParamField>
<ParamField path="--provider <name>" type="string">
Filtro por prefixo do provedor.
Filtro por prefixo de provedor.
</ParamField>
<ParamField path="--max-candidates <n>" type="number">
Tamanho da lista de fallback.
</ParamField>
<ParamField path="--set-default" type="boolean">
Defina `agents.defaults.model.primary` como a primeira seleção.
Defina `agents.defaults.model.primary` para a primeira seleção.
</ParamField>
<ParamField path="--set-image" type="boolean">
Defina `agents.defaults.imageModel.primary` como a primeira seleção de imagem.
Defina `agents.defaults.imageModel.primary` para a primeira seleção de imagem.
</ParamField>
<Note>
O catálogo `/models` do OpenRouter é público, então varreduras somente de metadados podem listar candidatos gratuitos sem uma chave. Sondagem e inferência ainda exigem uma chave de API do OpenRouter (de perfis de autenticação ou `OPENROUTER_API_KEY`). Se nenhuma chave estiver disponível, `openclaw models scan` recorre à saída somente de metadados e deixa a configuração inalterada. Use `--no-probe` para solicitar explicitamente o modo somente de metadados.
O catálogo `/models` do OpenRouter é público, então varreduras somente de metadados podem listar candidatos gratuitos sem uma chave. Sondagem e inferência ainda exigem uma chave de API do OpenRouter (de perfis de autenticação ou `OPENROUTER_API_KEY`). Se nenhuma chave estiver disponível, `openclaw models scan` recorre à saída somente de metadados e deixa a configuração inalterada. Use `--no-probe` para solicitar explicitamente o modo somente metadados.
</Note>
Os resultados da varredura são classificados por:
1. Suporte a imagens
2. Latência de ferramentas
3. Tamanho de contexto
1. Suporte a imagem
2. Latência de ferramenta
3. Tamanho do contexto
4. Contagem de parâmetros
Entrada:
- Lista `/models` do OpenRouter (filtro `:free`)
- Sondagens ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou `OPENROUTER_API_KEY` (consulte [Variáveis de ambiente](/pt-BR/help/environment))
- Sondagens ao vivo exigem chave de API do OpenRouter de perfis de autenticação ou `OPENROUTER_API_KEY` (veja [Variáveis de ambiente](/pt-BR/help/environment))
- Filtros opcionais: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Controles de solicitação/sondagem: `--timeout`, `--concurrency`
Quando sondagens ao vivo são executadas em um TTY, você pode selecionar fallbacks interativamente. No modo não interativo, passe `--yes` para aceitar os padrões. Resultados somente de metadados são informativos; `--set-default` e `--set-image` exigem sondagens ao vivo para que o OpenClaw não configure um modelo OpenRouter sem chave e inutilizável.
Quando sondagens ao vivo são executadas em uma TUI, você pode selecionar fallbacks interativamente. No modo não interativo, passe `--yes` para aceitar os padrões. Resultados somente de metadados são informativos; `--set-default` e `--set-image` exigem sondagens ao vivo para que o OpenClaw não configure um modelo OpenRouter sem chave e inutilizável.
## Registro de modelos (`models.json`)
Provedores personalizados em `models.providers` são gravados em `models.json` no diretório do agente (padrão `~/.openclaw/agents/<agentId>/agent/models.json`). Esse arquivo é mesclado por padrão, a menos que `models.mode` esteja definido como `replace`.
Provedores personalizados em `models.providers` são gravados em `models.json` no diretório do agente (padrão `~/.openclaw/agents/<agentId>/agent/models.json`). Esse arquivo é mesclado por padrão, a menos que `models.mode` seja definido como `replace`.
<AccordionGroup>
<Accordion title="Precedência do modo de mesclagem">
Precedência do modo de mesclagem para IDs de provedores correspondentes:
Precedência do modo de mesclagem para IDs de provedor correspondentes:
- `baseUrl` não vazio já presente no `models.json` do agente vence.
- `apiKey` não vazio no `models.json` do agente vence apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
- Valores `apiKey` de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para referências de env, `secretref-managed` para referências de arquivo/exec) em vez de persistir segredos resolvidos.
- Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para referências de env, `secretref-managed` para referências de arquivo/exec).
- `apiKey`/`baseUrl` vazios ou ausentes do agente recorrem a `models.providers` da configuração.
- Outros campos do provedor são atualizados a partir da configuração e de dados de catálogo normalizados.
- Valores de `apiKey` de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para referências de ambiente, `secretref-managed` para referências de arquivo/exec), em vez de persistir segredos resolvidos.
- Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para referências de ambiente, `secretref-managed` para referências de arquivo/exec).
- `apiKey`/`baseUrl` vazios ou ausentes no agente recorrem a `models.providers` da configuração.
- Outros campos de provedor são atualizados a partir da configuração e dos dados normalizados do catálogo.
</Accordion>
</AccordionGroup>
<Note>
A persistência de marcadores tem a origem como autoridade: o OpenClaw grava marcadores do snapshot da configuração de origem ativa (antes da resolução), não dos valores de segredo resolvidos em runtime. Isso se aplica sempre que o OpenClaw regenera `models.json`, incluindo caminhos acionados por comandos como `openclaw agent`.
A persistência de marcadores é autoritativa pela origem: o OpenClaw grava marcadores do snapshot de configuração de origem ativo (antes da resolução), não dos valores de segredo resolvidos em runtime. Isso se aplica sempre que o OpenClaw regenera `models.json`, incluindo caminhos acionados por comandos como `openclaw agent`.
</Note>
## Relacionado
## Relacionados
- [Runtimes de agentes](/pt-BR/concepts/agent-runtimes) — PI, Codex e outros runtimes de loop de agentes
- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — chaves de configuração de modelos
- [Geração de imagens](/pt-BR/tools/image-generation) — configuração de modelo de imagem
- [Runtimes de agente](/pt-BR/concepts/agent-runtimes) — PI, Codex e outros runtimes de loop de agente
- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — chaves de configuração de modelo
- [Geração de imagem](/pt-BR/tools/image-generation) — configuração de modelo de imagem
- [Failover de modelo](/pt-BR/concepts/model-failover) — cadeias de fallback
- [Provedores de modelos](/pt-BR/concepts/model-providers) — roteamento e autenticação de provedores
- [Provedores de modelo](/pt-BR/concepts/model-providers) — roteamento e autenticação de provedores
- [Geração de música](/pt-BR/tools/music-generation) — configuração de modelo de música
- [Geração de vídeo](/pt-BR/tools/video-generation) — configuração de modelo de vídeo

523
docs/pt-BR/concepts/qa-e2e-automation.md
View File

@ -1,68 +1,68 @@
---
read_when:
- Entendendo como a pilha de QA se encaixa
- Estendendo o qa-lab, o qa-channel ou um adaptador de transporte
- Adicionar cenários de QA baseados no repositório
- Criando automação de QA de maior realismo em torno do dashboard do Gateway
summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e geração de relatórios.'
- Entendendo como a pilha de QA funciona em conjunto
- Estendendo qa-lab, qa-channel ou um adaptador de transporte
- Adicionando cenários de QA apoiados por repositório
- Criando automação de QA de maior realismo em torno do painel do Gateway
summary: 'Visão geral da pilha de QA: qa-lab, qa-channel, cenários baseados no repositório, faixas de transporte ao vivo, adaptadores de transporte e relatórios.'
title: Visão geral de QA
x-i18n:
generated_at: "2026-05-04T05:52:10Z"
generated_at: "2026-05-05T01:45:29Z"
model: gpt-5.5
provider: openai
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
A stack privada de QA foi pensada para exercitar o OpenClaw de uma forma mais realista,
moldada por canais, do que um único teste unitário consegue.
A pilha privada de QA serve para exercitar o OpenClaw de uma forma mais realista,
com formato de canal, do que um único teste unitário conseguiria.
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-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,
injetar mensagens de entrada e exportar um relatório em Markdown.
injetar mensagens recebidas e exportar um relatório em Markdown.
- `extensions/qa-matrix`, plugins executores futuros: adaptadores de transporte ao vivo que
controlam um canal real dentro de um Gateway de QA filho.
- `qa/`: ativos de semente respaldados pelo repositório para a tarefa inicial e cenários
de QA de linha de base.
conduzem um canal real dentro de um Gateway de QA filho.
- `qa/`: ativos iniciais versionados no repositório para a tarefa de kickoff e cenários
de QA de base.
- [Mantis](/pt-BR/concepts/mantis): verificação ao vivo antes e depois para bugs que
precisam de transportes reais, capturas de tela do navegador, estado da VM e evidências de PR.
precisam de transportes reais, capturas de tela do navegador, estado de VM e evidências de PR.
## Superfície de comandos
Todo fluxo de QA é executado em `pnpm openclaw qa <subcommand>`. Muitos têm aliases de script `pnpm qa:*`;
Todo fluxo de QA roda em `pnpm openclaw qa <subcommand>`. Muitos têm aliases de script `pnpm qa:*`;
ambas as formas são compatíveis.
| Comando | Finalidade |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Autoverificação de QA incluída; grava um relatório em Markdown. |
| `qa suite` | Executa cenários respaldados pelo repositório contra a faixa do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. |
| `qa coverage` | Imprime o inventário markdown de cobertura de cenários (`--json` para saída de máquina). |
| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agêntica. |
| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Consulte [Relatórios](#reporting). |
| `qa manual` | Executa um prompt avulso contra a faixa de provedor/modelo selecionada. |
| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Compila a imagem Docker pré-preparada de QA. |
| `qa docker-scaffold` | Grava um scaffold docker-compose para o painel de QA + faixa do Gateway. |
| `qa up` | Compila o site de QA, inicia a stack apoiada por Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Inicia apenas o servidor do provedor AIMock. |
| `qa mock-openai` | Inicia apenas o servidor do provedor `mock-openai` ciente de cenários. |
| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais do Convex. |
| `qa matrix` | Faixa de transporte ao vivo contra um homeserver Tuwunel descartável. Consulte [QA do Matrix](/pt-BR/concepts/qa-matrix). |
| `qa telegram` | Faixa de transporte ao vivo contra um grupo privado real do Telegram. |
| `qa discord` | Faixa de transporte ao vivo contra um canal real de guild privada do Discord. |
| `qa slack` | Faixa de transporte ao vivo contra um canal privado real do Slack. |
| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com evidências de reações de status no Discord, smoke de desktop/navegador Crabbox e smoke de Slack em VNC. Consulte [Mantis](/pt-BR/concepts/mantis). |
| `qa suite` | Executa cenários versionados no repositório contra a trilha do Gateway de QA. Aliases: `pnpm openclaw qa suite --runner multipass` para uma VM Linux descartável. |
| `qa coverage` | Imprime o inventário de cobertura de cenários em markdown (`--json` para saída de máquina). |
| `qa parity-report` | Compara dois arquivos `qa-suite-summary.json` e grava o relatório de paridade agêntico. |
| `qa character-eval` | Executa o cenário de QA de personagem em vários modelos ao vivo com um relatório julgado. Consulte [Relatórios](#reporting). |
| `qa manual` | Executa um prompt avulso contra a trilha de provedor/modelo selecionada. |
| `qa ui` | Inicia a UI de depuração de QA e o barramento local de QA (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Cria a imagem Docker de QA pré-preparada. |
| `qa docker-scaffold` | Grava um scaffold docker-compose para o painel de QA + trilha de Gateway. |
| `qa up` | Cria o site de QA, inicia a pilha apoiada por Docker e imprime a URL (alias: `pnpm qa:lab:up`; a variante `:fast` adiciona `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Inicia somente o servidor do provedor AIMock. |
| `qa mock-openai` | Inicia somente o servidor do provedor `mock-openai` ciente de cenários. |
| `qa credentials doctor` / `add` / `list` / `remove` | Gerencia o pool compartilhado de credenciais Convex. |
| `qa matrix` | Trilha de transporte ao vivo contra um homeserver Tuwunel descartável. Consulte [QA do Matrix](/pt-BR/concepts/qa-matrix). |
| `qa telegram` | Trilha de transporte ao vivo contra um grupo privado real do Telegram. |
| `qa discord` | Trilha de transporte ao vivo contra um canal de guilda privado real do Discord. |
| `qa slack` | Trilha de transporte ao vivo contra um canal privado real do Slack. |
| `qa mantis` | Executor de verificação antes e depois para bugs de transporte ao vivo, com evidência de reações de status no Discord, smoke de desktop/navegador no Crabbox e smoke de Slack em VNC. Consulte [Mantis](/pt-BR/concepts/mantis). |
## Fluxo do operador
O fluxo atual do operador de QA é um site de QA com dois painéis:
- Esquerda: painel do Gateway (UI de Controle) com o agente.
- Direita: QA Lab, mostrando a transcrição estilo Slack e o plano do cenário.
- Direita: QA Lab, mostrando a transcrição no estilo Slack e o plano do cenário.
Execute com:
@ -70,13 +70,13 @@ Execute com:
pnpm qa:lab:up
```
Isso compila o site de QA, inicia a faixa do Gateway apoiada por 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 cria o site de QA, inicia a trilha de Gateway apoiada por 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 da UI do QA Lab sem recompilar a imagem Docker a cada vez,
inicie a stack com um pacote do QA Lab montado por bind:
Para uma iteração mais rápida da UI do QA Lab sem recriar a imagem Docker a cada vez,
inicie a pilha com um pacote do QA Lab montado por bind mount:
```bash
pnpm openclaw qa docker-build-image
@ -85,40 +85,40 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e monta por bind
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-criada e monta por bind mount
`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch`
recompila esse pacote em mudanças, e o navegador recarrega automaticamente quando o hash
do ativo do QA Lab muda.
recria esse pacote a cada alteração, e o navegador recarrega automaticamente quando o hash de ativos do QA Lab
muda.
Para um smoke local de trace do OpenTelemetry, execute:
Para um smoke de trace local do OpenTelemetry, execute:
```bash
pnpm qa:otel:smoke
```
Esse script inicia um receptor local de trace OTLP/HTTP, executa o cenário de QA
`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois decodifica os spans
protobuf exportados e verifica o formato crítico para release:
`otel-trace-smoke` com o plugin `diagnostics-otel` habilitado, depois
decodifica os spans protobuf exportados e valida o formato crítico de release:
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled` e `openclaw.message.delivery` devem estar presentes;
chamadas de modelo não devem exportar `StreamAbandoned` em turnos bem-sucedidos; IDs diagnósticos brutos e
atributos `openclaw.content.*` devem permanecer fora do trace. Ele grava
atributos `openclaw.content.*` devem ficar fora do trace. Ele grava
`otel-smoke-summary.json` ao lado dos artefatos da suíte de QA.
QA de observabilidade permanece restrito ao checkout do código-fonte. O tarball npm omite intencionalmente
o QA Lab, então as faixas de release Docker do pacote não executam comandos `qa`. Use
`pnpm qa:otel:smoke` a partir de um checkout de código-fonte compilado ao alterar a instrumentação
A QA de observabilidade permanece somente para checkout de código-fonte. O tarball npm omite intencionalmente
o QA Lab, então trilhas de release Docker de pacote não executam comandos `qa`. Use
`pnpm qa:otel:smoke` a partir de um checkout de código-fonte criado ao alterar a instrumentação
de diagnósticos.
Para uma faixa de smoke do Matrix com transporte real, execute:
Para uma trilha de smoke do Matrix com transporte real, execute:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
A referência completa da CLI, catálogo de perfis/cenários, vars de env e layout de artefatos desta faixa ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável em Docker, registra usuários temporários de driver/SUT/observer, executa o plugin real do Matrix dentro de um Gateway de QA filho escopado para esse transporte (sem `qa-channel`), depois grava um relatório em Markdown, resumo JSON, artefato de eventos observados e log de saída combinado em `.artifacts/qa-e2e/matrix-<timestamp>/`.
A referência completa da CLI, o catálogo de perfis/cenários, variáveis de ambiente e layout de artefatos dessa trilha ficam em [QA do Matrix](/pt-BR/concepts/qa-matrix). Em resumo: ela provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver/SUT/observador, executa o plugin Matrix real dentro de um Gateway de QA filho com escopo para esse transporte (sem `qa-channel`) e então grava um relatório em Markdown, um resumo JSON, um artefato de eventos observados e um log de saída combinado em `.artifacts/qa-e2e/matrix-<timestamp>/`.
Para faixas de smoke com transporte real de Telegram, Discord e Slack:
Para trilhas de smoke com transporte real do Telegram, Discord e Slack:
```bash
pnpm openclaw qa telegram
@ -126,7 +126,7 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
Elas miram um canal real pré-existente com dois bots (driver + SUT). Vars de env obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais do Convex estão documentados na [referência de QA para Telegram, Discord e Slack](#telegram-discord-and-slack-qa-reference) abaixo.
Elas miram um canal real preexistente com dois bots (driver + SUT). Variáveis de ambiente obrigatórias, listas de cenários, artefatos de saída e o pool de credenciais Convex estão documentados na [referência de QA do Telegram, Discord e Slack](#telegram-discord-and-slack-qa-reference) abaixo.
Para uma execução completa de VM desktop do Slack com resgate por VNC, execute:
@ -137,13 +137,13 @@ pnpm openclaw qa mantis slack-desktop-smoke \
--keep-lease
```
Esse comando aluga uma máquina desktop/navegador Crabbox, executa a faixa ao vivo do Slack
dentro da VM, abre o Slack Web no navegador VNC, captura o desktop e copia
`slack-qa/` mais `slack-desktop-smoke.png` de volta para o diretório de artefatos do Mantis.
Reutilize `--lease-id <cbx_...>` depois de fazer login no Slack Web manualmente
Esse comando aluga uma máquina de desktop/navegador do Crabbox, executa a trilha ao vivo do Slack
dentro da VM, abre o Slack Web no navegador VNC, captura o desktop e
copia `slack-qa/` mais `slack-desktop-smoke.png` de volta para o diretório de artefatos
do Mantis. Reutilize `--lease-id <cbx_...>` depois de entrar no Slack Web manualmente
pelo VNC. Com `--gateway-setup`, o Mantis deixa um Gateway Slack persistente do OpenClaw
em execução dentro da VM na porta `38973`; sem isso, o comando executa a
faixa normal de QA Slack bot a bot e sai após a captura de artefatos.
trilha normal de QA do Slack bot-para-bot e sai após a captura dos artefatos.
Antes de usar credenciais ao vivo em pool, execute:
@ -151,65 +151,65 @@ Antes de usar credenciais ao vivo em pool, execute:
pnpm openclaw qa credentials doctor
```
O doctor verifica o env do broker Convex, valida configurações de endpoint e verifica a acessibilidade de admin/list quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente dos segredos.
O doctor verifica o ambiente do broker Convex, valida as configurações de endpoint e verifica a alcançabilidade de admin/lista quando o segredo de mantenedor está presente. Ele relata apenas o status definido/ausente dos segredos.
## Cobertura de transporte ao vivo
As faixas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a suíte ampla de comportamento de produto sintético e não faz parte da matriz de cobertura de transporte ao vivo.
As trilhas de transporte ao vivo compartilham um contrato em vez de cada uma inventar seu próprio formato de lista de cenários. `qa-channel` é a suíte ampla de comportamento sintético do produto e não faz parte da matriz de cobertura de transporte ao vivo.
| Faixa | Canary | Gating de menção | Bot a bot | Bloqueio por lista de permissões | Resposta de nível superior | Retomada após reinício | Continuação de thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo |
| -------- | ------ | ---------------- | --------- | -------------------------------- | -------------------------- | ---------------------- | --------------------- | -------------------- | -------------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
| Trilha | Canary | Gate por menção | Bot-para-bot | Bloqueio por lista permitida | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | Registro de comando nativo |
| -------- | ------ | --------------- | ------------ | ---------------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
Isso mantém `qa-channel` como a suíte ampla de comportamento de produto, enquanto Matrix,
Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix,
Telegram e transportes ao vivo futuros compartilham uma checklist explícita de contrato
de transporte.
Para uma faixa de VM Linux descartável sem levar Docker para o caminho de QA, execute:
Para uma trilha de VM Linux descartável sem trazer Docker para o caminho de QA, execute:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Isso inicializa um guest Multipass novo, instala dependências, compila o OpenClaw
dentro do guest, executa `qa suite` e então copia o relatório de QA normal e o
Isso inicializa um convidado Multipass novo, instala dependências, compila o OpenClaw
dentro do convidado, 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ários que `qa suite` no host.
As execuções das suítes no host e no Multipass executam vários cenários selecionados em paralelo
Execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo
com workers de Gateway isolados por padrão. `qa-channel` usa concorrência
4 por padrão, limitada pela quantidade de cenários selecionados. Use `--concurrency <count>` para ajustar
a quantidade de workers, ou `--concurrency 1` para execução serial.
4 por padrão, limitada pela contagem de cenários selecionados. Use `--concurrency <count>` para ajustar
a contagem de workers, ou `--concurrency 1` para execução serial.
O comando sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando
você quiser artefatos sem um código de saída com falha.
quiser artefatos sem um código de saída de falha.
Execuções live encaminham as entradas de autenticação de QA compatíveis que são práticas para o
guest: chaves de provedores baseadas em env, o caminho da configuração do provedor live de QA e
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest
possa escrever de volta pelo workspace montado.
convidado: chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o convidado
possa gravar de volta pelo workspace montado.
## Referência de QA do Telegram, Discord e Slack
## Referência de QA para Telegram, Discord e Slack
Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa da sua quantidade de cenários e do provisionamento de homeserver apoiado por Docker. Telegram, Discord e Slack são menores — alguns cenários cada, sem sistema de perfis, contra canais reais preexistentes — então a referência deles fica aqui.
Matrix tem uma [página dedicada](/pt-BR/concepts/qa-matrix) por causa de sua contagem de cenários e do provisionamento de homeserver com suporte por Docker. Telegram, Discord e Slack são menores — alguns cenários cada, sem sistema de perfis, contra canais reais preexistentes — então sua referência fica aqui.
### Flags de CLI compartilhadas
### Flags compartilhadas da CLI
Essas lanes são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags:
Essas pistas são registradas por meio de `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` e aceitam as mesmas flags:
| Flag | Padrão | Descrição |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Executa somente este cenário. Repetível. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Onde os relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. |
| `--scenario <id>` | — | Executa apenas este cenário. Repetível. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Onde relatórios/resumo/mensagens observadas e o log de saída são gravados. Caminhos relativos são resolvidos em relação a `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Raiz do repositório ao invocar a partir de um cwd neutro. |
| `--sut-account <id>` | `sut` | ID temporário da conta dentro da configuração do Gateway de QA. |
| `--sut-account <id>` | `sut` | ID de conta temporário dentro da configuração do Gateway de QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` ou `live-frontier` (`live-openai` legado ainda funciona). |
| `--model <ref>` / `--alt-model <ref>` | padrão do provedor | Refs do modelo primário/alternativo. |
| `--fast` | desativado | Modo rápido do provedor quando compatível. |
| `--model <ref>` / `--alt-model <ref>` | padrão do provedor | Referências de modelo primário/alternativo. |
| `--fast` | desativado | Modo rápido do provedor onde compatível. |
| `--credential-source <env\|convex>` | `env` | Consulte [pool de credenciais Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` em CI, `maintainer` caso contrário | Papel usado quando `--credential-source convex`. |
| `--credential-role <maintainer\|ci>` | `ci` em CI, caso contrário `maintainer` | Função usada quando `--credential-source convex`. |
Cada lane sai com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída com falha.
Cada pista sai com código diferente de zero em qualquer cenário com falha. `--allow-failures` grava artefatos sem definir um código de saída de falha.
### QA do Telegram
@ -217,17 +217,17 @@ Cada lane sai com código diferente de zero em qualquer cenário com falha. `--a
pnpm openclaw qa telegram
```
Tem como alvo um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT deve ter um nome de usuário do Telegram; a observação bot-a-bot funciona melhor quando ambos os bots têm **Bot-to-Bot Communication Mode** habilitado no `@BotFather`.
Mira em um grupo privado real do Telegram com dois bots distintos (driver + SUT). O bot SUT precisa ter um nome de usuário do Telegram; a observação bot-para-bot funciona melhor quando ambos os bots têm **Bot-to-Bot Communication Mode** habilitado em `@BotFather`.
Env obrigatório quando `--credential-source env`:
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — ID numérico do chat (string).
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id numérico do chat (string).
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
Opcional:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas (o padrão é redigir).
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas (o padrão é redigir).
Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
@ -243,7 +243,7 @@ Cenários (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime
Artefatos de saída:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta SUT observada), começando pelo canary.
- `telegram-qa-summary.json` — inclui RTT por resposta (envio do driver → resposta observada do SUT) começando pelo canary.
- `telegram-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### QA do Discord
@ -252,7 +252,7 @@ Artefatos de saída:
pnpm openclaw qa discord
```
Tem como alvo um canal real de guilda privada do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Discord empacotado. Verifica o tratamento de menções de canal, que o bot SUT registrou o comando nativo `/help` com o Discord, e cenários de evidência Mantis opcionais.
Mira em um canal real privado de guilda do Discord com dois bots: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway OpenClaw filho por meio do Plugin Discord incluído. Verifica o tratamento de menções no canal, se o bot SUT registrou o comando nativo `/help` no Discord e cenários de evidência Mantis opcionais.
Env obrigatório quando `--credential-source env`:
@ -260,20 +260,20 @@ Env obrigatório quando `--credential-source env`:
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — deve corresponder ao ID de usuário do bot SUT retornado pelo Discord (caso contrário, a lane falha rapidamente).
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — precisa corresponder ao id de usuário do bot SUT retornado pelo Discord (caso contrário, a pista falha rapidamente).
Opcional:
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas.
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas.
Cenários (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`):
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — cenário Mantis opcional. Executa sozinho porque muda o SUT para respostas de guilda sempre ativas e somente por ferramenta com `messages.statusReactions.enabled=true`, e então captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG.
- `discord-status-reactions-tool-only` — cenário Mantis opcional. Executa sozinho porque alterna o SUT para respostas de guilda sempre ativas e apenas com ferramentas com `messages.statusReactions.enabled=true`, depois captura uma linha do tempo de reações REST mais um artefato visual HTML/PNG.
Execute explicitamente o cenário de reações de status do Mantis:
Execute explicitamente o cenário de reação de status Mantis:
```bash
pnpm openclaw qa discord \
@ -297,7 +297,7 @@ Artefatos de saída:
pnpm openclaw qa slack
```
Tem como alvo um canal privado real do Slack com dois bots distintos: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway filho do OpenClaw por meio do Plugin Slack empacotado.
Mira em um canal privado real do Slack com dois bots distintos: um bot driver controlado pelo harness e um bot SUT iniciado pelo Gateway OpenClaw filho por meio do Plugin Slack incluído.
Env obrigatório quando `--credential-source env`:
@ -308,7 +308,7 @@ Env obrigatório quando `--credential-source env`:
Opcional:
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mantém os corpos das mensagens nos artefatos de mensagens observadas.
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mantém corpos de mensagens nos artefatos de mensagens observadas.
Cenários (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
@ -321,55 +321,223 @@ Artefatos de saída:
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — corpos redigidos, a menos que `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
#### Configurando o workspace do Slack
A pista precisa de dois apps Slack distintos em um workspace, além de um canal do qual ambos os bots sejam membros:
- `channelId` — o id `Cxxxxxxxxxx` de um canal para o qual ambos os bots foram convidados. Use um canal dedicado; a pista publica em cada execução.
- `driverBotToken` — token de bot (`xoxb-...`) do app **Driver**.
- `sutBotToken` — token de bot (`xoxb-...`) do app **SUT**, que deve ser um app Slack separado do driver para que seu id de usuário de bot seja distinto.
- `sutAppToken` — token de nível de app (`xapp-...`) do app SUT com `connections:write`, usado pelo Socket Mode para que o app SUT possa receber eventos.
Prefira um workspace Slack dedicado a QA em vez de reutilizar um workspace de produção.
O manifesto do SUT abaixo espelha a instalação de produção do Plugin Slack incluído (`extensions/slack/src/setup-shared.ts:10`). Para a configuração de canal de produção como os usuários a veem, consulte [configuração rápida de canal do Slack](/pt-BR/channels/slack#quick-setup); o par Driver/SUT de QA é intencionalmente separado porque a pista precisa de dois ids de usuário de bot distintos em um workspace.
**1. Crie o app Driver**
Acesse [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → escolha o workspace de QA, cole o manifesto a seguir e depois _Install to Workspace_:
```json
{
"display_information": {
"name": "OpenClaw QA Driver",
"description": "Test driver bot for OpenClaw QA Slack live lane"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA Driver",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "channels:history", "groups:history", "users:read"]
}
},
"settings": {
"socket_mode_enabled": false
}
}
```
Copie o _Bot User OAuth Token_ (`xoxb-...`) — isso se torna `driverBotToken`. O driver só precisa publicar mensagens e se identificar; sem eventos, sem Socket Mode.
**2. Crie o app SUT**
Repita _Create New App → From a manifest_ no mesmo workspace. O conjunto de escopos espelha a instalação de produção do Plugin Slack incluído (`extensions/slack/src/setup-shared.ts:10`):
```json
{
"display_information": {
"name": "OpenClaw QA SUT",
"description": "OpenClaw QA SUT connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA SUT",
"always_online": true
},
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_home_opened",
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
Depois que o Slack criar o app, faça duas coisas na página de configurações dele:
- _Install to Workspace_ → copie o _Bot User OAuth Token_ → isso se torna `sutBotToken`.
- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → adicione o escopo `connections:write` → salve → copie o valor `xapp-...` → isso se torna `sutAppToken`.
Verifique se os dois bots têm IDs de usuário distintos chamando `auth.test` em cada token. O runtime diferencia driver e SUT pelo ID do usuário; reutilizar um app para ambos falhará imediatamente no gating de menções.
**3. Crie o canal**
No workspace de QA, crie um canal (por exemplo, `#openclaw-qa`) e convide ambos os bots de dentro do canal:
```
/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT
```
Copie o ID `Cxxxxxxxxxx` de _channel info → About → Channel ID_ — ele se torna `channelId`. Um canal público funciona; se você usar um canal privado, ambos os apps já têm `groups:history`, então as leituras de histórico do harness ainda terão sucesso.
**4. Registre as credenciais**
Duas opções. Use variáveis de ambiente para depuração em uma única máquina (defina as quatro variáveis `OPENCLAW_QA_SLACK_*` e passe `--credential-source env`) ou semeie o pool Convex compartilhado para que o CI e outros mantenedores possam alugá-las.
Para o pool Convex, grave os quatro campos em um arquivo JSON:
```json
{
"channelId": "Cxxxxxxxxxx",
"driverBotToken": "xoxb-...",
"sutBotToken": "xoxb-...",
"sutAppToken": "xapp-..."
}
```
Com `OPENCLAW_QA_CONVEX_SITE_URL` e `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` exportados no seu shell, registre e verifique:
```bash
pnpm openclaw qa credentials add \
--kind slack \
--payload-file slack-creds.json \
--note "QA Slack pool seed"
pnpm openclaw qa credentials list --kind slack --status all --json
```
Espere `count: 1`, `status: "active"`, sem campo `lease`.
**5. Verifique de ponta a ponta**
Execute a lane localmente para confirmar que ambos os bots conseguem conversar entre si por meio do broker:
```bash
pnpm openclaw qa slack \
--credential-source convex \
--credential-role maintainer \
--output-dir .artifacts/qa-e2e/slack-local
```
Uma execução verde é concluída em bem menos de 30 segundos, e `slack-qa-report.md` mostra tanto `slack-canary` quanto `slack-mention-gating` com status `pass`. Se a lane travar por cerca de 90 segundos e sair com `Convex credential pool exhausted for kind "slack"`, o pool está vazio ou todas as linhas estão alugadas — `qa credentials list --kind slack --status all --json` indicará qual é o caso.
### Pool de credenciais Convex
As lanes do Telegram, Discord e Slack podem alugar credenciais de um pool Convex compartilhado em vez de ler as variáveis de env acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire uma locação exclusiva, envia heartbeats durante a execução e a libera no desligamento. Os tipos de pool são `"telegram"`, `"discord"` e `"slack"`.
As lanes Telegram, Discord e Slack podem alugar credenciais de um pool Convex compartilhado em vez de ler as variáveis de ambiente acima. Passe `--credential-source convex` (ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); o QA Lab adquire um lease exclusivo, envia Heartbeats durante a execução e o libera no encerramento. Os tipos do pool são `"telegram"`, `"discord"` e `"slack"`.
Formatos de payload que o broker valida em `admin/add`:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string de ID numérico de chat.
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` deve ser uma string numérica de chat-id.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` deve corresponder a `^[A-Z][A-Z0-9]+$` (um ID do Slack como `Cxxxxxxxxxx`). Consulte [Configurando o workspace Slack](#setting-up-the-slack-workspace) para o provisionamento de app e escopos.
As variáveis de env operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais compartilhadas do Telegram via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos).
As variáveis de ambiente operacionais e o contrato do endpoint do broker Convex ficam em [Testes → Credenciais Telegram compartilhadas via Convex](/pt-BR/help/testing#shared-telegram-credentials-via-convex-v1) (o nome da seção é anterior ao suporte ao Discord; a semântica do broker é idêntica para ambos os tipos).
## Seeds apoiados pelo repositório
## Seeds baseados no repositório
Os ativos de seed ficam em `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Eles ficam intencionalmente no git para que o plano de QA fique visível tanto para humanos quanto para o
agente.
Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o agente.
`qa-lab` deve continuar sendo um executor genérico de markdown. Cada arquivo markdown de cenário é
a fonte da verdade para uma execução de teste e deve definir:
`qa-lab` deve permanecer um runner Markdown genérico. Cada arquivo Markdown de cenário é a fonte da verdade para uma execução de teste e deve definir:
- metadados do cenário
- metadados opcionais de categoria, capacidade, lane e risco
- refs de docs e código
- requisitos opcionais de Plugin
- referências de docs e código
- requisitos opcionais de plugin
- patch opcional de configuração do Gateway
- o `qa-flow` executável
A superfície de runtime reutilizável que sustenta `qa-flow` pode continuar genérica
e transversal. Por exemplo, cenários markdown podem combinar auxiliares do lado do transporte
com auxiliares do lado do navegador que conduzem a Control UI incorporada por meio da
seam `browser.request` do Gateway sem adicionar um runner especial.
A superfície reutilizável de runtime que sustenta `qa-flow` pode permanecer genérica e transversal. Por exemplo, cenários Markdown podem combinar helpers do lado do transporte com helpers do lado do navegador que controlam a Control UI incorporada por meio da costura `browser.request` do Gateway sem adicionar um runner especial para esse caso.
Os arquivos de cenário devem ser agrupados por capacidade de produto, em vez de pasta
da árvore de código-fonte. Mantenha os IDs de cenário estáveis quando arquivos forem movidos; use `docsRefs` e `codeRefs`
para rastreabilidade da implementação.
Os arquivos de cenário devem ser agrupados por capacidade do produto, não por pasta da árvore de origem. Mantenha os IDs de cenário estáveis quando os arquivos forem movidos; use `docsRefs` e `codeRefs` para rastreabilidade da implementação.
A lista de base deve permanecer ampla o suficiente para cobrir:
- chat por DM e canal
- chat em DM e canal
- comportamento de threads
- ciclo de vida de ações de mensagem
- callbacks de cron
- recall de memória
- callbacks de Cron
- recuperação de memória
- troca de modelo
- handoff para subagente
- handoff de subagente
- leitura de repositório e leitura de docs
- uma pequena tarefa de build, como Lobster Invaders
@ -377,78 +545,71 @@ A lista de base deve permanecer ampla o suficiente para cobrir:
`qa suite` tem duas lanes locais de mock de provedor:
- `mock-openai` é o mock do OpenClaw ciente de cenários. Ele continua sendo a lane de mock determinística
padrão para QA apoiado pelo repositório e gates de paridade.
- `aimock` inicia um servidor de provedor apoiado pelo AIMock para cobertura experimental de protocolo,
fixture, gravação/reprodução e caos. Ele é aditivo e não
substitui o dispatcher de cenários `mock-openai`.
- `mock-openai` é o mock OpenClaw ciente de cenários. Ele permanece a lane de mock determinística padrão para QA baseado no repositório e gates de paridade.
- `aimock` inicia um servidor de provedor baseado em AIMock para cobertura experimental de protocolo, fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o dispatcher de cenários `mock-openai`.
A implementação de lanes de provedor fica em `extensions/qa-lab/src/providers/`.
Cada provedor possui seus padrões, inicialização de servidor local, configuração de modelo do Gateway,
necessidades de preparação de perfil de autenticação e flags de capacidade live/mock. O código compartilhado da suíte e do
Gateway deve rotear pelo registro de provedores em vez de ramificar por
nomes de provedores.
A implementação de lanes de provedor fica em `extensions/qa-lab/src/providers/`. Cada provedor possui seus próprios padrões, inicialização de servidor local, configuração de modelo do Gateway, necessidades de staging de auth-profile e flags de capacidade live/mock. O código compartilhado da suite e do Gateway deve rotear pelo registro de provedores em vez de ramificar por nomes de provedores.
## Adaptadores de transporte
`qa-lab` possui uma seam de transporte genérica para cenários de QA em markdown. `qa-channel` é o primeiro adaptador nessa seam, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suíte em vez de adicionar um runner de QA específico para transporte.
`qa-lab` possui uma costura de transporte genérica para cenários Markdown de QA. `qa-channel` é o primeiro adaptador nessa costura, mas o alvo de design é mais amplo: canais reais ou sintéticos futuros devem se conectar ao mesmo runner de suite em vez de adicionar um runner de QA específico para transporte.
No nível de arquitetura, a divisão é:
- `qa-lab` possui execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios.
- `qa-lab` possui execução genérica de cenários, concorrência de workers, escrita de artefatos e relatórios.
- O adaptador de transporte possui configuração do Gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado.
- Arquivos de cenário markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa.
- Arquivos de cenário Markdown em `qa/scenarios/` definem a execução do teste; `qa-lab` fornece a superfície reutilizável de runtime que os executa.
### Adicionando um canal
Adicionar um canal ao sistema de QA em markdown exige exatamente duas coisas:
Adicionar um canal ao sistema de QA Markdown exige exatamente duas coisas:
1. Um adaptador de transporte para o canal.
2. Um pacote de cenários que exercite o contrato do canal.
Não adicione uma nova raiz de comando de QA de nível superior quando o host `qa-lab` compartilhado puder ser dono do fluxo.
Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder possuir o fluxo.
`qa-lab` é responsável pela mecânica compartilhada do host:
`qa-lab` possui a mecânica do host compartilhado:
- a raiz do comando `openclaw qa`
- inicialização e encerramento da suíte
- inicialização e teardown da suite
- concorrência de workers
- gravação de artefatos
- escrita de artefatos
- geração de relatórios
- execução de cenários
- aliases de compatibilidade para cenários `qa-channel` mais antigos
Os plugins executores são responsáveis pelo contrato de transporte:
Plugins de runner possuem o contrato de transporte:
- como `openclaw qa <runner>` é montado abaixo da raiz `qa` compartilhada
- como o gateway é configurado para esse transporte
- como `openclaw qa <runner>` é montado abaixo da raiz compartilhada `qa`
- como o Gateway é configurado para esse transporte
- como a prontidão é verificada
- como eventos de entrada são injetados
- como mensagens de saída são observadas
- como transcrições e o estado normalizado do transporte são expostos
- como ações respaldadas pelo transporte são executadas
- como redefinições ou limpezas específicas do transporte são tratadas
- como transcrições e estado de transporte normalizado são expostos
- como ações apoiadas por transporte são executadas
- como reset ou limpeza específicos do transporte são tratados
O nível mínimo de adoção para um novo canal:
O patamar mínimo de adoção para um novo canal:
1. Mantenha `qa-lab` como responsável pela raiz `qa` compartilhada.
2. Implemente o executor de transporte na interface compartilhada de host do `qa-lab`.
3. Mantenha a mecânica específica de transporte dentro do plugin executor ou do harness de canal.
4. Monte o executor como `openclaw qa <runner>` em vez de registrar um comando raiz concorrente. Plugins executores devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; a CLI preguiçosa e a execução do executor devem ficar atrás de pontos de entrada separados.
1. Mantenha `qa-lab` como proprietário da raiz compartilhada `qa`.
2. Implemente o runner de transporte na costura do host compartilhado `qa-lab`.
3. Mantenha a mecânica específica do transporte dentro do plugin de runner ou harness do canal.
4. Monte o runner como `openclaw qa <runner>` em vez de registrar um comando raiz concorrente. Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. Mantenha `runtime-api.ts` leve; a CLI lazy e a execução do runner devem permanecer atrás de entrypoints separados.
5. Crie ou adapte cenários Markdown nos diretórios temáticos `qa/scenarios/`.
6. Use os auxiliares genéricos de cenário para novos cenários.
7. Mantenha os aliases de compatibilidade existentes funcionando, a menos que o repo esteja fazendo uma migração intencional.
6. Use os helpers genéricos de cenário para novos cenários.
7. Mantenha os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional.
A regra de decisão é estrita:
- Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`.
- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin executor ou harness de plugin.
- Se um cenário precisar de um novo recurso que mais de um canal possa usar, adicione um auxiliar genérico em vez de uma ramificação específica de canal em `suite.ts`.
- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico de transporte e deixe isso explícito no contrato do cenário.
- Se o comportamento depender de um transporte de canal, mantenha-o nesse plugin de runner ou harness de plugin.
- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de uma ramificação específica de canal em `suite.ts`.
- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico de transporte e explicite isso no contrato do cenário.
### Nomes dos auxiliares de cenário
### Nomes de helpers de cenário
Auxiliares genéricos preferidos para novos cenários:
Helpers genéricos preferidos para novos cenários:
- `waitForTransportReady`
- `waitForChannelReady`
@ -463,11 +624,11 @@ Auxiliares genéricos preferidos para novos cenários:
- `formatTransportTranscript`
- `resetTransport`
Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a criação de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração completa de uma só vez, não como o modelo daqui em diante.
Aliases de compatibilidade continuam disponíveis para cenários existentes — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — mas a autoria de novos cenários deve usar os nomes genéricos. Os aliases existem para evitar uma migração flag-day, não como o modelo daqui para frente.
## Relatórios
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do barramento.
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado.
O relatório deve responder:
- O que funcionou
@ -477,8 +638,7 @@ O relatório deve responder:
Para o inventário de cenários disponíveis — útil ao dimensionar trabalho de acompanhamento ou conectar um novo transporte — execute `pnpm openclaw qa coverage` (adicione `--json` para saída legível por máquina).
Para verificações de personagem e estilo, execute o mesmo cenário em várias refs de modelos ao vivo
e grave um relatório julgado em Markdown:
Para verificações de caráter e estilo, execute o mesmo cenário em múltiplas refs de modelo live e grave um relatório Markdown julgado:
```bash
pnpm openclaw qa character-eval \
@ -497,42 +657,23 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
O comando executa processos filhos locais do Gateway de QA, não Docker. Cenários de avaliação de personagem
devem definir a persona por meio de `SOUL.md` e depois executar turnos comuns de usuário,
como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato
não deve ser informado de que 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`, quando houver suporte, para classificar as execuções por naturalidade, vibe e humor.
Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe
todas as transcrições e estados 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.
Execuções candidatas usam `high` thinking por padrão, com `medium` para GPT-5.5 e `xhigh`
para refs de avaliação OpenAI mais antigas que oferecem suporte. Substitua um candidato específico em linha com
`--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um
fallback global, e a forma mais antiga `--model-thinking <provider/model=level>` é
mantida para compatibilidade.
Refs candidatas OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado onde
o provedor oferece suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` em linha 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 de benchmark, mas os prompts dos juízes dizem explicitamente
para não classificar por velocidade.
Execuções dos modelos candidatos e juízes usam concorrência 16 por padrão. Reduza
`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão local do Gateway
tornarem uma execução ruidosa demais.
Quando nenhum candidato `--model` é passado, a avaliação de personagem usa por padrão
O comando executa processos filhos do Gateway de QA local, não Docker. Cenários de avaliação de personagem devem definir a persona por meio de `SOUL.md` e, depois, executar turnos comuns de usuário, como chat, ajuda no workspace e pequenas tarefas de arquivo. O modelo candidato não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição completa, registra estatísticas básicas da execução e, depois, pede aos modelos julgadores em modo rápido, com raciocínio `xhigh` quando houver suporte, que classifiquem as execuções por naturalidade, tom e humor.
Use `--blind-judge-models` ao comparar provedores: o prompt do julgador ainda recebe cada transcrição e status de execução, mas as refs dos candidatos 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.
Execuções de candidatos usam `high` como padrão de thinking, com `medium` para GPT-5.5 e `xhigh` para refs de avaliação mais antigas da OpenAI que oferecem suporte a isso. Sobrescreva um candidato específico inline com `--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um fallback global, e o formato antigo `--model-thinking <provider/model=level>` é mantido por compatibilidade.
Refs de candidatos da OpenAI usam modo rápido por padrão para que o processamento prioritário seja usado quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um único candidato ou julgador precisar de uma substituição. Passe `--fast` apenas quando quiser forçar o modo rápido para todos os modelos candidatos. As durações de candidatos e julgadores são registradas no relatório para análise de benchmark, mas os prompts dos julgadores dizem explicitamente para não classificar por velocidade.
Execuções de modelos candidatos e julgadores usam concorrência 16 por padrão. Reduza `--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway local tornarem uma execução ruidosa demais.
Quando nenhum `--model` de candidato é passado, a avaliação de personagem usa como padrão
`openai/gpt-5.5`, `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
`google/gemini-3.1-pro-preview` quando nenhum `--model` é passado.
Quando nenhum `--judge-model` é passado, os juízes usam por padrão
Quando nenhum `--judge-model` é passado, os julgadores usam como padrão
`openai/gpt-5.5,thinking=xhigh,fast` e
`anthropic/claude-opus-4-6,thinking=high`.
## Documentos relacionados
## Documentação relacionada
- [QA de matriz](/pt-BR/concepts/qa-matrix)
- [Matriz de QA](/pt-BR/concepts/qa-matrix)
- [Canal de QA](/pt-BR/channels/qa-channel)
- [Testes](/pt-BR/help/testing)
- [Dashboard](/pt-BR/web/dashboard)
- [Painel](/pt-BR/web/dashboard)

178
docs/pt-BR/gateway/config-tools.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Configurando a política `tools.*`, listas de permissões ou recursos experimentais
- Configurando a política de `tools.*`, listas de permissões ou recursos experimentais
- Registrando provedores personalizados ou substituindo URLs base
- Configurando endpoints auto-hospedados compatíveis com OpenAI
sidebarTitle: Tools and custom providers
summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas com suporte de provedor) e configuração personalizada de provedor/base-URL
summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas apoiadas por provedor) e configuração personalizada de provedor/URL base
title: Configuração — ferramentas e provedores personalizados
x-i18n:
generated_at: "2026-05-03T21:31:35Z"
generated_at: "2026-05-05T01:45:57Z"
model: gpt-5.5
provider: openai
source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da
source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883
source_path: gateway/config-tools.md
workflow: 16
---
`tools.*` chaves de configuração e configuração personalizada de provedor / URL base. Para agentes, canais e outras chaves de configuração de nível superior, consulte [Referência de configuração](/pt-BR/gateway/configuration-reference).
`tools.*` chaves de configuração e configuração de provedor personalizado / URL base. Para agentes, canais e outras chaves de configuração de nível superior, consulte [Referência de configuração](/pt-BR/gateway/configuration-reference).
## Ferramentas
### Perfis de ferramentas
`tools.profile` define uma lista de permissões base antes de `tools.allow`/`tools.deny`:
`tools.profile` define uma lista de permissão base antes de `tools.allow`/`tools.deny`:
<Note>
A integração local define novas configurações locais como `tools.profile: "coding"` quando não estiver definido (perfis explícitos existentes são preservados).
O onboarding local define novas configurações locais como `tools.profile: "coding"` quando não estiver definido (perfis explícitos existentes são preservados).
</Note>
| Perfil | Inclui |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `minimal` | somente `session_status` |
| `minimal` | apenas `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Sem restrição (igual a não definido) |
@ -49,11 +49,11 @@ A integração local define novas configurações locais como `tools.profile: "c
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Todas as ferramentas integradas (exclui Plugins de provedor) |
| `group:openclaw` | Todas as ferramentas integradas (exclui plugins de provedor) |
### `tools.allow` / `tools.deny`
Política global de permissão/negação de ferramentas (negação prevalece). Não diferencia maiúsculas de minúsculas, aceita curingas `*`. Aplicada mesmo quando o sandbox do Docker está desativado.
Política global de permissão/negação de ferramentas (`deny` prevalece). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado.
```json5
{
@ -61,7 +61,7 @@ Política global de permissão/negação de ferramentas (negação prevalece). N
}
```
`write` e `apply_patch` são IDs de ferramentas separados. `allow: ["write"]` também habilita `apply_patch` para modelos compatíveis, mas `deny: ["write"]` não nega `apply_patch`. Para bloquear toda mutação de arquivos, negue `group:fs` ou liste explicitamente cada ferramenta de mutação:
`write` e `apply_patch` são ids de ferramenta separados. `allow: ["write"]` também habilita `apply_patch` para modelos compatíveis, mas `deny: ["write"]` não nega `apply_patch`. Para bloquear toda mutação de arquivos, negue `group:fs` ou liste explicitamente cada ferramenta de mutação:
```json5
{
@ -71,7 +71,7 @@ Política global de permissão/negação de ferramentas (negação prevalece). N
### `tools.byProvider`
Restrinja ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permissão/negação.
Restringe ainda mais as ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permissão/negação.
```json5
{
@ -87,7 +87,7 @@ Restrinja ainda mais ferramentas para provedores ou modelos específicos. Ordem:
### `tools.elevated`
Controla o acesso elevado de exec fora do sandbox:
Controla o acesso elevado de `exec` fora do sandbox:
```json5
{
@ -105,7 +105,7 @@ Controla o acesso elevado de exec fora do sandbox:
- A substituição por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais.
- `/elevated on|off|ask|full` armazena o estado por sessão; diretivas inline se aplicam a uma única mensagem.
- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino de exec é `node`).
- `exec` elevado ignora o sandboxing e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o alvo de `exec` é `node`).
### `tools.exec`
@ -129,7 +129,7 @@ Controla o acesso elevado de exec fora do sandbox:
### `tools.loopDetection`
As verificações de segurança contra loops de ferramentas são **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`.
As verificações de segurança contra loops de ferramentas estão **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`.
```json5
{
@ -151,25 +151,25 @@ As verificações de segurança contra loops de ferramentas são **desativadas p
```
<ParamField path="historySize" type="number">
Máximo de histórico de chamadas de ferramenta mantido para análise de loops.
Histórico máximo de chamadas de ferramenta retido para análise de loops.
</ParamField>
<ParamField path="warningThreshold" type="number">
Limite de padrões repetidos sem progresso para avisos.
Limite de padrão repetido sem progresso para avisos.
</ParamField>
<ParamField path="criticalThreshold" type="number">
Limite de repetição mais alto para bloquear loops críticos.
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
Limite de parada rígida para qualquer execução sem progresso.
Limite de parada forçada para qualquer execução sem progresso.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Avisa sobre chamadas repetidas com a mesma ferramenta/os mesmos argumentos.
Avisar sobre chamadas repetidas com a mesma ferramenta/os mesmos argumentos.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Avisa/bloqueia ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.).
Avisar/bloquear em ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.).
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
Avisa/bloqueia padrões alternados de pares sem progresso.
Avisar/bloquear em padrões alternados de pares sem progresso.
</ParamField>
<Warning>
@ -208,7 +208,7 @@ Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircui
### `tools.media`
Configura a compreensão de mídia recebida (imagem/áudio/vídeo):
Configura o entendimento de mídia recebida (imagem/áudio/vídeo):
```json5
{
@ -216,7 +216,7 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo):
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async video directly to the channel
directSend: false, // deprecated: completions stay agent-mediated
},
audio: {
enabled: true,
@ -246,30 +246,30 @@ Configura a compreensão de mídia recebida (imagem/áudio/vídeo):
```
<AccordionGroup>
<Accordion title="Media model entry fields">
<Accordion title="Campos de entrada do modelo de mídia">
**Entrada de provedor** (`type: "provider"` ou omitido):
- `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
- `model`: substituição do ID do modelo
- `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json`
- `provider`: id do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
- `model`: substituição do id do modelo
- `profile` / `preferredProfile`: seleção de perfil de `auth-profiles.json`
**Entrada de CLI** (`type: "cli"`):
- `command`: executável a executar
- `args`: argumentos com modelo (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.; `openclaw doctor --fix` migra placeholders `{input}` obsoletos para `{{MediaPath}}`)
- `command`: executável a ser executado
- `args`: argumentos com modelo (aceita `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.; `openclaw doctor --fix` migra placeholders obsoletos `{input}` para `{{MediaPath}}`)
**Campos comuns:**
- `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → imagem, `google` → imagem+áudio+vídeo, `groq` → áudio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada.
- `tools.media.image.timeoutSeconds` e entradas correspondentes de `timeoutSeconds` do modelo de imagem também se aplicam quando o agente chama a ferramenta explícita `image`.
- As falhas recorrem à próxima entrada.
- Falhas recorrem à próxima entrada.
A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`.
**Campos de conclusão assíncrona:**
- `asyncCompletion.directSend`: quando `true`, tarefas de mídia assíncronas concluídas que são compatíveis com entrega direta de conclusão tentam primeiro a entrega direta ao canal. Padrão: `false` (caminho de despertar da sessão solicitante/entrega por modelo). Atualmente, isso se aplica a `video_generate` assíncrono; conclusões assíncronas de `music_generate` continuam mediadas pela sessão solicitante mesmo quando isso está ativado.
- `asyncCompletion.directSend`: sinalizador de compatibilidade obsoleto. Tarefas assíncronas de mídia concluídas permanecem mediadas pela sessão solicitante para que o agente receba o resultado, decida como informar o usuário e use a ferramenta de mensagem quando a entrega de origem exigir.
</Accordion>
</AccordionGroup>
@ -305,12 +305,12 @@ Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes).
```
<AccordionGroup>
<Accordion title="Visibility scopes">
- `self`: somente a chave da sessão atual.
<Accordion title="Escopos de visibilidade">
- `self`: apenas a chave da sessão atual.
- `tree`: sessão atual + sessões geradas pela sessão atual (subagentes).
- `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente).
- `all`: qualquer sessão. O direcionamento entre agentes ainda requer `tools.agentToAgent`.
- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`.
- `agent`: qualquer sessão pertencente ao id do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo id de agente).
- `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`.
- Restrição de sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo que `tools.sessions.visibility="all"`.
</Accordion>
</AccordionGroup>
@ -339,10 +339,10 @@ Controla o suporte a anexos inline para `sessions_spawn`.
<Accordion title="Notas sobre anexos">
- Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita.
- Os arquivos são materializados no workspace filho em `.openclaw/attachments/<uuid>/` com um `.manifest.json`.
- O conteúdo dos anexos é automaticamente redigido da persistência da transcrição.
- Entradas Base64 são validadas com verificações estritas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação.
- O conteúdo dos anexos é automaticamente censurado da persistência da transcrição.
- Entradas Base64 são validadas com verificações rigorosas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação.
- As permissões de arquivo são `0700` para diretórios e `0600` para arquivos.
- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`.
- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os mantém apenas quando `retainOnSessionKeep: true`.
</Accordion>
</AccordionGroup>
@ -351,7 +351,7 @@ Controla o suporte a anexos inline para `sessions_spawn`.
### `tools.experimental`
Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos que uma regra de ativação automática strict-agentic do GPT-5 se aplique.
Flags experimentais de ferramentas integradas. Desativado por padrão, a menos que uma regra de ativação automática strict-agentic do GPT-5 se aplique.
```json5
{
@ -363,8 +363,8 @@ Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos
}
```
- `planTool`: habilita a ferramenta estruturada `update_plan` para rastreamento de trabalho não trivial em várias etapas.
- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 do OpenAI ou OpenAI Codex. Defina como `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções strict-agentic do GPT-5.
- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhar trabalhos não triviais de várias etapas.
- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 strict-agentic.
- Quando habilitado, o prompt do sistema também adiciona orientações de uso para que o modelo a use apenas em trabalhos substanciais e mantenha no máximo uma etapa `in_progress`.
### `agents.defaults.subagents`
@ -385,16 +385,16 @@ Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos
}
```
- `model`: modelo padrão para subagentes gerados. Se omitido, os subagentes herdam o modelo do chamador.
- `allowAgents`: lista de permissões padrão de IDs de agentes de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: apenas o mesmo agente).
- `runTimeoutSeconds`: tempo limite padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem tempo limite.
- Política de ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
- `model`: modelo padrão para subagentes iniciados. Se omitido, os subagentes herdam o modelo do chamador.
- `allowAgents`: lista de permissões padrão de IDs de agentes de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: somente o mesmo agente).
- `runTimeoutSeconds`: timeout padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem timeout.
- Política de ferramentas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
## Provedores personalizados e URLs base
O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizados via `models.providers` na configuração ou em `~/.openclaw/agents/<agentId>/agent/models.json`.
OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizados via `models.providers` na configuração ou em `~/.openclaw/agents/<agentId>/agent/models.json`.
```json5
{
@ -427,75 +427,75 @@ O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personaliza
<Accordion title="Autenticação e precedência de mesclagem">
- Use `authHeader: true` + `headers` para necessidades de autenticação personalizada.
- Substitua a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente).
- Precedência de mesclagem para IDs de provedor correspondentes:
- Valores `baseUrl` não vazios de `models.json` do agente vencem.
- Valores `apiKey` não vazios do agente vencem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
- Valores `apiKey` de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos.
- Valores de cabeçalho de provedor gerenciado por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec).
- `apiKey`/`baseUrl` vazios ou ausentes do agente recorrem a `models.providers` na configuração.
- `contextWindow`/`maxTokens` de modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo.
- `contextTokens` de modelo correspondente preserva um limite de runtime explícito quando presente; use-o para limitar o contexto efetivo sem alterar metadados nativos do modelo.
- Precedência de mesclagem para IDs de provedores correspondentes:
- Valores `baseUrl` não vazios do `models.json` do agente vencem.
- Valores `apiKey` não vazios do agente vencem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação.
- Valores `apiKey` de provedor gerenciado por SecretRef são atualizados a partir dos marcadores de origem (`ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos.
- Valores de cabeçalho de provedor gerenciado por SecretRef são atualizados a partir dos marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de arquivo/exec).
- `apiKey`/`baseUrl` vazios ou ausentes do agente voltam para `models.providers` na configuração.
- `contextWindow`/`maxTokens` de modelos correspondentes usam o maior valor entre a configuração explícita e os valores implícitos do catálogo.
- `contextTokens` de modelos correspondentes preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo.
- Use `models.mode: "replace"` quando quiser que a configuração reescreva completamente `models.json`.
- A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot de configuração de origem ativo (antes da resolução), não dos valores de segredo de runtime resolvidos.
- A persistência de marcadores tem a origem como autoridade: os marcadores são escritos a partir do snapshot da configuração de origem ativa (pré-resolução), não dos valores de segredo resolvidos em runtime.
</Accordion>
</AccordionGroup>
### Detalhes dos campos de provedor
### Detalhes dos campos do provedor
<AccordionGroup>
<Accordion title="Catálogo de nível superior">
- `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`).
- `models.providers`: mapa de provedores personalizados indexado por ID de provedor.
- `models.providers`: mapa de provedores personalizados indexado pelo ID do provedor.
- Edições seguras: use `openclaw config set models.providers.<id> '<json>' --strict-json --merge` ou `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` para atualizações aditivas. `config set` recusa substituições destrutivas, a menos que você passe `--replace`.
</Accordion>
<Accordion title="Conexão e autenticação do provedor">
- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). Para backends auto-hospedados de `/v1/chat/completions`, como MLX, vLLM, SGLang e a maioria dos servidores locais compatíveis com OpenAI, use `openai-completions`. Um provedor personalizado com `baseUrl` mas sem `api` usa `openai-completions` por padrão; defina `openai-responses` apenas quando o backend oferecer suporte a `/v1/responses`.
- `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por env).
- `models.providers.*.api`: adaptador de solicitação (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc). Para backends auto-hospedados `/v1/chat/completions`, como MLX, vLLM, SGLang e a maioria dos servidores locais compatíveis com OpenAI, use `openai-completions`. Um provedor personalizado com `baseUrl` mas sem `api` usa `openai-completions` como padrão; defina `openai-responses` apenas quando o backend for compatível com `/v1/responses`.
- `models.providers.*.apiKey`: credencial do provedor (prefira substituição por SecretRef/env).
- `models.providers.*.auth`: estratégia de autenticação (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.contextWindow`: janela de contexto nativa padrão para modelos neste provedor quando a entrada do modelo não define `contextWindow`.
- `models.providers.*.contextTokens`: limite efetivo padrão de contexto de runtime para modelos neste provedor quando a entrada do modelo não define `contextTokens`.
- `models.providers.*.maxTokens`: limite padrão de tokens de saída para modelos neste provedor quando a entrada do modelo não define `maxTokens`.
- `models.providers.*.timeoutSeconds`: tempo limite opcional por provedor para requisições HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de abortamento total da requisição.
- `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas requisições (padrão: `true`).
- `models.providers.*.contextWindow`: janela de contexto nativa padrão para modelos desse provedor quando a entrada do modelo não define `contextWindow`.
- `models.providers.*.contextTokens`: limite efetivo padrão de contexto em runtime para modelos desse provedor quando a entrada do modelo não define `contextTokens`.
- `models.providers.*.maxTokens`: limite padrão de tokens de saída para modelos desse provedor quando a entrada do modelo não define `maxTokens`.
- `models.providers.*.timeoutSeconds`: timeout opcional por provedor para solicitações HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de aborto da solicitação total.
- `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas solicitações (padrão: `true`).
- `models.providers.*.authHeader`: força o transporte de credenciais no cabeçalho `Authorization` quando necessário.
- `models.providers.*.baseUrl`: URL base da API upstream.
- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento de proxy/tenant.
</Accordion>
<Accordion title="Substituições de transporte da requisição">
`models.providers.*.request`: substituições de transporte para requisições HTTP de provedores de modelo.
<Accordion title="Substituições de transporte da solicitação">
`models.providers.*.request`: substituições de transporte para solicitações HTTP do provedor de modelos.
- `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Os valores aceitam SecretRef.
- `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional).
- `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Valores aceitam SecretRef.
- `request.auth`: substituição de estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional).
- `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional.
- `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para faixas privadas, CGNAT ou semelhantes, via proteção de fetch HTTP do provedor (aceite explícito do operador para endpoints auto-hospedados compatíveis com OpenAI e confiáveis). URLs de stream de provedor de modelo em local loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isso seja definido explicitamente como `false`; hosts LAN, tailnet e DNS privado ainda exigem aceite explícito. WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não esse bloqueio SSRF de fetch. Padrão `false`.
- `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou similares, por meio da proteção de fetch HTTP do provedor (adesão explícita do operador para endpoints auto-hospedados confiáveis compatíveis com OpenAI). URLs de stream de provedor de modelos em local loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isso seja explicitamente definido como `false`; hosts de LAN, tailnet e DNS privado ainda exigem adesão explícita. WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa barreira SSRF de fetch. Padrão `false`.
</Accordion>
<Accordion title="Entradas do catálogo de modelos">
- `models.providers.*.models`: entradas explícitas do catálogo de modelos do provedor.
- `models.providers.*.models.*.input`: modalidades de entrada do modelo. Use `["text"]` para modelos somente texto e `["text", "image"]` para modelos nativos de imagem/visão. Anexos de imagem são injetados em turnos do agente apenas quando o modelo selecionado está marcado como compatível com imagens.
- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. Isso substitui `contextWindow` em nível de provedor para esse modelo.
- `models.providers.*.models.*.contextTokens`: limite opcional de contexto de runtime. Isso substitui `contextTokens` em nível de provedor; use quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo; `openclaw models list` mostra ambos os valores quando eles diferem.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com um `baseUrl` não vazio e não nativo (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI.
- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas strings. Quando `true`, o OpenClaw achata arrays `messages[].content` de texto puro em strings simples antes de enviar a requisição.
- `models.providers.*.models.*.input`: modalidades de entrada do modelo. Use `["text"]` para modelos somente texto e `["text", "image"]` para modelos nativos de imagem/visão. Anexos de imagem só são injetados em turnos do agente quando o modelo selecionado está marcado como compatível com imagem.
- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. Isso substitui o `contextWindow` em nível de provedor para esse modelo.
- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Isso substitui o `contextTokens` em nível de provedor; use quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo; `openclaw models list` mostra ambos os valores quando diferem.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com um `baseUrl` não nativo e não vazio (host diferente de `api.openai.com`), OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI.
- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam somente strings. Quando `true`, OpenClaw achata arrays de texto puro `messages[].content` em strings simples antes de enviar a solicitação.
</Accordion>
<Accordion title="Descoberta do Amazon Bedrock">
- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de descoberta automática do Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa a descoberta implícita.
- `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para descoberta.
- `plugins.entries.amazon-bedrock.config.discovery.region`: região da AWS para descoberta.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional por ID de provedor para descoberta direcionada.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto reserva para modelos descobertos.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída reserva para modelos descobertos.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto de fallback para modelos descobertos.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos.
</Accordion>
</AccordionGroup>
O onboarding interativo de provedores personalizados infere entrada de imagem para IDs comuns de modelos de visão, como GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V e GLM-4V, e ignora a pergunta extra para famílias conhecidas somente texto. IDs de modelo desconhecidos ainda solicitam suporte a imagem. O onboarding não interativo usa a mesma inferência; passe `--custom-image-input` para forçar metadados compatíveis com imagem ou `--custom-text-input` para forçar metadados somente texto.
A integração interativa de provedores personalizados infere entrada de imagem para IDs comuns de modelos de visão, como GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V e GLM-4V, e pula a pergunta extra para famílias conhecidas somente texto. IDs de modelos desconhecidos ainda perguntam sobre suporte a imagem. A integração não interativa usa a mesma inferência; passe `--custom-image-input` para forçar metadados compatíveis com imagem ou `--custom-text-input` para forçar metadados somente texto.
### Exemplos de provedores
@ -538,7 +538,7 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa
Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI direto.
</Accordion>
<Accordion title="Programação com Kimi">
<Accordion title="Kimi Coding">
```json5
{
env: { KIMI_API_KEY: "sk-..." },
@ -554,10 +554,10 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa
Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`.
</Accordion>
<Accordion title="Modelos locais (LM Studio)">
Consulte [Modelos locais](/pt-BR/gateway/local-models). TL;DR: execute um modelo local grande pela API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados como fallback.
<Accordion title="Local models (LM Studio)">
Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um modelo local grande pela LM Studio Responses API em hardware robusto; mantenha os modelos hospedados mesclados para fallback.
</Accordion>
<Accordion title="MiniMax M2.7 (direto)">
<Accordion title="MiniMax M2.7 (direct)">
```json5
{
agents: {
@ -631,7 +631,7 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa
Para o endpoint da China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`.
Endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte `openai-completions` compartilhado, e o OpenClaw determina isso com base nas capacidades do endpoint, não apenas no id do provedor integrado.
Os endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado `openai-completions`, e o OpenClaw determina isso pelas capacidades do endpoint, não apenas pelo id do provedor integrado.
</Accordion>
<Accordion title="OpenCode">
@ -646,10 +646,10 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa
}
```
Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencode/...` para o catálogo Zen ou referências `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`.
Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use refs `opencode/...` para o catálogo Zen ou refs `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`.
</Accordion>
<Accordion title="Sintético (compatível com Anthropic)">
<Accordion title="Synthetic (Anthropic-compatible)">
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
@ -709,9 +709,9 @@ O onboarding interativo de provedores personalizados infere entrada de imagem pa
---
## Relacionado
## Relacionados
- [Configuração — agentes](/pt-BR/gateway/config-agents)
- [Configuração — canais](/pt-BR/gateway/config-channels)
- [Configuração — agents](/pt-BR/gateway/config-agents)
- [Configuração — channels](/pt-BR/gateway/config-channels)
- [Referência de configuração](/pt-BR/gateway/configuration-reference) — outras chaves de nível superior
- [Ferramentas e plugins](/pt-BR/tools)

514
docs/pt-BR/gateway/configuration-reference.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Você precisa de semântica ou padrões exatos de configuração no nível dos campos
- Você precisa da semântica exata de configuração em nível de campo ou dos valores padrão
- Você está validando blocos de configuração de canal, modelo, Gateway ou ferramenta
summary: Referência de configuração do Gateway para chaves centrais do OpenClaw, valores padrão e links para referências dedicadas de subsistemas
summary: Referência de configuração do Gateway para chaves centrais do OpenClaw, valores padrão e links para referências dedicadas de subsistema
title: Referência de configuração
x-i18n:
generated_at: "2026-05-03T21:31:42Z"
generated_at: "2026-05-05T01:45:59Z"
model: gpt-5.5
provider: openai
source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9
source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684
source_path: gateway/configuration-reference.md
workflow: 16
---
Referência da configuração principal para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuração](/pt-BR/gateway/configuration).
Referência de configuração principal para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuração](/pt-BR/gateway/configuration).
Abrange as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria referência mais aprofundada. Catálogos de comandos pertencentes a canais e plugins e ajustes avançados de memória/QMD ficam em suas próprias páginas, não nesta.
Abrange as principais superfícies de configuração do OpenClaw e aponta para outras páginas quando um subsistema tem sua própria referência mais aprofundada. Catálogos de comandos pertencentes a canais e Plugins, além de ajustes avançados de memória/QMD, ficam em suas próprias páginas, em vez desta.
Verdade do código:
Fonte da verdade no código:
- `openclaw config schema` imprime o JSON Schema ativo usado para validação e Control UI, com metadados de bundles/plugins/canais mesclados quando disponíveis
- `config.schema.lookup` retorna um nó de schema com escopo de caminho para ferramentas de detalhamento
- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de baseline da documentação de configuração em relação à superfície de schema atual
- `openclaw config schema` imprime o JSON Schema ativo usado para validação e Control UI, com metadados de pacotes/Plugins/canais mesclados quando disponíveis
- `config.schema.lookup` retorna um nó de esquema com escopo por caminho para ferramentas de inspeção detalhada
- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de base da documentação de configuração contra a superfície de esquema atual
Caminho de consulta do agente: use a ação de ferramenta `config.schema.lookup` do `gateway` para
Caminho de consulta do agente: use a ação de ferramenta `gateway` `config.schema.lookup` para
documentação e restrições exatas em nível de campo antes de editar. Use
[Configuração](/pt-BR/gateway/configuration) para orientação orientada a tarefas e esta página
para o mapa de campos mais amplo, padrões e links para referências de subsistemas.
Referências aprofundadas dedicadas:
- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de dreaming em `plugins.entries.memory-core.config.dreaming`
- [Comandos slash](/pt-BR/tools/slash-commands) para o catálogo atual de comandos integrados + em bundle
- páginas dos canais/plugins proprietários para superfícies de comandos específicas de canais
- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de Dreaming em `plugins.entries.memory-core.config.dreaming`
- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos integrados + empacotados
- páginas dos canais/Plugins proprietários para superfícies de comandos específicas de canal
O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos.
O formato da configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando eles são omitidos.
---
@ -43,20 +43,20 @@ O formato de configuração é **JSON5** (comentários + vírgulas finais permit
As chaves de configuração por canal foram movidas para uma página dedicada — consulte
[Configuração — canais](/pt-BR/gateway/config-channels) para `channels.*`,
incluindo Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e outros
canais em bundle (autenticação, controle de acesso, várias contas, controle de menções).
canais empacotados (autenticação, controle de acesso, várias contas, bloqueio por menções).
## Padrões de agente, multiagente, sessões e mensagens
Movido para uma página dedicada — consulte
[Configuração — agentes](/pt-BR/gateway/config-agents) para:
- `agents.defaults.*` (workspace, modelo, raciocínio, heartbeat, memória, mídia, skills, sandbox)
- `multiAgent.*` (roteamento e vinculações multiagente)
- `session.*` (ciclo de vida da sessão, compaction, poda)
- `messages.*` (entrega de mensagens, TTS, renderização markdown)
- `agents.defaults.*` (workspace, modelo, raciocínio, Heartbeat, memória, mídia, Skills, sandbox)
- `multiAgent.*` (roteamento e vínculos multiagente)
- `session.*` (ciclo de vida da sessão, Compaction, poda)
- `messages.*` (entrega de mensagens, TTS, renderização de markdown)
- `talk.*` (modo Talk)
- `talk.speechLocale`: id de localidade BCP 47 opcional para reconhecimento de fala do Talk no iOS/macOS
- `talk.silenceTimeoutMs`: quando não definido, o Talk mantém a janela de pausa padrão da plataforma antes de enviar a transcrição (`700 ms on macOS and Android, 900 ms on iOS`)
- `talk.silenceTimeoutMs`: quando não definido, o Talk mantém a janela de pausa padrão da plataforma antes de enviar a transcrição (`700 ms no macOS e Android, 900 ms no iOS`)
## Ferramentas e provedores personalizados
@ -66,7 +66,7 @@ provedor personalizado / URL base foram movidas para uma página dedicada — co
## Modelos
Definições de provedores, allowlists de modelos e configuração de provedor personalizado ficam em
Definições de provedores, listas de modelos permitidos e configuração de provedores personalizados ficam em
[Configuração — ferramentas e provedores personalizados](/pt-BR/gateway/config-tools#custom-providers-and-base-urls).
A raiz `models` também controla o comportamento global do catálogo de modelos.
@ -80,11 +80,11 @@ A raiz `models` também controla o comportamento global do catálogo de modelos.
```
- `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`).
- `models.providers`: mapa de provedores personalizados indexado por id de provedor.
- `models.providers`: mapa de provedores personalizados indexado por id do provedor.
- `models.pricing.enabled`: controla a inicialização de preços em segundo plano que
começa depois que sidecars e canais chegam ao caminho pronto do Gateway. Quando `false`,
começa depois que sidecars e canais alcançam o caminho pronto do Gateway. Quando `false`,
o Gateway ignora buscas de catálogo de preços do OpenRouter e LiteLLM; valores
`models.providers.*.models[].cost` configurados ainda funcionam para estimativas locais de custo.
`models.providers.*.models[].cost` configurados ainda funcionam para estimativas de custo locais.
## MCP
@ -120,15 +120,15 @@ servidor de destino durante edições de configuração.
Entradas remotas usam `transport: "streamable-http"` ou `transport: "sse"`;
`type: "http"` é um alias nativo da CLI que `openclaw mcp set` e
`openclaw doctor --fix` normalizam para o campo canônico `transport`.
- `mcp.sessionIdleTtlMs`: TTL ocioso para runtimes MCP em bundle com escopo de sessão.
Execuções incorporadas pontuais solicitam limpeza ao fim da execução; este TTL é o recurso de segurança para
sessões de longa duração e futuros chamadores.
- Alterações em `mcp.*` são aplicadas a quente ao descartar runtimes MCP de sessão em cache.
- `mcp.sessionIdleTtlMs`: TTL ocioso para runtimes MCP empacotados com escopo de sessão.
Execuções incorporadas pontuais solicitam limpeza ao fim da execução; este TTL é a proteção para
sessões de longa duração e chamadores futuros.
- Alterações em `mcp.*` são aplicadas a quente descartando runtimes MCP de sessão em cache.
A próxima descoberta/uso de ferramenta os recria a partir da nova configuração, então entradas
`mcp.servers` removidas são coletadas imediatamente em vez de aguardar o TTL ocioso.
Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e
[Backends de CLI](/pt-BR/gateway/cli-backends#bundle-mcp-overlays) para o comportamento em runtime.
[backends da CLI](/pt-BR/gateway/cli-backends#bundle-mcp-overlays) para o comportamento de runtime.
## Skills
@ -155,14 +155,14 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e
}
```
- `allowBundled`: allowlist opcional apenas para Skills em bundle (Skills gerenciadas/de workspace não são afetadas).
- `load.extraDirs`: raízes extras de Skills compartilhadas (menor precedência).
- `install.preferBrew`: quando verdadeiro, prefere instaladores Homebrew quando `brew` está
- `allowBundled`: allowlist opcional apenas para Skills empacotadas (Skills gerenciadas/de workspace não são afetadas).
- `load.extraDirs`: raízes adicionais compartilhadas de Skills (menor precedência).
- `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está
disponível antes de recorrer a outros tipos de instalador.
- `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install`
(`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` desativa uma Skill mesmo que esteja em bundle/instalada.
- `entries.<skillKey>.apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string em texto puro ou objeto SecretRef).
- `entries.<skillKey>.enabled: false` desativa uma Skill mesmo se ela estiver empacotada/instalada.
- `entries.<skillKey>.apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string de texto puro ou objeto SecretRef).
---
@ -173,6 +173,7 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e
plugins: {
enabled: true,
allow: ["voice-call"],
bundledDiscovery: "allowlist",
deny: [],
load: {
paths: ["~/Projects/oss/voice-call-plugin"],
@ -191,40 +192,44 @@ Consulte [MCP](/pt-BR/cli/mcp#openclaw-as-an-mcp-client-registry) e
```
- Carregado de `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, além de `plugins.load.paths`.
- A descoberta aceita Plugins nativos do OpenClaw mais bundles Codex compatíveis e bundles Claude, incluindo bundles Claude sem manifesto com layout padrão.
- **Alterações de configuração exigem reinicialização do gateway.**
- `allow`: allowlist opcional (apenas plugins listados são carregados). `deny` prevalece.
- `plugins.entries.<id>.apiKey`: campo de conveniência de chave de API em nível de Plugin (quando suportado pelo Plugin).
- A descoberta aceita Plugins nativos do OpenClaw, além de pacotes Codex compatíveis e pacotes Claude, incluindo pacotes Claude de layout padrão sem manifesto.
- **Alterações de configuração exigem reinício do Gateway.**
- `allow`: allowlist opcional (somente Plugins listados são carregados). `deny` prevalece.
- `bundledDiscovery`: o padrão é `"allowlist"` para novas configurações, então um
`plugins.allow` não vazio também bloqueia Plugins de provedores empacotados, incluindo provedores
de runtime de pesquisa na web. O Doctor grava `"compat"` para configurações
allowlist legadas migradas para preservar o comportamento existente de provedores empacotados até você optar pela nova política.
- `plugins.entries.<id>.apiKey`: campo de conveniência de chave de API em nível de Plugin (quando compatível com o Plugin).
- `plugins.entries.<id>.env`: mapa de variáveis de ambiente com escopo de Plugin.
- `plugins.entries.<id>.hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompts de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de Plugin nativos e diretórios de hooks fornecidos por bundles compatíveis.
- `plugins.entries.<id>.hooks.allowConversationAccess`: quando `true`, Plugins não incluídos em bundle e confiáveis podem ler conteúdo bruto de conversas de hooks tipados como `llm_input`, `llm_output`, `before_agent_finalize` e `agent_end`.
- `plugins.entries.<id>.subagent.allowModelOverride`: confie explicitamente neste Plugin para solicitar substituições de `provider` e `model` por execução em execuções de subagentes em segundo plano.
- `plugins.entries.<id>.subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando você intencionalmente quiser permitir qualquer modelo.
- `plugins.entries.<id>.config`: objeto de configuração definido pelo Plugin (validado pelo schema nativo de Plugin do OpenClaw quando disponível).
- `plugins.entries.<id>.hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que mutam prompts de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de Plugins nativos e diretórios de hooks fornecidos por pacotes compatíveis.
- `plugins.entries.<id>.hooks.allowConversationAccess`: quando `true`, Plugins confiáveis não empacotados podem ler conteúdo bruto de conversas de hooks tipados como `llm_input`, `llm_output`, `before_agent_finalize` e `agent_end`.
- `plugins.entries.<id>.subagent.allowModelOverride`: confia explicitamente neste Plugin para solicitar substituições de `provider` e `model` por execução em execuções de subagentes em segundo plano.
- `plugins.entries.<id>.subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para substituições confiáveis de subagentes. Use `"*"` somente quando você quiser intencionalmente permitir qualquer modelo.
- `plugins.entries.<id>.config`: objeto de configuração definido pelo Plugin (validado pelo esquema de Plugin nativo do OpenClaw quando disponível).
- Configurações de conta/runtime de Plugin de canal ficam em `channels.<id>` e devem ser descritas pelos metadados `channelConfigs` do manifesto do Plugin proprietário, não por um registro central de opções do OpenClaw.
- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de busca web Firecrawl.
- `apiKey`: chave de API Firecrawl (aceita SecretRef). Usa como fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, o legado `tools.web.fetch.firecrawl.apiKey` ou a variável de ambiente `FIRECRAWL_API_KEY`.
- `baseUrl`: URL base da API Firecrawl (padrão: `https://api.firecrawl.dev`; substituições self-hosted devem apontar para endpoints privados/internos).
- `onlyMainContent`: extrair apenas o conteúdo principal das páginas (padrão: `true`).
- `apiKey`: chave de API do Firecrawl (aceita SecretRef). Recorre a `plugins.entries.firecrawl.config.webSearch.apiKey`, ao legado `tools.web.fetch.firecrawl.apiKey` ou à variável de ambiente `FIRECRAWL_API_KEY`.
- `baseUrl`: URL base da API do Firecrawl (padrão: `https://api.firecrawl.dev`; substituições auto-hospedadas devem apontar para endpoints privados/internos).
- `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`).
- `maxAgeMs`: idade máxima do cache em milissegundos (padrão: `172800000` / 2 dias).
- `timeoutSeconds`: tempo limite da solicitação de scrape em segundos (padrão: `60`).
- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (busca web Grok).
- `enabled`: habilita o provedor X Search.
- `model`: modelo Grok a usar para busca (por exemplo, `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limiares.
- `enabled`: chave mestre de dreaming (padrão `false`).
- `frequency`: cadência cron para cada varredura completa de dreaming (`"0 3 * * *"` por padrão).
- `model`: substituição opcional de modelo do subagente Dream Diary. Requer `plugins.entries.memory-core.subagent.allowModelOverride: true`; combine com `allowedModels` para restringir destinos. Erros de modelo indisponível tentam novamente uma vez com o modelo padrão da sessão; falhas de confiança ou allowlist não fazem fallback silenciosamente.
- política de fases e limiares são detalhes de implementação (não chaves de configuração voltadas ao usuário).
- `timeoutSeconds`: timeout da solicitação de raspagem em segundos (padrão: `60`).
- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (pesquisa web Grok).
- `enabled`: ativa o provedor X Search.
- `model`: modelo Grok a usar para pesquisa (por exemplo, `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: configurações de Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites.
- `enabled`: alternância principal de Dreaming (padrão `false`).
- `frequency`: cadência Cron para cada varredura completa de Dreaming (`"0 3 * * *"` por padrão).
- `model`: substituição opcional de modelo de subagente Dream Diary. Exige `plugins.entries.memory-core.subagent.allowModelOverride: true`; combine com `allowedModels` para restringir destinos. Erros de modelo indisponível tentam novamente uma vez com o modelo padrão da sessão; falhas de confiança ou allowlist não fazem fallback silenciosamente.
- política de fases e limites são detalhes de implementação (não chaves de configuração voltadas ao usuário).
- A configuração completa de memória fica em [Referência de configuração de memória](/pt-BR/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- Plugins de bundle Claude habilitados também podem contribuir padrões incorporados do Pi a partir de `settings.json`; o OpenClaw aplica isso como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw.
- `plugins.slots.memory`: escolha o id do Plugin de memória ativo, ou `"none"` para desativar Plugins de memória.
- `plugins.slots.contextEngine`: escolha o id do Plugin de mecanismo de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo.
- Plugins de pacote Claude ativados também podem contribuir padrões incorporados do Pi a partir de `settings.json`; o OpenClaw aplica esses valores como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw.
- `plugins.slots.memory`: escolhe o id do Plugin de memória ativo, ou `"none"` para desativar Plugins de memória.
- `plugins.slots.contextEngine`: escolhe o id do Plugin de mecanismo de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo.
Consulte [Plugins](/pt-BR/tools/plugin).
@ -232,10 +237,10 @@ Consulte [Plugins](/pt-BR/tools/plugin).
## Compromissos
`commitments` controla memória de acompanhamento inferida: o OpenClaw pode detectar check-ins a partir de turnos de conversa e entregá-los por execuções de heartbeat.
`commitments` controla memória inferida de acompanhamento: o OpenClaw pode detectar check-ins a partir de turnos de conversa e entregá-los por meio de execuções de Heartbeat.
- `commitments.enabled`: habilita extração LLM oculta, armazenamento e entrega por heartbeat para compromissos de acompanhamento inferidos. Padrão: `false`.
- `commitments.maxPerDay`: máximo de compromissos de acompanhamento inferidos entregues por sessão de agente em um dia contínuo. Padrão: `3`.
- `commitments.enabled`: ativa extração LLM oculta, armazenamento e entrega por Heartbeat de compromissos de acompanhamento inferidos. Padrão: `false`.
- `commitments.maxPerDay`: número máximo de compromissos de acompanhamento inferidos entregues por sessão de agente em um dia móvel. Padrão: `3`.
Consulte [Compromissos inferidos](/pt-BR/concepts/commitments).
@ -291,50 +296,50 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments).
- `tabCleanup` recupera abas rastreadas do agente principal após tempo ocioso ou quando uma
sessão excede seu limite. Defina `idleMinutes: 0` ou `maxTabsPerSession: 0` para
desativar esses modos individuais de limpeza.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, então a navegação do navegador permanece restrita por padrão.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, então a navegação do navegador permanece estrita por padrão.
- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` somente quando você confiar intencionalmente na navegação do navegador em rede privada.
- No modo restrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de acessibilidade/descoberta.
- No modo estrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) ficam sujeitos ao mesmo bloqueio de rede privada durante verificações de acessibilidade/descoberta.
- `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado.
- No modo restrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas.
- No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas.
- Perfis remotos são somente anexação (iniciar/parar/redefinir desativados).
- `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`.
Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S)
quando seu provedor fornecer uma URL WebSocket direta do DevTools.
quando seu provedor fornecer uma URL direta de DevTools WebSocket.
- `remoteCdpTimeoutMs` e `remoteCdpHandshakeTimeoutMs` se aplicam à acessibilidade CDP remota e
`attachOnly`, além de solicitações de abertura de abas. Perfis local loopback
gerenciados mantêm os padrões locais de CDP.
`attachOnly`, além de solicitações de abertura de abas. Perfis gerenciados por loopback
mantêm os padrões locais de CDP.
- Se um serviço CDP gerenciado externamente estiver acessível por loopback, defina
`attachOnly: true` nesse perfil; caso contrário, o OpenClaw trata a porta loopback como um
`attachOnly: true` nesse perfil; caso contrário, o OpenClaw trata a porta de loopback como um
perfil de navegador local gerenciado e pode relatar erros de propriedade de porta local.
- Perfis `existing-session` usam Chrome MCP em vez de CDP e podem se anexar no
- Perfis `existing-session` usam Chrome MCP em vez de CDP e podem anexar no
host selecionado ou por meio de um nó de navegador conectado.
- Perfis `existing-session` podem definir `userDataDir` para apontar para um perfil
- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil
específico de navegador baseado em Chromium, como Brave ou Edge.
- Perfis `existing-session` mantêm os limites atuais da rota Chrome MCP:
ações orientadas por snapshot/ref em vez de segmentação por seletor CSS, hooks de upload
de arquivo único, sem substituições de tempo limite de diálogo, sem `wait --load networkidle` e sem
`responsebody`, exportação PDF, interceptação de download ou ações em lote.
- Perfis `openclaw` locais gerenciados atribuem automaticamente `cdpPort` e `cdpUrl`; defina
ações orientadas por snapshot/ref em vez de direcionamento por seletor CSS, hooks de upload
de um arquivo, sem substituições de tempo limite de diálogo, sem `wait --load networkidle` e sem
`responsebody`, exportação de PDF, interceptação de downloads ou ações em lote.
- Perfis `openclaw` gerenciados localmente atribuem automaticamente `cdpPort` e `cdpUrl`; defina
`cdpUrl` explicitamente somente para CDP remoto.
- Perfis locais gerenciados podem definir `executablePath` para substituir o
`browser.executablePath` global desse perfil. Use isso para executar um perfil no
- Perfis gerenciados localmente podem definir `executablePath` para substituir o
`browser.executablePath` global para esse perfil. Use isso para executar um perfil no
Chrome e outro no Brave.
- Perfis locais gerenciados usam `browser.localLaunchTimeoutMs` para descoberta HTTP do Chrome CDP
após o início do processo e `browser.localCdpReadyTimeoutMs` para
- Perfis gerenciados localmente usam `browser.localLaunchTimeoutMs` para descoberta HTTP
CDP do Chrome após o início do processo e `browser.localCdpReadyTimeoutMs` para
prontidão do websocket CDP pós-inicialização. Aumente-os em hosts mais lentos nos quais o Chrome
inicia com sucesso, mas as verificações de prontidão disputam com a inicialização. Ambos os valores devem ser
inteiros positivos até `120000` ms; valores de configuração inválidos são rejeitados.
- Ordem de detecção automática: navegador padrão se baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
- `browser.executablePath` e `browser.profiles.<name>.executablePath` aceitam
`~` e `~/...` para o diretório inicial do seu SO antes da inicialização do Chromium.
`userDataDir` por perfil em perfis `existing-session` também passa por expansão de til.
`userDataDir` por perfil em perfis `existing-session` também tem til expandidos.
- Serviço de controle: somente loopback (porta derivada de `gateway.port`, padrão `18791`).
- `extraArgs` acrescenta flags extras de inicialização ao startup local do Chromium (por exemplo
- `extraArgs` acrescenta flags extras de inicialização à inicialização local do Chromium (por exemplo
`--disable-gpu`, dimensionamento de janela ou flags de depuração).
---
## Interface de usuário
## UI
```json5
{
@ -348,8 +353,8 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments).
}
```
- `seamColor`: cor de destaque para a moldura da interface do usuário do app nativo (matiz do balão do Modo de conversa etc.).
- `assistant`: substituição da identidade da Interface de controle. Usa como fallback a identidade do agente ativo.
- `seamColor`: cor de destaque para o chrome da UI do app nativo (tom do balão do Talk Mode etc.).
- `assistant`: substituição de identidade da Control UI. Recua para a identidade do agente ativo.
---
@ -427,52 +432,53 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments).
<Accordion title="Detalhes dos campos do Gateway">
- `mode`: `local` (executar o Gateway) ou `remote` (conectar-se ao Gateway remoto). O Gateway se recusa a iniciar a menos que seja `local`.
- `mode`: `local` (executar Gateway) ou `remote` (conectar a um Gateway remoto). O Gateway se recusa a iniciar a menos que seja `local`.
- `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (somente IP do Tailscale) ou `custom`.
- **Aliases legados de bind**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o Gateway fica inacessível. Use `--network host` ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces.
- **Auth**: exigida por padrão. Binds que não são loopback exigem autenticação do Gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade usando `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão.
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Os fluxos de inicialização e de instalação/reparo de serviço falham quando ambos estão configurados e o modo não foi definido.
- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações confiáveis de local loopback; isso não é oferecido intencionalmente pelos prompts de onboarding.
- `gateway.auth.mode: "trusted-proxy"`: delega a autenticação do navegador/usuário a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não loopback** por padrão; proxies reversos de loopback no mesmo host exigem `gateway.auth.trustedProxy.allowLoopback = true` explicitamente. Chamadores internos no mesmo host podem usar `gateway.auth.password` como fallback direto local; `gateway.auth.token` permanece mutuamente exclusivo com o modo trusted-proxy.
- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da UI de Controle/WebSocket (verificada via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação de cabeçalho do Tailscale; em vez disso, seguem o modo normal de autenticação HTTP do Gateway. Esse fluxo sem token assume que o host do Gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`.
- **Aliases de bind legados**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Observação sobre Docker**: o bind `loopback` padrão escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o Gateway fica inacessível. Use `--network host`, ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces.
- **Autenticação**: obrigatória por padrão. Binds que não sejam loopback exigem autenticação do Gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão.
- Se tanto `gateway.auth.token` quanto `gateway.auth.password` estiverem configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Fluxos de inicialização e de instalação/reparo de serviço falham quando ambos estão configurados e o modo não está definido.
- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use somente para configurações confiáveis de local loopback; isso é intencionalmente não oferecido pelos prompts de onboarding.
- `gateway.auth.mode: "trusted-proxy"`: delega a autenticação de navegador/usuário a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não loopback** por padrão; proxies reversos loopback no mesmo host exigem `gateway.auth.trustedProxy.allowLoopback = true` explícito. Chamadores internos no mesmo host podem usar `gateway.auth.password` como fallback direto local; `gateway.auth.token` permanece mutuamente exclusivo com o modo trusted-proxy.
- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificada via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; em vez disso, seguem o modo normal de autenticação HTTP do Gateway. Esse fluxo sem token pressupõe que o host do Gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: limitador opcional de falhas de autenticação. Aplica-se por IP de cliente e por escopo de autenticação (shared-secret e device-token são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`.
- No caminho assíncrono da UI de Controle do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Tentativas incorretas simultâneas do mesmo cliente podem, portanto, acionar o limitador na segunda solicitação, em vez de ambas passarem em corrida como simples incompatibilidades.
- `gateway.auth.rateLimit.exemptLoopback` tem `true` como padrão; defina `false` quando você quiser intencionalmente limitar também o tráfego de localhost (para configurações de teste ou implantações estritas de proxy).
- Tentativas de autenticação WS com origem em navegador são sempre limitadas, com isenção de loopback desativada (defesa em profundidade contra força bruta em localhost baseada em navegador).
- Em loopback, esses bloqueios com origem em navegador são isolados por valor
normalizado de `Origin`, então falhas repetidas de uma origem localhost não
bloqueiam automaticamente uma origem diferente.
- `tailscale.mode`: `serve` (somente tailnet, bind de loopback) ou `funnel` (público, exige autenticação).
- `controlUi.allowedOrigins`: allowlist explícita de origens de navegador para conexões WebSocket do Gateway. Exigida quando clientes de navegador são esperados de origens não loopback.
- `controlUi.chatMessageMaxWidth`: largura máxima opcional para mensagens de chat agrupadas da UI de Controle. Aceita valores de largura CSS restritos, como `960px`, `82%`, `min(1280px, 82%)` e `calc(100% - 2rem)`.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente de política de origem por cabeçalho Host.
- No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Portanto, tentativas inválidas simultâneas do mesmo cliente podem acionar o limitador na segunda solicitação, em vez de ambas passarem como simples incompatibilidades.
- `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando você quiser intencionalmente que o tráfego localhost também tenha limite de taxa (para configurações de teste ou implantações de proxy estritas).
- Tentativas de autenticação WS com origem em navegador sempre são limitadas, com isenção de loopback desabilitada (defesa em profundidade contra força bruta de localhost baseada em navegador).
- Em loopback, esses bloqueios com origem em navegador são isolados por valor de `Origin`
normalizado, então falhas repetidas de uma origem localhost não bloqueiam automaticamente
uma origem diferente.
- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, exige autenticação).
- `controlUi.allowedOrigins`: allowlist explícita de origens de navegador para conexões WebSocket do Gateway. Obrigatória quando clientes de navegador são esperados de origens que não sejam loopback.
- `controlUi.chatMessageMaxWidth`: largura máxima opcional para mensagens de chat agrupadas da Control UI. Aceita valores de largura CSS restritos, como `960px`, `82%`, `min(1280px, 82%)` e `calc(100% - 2rem)`.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente da política de origem por cabeçalho Host.
- `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição de emergência no ambiente do processo
do lado do cliente que permite `ws://` em texto claro para IPs confiáveis de rede privada;
o padrão continua sendo somente loopback para texto claro. Não há equivalente em
`openclaw.json`, e configurações de rede privada do navegador, como
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, não afetam clientes WebSocket do Gateway.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição emergencial do ambiente de processo
no lado do cliente que permite `ws://` em texto puro para IPs confiáveis de rede privada;
o padrão permanece somente loopback para texto puro. Não há equivalente em `openclaw.json`,
e configurações de rede privada do navegador, como
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, não afetam clientes WebSocket
do Gateway.
- `gateway.remote.token` / `.password` são campos de credenciais de cliente remoto. Eles não configuram a autenticação do Gateway por si só.
- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay externo de APNs usado por builds oficiais/TestFlight de iOS depois que publicam registros apoiados por relay no Gateway. Essa URL deve corresponder à URL do relay compilada no build de iOS.
- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds iOS oficiais/TestFlight depois que elas publicam registros com suporte a relay no Gateway. Essa URL deve corresponder à URL do relay compilada na build iOS.
- `gateway.push.apns.relay.timeoutMs`: timeout de envio do Gateway para o relay em milissegundos. O padrão é `10000`.
- Registros apoiados por relay são delegados a uma identidade específica do Gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha ao Gateway uma concessão de envio com escopo de registro. Outro Gateway não pode reutilizar esse registro armazenado.
- Registros com suporte a relay são delegados a uma identidade específica do Gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha ao Gateway uma concessão de envio com escopo de registro. Outro Gateway não pode reutilizar esse registro armazenado.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias de env para a configuração de relay acima.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch somente para desenvolvimento para URLs de relay HTTP em loopback. URLs de relay de produção devem permanecer em HTTPS.
- `gateway.handshakeTimeoutMs`: timeout de handshake WebSocket do Gateway antes da autenticação, em milissegundos. Padrão: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` tem precedência quando definido. Aumente isso em hosts carregados ou de baixa potência onde clientes locais conseguem conectar enquanto o aquecimento de inicialização ainda está estabilizando.
- `gateway.channelHealthCheckMinutes`: intervalo do monitor de integridade de canais em minutos. Defina `0` para desativar reinicializações do monitor de integridade globalmente. Padrão: `5`.
- `gateway.handshakeTimeoutMs`: timeout do handshake WebSocket pré-autenticação do Gateway em milissegundos. Padrão: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` tem precedência quando definido. Aumente isso em hosts carregados ou de baixa potência onde clientes locais conseguem conectar enquanto o aquecimento da inicialização ainda está estabilizando.
- `gateway.channelHealthCheckMinutes`: intervalo do monitor de integridade de canais em minutos. Defina `0` para desabilitar reinicializações do monitor de integridade globalmente. Padrão: `5`.
- `gateway.channelStaleEventThresholdMinutes`: limite de socket obsoleto em minutos. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`.
- `gateway.channelMaxRestartsPerHour`: máximo de reinicializações do monitor de integridade por canal/conta em uma hora móvel. Padrão: `10`.
- `channels.<provider>.healthMonitor.enabled`: opt-out por canal para reinicializações do monitor de integridade, mantendo o monitor global habilitado.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definida, tem precedência sobre a substituição no nível do canal.
- Caminhos de chamadas do Gateway local podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não estiver definido.
- Se `gateway.auth.token` / `gateway.auth.password` for configurado explicitamente via SecretRef e não for resolvido, a resolução falha de forma fechada (sem mascaramento por fallback remoto).
- `trustedProxies`: IPs de proxy reverso que encerram TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies que você controla. Entradas de loopback ainda são válidas para configurações de proxy/detecção local no mesmo host (por exemplo, Tailscale Serve ou um proxy reverso local), mas elas **não** tornam solicitações de loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: substituição por conta para canais multi-conta. Quando definido, tem precedência sobre a substituição em nível de canal.
- Caminhos de chamada do Gateway local podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não estiver definido.
- Se `gateway.auth.token` / `gateway.auth.password` for configurado explicitamente via SecretRef e não resolvido, a resolução falha fechada (sem mascaramento por fallback remoto).
- `trustedProxies`: IPs de proxy reverso que terminam TLS ou injetam cabeçalhos de cliente encaminhado. Liste somente proxies que você controla. Entradas loopback ainda são válidas para configurações de proxy/detecção local no mesmo host (por exemplo, Tailscale Serve ou um proxy reverso local), mas elas **não** tornam solicitações loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`.
- `allowRealIpFallback`: quando `true`, o Gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento fail-closed.
- `gateway.nodes.pairing.autoApproveCidrs`: allowlist CIDR/IP opcional para aprovar automaticamente o pareamento inicial de dispositivo de Node sem escopos solicitados. Fica desativada quando não definida. Isso não aprova automaticamente o pareamento de operador/navegador/UI de Controle/WebChat, e não aprova automaticamente upgrades de função, escopo, metadados ou chave pública.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: modelagem global de allow/deny para comandos de Node declarados após o pareamento e a avaliação da allowlist da plataforma. Use `allowCommands` para optar por comandos de Node perigosos, como `camera.snap`, `camera.clip` e `screen.record`; `denyCommands` remove um comando mesmo que um padrão da plataforma ou uma permissão explícita o incluísse de outra forma. Depois que um Node altera sua lista de comandos declarados, rejeite e aprove novamente esse pareamento de dispositivo para que o Gateway armazene o snapshot de comandos atualizado.
- `gateway.tools.deny`: nomes extras de ferramentas bloqueadas para HTTP `POST /tools/invoke` (estende a lista deny padrão).
- `gateway.nodes.pairing.autoApproveCidrs`: allowlist opcional de CIDR/IP para aprovar automaticamente o pareamento inicial de dispositivo de Node sem escopos solicitados. Fica desabilitada quando não definida. Isso não aprova automaticamente pareamento de operador/navegador/Control UI/WebChat, e não aprova automaticamente upgrades de função, escopo, metadados ou chave pública.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: modelagem global de allow/deny para comandos de Node declarados após pareamento e avaliação da allowlist da plataforma. Use `allowCommands` para optar por comandos perigosos de Node, como `camera.snap`, `camera.clip` e `screen.record`; `denyCommands` remove um comando mesmo que um padrão da plataforma ou allow explícito o incluísse de outra forma. Depois que um Node altera sua lista de comandos declarados, rejeite e reaprove o pareamento desse dispositivo para que o Gateway armazene o snapshot de comandos atualizado.
- `gateway.tools.deny`: nomes de ferramentas extras bloqueados para HTTP `POST /tools/invoke` (estende a lista deny padrão).
- `gateway.tools.allow`: remove nomes de ferramentas da lista deny HTTP padrão.
</Accordion>
@ -481,16 +487,16 @@ Consulte [Compromissos inferidos](/pt-BR/concepts/commitments).
- Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
- Endurecimento de entrada por URL de Responses:
- Endurecimento de entrada por URL em Responses:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
Allowlists vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false`
e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desativar a busca por URL.
- Cabeçalho opcional de endurecimento de resposta:
- `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS que você controla; veja [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts))
e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar a busca de URLs.
- Cabeçalho opcional de endurecimento da resposta:
- `gateway.http.securityHeaders.strictTransportSecurity` (defina somente para origens HTTPS que você controla; consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Isolamento de várias instâncias
### Isolamento multi-instância
Execute vários Gateways em um host com portas e diretórios de estado únicos:
@ -502,7 +508,7 @@ openclaw gateway --port 19001
Flags de conveniência: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile <name>` (usa `~/.openclaw-<name>`).
Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways).
Consulte [Vários Gateways](/pt-BR/gateway/multiple-gateways).
### `gateway.tls`
@ -520,11 +526,11 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways).
}
```
- `enabled`: habilita terminação TLS no listener do Gateway (HTTPS/WSS) (padrão: `false`).
- `autoGenerate`: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; somente para uso local/dev.
- `enabled`: habilita a terminação TLS no listener do Gateway (HTTPS/WSS) (padrão: `false`).
- `autoGenerate`: gera automaticamente um par de cert/key local autoassinado quando arquivos explícitos não estão configurados; somente para uso local/dev.
- `certPath`: caminho do sistema de arquivos para o arquivo de certificado TLS.
- `keyPath`: caminho do sistema de arquivos para o arquivo de chave privada TLS; mantenha permissões restritas.
- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança personalizadas.
- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança customizadas.
### `gateway.reload`
@ -540,17 +546,17 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways).
}
```
- `mode`: controla como edições de configuração são aplicadas em tempo de execução.
- `mode`: controla como edições de configuração são aplicadas em runtime.
- `"off"`: ignora edições ao vivo; alterações exigem uma reinicialização explícita.
- `"restart"`: sempre reinicia o processo do Gateway em alterações de configuração.
- `"hot"`: aplica alterações dentro do processo sem reiniciar.
- `"hybrid"` (padrão): tenta hot reload primeiro; recorre a reinicialização se necessário.
- `debounceMs`: janela de debounce em ms antes de as alterações de configuração serem aplicadas (inteiro não negativo).
- `deferralTimeoutMs`: tempo máximo opcional em ms para aguardar operações em andamento antes de forçar uma reinicialização. Omita para usar a espera limitada padrão (`300000`); defina `0` para aguardar indefinidamente e registrar avisos periódicos de ainda pendente.
- `"hot"`: aplica alterações no processo sem reiniciar.
- `"hybrid"` (padrão): tenta hot reload primeiro; recorre à reinicialização se necessário.
- `debounceMs`: janela de debounce em ms antes que alterações de configuração sejam aplicadas (inteiro não negativo).
- `deferralTimeoutMs`: tempo máximo opcional em ms para aguardar operações em andamento antes de forçar uma reinicialização. Omita para usar a espera limitada padrão (`300000`); defina `0` para aguardar indefinidamente e registrar avisos periódicos de pendências ainda existentes.
---
## Hooks
## Ganchos
```json5
{
@ -584,15 +590,15 @@ Veja [Vários Gateways](/pt-BR/gateway/multiple-gateways).
```
Autenticação: `Authorization: Bearer <token>` ou `x-openclaw-token: <token>`.
Tokens de hook na string de consulta são rejeitados.
Tokens de hook em string de consulta são rejeitados.
Notas de validação e segurança:
- `hooks.enabled=true` exige um `hooks.token` não vazio.
- `hooks.token` deve ser **distinto** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado.
- `hooks.token` deve ser **diferente** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado.
- `hooks.path` não pode ser `/`; use um subcaminho dedicado, como `/hooks`.
- Se `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por exemplo, `["hook:"]`).
- Se um mapeamento ou preset usa um `sessionKey` com template, defina `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Chaves de mapeamento estáticas não exigem essa opção explícita.
- Se um mapeamento ou preset usar um `sessionKey` com template, defina `hooks.allowedSessionKeyPrefixes` e `hooks.allowRequestSessionKey=true`. Chaves de mapeamento estáticas não exigem essa adesão explícita.
**Pontos de extremidade:**
@ -602,20 +608,20 @@ Notas de validação e segurança:
- `POST /hooks/<name>` → resolvido via `hooks.mappings`
- Valores de `sessionKey` de mapeamento renderizados por template são tratados como fornecidos externamente e também exigem `hooks.allowRequestSessionKey=true`.
<Accordion title="Mapping details">
<Accordion title="Detalhes do mapeamento">
- `match.path` corresponde ao subcaminho após `/hooks` (por exemplo, `/hooks/gmail` → `gmail`).
- `match.source` corresponde a um campo do payload para caminhos genéricos.
- Templates como `{{messages[0].subject}}` leem do payload.
- `transform` pode apontar para um módulo JS/TS que retorna uma ação de hook.
- `transform.module` deve ser um caminho relativo e permanece dentro de `hooks.transformsDir` (caminhos absolutos e travessia são rejeitados).
- Mantenha `hooks.transformsDir` em `~/.openclaw/hooks/transforms`; diretórios de Skills do workspace são rejeitados. Se `openclaw doctor` relatar esse caminho como inválido, mova o módulo de transformação para o diretório de transforms de hooks ou remova `hooks.transformsDir`.
- `agentId` roteia para um agente específico; IDs desconhecidos retornam ao padrão.
- Mantenha `hooks.transformsDir` em `~/.openclaw/hooks/transforms`; diretórios de Skills do workspace são rejeitados. Se `openclaw doctor` relatar esse caminho como inválido, mova o módulo de transformação para o diretório de transformações de hooks ou remova `hooks.transformsDir`.
- `agentId` roteia para um agente específico; IDs desconhecidos voltam para o padrão.
- `allowedAgentIds`: restringe o roteamento explícito (`*` ou omitido = permitir todos, `[]` = negar todos).
- `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente de hook sem `sessionKey` explícito.
- `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` e chaves de sessão de mapeamento baseadas em template definam `sessionKey` (padrão: `false`).
- `allowedSessionKeyPrefixes`: lista opcional de prefixos permitidos para valores explícitos de `sessionKey` (solicitação + mapeamento), por exemplo, `["hook:"]`. Ela se torna obrigatória quando qualquer mapeamento ou preset usa um `sessionKey` com template.
- `deliver: true` envia a resposta final para um canal; `channel` usa `last` por padrão.
- `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` e chaves de sessão de mapeamento orientadas por template definam `sessionKey` (padrão: `false`).
- `allowedSessionKeyPrefixes`: lista de permissões opcional de prefixos para valores explícitos de `sessionKey` (solicitação + mapeamento), por exemplo `["hook:"]`. Ela se torna obrigatória quando qualquer mapeamento ou preset usa um `sessionKey` com template.
- `deliver: true` envia a resposta final para um canal; `channel` usa `last` como padrão.
- `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido).
</Accordion>
@ -623,8 +629,8 @@ Notas de validação e segurança:
### Integração com Gmail
- O preset integrado do Gmail usa `sessionKey: "hook:gmail:{{messages[0].id}}"`.
- Se você mantiver esse roteamento por mensagem, defina `hooks.allowRequestSessionKey: true` e restrinja `hooks.allowedSessionKeyPrefixes` para corresponder ao namespace do Gmail, por exemplo, `["hook:", "hook:gmail:"]`.
- Se precisar de `hooks.allowRequestSessionKey: false`, substitua o preset por um `sessionKey` estático em vez do padrão com template.
- Se você mantiver esse roteamento por mensagem, defina `hooks.allowRequestSessionKey: true` e restrinja `hooks.allowedSessionKeyPrefixes` para corresponder ao namespace do Gmail, por exemplo `["hook:", "hook:gmail:"]`.
- Se você precisar de `hooks.allowRequestSessionKey: false`, substitua o preset por um `sessionKey` estático em vez do padrão com template.
```json5
{
@ -652,7 +658,7 @@ Notas de validação e segurança:
---
## Host de canvas
## Host do canvas
```json5
{
@ -664,12 +670,12 @@ Notas de validação e segurança:
}
```
- Serve HTML/CSS/JS editáveis por agentes e A2UI via HTTP sob a porta do Gateway:
- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP na porta do Gateway:
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- Somente local: mantenha `gateway.bind: "loopback"` (padrão).
- Binds sem loopback: rotas de canvas exigem autenticação do Gateway (token/senha/proxy confiável), igual a outras superfícies HTTP do Gateway.
- WebViews do Node normalmente não enviam cabeçalhos de autenticação; depois que um nó é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo do nó para acesso a canvas/A2UI.
- Vínculos que não são loopback: rotas de canvas exigem autenticação do Gateway (token/senha/proxy confiável), igual a outras superfícies HTTP do Gateway.
- WebViews de Node normalmente não enviam cabeçalhos de autenticação; depois que um nó é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo de nó para acesso ao canvas/A2UI.
- URLs de capacidade são vinculadas à sessão WS ativa do nó e expiram rapidamente. Fallback baseado em IP não é usado.
- Injeta cliente de recarregamento ao vivo no HTML servido.
- Cria automaticamente um `index.html` inicial quando vazio.
@ -693,11 +699,11 @@ Notas de validação e segurança:
}
```
- `minimal` (padrão quando o Plugin `bonjour` integrado está habilitado): omite `cliPath` + `sshPort` dos registros TXT.
- `full`: inclui `cliPath` + `sshPort`; a publicidade multicast em LAN ainda exige que o Plugin `bonjour` integrado esteja habilitado.
- `off`: suprime a publicidade multicast em LAN sem alterar a habilitação do Plugin.
- O Plugin `bonjour` integrado inicia automaticamente em hosts macOS e é opcional em implantações do Gateway em Linux, Windows e containers.
- O hostname usa por padrão o hostname do sistema quando ele é um rótulo DNS válido, com fallback para `openclaw`. Substitua com `OPENCLAW_MDNS_HOSTNAME`.
- `minimal` (padrão quando o Plugin `bonjour` empacotado está habilitado): omite `cliPath` + `sshPort` dos registros TXT.
- `full`: inclui `cliPath` + `sshPort`; a divulgação multicast em LAN ainda exige que o Plugin `bonjour` empacotado esteja habilitado.
- `off`: suprime a divulgação multicast em LAN sem alterar a habilitação do Plugin.
- O Plugin `bonjour` empacotado inicia automaticamente em hosts macOS e é opcional no Linux, Windows e em implantações de Gateway em contêiner.
- O nome do host usa como padrão o nome de host do sistema quando ele é um rótulo DNS válido, recorrendo a `openclaw` caso contrário. Substitua com `OPENCLAW_MDNS_HOSTNAME`.
### Área ampla (DNS-SD)
@ -734,8 +740,8 @@ Configuração: `openclaw dns setup --apply`.
}
```
- Variáveis de ambiente inline são aplicadas somente se a variável de ambiente do processo não tiver a chave.
- Arquivos `.env`: `.env` no CWD + `~/.openclaw/.env` (nenhum deles substitui variáveis existentes).
- Variáveis de ambiente inline só são aplicadas se a variável de ambiente do processo não tiver a chave.
- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes).
- `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login.
- Consulte [Ambiente](/pt-BR/help/environment) para a precedência completa.
@ -751,8 +757,8 @@ Referencie variáveis de ambiente em qualquer string de configuração com `${VA
}
```
- Somente nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*`.
- Variáveis ausentes/vazias geram um erro ao carregar a configuração.
- Apenas nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*`.
- Variáveis ausentes/vazias geram um erro no carregamento da configuração.
- Escape com `$${VAR}` para um `${VAR}` literal.
- Funciona com `$include`.
@ -760,7 +766,7 @@ Referencie variáveis de ambiente em qualquer string de configuração com `${VA
## Segredos
Referências de segredo são aditivas: valores em texto simples ainda funcionam.
Refs de segredo são aditivas: valores em texto claro ainda funcionam.
### `SecretRef`
@ -772,19 +778,19 @@ Use um formato de objeto:
Validação:
- Padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$`
- Padrão de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
- id para `source: "file"`: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`)
- Padrão de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- ids de `source: "exec"` não devem conter segmentos de caminho delimitados por barras `.` ou `..` (por exemplo, `a/../b` é rejeitado)
- padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$`
- padrão de id de `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
- id de `source: "file"`: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`)
- padrão de id de `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- ids de `source: "exec"` não podem conter segmentos de caminho delimitados por barras `.` ou `..` (por exemplo, `a/../b` é rejeitado)
### Superfície de credenciais compatível
- Matriz canônica: [Superfície de Credenciais SecretRef](/pt-BR/reference/secretref-credential-surface)
- `secrets apply` direciona caminhos de credenciais compatíveis em `openclaw.json`.
- Referências de `auth-profiles.json` são incluídas na resolução em tempo de execução e na cobertura de auditoria.
- Matriz canônica: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface)
- `secrets apply` mira caminhos de credenciais compatíveis em `openclaw.json`.
- Refs de `auth-profiles.json` são incluídas na resolução em tempo de execução e na cobertura de auditoria.
### Configuração de provedores de segredos
### Configuração de provedores de segredo
```json5
{
@ -814,14 +820,14 @@ Validação:
Observações:
- O provedor `file` oferece suporte a `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue).
- Caminhos dos provedores file e exec falham em modo fechado quando a verificação de ACL do Windows não está disponível. Defina `allowInsecurePath: true` somente para caminhos confiáveis que não possam ser verificados.
- O provedor `file` é compatível com `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue).
- Caminhos de provedores file e exec falham fechados quando a verificação de ACL do Windows não está disponível. Defina `allowInsecurePath: true` apenas para caminhos confiáveis que não podem ser verificados.
- O provedor `exec` exige um caminho absoluto de `command` e usa payloads de protocolo em stdin/stdout.
- Por padrão, caminhos de comando por symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos por symlink enquanto valida o caminho de destino resolvido.
- Por padrão, caminhos de comando com symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos com symlink enquanto valida o caminho de destino resolvido.
- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho de destino resolvido.
- O ambiente filho de `exec` é mínimo por padrão; passe variáveis necessárias explicitamente com `passEnv`.
- Referências de segredo são resolvidas no momento da ativação em um snapshot em memória; depois, os caminhos de solicitação leem somente o snapshot.
- A filtragem de superfície ativa se aplica durante a ativação: referências não resolvidas em superfícies habilitadas fazem a inicialização/recarga falhar, enquanto superfícies inativas são ignoradas com diagnósticos.
- O ambiente filho de `exec` é mínimo por padrão; passe as variáveis necessárias explicitamente com `passEnv`.
- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória; depois, os caminhos de requisição leem apenas o snapshot.
- A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/recarregamento falhar, enquanto superfícies inativas são ignoradas com diagnósticos.
---
@ -844,13 +850,13 @@ Observações:
```
- Perfis por agente são armazenados em `<agentDir>/auth-profiles.json`.
- `auth-profiles.json` oferece suporte a referências no nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credenciais estáticas.
- Mapas simples legados de `auth-profiles.json`, como `{ "provider": { "apiKey": "..." } }`, não são um formato de tempo de execução; `openclaw doctor --fix` os reescreve para perfis canônicos de chave de API `provider:default` com um backup `.legacy-flat.*.bak`.
- Perfis no modo OAuth (`auth.profiles.<id>.mode = "oauth"`) não oferecem suporte a credenciais de perfil de autenticação baseadas em SecretRef.
- Credenciais estáticas de tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando descobertas.
- `auth-profiles.json` é compatível com refs em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática.
- Mapas planos legados de `auth-profiles.json`, como `{ "provider": { "apiKey": "..." } }`, não são um formato de tempo de execução; `openclaw doctor --fix` os reescreve para perfis de chave de API canônicos `provider:default` com um backup `.legacy-flat.*.bak`.
- Perfis em modo OAuth (`auth.profiles.<id>.mode = "oauth"`) não são compatíveis com credenciais de perfil de autenticação baseadas em SecretRef.
- Credenciais estáticas em tempo de execução vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando descobertas.
- Importações OAuth legadas vêm de `~/.openclaw/credentials/oauth.json`.
- Consulte [OAuth](/pt-BR/concepts/oauth).
- Comportamento em tempo de execução de segredos e ferramentas `audit/configure/apply`: [Gerenciamento de Segredos](/pt-BR/gateway/secrets).
- Comportamento de segredos em tempo de execução e ferramentas `audit/configure/apply`: [Gerenciamento de segredos](/pt-BR/gateway/secrets).
### `auth.cooldowns`
@ -872,19 +878,19 @@ Observações:
}
```
- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a erros reais de cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode chegar aqui mesmo em respostas `401`/`403`, mas os correspondentes de texto específicos de provedor permanecem restritos ao provedor que os possui (por exemplo, OpenRouter `Key limit exceeded`). Mensagens retentáveis de HTTP `402` de janela de uso ou limite de gastos de organização/workspace permanecem no caminho `rate_limit`.
- `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de cobrança.
- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de cobrança (padrão: `24`).
- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a erros reais de faturamento/crédito insuficiente (padrão: `5`). Texto explícito de faturamento ainda pode cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto específicas do provedor permanecem limitadas ao provedor que as possui (por exemplo, OpenRouter `Key limit exceeded`). Mensagens HTTP `402` repetíveis de janela de uso ou limite de gastos de organização/workspace permanecem no caminho `rate_limit`.
- `billingBackoffHoursByProvider`: substituições opcionais por provedor para as horas de backoff de faturamento.
- `billingMaxHours`: limite em horas para o crescimento exponencial do backoff de faturamento (padrão: `24`).
- `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`).
- `authPermanentMaxMinutes`: limite em minutos para o crescimento do backoff de `auth_permanent` (padrão: `60`).
- `authPermanentMaxMinutes`: limite em minutos para o crescimento do backoff `auth_permanent` (padrão: `60`).
- `failureWindowHours`: janela móvel em horas usada para contadores de backoff (padrão: `24`).
- `overloadedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de sobrecarga antes de alternar para o fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, chegam aqui.
- `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`).
- `rateLimitedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de limite de taxa antes de alternar para o fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui textos no formato do provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`.
- `overloadedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de sobrecarga antes de alternar para o fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, caem aqui.
- `overloadedBackoffMs`: atraso fixo antes de repetir uma rotação de provedor/perfil sobrecarregado (padrão: `0`).
- `rateLimitedProfileRotations`: máximo de rotações de perfis de autenticação do mesmo provedor para erros de limite de taxa antes de alternar para o fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto no formato do provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`.
---
## Registro em log
## Registro em logs
```json5
{
@ -902,8 +908,8 @@ Observações:
- Arquivo de log padrão: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
- Defina `logging.file` para um caminho estável.
- `consoleLevel` sobe para `debug` quando `--verbose`.
- `maxFileBytes`: tamanho máximo do arquivo de log ativo em bytes antes da rotação (inteiro positivo; padrão: `104857600` = 100 MB). O OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo.
- `redactSensitive` / `redactPatterns`: mascaramento de melhor esforço para saída do console, logs de arquivo, registros de log OTLP e texto persistido de transcrição da sessão. `redactSensitive: "off"` desativa apenas essa política geral de log/transcrição; superfícies de segurança de UI/ferramenta/diagnóstico ainda redigem segredos antes da emissão.
- `maxFileBytes`: tamanho máximo do arquivo de log ativo em bytes antes da rotação (inteiro positivo; padrão: `104857600` = 100 MB). OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo.
- `redactSensitive` / `redactPatterns`: mascaramento de melhor esforço para saída do console, logs de arquivo, registros de log OTLP e texto persistido de transcrição de sessão. `redactSensitive: "off"` desativa apenas esta política geral de logs/transcrições; superfícies de segurança de UI/ferramentas/diagnóstico ainda redigem segredos antes da emissão.
---
@ -952,22 +958,22 @@ Observações:
```
- `enabled`: alternância principal para saída de instrumentação (padrão: `true`).
- `flags`: array de strings de flags que habilitam saída de log direcionada (aceita curingas como `"telegram.*"` ou `"*"`).
- `stuckSessionWarnMs`: limite de idade sem progresso em ms para classificar sessões de processamento de longa duração como `session.long_running`, `session.stalled` ou `session.stuck`. Resposta, ferramenta, status, bloco e progresso de ACP reiniciam o temporizador; diagnósticos `session.stuck` repetidos recuam enquanto não houver alterações.
- `otel.enabled`: habilita o pipeline de exportação do OpenTelemetry (padrão: `false`). Para a configuração completa, catálogo de sinais e modelo de privacidade, consulte [exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry).
- `flags`: array de strings de flags que ativam saída de log direcionada (aceita curingas como `"telegram.*"` ou `"*"`).
- `stuckSessionWarnMs`: limite de idade sem progresso em ms para classificar sessões de processamento de longa duração como `session.long_running`, `session.stalled` ou `session.stuck`. Resposta, ferramenta, status, bloco e progresso ACP reiniciam o temporizador; diagnósticos `session.stuck` repetidos recuam enquanto não houver mudanças.
- `otel.enabled`: ativa o pipeline de exportação OpenTelemetry (padrão: `false`). Para a configuração completa, o catálogo de sinais e o modelo de privacidade, consulte [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry).
- `otel.endpoint`: URL do coletor para exportação OTel.
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: endpoints OTLP opcionais específicos por sinal. Quando definidos, substituem `otel.endpoint` apenas para esse sinal.
- `otel.protocol`: `"http/protobuf"` (padrão) ou `"grpc"`.
- `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com solicitações de exportação OTel.
- `otel.serviceName`: nome do serviço para atributos de recurso.
- `otel.traces` / `otel.metrics` / `otel.logs`: habilitam exportação de traces, métricas ou logs.
- `otel.sampleRate`: taxa de amostragem de trace `0`–`1`.
- `otel.traces` / `otel.metrics` / `otel.logs`: ativa exportação de traces, métricas ou logs.
- `otel.sampleRate`: taxa de amostragem de traces de `0` a `1`.
- `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms.
- `otel.captureContent`: captura opcional de conteúdo bruto para atributos de span OTEL. O padrão é desativado. O booleano `true` captura conteúdo de mensagem/ferramenta que não seja do sistema; o formato de objeto permite habilitar `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` e `systemPrompt` explicitamente.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: alternância de ambiente para os atributos experimentais mais recentes de provedor de span GenAI. Por padrão, spans mantêm o atributo legado `gen_ai.system` para compatibilidade; métricas GenAI usam atributos semânticos limitados.
- `OPENCLAW_OTEL_PRELOADED=1`: alternância de ambiente para hosts que já registraram um SDK global do OpenTelemetry. Então o OpenClaw ignora a inicialização/desligamento do SDK pertencente ao Plugin, mantendo os listeners de diagnóstico ativos.
- `otel.captureContent`: captura opcional explícita de conteúdo bruto para atributos de spans OTEL. O padrão é desativado. O booleano `true` captura conteúdo não sistêmico de mensagens/ferramentas; a forma de objeto permite ativar `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` e `systemPrompt` explicitamente.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: alternância de ambiente para os atributos experimentais mais recentes de provedor de spans GenAI. Por padrão, spans mantêm o atributo legado `gen_ai.system` para compatibilidade; métricas GenAI usam atributos semânticos limitados.
- `OPENCLAW_OTEL_PRELOADED=1`: alternância de ambiente para hosts que já registraram um SDK OpenTelemetry global. O OpenClaw então ignora a inicialização/desligamento do SDK pertencente ao Plugin, mantendo os listeners de diagnóstico ativos.
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` e `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: variáveis de ambiente de endpoint específicas por sinal usadas quando a chave de configuração correspondente não está definida.
- `cacheTrace.enabled`: registra snapshots de trace de cache para execuções embutidas (padrão: `false`).
- `cacheTrace.enabled`: registra snapshots de trace de cache para execuções incorporadas (padrão: `false`).
- `cacheTrace.filePath`: caminho de saída para JSONL de trace de cache (padrão: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de trace de cache (todos padrão: `true`).
@ -991,12 +997,12 @@ Observações:
}
```
- `channel`: canal de lançamento para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`.
- `checkOnStart`: verifica atualizações npm quando o gateway inicia (padrão: `true`).
- `auto.enabled`: habilita atualização automática em segundo plano para instalações de pacote (padrão: `false`).
- `channel`: canal de release para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`.
- `checkOnStart`: verifica atualizações do npm quando o gateway inicia (padrão: `true`).
- `auto.enabled`: ativa atualização automática em segundo plano para instalações de pacote (padrão: `false`).
- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máx.: `168`).
- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máx.: `168`).
- `auto.betaCheckIntervalHours`: frequência em horas das verificações do canal beta (padrão: `1`; máx.: `24`).
- `auto.stableJitterHours`: janela extra em horas para espalhamento de rollout no canal estável (padrão: `12`; máx.: `168`).
- `auto.betaCheckIntervalHours`: frequência, em horas, das verificações do canal beta (padrão: `1`; máx.: `24`).
---
@ -1029,23 +1035,23 @@ Observações:
}
```
- `enabled`: gate global do recurso ACP (padrão: `true`; defina `false` para ocultar envio ACP e affordances de spawn).
- `dispatch.enabled`: gate independente para envio de turnos de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução.
- `enabled`: gate global do recurso ACP (padrão: `true`; defina como `false` para ocultar dispatch ACP e affordances de spawn).
- `dispatch.enabled`: gate independente para dispatch de turnos de sessão ACP (padrão: `true`). Defina como `false` para manter comandos ACP disponíveis enquanto bloqueia a execução.
- `backend`: id padrão do backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado).
Instale primeiro o Plugin de backend e, se `plugins.allow` estiver definido, inclua o id do Plugin de backend (por exemplo, `acpx`) ou o backend ACP não será carregado.
- `defaultAgent`: id do agente de destino ACP de fallback quando spawns não especificam um destino explícito.
- `allowedAgents`: lista de permissões de ids de agentes permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional.
Instale o Plugin de backend primeiro e, se `plugins.allow` estiver definido, inclua o id do Plugin de backend (por exemplo, `acpx`) ou o backend ACP não será carregado.
- `defaultAgent`: id do agente ACP de fallback quando spawns não especificam um destino explícito.
- `allowedAgents`: allowlist de ids de agentes permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional.
- `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente.
- `stream.coalesceIdleMs`: janela de flush ociosa em ms para texto transmitido.
- `stream.maxChunkChars`: tamanho máximo do chunk antes de dividir a projeção de bloco transmitida.
- `stream.coalesceIdleMs`: janela de flush ocioso em ms para texto transmitido por stream.
- `stream.maxChunkChars`: tamanho máximo de chunk antes de dividir a projeção do bloco transmitido por stream.
- `stream.repeatSuppression`: suprime linhas repetidas de status/ferramenta por turno (padrão: `true`).
- `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` armazena em buffer até eventos terminais do turno.
- `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`).
- `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos de ferramenta ocultos (padrão: `"paragraph"`).
- `stream.maxOutputChars`: máximo de caracteres de saída do assistente projetados por turno ACP.
- `stream.maxSessionUpdateChars`: máximo de caracteres para linhas projetadas de status/atualização ACP.
- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos.
- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de serem elegíveis para limpeza.
- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP.
- `stream.maxSessionUpdateChars`: máximo de caracteres para linhas de status/atualização ACP projetadas.
- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos por stream.
- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de se tornarem elegíveis para limpeza.
- `runtime.installCommand`: comando de instalação opcional a executar ao inicializar um ambiente de runtime ACP.
---
@ -1064,14 +1070,14 @@ Observações:
- `cli.banner.taglineMode` controla o estilo da tagline do banner:
- `"random"` (padrão): taglines engraçadas/sazonais rotativas.
- `"default"`: tagline neutra fixa (`All your chats, one OpenClaw.`).
- `"off"`: sem texto de tagline (título/versão do banner ainda são exibidos).
- `"off"`: sem texto de tagline (título/versão do banner ainda exibidos).
- Para ocultar o banner inteiro (não apenas as taglines), defina a env `OPENCLAW_HIDE_BANNER=1`.
---
## Assistente
Metadados gravados por fluxos de configuração guiada da CLI (`onboard`, `configure`, `doctor`):
Metadados escritos por fluxos de configuração guiada da CLI (`onboard`, `configure`, `doctor`):
```json5
{
@ -1089,15 +1095,15 @@ Metadados gravados por fluxos de configuração guiada da CLI (`onboard`, `confi
## Identidade
Consulte os campos de identidade de `agents.list` em [Padrões de agente](/pt-BR/gateway/config-agents#agent-defaults).
Consulte os campos de identidade `agents.list` em [Padrões de agente](/pt-BR/gateway/config-agents#agent-defaults).
---
## Bridge (legado, removido)
## Ponte (legada, removida)
As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. As chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até que sejam removidas; `openclaw doctor --fix` pode remover chaves desconhecidas).
As builds atuais não incluem mais a ponte TCP. Nodes se conectam pelo WebSocket do Gateway. Chaves `bridge.*` não fazem mais parte do esquema de configuração (a validação falha até serem removidas; `openclaw doctor --fix` pode remover chaves desconhecidas).
<Accordion title="Configuração legada da bridge (referência histórica)">
<Accordion title="Legacy bridge config (historical reference)">
```json
{
@ -1135,11 +1141,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke
}
```
- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições cron arquivadas e excluídas. Padrão: `24h`; defina `false` para desativar.
- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções Cron isoladas antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas de Cron excluídas. Padrão: `24h`; defina como `false` para desativar.
- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/<jobId>.jsonl`) antes da remoção. Padrão: `2_000_000` bytes.
- `runLog.keepLines`: linhas mais recentes retidas quando a remoção de logs de execução é acionada. Padrão: `2000`.
- `webhookToken`: token bearer usado para entrega POST de webhook cron (`delivery.mode = "webhook"`), se omitido nenhum cabeçalho de autenticação é enviado.
- `webhook`: URL legada de fallback de Webhook (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`.
- `runLog.keepLines`: linhas mais recentes retidas quando a remoção do log de execução é acionada. Padrão: `2000`.
- `webhookToken`: token bearer usado para entrega POST do Webhook do Cron (`delivery.mode = "webhook"`), se omitido nenhum cabeçalho de auth será enviado.
- `webhook`: URL legada obsoleta de Webhook de fallback (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`.
### `cron.retry`
@ -1155,11 +1161,11 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke
}
```
- `maxAttempts`: máximo de novas tentativas para tarefas de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`).
- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de repetição (padrão: `[30000, 60000, 300000]`; 1–10 entradas).
- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para repetir todos os tipos transitórios.
- `maxAttempts`: máximo de novas tentativas para trabalhos de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`).
- `backoffMs`: array de atrasos de recuo em ms para cada tentativa de repetição (padrão: `[30000, 60000, 300000]`; 1–10 entradas).
- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente todos os tipos transitórios.
Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam tratamento de falhas separado.
Aplica-se somente a trabalhos Cron de execução única. Trabalhos recorrentes usam tratamento de falhas separado.
### `cron.failureAlert`
@ -1178,12 +1184,12 @@ Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam
}
```
- `enabled`: habilita alertas de falha para tarefas Cron (padrão: `false`).
- `enabled`: habilita alertas de falha para trabalhos Cron (padrão: `false`).
- `after`: falhas consecutivas antes de um alerta ser disparado (inteiro positivo, mín.: `1`).
- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para a mesma tarefa (inteiro não negativo).
- `includeSkipped`: contabiliza execuções ignoradas consecutivas para o limite de alerta (padrão: `false`). Execuções ignoradas são rastreadas separadamente e não afetam o backoff de erros de execução.
- `mode`: modo de entrega — `"announce"` envia por meio de uma mensagem de canal; `"webhook"` publica no Webhook configurado.
- `accountId`: ID opcional de conta ou canal para delimitar a entrega de alertas.
- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para o mesmo trabalho (inteiro não negativo).
- `includeSkipped`: conta execuções ignoradas consecutivas para o limite de alerta (padrão: `false`). Execuções ignoradas são rastreadas separadamente e não afetam o recuo de erros de execução.
- `mode`: modo de entrega — `"announce"` envia por uma mensagem de canal; `"webhook"` publica no Webhook configurado.
- `accountId`: conta ou ID de canal opcional para limitar o escopo da entrega do alerta.
### `cron.failureDestination`
@ -1200,22 +1206,22 @@ Aplica-se somente a tarefas Cron de execução única. Tarefas recorrentes usam
}
```
- Destino padrão para notificações de falha do Cron em todas as tarefas.
- Destino padrão para notificações de falha de Cron em todos os trabalhos.
- `mode`: `"announce"` ou `"webhook"`; usa `"announce"` como padrão quando existem dados de destino suficientes.
- `channel`: substituição de canal para entrega por anúncio. `"last"` reutiliza o último canal de entrega conhecido.
- `to`: destino de anúncio explícito ou URL de Webhook. Obrigatório no modo Webhook.
- `to`: destino explícito de anúncio ou URL de Webhook. Obrigatório para o modo Webhook.
- `accountId`: substituição opcional de conta para entrega.
- `delivery.failureDestination` por tarefa substitui esse padrão global.
- Quando nem o destino de falha global nem o por tarefa está definido, tarefas que já entregam via `announce` recorrem a esse destino principal de anúncio em caso de falha.
- `delivery.failureDestination` só é compatível com tarefas `sessionTarget="isolated"`, a menos que o `delivery.mode` principal da tarefa seja `"webhook"`.
- `delivery.failureDestination` por trabalho substitui esse padrão global.
- Quando nenhum destino de falha global ou por trabalho está definido, trabalhos que já entregam via `announce` usam esse destino principal de anúncio como fallback em caso de falha.
- `delivery.failureDestination` só é compatível com trabalhos `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do trabalho seja `"webhook"`.
Veja [Tarefas Cron](/pt-BR/automation/cron-jobs). Execuções Cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks).
Consulte [Trabalhos Cron](/pt-BR/automation/cron-jobs). Execuções Cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks).
---
## Variáveis de modelo para template de mídia
## Variáveis de modelo de mídia
Espaços reservados de modelo expandidos em `tools.media.models[].args`:
Placeholders de modelo expandidos em `tools.media.models[].args`:
| Variável | Descrição |
| ------------------ | ------------------------------------------------- |
@ -1223,26 +1229,26 @@ Espaços reservados de modelo expandidos em `tools.media.models[].args`:
| `{{RawBody}}` | Corpo bruto (sem wrappers de histórico/remetente) |
| `{{BodyStripped}}` | Corpo com menções de grupo removidas |
| `{{From}}` | Identificador do remetente |
| `{{To}}` | Identificador do destino |
| `{{To}}` | Identificador de destino |
| `{{MessageSid}}` | ID da mensagem do canal |
| `{{SessionId}}` | UUID da sessão atual |
| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada |
| `{{MediaUrl}}` | Pseudo-URL da mídia recebida |
| `{{MediaPath}}` | Caminho local da mídia |
| `{{MediaType}}` | Tipo de mídia (imagem/áudio/documento/…) |
| `{{Transcript}}` | Transcrição do áudio |
| `{{Transcript}}` | Transcrição de áudio |
| `{{Prompt}}` | Prompt de mídia resolvido para entradas da CLI |
| `{{MaxChars}}` | Máximo resolvido de caracteres de saída para entradas da CLI |
| `{{MaxChars}}` | Máximo de caracteres de saída resolvido para entradas da CLI |
| `{{ChatType}}` | `"direct"` ou `"group"` |
| `{{GroupSubject}}` | Assunto do grupo (melhor esforço) |
| `{{GroupMembers}}` | Prévia dos membros do grupo (melhor esforço) |
| `{{SenderName}}` | Nome de exibição do remetente (melhor esforço) |
| `{{SenderE164}}` | Número de telefone do remetente (melhor esforço) |
| `{{Provider}}` | Dica de provedor (whatsapp, telegram, discord, etc.) |
| `{{Provider}}` | Dica do provedor (whatsapp, telegram, discord, etc.) |
---
## Inclusões de configuração (`$include`)
## Includes de configuração (`$include`)
Divida a configuração em vários arquivos:
@ -1260,17 +1266,17 @@ Divida a configuração em vários arquivos:
**Comportamento de mesclagem:**
- Arquivo único: substitui o objeto que o contém.
- Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores).
- Chaves irmãs: mescladas após as inclusões (substituem valores incluídos).
- Inclusões aninhadas: até 10 níveis de profundidade.
- Caminhos: resolvidos em relação ao arquivo que faz a inclusão, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda resolvem dentro desse limite.
- Gravações de propriedade do OpenClaw que alteram apenas uma seção de nível superior apoiada por uma inclusão de arquivo único gravam nesse arquivo incluído. Por exemplo, `plugins install` atualiza `plugins: { $include: "./plugins.json5" }` em `plugins.json5` e deixa `openclaw.json` intacto.
- Inclusões raiz, arrays de inclusão e inclusões com substituições por chaves irmãs são somente leitura para gravações de propriedade do OpenClaw; essas gravações falham de forma fechada em vez de achatar a configuração.
- Erros: mensagens claras para arquivos ausentes, erros de análise e inclusões circulares.
- Array de arquivos: mesclados profundamente em ordem (posteriores substituem anteriores).
- Chaves irmãs: mescladas após includes (substituem valores incluídos).
- Includes aninhados: até 10 níveis de profundidade.
- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas somente quando ainda resolvem dentro desse limite.
- Escritas de propriedade do OpenClaw que alteram apenas uma seção de nível superior respaldada por um include de arquivo único escrevem nesse arquivo incluído. Por exemplo, `plugins install` atualiza `plugins: { $include: "./plugins.json5" }` em `plugins.json5` e deixa `openclaw.json` intacto.
- Includes raiz, arrays de include e includes com substituições irmãs são somente leitura para escritas de propriedade do OpenClaw; essas escritas falham de forma fechada em vez de achatar a configuração.
- Erros: mensagens claras para arquivos ausentes, erros de análise e includes circulares.
---
_Relacionado: [Configuração](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_
_Relacionado: [Configuração](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Diagnóstico](/pt-BR/gateway/doctor)_
## Relacionado

115
docs/pt-BR/gateway/diagnostics.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Preparando um relatório de bug ou solicitação de suporte
- Depuração de falhas, reinicializações, pressão de memória ou cargas úteis excessivamente grandes do Gateway
- Revisando quais dados de diagnóstico são registrados ou ocultados
summary: Criar pacotes de diagnóstico do Gateway compartilháveis para relatórios de bugs
- Preparando um relatório de bug ou uma solicitação de suporte
- Depuração de falhas do Gateway, reinicializações, pressão de memória ou cargas úteis superdimensionadas
- Analisando quais dados de diagnóstico são registrados ou ocultados
summary: Crie pacotes de diagnóstico do Gateway compartilháveis para relatórios de bugs
title: Exportação de diagnósticos
x-i18n:
generated_at: "2026-05-03T21:32:00Z"
generated_at: "2026-05-05T01:46:16Z"
model: gpt-5.5
provider: openai
source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b
source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382
source_path: gateway/diagnostics.md
workflow: 16
---
O OpenClaw pode criar um zip de diagnósticos local para relatórios de bugs. Ele combina
status, integridade, logs, formato de configuração e eventos recentes de estabilidade
sem payload do Gateway, com sanitização.
status, integridade, logs, formato da configuração e eventos recentes de estabilidade
sem payload do Gateway, todos sanitizados.
Trate pacotes de diagnósticos como segredos até revisá-los. Eles são
projetados para omitir ou redigir payloads e credenciais, mas ainda resumem
logs locais do Gateway e estado de runtime no nível do host.
Trate pacotes de diagnósticos como segredos até revisá-los. Eles são projetados
para omitir ou redigir payloads e credenciais, mas ainda resumem logs locais do
Gateway e o estado de runtime no nível do host.
## Início rápido
@ -42,94 +42,101 @@ openclaw gateway diagnostics export --json
## Comando de chat
Proprietários podem usar `/diagnostics [note]` no chat para solicitar uma exportação local do Gateway.
Use isso quando o bug aconteceu em uma conversa real e você quiser um relatório
copiável e colável para suporte:
Proprietários podem usar `/diagnostics [note]` no chat para solicitar uma exportação
local do Gateway. Use isso quando o bug aconteceu em uma conversa real e você quiser
um relatório copiável para o suporte:
1. Envie `/diagnostics` na conversa em que você percebeu o problema. Adicione uma
nota curta se ajudar, por exemplo `/diagnostics bad tool choice`.
2. O OpenClaw envia o preâmbulo de diagnósticos e pede uma aprovação explícita de exec.
A aprovação executa `openclaw gateway diagnostics export --json`.
observação curta se ajudar, por exemplo `/diagnostics bad tool choice`.
2. O OpenClaw envia o preâmbulo de diagnósticos e pede uma aprovação explícita
de exec. A aprovação executa `openclaw gateway diagnostics export --json`.
Não aprove diagnósticos por meio de uma regra allow-all.
3. Após a aprovação, o OpenClaw responde com um relatório colável contendo o caminho
do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes.
do pacote local, o resumo do manifesto, observações de privacidade e ids de sessão relevantes.
Em chats em grupo, um proprietário ainda pode executar `/diagnostics`, mas o OpenClaw não
publica os detalhes de diagnóstico de volta no chat compartilhado. Ele envia o preâmbulo,
prompts de aprovação, resultado da exportação do Gateway e detalhamento de sessão/thread do Codex
os prompts de aprovação, o resultado da exportação do Gateway e a divisão de sessão/thread do Codex
ao proprietário pela rota privada de aprovação. O grupo recebe apenas um aviso curto
de que o fluxo de diagnósticos foi enviado em particular. Se o OpenClaw não conseguir encontrar uma rota privada
para o proprietário, o comando falha de forma fechada e pede que o proprietário o execute a partir de uma DM.
de que o fluxo de diagnósticos foi enviado em particular. Se o OpenClaw não conseguir encontrar uma rota
privada para o proprietário, o comando falha de forma fechada e pede que o proprietário o execute por DM.
Quando a sessão ativa do OpenClaw está usando o harness nativo do OpenAI Codex,
a mesma aprovação de exec também cobre um upload de feedback do OpenAI para as threads de runtime
do Codex que o OpenClaw conhece. Esse upload é separado do zip local do
Gateway e aparece apenas para sessões do harness do Codex. Antes da aprovação, o
a mesma aprovação de exec também cobre um upload de feedback para a OpenAI referente às threads
de runtime do Codex que o OpenClaw conhece. Esse upload é separado do zip local
do Gateway e aparece apenas para sessões do harness Codex. Antes da aprovação, o
prompt explica que aprovar diagnósticos também enviará feedback do Codex, mas ele
não lista ids de sessão ou thread do Codex. Após a aprovação, a resposta do chat lista
não lista ids de sessão ou thread do Codex. Após a aprovação, a resposta no chat lista
os canais, ids de sessão do OpenClaw, ids de thread do Codex e comandos locais de retomada
para as threads que foram enviadas aos servidores da OpenAI. Se você negar ou ignorar a
aprovação, o OpenClaw não executa a exportação, não envia feedback do Codex e
não imprime os ids do Codex.
Isso torna curto o loop comum de depuração do Codex: perceba o mau comportamento no
Isso torna curto o loop comum de depuração do Codex: perceba o comportamento ruim no
Telegram, Discord ou outro canal, execute `/diagnostics`, aprove uma vez, compartilhe
o relatório com o suporte e então execute localmente o comando `codex resume <thread-id>` impresso
se quiser inspecionar você mesmo a thread nativa do Codex. Consulte
[Harness do Codex](/pt-BR/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) para
o relatório com o suporte e então execute localmente o comando `codex resume <thread-id>`
impresso se quiser inspecionar você mesmo a thread nativa do Codex. Consulte
[harness Codex](/pt-BR/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) para
esse fluxo de inspeção.
## O que a exportação contém
O zip inclui:
- `summary.md`: visão geral legível por humanos para suporte.
- `summary.md`: visão geral legível por humanos para o suporte.
- `diagnostics.json`: resumo legível por máquina de configuração, logs, status, integridade
e dados de estabilidade.
- `manifest.json`: metadados de exportação e lista de arquivos.
- Formato de configuração sanitizado e detalhes de configuração não secretos.
- Formato da configuração sanitizado e detalhes de configuração não secretos.
- Resumos de logs sanitizados e linhas recentes de log redigidas.
- Snapshots de status e integridade do Gateway por melhor esforço.
- Snapshots de status e integridade do Gateway em melhor esforço.
- `stability/latest.json`: pacote de estabilidade persistido mais recente, quando disponível.
A exportação é útil mesmo quando o Gateway não está íntegro. Se o Gateway não conseguir
responder a solicitações de status ou integridade, os logs locais, o formato de configuração e o pacote de
estabilidade mais recente ainda serão coletados quando disponíveis.
responder a solicitações de status ou integridade, os logs locais, o formato da configuração e o pacote
de estabilidade mais recente ainda serão coletados quando disponíveis.
## Modelo de privacidade
Diagnósticos são projetados para serem compartilháveis. A exportação mantém dados operacionais
Os diagnósticos são projetados para serem compartilháveis. A exportação mantém dados operacionais
que ajudam na depuração, como:
- nomes de subsistemas, ids de Plugin, ids de provedores, ids de canais e modos configurados
- códigos de status, durações, contagens de bytes, estado de fila e leituras de memória
- nomes de subsistemas, ids de plugins, ids de provedores, ids de canais e modos configurados
- códigos de status, durações, contagens de bytes, estado da fila e leituras de memória
- metadados de log sanitizados e mensagens operacionais redigidas
- formato de configuração e configurações de recursos não secretas
- formato da configuração e configurações de recursos não secretas
A exportação omite ou redige:
- texto de chat, prompts, instruções, corpos de Webhook e saídas de ferramentas
- texto de chat, prompts, instruções, corpos de webhook e saídas de ferramentas
- credenciais, chaves de API, tokens, cookies e valores secretos
- corpos brutos de solicitação ou resposta
- ids de conta, ids de mensagem, ids brutos de sessão, nomes de host e nomes de usuário locais
Quando uma mensagem de log parece texto de usuário, chat, prompt ou payload de ferramenta, a
exportação mantém apenas o fato de que uma mensagem foi omitida e a contagem de bytes.
Quando uma mensagem de log parece texto de payload de usuário, chat, prompt ou ferramenta, a
exportação mantém apenas que uma mensagem foi omitida e a contagem de bytes.
## Gravador de estabilidade
O Gateway registra por padrão um fluxo de estabilidade limitado e sem payload quando
diagnósticos estão habilitados. Ele é para fatos operacionais, não para conteúdo.
os diagnósticos estão habilitados. Ele é para fatos operacionais, não conteúdo.
O mesmo Heartbeat de diagnóstico registra amostras de vivacidade quando o Gateway continua
em execução, mas o loop de eventos do Node.js ou a CPU parece saturado. Esses eventos
O mesmo heartbeat de diagnóstico registra amostras de atividade quando o Gateway continua
em execução, mas o loop de eventos do Node.js ou a CPU parecem saturados. Esses eventos
`diagnostic.liveness.warning` incluem atraso do loop de eventos, utilização do loop de eventos,
proporção de núcleos de CPU e contagens de sessões ativas/em espera/enfileiradas. Amostras ociosas
permanecem na telemetria no nível `info`. Amostras de vivacidade se tornam avisos do Gateway
apenas quando há trabalho em espera ou enfileirado, ou quando trabalho ativo se sobrepõe a
atraso sustentado do loop de eventos. Picos transitórios de atraso máximo durante trabalho em segundo plano
saudável permanecem nos logs de debug. Eles não reiniciam o Gateway por
si só.
proporção de núcleos de CPU, contagens de sessões ativas/em espera/enfileiradas, a fase atual
de inicialização/runtime quando conhecida, spans de fases recentes e rótulos limitados de trabalho
ativo/enfileirado. Amostras ociosas permanecem na telemetria no nível `info`. Amostras de atividade
se tornam avisos do Gateway apenas quando há trabalho aguardando ou enfileirado, ou quando trabalho ativo
se sobrepõe a atraso sustentado do loop de eventos. Picos transitórios de atraso máximo durante
trabalho em segundo plano saudável permanecem nos logs de debug. Eles não reiniciam o
Gateway por si só.
As fases de inicialização também emitem eventos `diagnostic.phase.completed` com tempo de relógio de parede e
tempo de CPU. Diagnósticos de execução incorporada travados marcam `terminalProgressStale=true`
quando o último progresso da ponte parecia terminal, como um item bruto de resposta ou
evento de conclusão de resposta, mas o Gateway ainda considera a execução incorporada
ativa.
Inspecione o gravador ao vivo:
@ -140,7 +147,7 @@ openclaw gateway stability --json
```
Inspecione o pacote de estabilidade persistido mais recente após uma saída fatal, timeout de desligamento
ou falha de inicialização após reinício:
ou falha de inicialização por reinício:
```bash
openclaw gateway stability --bundle latest
@ -169,13 +176,13 @@ openclaw gateway diagnostics export \
- `--url <url>`: URL WebSocket do Gateway para snapshots de status e integridade.
- `--token <token>`: token do Gateway para snapshots de status e integridade.
- `--password <password>`: senha do Gateway para snapshots de status e integridade.
- `--timeout <ms>`: timeout de snapshot de status e integridade.
- `--timeout <ms>`: timeout de snapshots de status e integridade.
- `--no-stability-bundle`: ignora a busca por pacote de estabilidade persistido.
- `--json`: imprime metadados de exportação legíveis por máquina.
## Desabilitar diagnósticos
Diagnósticos são habilitados por padrão. Para desabilitar o gravador de estabilidade e
Os diagnósticos são habilitados por padrão. Para desabilitar o gravador de estabilidade e
a coleta de eventos de diagnóstico:
```json5
@ -186,7 +193,7 @@ a coleta de eventos de diagnóstico:
}
```
Desabilitar diagnósticos reduz os detalhes do relatório de bugs. Isso não afeta o logging
Desabilitar diagnósticos reduz os detalhes do relatório de bug. Isso não afeta o registro
normal do Gateway.
## Relacionado

360
docs/pt-BR/gateway/doctor.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Adicionando ou modificando migrações do doctor
- Introduzindo alterações de configuração incompatíveis
- Adição ou modificação de migrações de diagnóstico
- Introduzindo alterações incompatíveis na configuração
sidebarTitle: Doctor
summary: 'Comando doctor: verificações de integridade, migrações de configuração e etapas de reparo'
title: Diagnóstico
x-i18n:
generated_at: "2026-05-04T09:36:57Z"
generated_at: "2026-05-05T01:46:22Z"
model: gpt-5.5
provider: openai
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configuração/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
## Início rápido
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Aplica também reparos agressivos (sobrescreve configurações personalizadas de supervisor).
Também aplica reparos agressivos (sobrescreve configurações personalizadas do supervisor).
</Tab>
<Tab title="--non-interactive">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
Verifica serviços do sistema em busca de instalações extras do gateway (launchd/systemd/schtasks).
Verifica serviços do sistema em busca de instalações extras do Gateway (launchd/systemd/schtasks).
</Tab>
</Tabs>
Se quiser revisar as mudanças antes de gravar, abra o arquivo de configuração primeiro:
Se você quiser revisar as alterações antes de gravar, abra o arquivo de configuração primeiro:
```bash
cat ~/.openclaw/openclaw.json
@ -76,106 +76,109 @@ cat ~/.openclaw/openclaw.json
## O que ele faz (resumo)
<AccordionGroup>
<Accordion title="Integridade, UI e atualizações">
- Atualização prévia opcional para instalações via git (somente interativo).
- Verificação de atualização do protocolo da UI (recompila a Control UI quando o schema do protocolo é mais recente).
<Accordion title="Integridade, interface e atualizações">
- Atualização opcional de pré-verificação para instalações via git (somente interativo).
- Verificação de atualização do protocolo da interface (recompila a Interface de Controle quando o esquema do protocolo é mais recente).
- Verificação de integridade + prompt de reinicialização.
- Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de Plugin.
- Resumo de status de Skills (qualificadas/ausentes/bloqueadas) e status de plugins.
</Accordion>
<Accordion title="Configuração e migrações">
- Normalização de configuração para valores legados.
- Migração da configuração do Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
- Verificações de migração do navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP.
- Avisos de substituição do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Migração da configuração de Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
- Verificações de migração do navegador para configurações legadas da extensão do Chrome e prontidão do MCP do Chrome.
- Avisos de sobrescrita do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Avisos de sombreamento do OAuth do Codex (`models.providers.openai-codex`).
- Verificação de pré-requisitos de TLS do OAuth para perfis OAuth do OpenAI Codex.
- Avisos de lista de permissões de plugins/ferramentas quando `plugins.allow` é restritiva, mas a política de ferramentas ainda pede curingas ou ferramentas pertencentes a plugins.
- Migração de estado legado em disco (sessions/agent dir/autenticação do WhatsApp).
- Migração de chaves legadas de contrato de manifesto de plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migração de armazenamento Cron legado (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, tarefas simples de fallback de Webhook `notify: true`).
- Migração de política de runtime de agentes legada para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Limpeza de configuração obsoleta de Plugin quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como configuração inerte de contenção e são preservadas.
- Verificação de pré-requisitos de TLS do OAuth para perfis de OAuth do OpenAI Codex.
- Avisos de lista de permissões de Plugin/ferramenta quando `plugins.allow` é restritiva, mas a política de ferramentas ainda solicita curingas ou ferramentas pertencentes a plugins.
- Migração de estado legado em disco (sessões/diretório de agentes/autenticação do WhatsApp).
- Migração de chaves legadas de contrato do manifesto do plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migração do armazenamento legado de Cron (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, jobs fallback simples de Webhook `notify: true`).
- Migração legada da política de runtime do agente para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Limpeza de configurações obsoletas de plugins quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de plugins são tratadas como configuração inerte de contenção e são preservadas.
</Accordion>
<Accordion title="Estado e integridade">
- Inspeção de arquivos de bloqueio de sessão e limpeza de bloqueios obsoletos.
- Reparo de transcrições de sessão para branches duplicados de reescrita de prompt criados por builds 2026.4.24 afetadas.
- Detecção de tombstone de recuperação de reinicialização de subagentes travados, com suporte a `--fix` para limpar flags obsoletas de recuperação abortada para que a inicialização não continue tratando o filho como abortado na reinicialização.
- Reparo de transcrições de sessão para branches duplicados de reescrita de prompt criados por builds 2026.4.24 afetados.
- Detecção de tombstone de recuperação por reinicialização de subagente travado, com suporte a `--fix` para limpar flags obsoletos de recuperação abortada, para que a inicialização não continue tratando o filho como abortado por reinicialização.
- Verificações de integridade de estado e permissões (sessões, transcrições, diretório de estado).
- Verificações de permissões do arquivo de configuração (chmod 600) ao executar localmente.
- Integridade da autenticação de modelos: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e informa estados de cooldown/desabilitado de perfis de autenticação.
- Verificações de permissão do arquivo de configuração (chmod 600) ao executar localmente.
- Integridade de autenticação do modelo: verifica expiração do OAuth, pode atualizar tokens prestes a expirar e relata estados de cooldown/desabilitado de perfis de autenticação.
- Detecção de diretório extra de workspace (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, serviços e supervisores">
- Reparo da imagem de sandbox quando o sandboxing está habilitado.
- Migração de serviço legado e detecção de gateways extras.
- Reparo de imagem de sandbox quando o sandboxing está habilitado.
- Migração de serviço legado e detecção de Gateways extras.
- Migração de estado legado do canal Matrix (no modo `--fix` / `--repair`).
- Verificações de runtime do Gateway (serviço instalado, mas não em execução; rótulo launchd em cache).
- Avisos de status de canais (sondados a partir do gateway em execução).
- Auditoria de configuração de supervisor (launchd/systemd/schtasks) com reparo opcional.
- Limpeza do ambiente de proxy embutido para serviços de Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização.
- Avisos de status de canal (sondados a partir do Gateway em execução).
- Auditoria de configuração do supervisor (launchd/systemd/schtasks) com reparo opcional.
- Limpeza do ambiente de proxy embutido para serviços do Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante instalação ou atualização.
- Verificações de boas práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciadores de versão).
- Diagnósticos de colisão de porta do Gateway (padrão `18789`).
</Accordion>
<Accordion title="Autenticação, segurança e pareamento">
- Avisos de segurança para políticas de DM abertas.
- Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando não existe fonte de token; não sobrescreve configurações de SecretRef de token).
- Detecção de problemas de pareamento de dispositivos (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, divergência obsoleta do cache local de token de dispositivo e divergência de autenticação de registro pareado).
- Avisos de segurança para políticas de DM aberto.
- Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando nenhuma fonte de token existe; não sobrescreve configurações de SecretRef de token).
- Detecção de problemas de pareamento de dispositivo (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, desvio de cache obsoleto de token de dispositivo local e desvio de autenticação de registros pareados).
</Accordion>
<Accordion title="Workspace e shell">
- Verificação de linger do systemd no Linux.
- Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/próximo do limite para arquivos de contexto).
- Verificação de prontidão de Skills para o agente padrão; informa skills permitidas com bins, env, configuração ou requisitos de SO ausentes, e `--fix` pode desabilitar skills indisponíveis em `skills.entries`.
- Verificação de status de conclusão do shell e instalação/upgrade automático.
- Verificação de prontidão do provedor de embeddings de busca de memória (modelo local, chave de API remota ou binário QMD).
- Verificações de instalação a partir do código-fonte (incompatibilidade do workspace pnpm, assets de UI ausentes, binário tsx ausente).
- Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/próximo ao limite para arquivos de contexto).
- Verificação de prontidão de Skills para o agente padrão; relata Skills permitidas com bins, env, config ou requisitos de SO ausentes, e `--fix` pode desabilitar Skills indisponíveis em `skills.entries`.
- Verificação de status de completação do shell e instalação/upgrade automáticos.
- Verificação de prontidão do provedor de embeddings da busca de memória (modelo local, chave de API remota ou binário QMD).
- Verificações de instalação a partir do código-fonte (incompatibilidade de workspace pnpm, assets de UI ausentes, binário tsx ausente).
- Grava configuração atualizada + metadados do assistente.
</Accordion>
</AccordionGroup>
## Backfill e reset da UI Dreams
## Backfill e redefinição da interface Dreams
A cena Dreams da Control UI inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de dreaming ancorado. Essas ações usam métodos RPC no estilo doctor do gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
A cena Dreams da Interface de Controle inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de Dreaming fundamentado. Essas ações usam métodos RPC no estilo do doctor do Gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
O que elas fazem:
- **Backfill** verifica arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM ancorado e grava entradas reversíveis de backfill em `DREAMS.md`.
- **Backfill** verifica arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem do diário REM fundamentado e grava entradas reversíveis de backfill em `DREAMS.md`.
- **Reset** remove apenas essas entradas marcadas de diário de backfill de `DREAMS.md`.
- **Clear Grounded** remove apenas entradas encenadas de curto prazo, somente ancoradas, que vieram de replay histórico e ainda não acumularam recordação ao vivo ou suporte diário.
- **Clear Grounded** remove apenas entradas de curto prazo preparadas e somente fundamentadas que vieram de replay histórico e ainda não acumularam recall ao vivo ou suporte diário.
O que elas **não** fazem por si só:
- elas não editam `MEMORY.md`
- elas não executam migrações completas do doctor
- elas não encenam automaticamente candidatos ancorados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho encenado da CLI primeiro
- elas não preparam automaticamente candidatos fundamentados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho preparado da CLI primeiro
Se quiser que o replay histórico ancorado influencie a faixa normal de promoção profunda, use o fluxo da CLI em vez disso:
Se você quiser que o replay histórico fundamentado influencie a trilha normal de promoção profunda, use o fluxo da CLI em vez disso:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão.
Isso prepara candidatos duráveis fundamentados no armazenamento de Dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão.
## Comportamento detalhado e justificativa
<AccordionGroup>
<Accordion title="0. Atualização opcional (instalações via git)">
Se este for um checkout git e o doctor estiver sendo executado de forma interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor.
Se este for um checkout do git e o doctor estiver em execução interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor.
</Accordion>
<Accordion title="1. Normalização de configuração">
Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição específica de canal), o doctor os normaliza para o schema atual.
Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma sobrescrita específica de canal), o doctor os normaliza para o esquema atual.
Isso inclui campos planos legados do Talk. A configuração pública atual do Talk é `talk.provider` + `talk.providers.<provider>`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` para o mapa de provedores.
Isso inclui campos planos legados de Talk. A configuração pública atual de Talk é `talk.provider` + `talk.providers.<provider>`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` no mapa de provedores.
O doctor também avisa quando `plugins.allow` não está vazio e a política de ferramentas usa
curingas ou entradas de ferramentas pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas
de plugins que realmente carregam; ele não ignora a lista de permissões exclusiva de plugins.
entradas de ferramenta curingas ou pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas
de plugins que realmente carregam; ele não contorna a lista exclusiva de permissões de plugins.
O doctor grava `plugins.bundledDiscovery: "compat"` para configurações legadas migradas
de lista de permissões para preservar o comportamento existente de provedores empacotados e
então aponta para a configuração mais rígida `"allowlist"`.
</Accordion>
<Accordion title="2. Migrações de chaves de configuração legadas">
@ -184,10 +187,10 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
O doctor irá:
- Explicar quais chaves legadas foram encontradas.
- Mostrar a migração que ele aplicou.
- Reescrever `~/.openclaw/openclaw.json` com o schema atualizado.
- Mostrar a migração aplicada.
- Reescrever `~/.openclaw/openclaw.json` com o esquema atualizado.
O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações de armazenamento de tarefas Cron são tratadas por `openclaw doctor --fix`.
O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações do armazenamento de jobs de Cron são tratadas por `openclaw doctor --fix`.
Migrações atuais:
@ -195,11 +198,12 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- configurações de canais configurados sem política de resposta visível → `messages.groupChat.visibleReplies: "message_tool"`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` de nível superior
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` legados → `talk.provider` + `talk.providers.<provider>`
- legado `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -213,70 +217,76 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Para canais com `accounts` nomeadas, mas valores de canal de nível superior de conta única remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
- Para canais com `accounts` nomeadas, mas com valores de canal de nível superior de conta única ainda remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- remova `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para tempos limite de provedores/modelos lentos
- remova `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para tempos limite lentos de provedor/modelo
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- remova `browser.relayBindHost` (configuração legada de retransmissão da extensão)
- `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como um valor enum futuro ou desconhecido, em vez de falhar fechado)
- legado `models.providers.*.api: "openai"` → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como um valor de enum futuro ou desconhecido, em vez de falhar de forma fechada)
Os avisos do doctor também incluem orientação de conta padrão para canais com várias contas:
Os avisos do Doctor também incluem orientação de conta padrão para canais com várias contas:
- Se duas ou mais entradas `channels.<channel>.accounts` estiverem configuradas sem `channels.<channel>.defaultAccount` ou `accounts.default`, o doctor avisa que o roteamento de fallback pode escolher uma conta inesperada.
- Se `channels.<channel>.defaultAccount` estiver definido como um ID de conta desconhecido, o doctor avisa e lista os IDs de conta configurados.
</Accordion>
<Accordion title="2b. Substituições do provedor OpenCode">
Se você adicionou `models.providers.opencode`, `opencode-zen` ou `opencode-go` manualmente, isso substitui o catálogo OpenCode integrado de `@mariozechner/pi-ai`. Isso pode forçar modelos para a API errada ou zerar custos. O doctor avisa para que você possa remover a substituição e restaurar o roteamento de API + custos por modelo.
<Accordion title="2b. Substituições de provedor OpenCode">
Se você adicionou `models.providers.opencode`, `opencode-zen` ou `opencode-go` manualmente, isso substitui o catálogo OpenCode integrado de `@mariozechner/pi-ai`. Isso pode forçar modelos para a API errada ou zerar custos. O Doctor avisa para que você possa remover a substituição e restaurar o roteamento de API por modelo + custos.
</Accordion>
<Accordion title="2c. Migração de navegador e prontidão do Chrome MCP">
Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação do Chrome MCP local ao host:
Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação Chrome MCP local ao host:
- `browser.profiles.*.driver: "extension"` se torna `"existing-session"`
- `browser.relayBindHost` é removido
O doctor também audita o caminho do Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
O Doctor também audita o caminho Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
- verifica se o Google Chrome está instalado no mesmo host para perfis padrão de conexão automática
- verifica a versão detectada do Chrome e avisa quando ela está abaixo do Chrome 144
- lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`)
- verifica a versão detectada do Chrome e avisa quando ela é inferior ao Chrome 144
- lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`)
O doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
O Doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
- um navegador baseado em Chromium 144+ no host do gateway/node
- o navegador em execução localmente
- depuração remota habilitada nesse navegador
- aprovação do primeiro prompt de consentimento de anexação no navegador
A prontidão aqui diz respeito apenas aos pré-requisitos de anexação local. `Existing-session` mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto.
A prontidão aqui se refere apenas aos pré-requisitos de anexação local. Existing-session mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou um perfil CDP bruto.
Esta verificação **não** se aplica a Docker, sandbox, navegador remoto ou outros fluxos headless. Eles continuam usando CDP bruto.
Esta verificação **não** se aplica a Docker, sandbox, remote-browser ou outros fluxos headless. Eles continuam usando CDP bruto.
</Accordion>
<Accordion title="2d. Pré-requisitos de TLS do OAuth">
Quando um perfil OAuth do OpenAI Codex está configurado, o doctor consulta o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a consulta falhar com um erro de certificado (por exemplo, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientação de correção específica para a plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a consulta é executada mesmo se o gateway estiver saudável.
<Accordion title="2d. Pré-requisitos de TLS para OAuth">
Quando um perfil OAuth do OpenAI Codex está configurado, o doctor sonda o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a sondagem falhar com um erro de certificado (por exemplo `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientações de correção específicas da plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a sondagem é executada mesmo se o gateway estiver saudável.
</Accordion>
<Accordion title="2e. Substituições do provedor OAuth do Codex">
Se você adicionou anteriormente configurações legadas de transporte da OpenAI em `models.providers.openai-codex`, elas podem sombrear o caminho integrado do provedor OAuth do Codex que versões mais novas usam automaticamente. O doctor avisa quando vê essas configurações antigas de transporte junto com o OAuth do Codex para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam este aviso.
<Accordion title="2e. Substituições de provedor OAuth do Codex">
Se você adicionou anteriormente configurações legadas de transporte OpenAI em `models.providers.openai-codex`, elas podem mascarar o caminho do provedor OAuth do Codex integrado que versões mais recentes usam automaticamente. O Doctor avisa quando detecta essas configurações antigas de transporte junto com Codex OAuth, para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições somente de cabeçalhos ainda são compatíveis e não acionam este aviso.
</Accordion>
<Accordion title="2f. Avisos de rota do Plugin Codex">
Quando o Plugin Codex incluído está habilitado, o doctor também verifica se referências de modelo primário `openai-codex/*` ainda são resolvidas pelo executor padrão do PI. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex pelo PI, mas é fácil confundi-la com o harness nativo do app-server do Codex. O doctor avisa e aponta para o formato explícito do app-server: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
Quando o Plugin Codex incluído está habilitado, o doctor também verifica se refs de modelo primário `openai-codex/*` ainda resolvem pelo executor PI padrão. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex por meio do PI, mas é fácil confundi-la com o harness nativo do servidor de aplicativo do Codex. O Doctor avisa e aponta para o formato explícito do servidor de aplicativo: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
O doctor não repara isso automaticamente porque ambas as rotas são válidas:
O Doctor não repara isso automaticamente porque ambas as rotas são válidas:
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo executor normal do OpenClaw."
- `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado pelo app-server nativo do Codex."
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex pelo chat."
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex por meio do executor normal do OpenClaw."
- `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado por meio do servidor de aplicativo nativo do Codex."
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex a partir do chat."
- `/acp ...` ou `runtime: "acp"` significa "usar o adaptador externo ACP/acpx."
Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando o OAuth do Codex via PI for intencional.
Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando o PI Codex OAuth for intencional.
</Accordion>
<Accordion title="2g. Limpeza de rota de sessão">
O Doctor também verifica o armazenamento de sessões ativas em busca de estado de rota obsoleto criado automaticamente depois que você move o modelo ou runtime padrão/fallback configurado para longe de uma rota pertencente a um Plugin, como Codex.
`openclaw doctor --fix` pode limpar estado obsoleto criado automaticamente, como pins de modelo `modelOverrideSource: "auto"`, metadados de modelo de runtime, IDs de harness fixados, vinculações de sessão da CLI e substituições automáticas de perfil de autenticação quando a rota proprietária deles não está mais configurada. Escolhas explícitas de usuário ou modelos de sessão legados são relatadas para revisão manual e deixadas intactas; troque-as com `/model ...`, `/new` ou redefina a sessão quando essa rota não for mais pretendida.
</Accordion>
<Accordion title="3. Migrações de estado legado (layout em disco)">
O doctor pode migrar layouts mais antigos em disco para a estrutura atual:
O Doctor pode migrar layouts em disco mais antigos para a estrutura atual:
- Armazenamento de sessões + transcrições:
- de `~/.openclaw/sessions/` para `~/.openclaw/agents/<agentId>/sessions/`
@ -286,14 +296,14 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
- de `~/.openclaw/credentials/*.json` legado (exceto `oauth.json`)
- para `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID da conta padrão: `default`)
Essas migrações são por melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento legado de sessões + diretório do agente na inicialização para que histórico/autenticação/modelos cheguem ao caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diferenças apenas na ordem das chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento de sessões legado + diretório do agente na inicialização, para que histórico/autenticação/modelos entrem no caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de Talk agora compara por igualdade estrutural, portanto diferenças apenas na ordem das chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
</Accordion>
<Accordion title="3a. Migrações de manifestos de Plugin legados">
O doctor verifica todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada é removida sem duplicar os dados.
<Accordion title="3a. Migrações de manifesto de Plugin legado">
O Doctor verifica todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada será removida sem duplicar os dados.
</Accordion>
<Accordion title="3b. Migrações de armazenamento Cron legado">
O doctor também verifica o armazenamento de trabalhos cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de trabalhos que o agendador ainda aceita por compatibilidade.
O Doctor também verifica o armazenamento de jobs Cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de job que o agendador ainda aceita por compatibilidade.
As limpezas atuais de cron incluem:
@ -302,160 +312,160 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
- campos de payload de nível superior (`message`, `model`, `thinking`, ...) → `payload`
- campos de entrega de nível superior (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- aliases de entrega `provider` do payload → `delivery.channel` explícito
- trabalhos simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
- jobs simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
O doctor só migra automaticamente trabalhos `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um trabalho combina fallback legado de notificação com um modo de entrega não webhook existente, o doctor avisa e deixa esse trabalho para revisão manual.
O Doctor só migra automaticamente jobs `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um job combinar fallback de notificação legado com um modo de entrega não webhook existente, o doctor avisa e deixa esse job para revisão manual.
No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o `~/.openclaw/bin/ensure-whatsapp.sh` legado. Esse script local ao host não é mantido pelo OpenClaw atual e pode gravar mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para verificações de integridade atuais.
No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o legado `~/.openclaw/bin/ensure-whatsapp.sh`. Esse script local do host não é mantido pelo OpenClaw atual e pode gravar mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para as verificações de integridade atuais.
</Accordion>
<Accordion title="3c. Limpeza de bloqueios de sessão">
O doctor verifica cada diretório de sessão de agente em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele relata: o caminho, PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID inativo ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
<Accordion title="3c. Limpeza de bloqueio de sessão">
O Doctor verifica todos os diretórios de sessão de agentes em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele informa: o caminho, PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID morto ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
</Accordion>
<Accordion title="3d. Reparo de ramificação de transcrição de sessão">
O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicada criado pelo bug de reescrita de transcrição de prompt de 2026.4.24: uma interação de usuário abandonada com contexto de runtime interno do OpenClaw mais uma ramificação irmã ativa contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais interações duplicadas.
O Doctor verifica arquivos JSONL de sessão de agentes em busca do formato de ramificação duplicada criado pelo bug de reescrita da transcrição de prompt de 2026.4.24: uma rodada abandonada do usuário com contexto de runtime interno do OpenClaw, além de uma ramificação irmã ativa contendo o mesmo prompt visível do usuário. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais rodadas duplicadas.
</Accordion>
<Accordion title="4. Verificações de integridade de estado (persistência de sessão, roteamento e segurança)">
O diretório de estado é o tronco encefálico operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
O diretório de estado é o tronco cerebral operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
O doctor verifica:
O Doctor verifica:
- **Diretório de estado ausente**: alerta sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não consegue recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica a permissão de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma incompatibilidade de proprietário/grupo é detectada).
- **Diretório de estado sincronizado com nuvem no macOS**: alerta quando o estado é resolvido sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização.
- **Diretório de estado em SD ou eMMC no Linux**: alerta quando o estado é resolvido para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rapidamente com escritas de sessão e credenciais.
- **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são necessários para persistir histórico e evitar falhas `ENOENT`.
- **Incompatibilidade de transcrição**: alerta quando entradas recentes de sessão têm arquivos de transcrição ausentes.
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está acumulando).
- **Múltiplos diretórios de estado**: alerta quando existem várias pastas `~/.openclaw` entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações).
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não pode recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica a possibilidade de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma divergência de proprietário/grupo é detectada).
- **Diretório de estado sincronizado com nuvem no macOS**: avisa quando o estado resolve sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização.
- **Diretório de estado em SD ou eMMC no Linux**: avisa quando o estado resolve para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rapidamente com escritas de sessões e credenciais.
- **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são obrigatórios para persistir histórico e evitar falhas `ENOENT`.
- **Incompatibilidade de transcrição**: avisa quando entradas de sessão recentes têm arquivos de transcrição ausentes.
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está se acumulando).
- **Múltiplos diretórios de estado**: avisa quando múltiplas pastas `~/.openclaw` existem entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode ser dividido entre instalações).
- **Lembrete de modo remoto**: se `gateway.mode=remote`, o doctor lembra você de executá-lo no host remoto (o estado fica lá).
- **Permissões do arquivo de configuração**: alerta se `~/.openclaw/openclaw.json` pode ser lido por grupo/todos e oferece restringir para `600`.
- **Permissões do arquivo de configuração**: avisa se `~/.openclaw/openclaw.json` é legível por grupo/mundo e oferece restringir para `600`.
</Accordion>
<Accordion title="5. Saúde da autenticação de modelo (expiração de OAuth)">
O doctor inspeciona perfis OAuth no armazenamento de autenticação, alerta quando tokens estão expirando/expirados e pode renová-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Solicitações de renovação só aparecem ao executar interativamente (TTY); `--non-interactive` ignora tentativas de renovação.
<Accordion title="5. Integridade de autenticação de modelo (expiração do OAuth)">
O Doctor inspeciona perfis OAuth no armazenamento de autenticação, avisa quando tokens estão expirando/expirados e pode atualizá-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Prompts de atualização aparecem apenas ao executar interativamente (TTY); `--non-interactive` ignora tentativas de atualização.
Quando uma renovação OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado.
Quando uma atualização OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor solicitando que você entre novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado.
O doctor também relata perfis de autenticação temporariamente inutilizáveis devido a:
O Doctor também informa perfis de autenticação que estão temporariamente inutilizáveis devido a:
- períodos curtos de espera (limites de taxa/timeouts/falhas de autenticação)
- desativações mais longas (falhas de cobrança/crédito)
- cooldowns curtos (limites de taxa/timeouts/falhas de autenticação)
- desativações mais longas (falhas de faturamento/crédito)
</Accordion>
<Accordion title="6. Validação de modelo de hooks">
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo contra o catálogo e a allowlist e alerta quando ela não puder ser resolvida ou não for permitida.
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo contra o catálogo e a lista de permissões e avisa quando ela não resolve ou não é permitida.
</Accordion>
<Accordion title="7. Reparo de imagem de sandbox">
Quando o sandboxing está ativado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente.
Quando sandboxing está habilitado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente.
</Accordion>
<Accordion title="7b. Limpeza de instalação de Plugin">
O doctor remove estado legado de preparação de dependências de Plugin gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes obsoletas de dependências geradas, diretórios antigos de etapa de instalação, resíduos locais de pacote de código anterior de reparo de dependências de Plugin empacotado e cópias npm gerenciadas órfãs ou recuperadas de Plugins `@openclaw/*` empacotados que podem sombrear o manifesto empacotado atual.
O Doctor remove o estado legado de preparação de dependências de Plugin gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes de dependências geradas obsoletas, diretórios antigos de estágio de instalação, resíduos locais de pacote de código anterior de reparo de dependências de plugins incluídos e cópias npm gerenciadas órfãs ou recuperadas de plugins `@openclaw/*` incluídos que podem sombrear o manifesto incluído atual.
O doctor também pode reinstalar Plugins baixáveis configurados quando a configuração os referencia, mas o registro local de Plugins não consegue encontrá-los. Para a externalização de Plugins empacotados de 2026.5.2, o doctor instala automaticamente Plugins baixáveis que a configuração existente já usa e então depende de `meta.lastTouchedVersion` para executar essa passagem de versão apenas uma vez. A inicialização do Gateway e o recarregamento de configuração não executam gerenciadores de pacotes; instalações de Plugin continuam sendo trabalho explícito de doctor/instalação/atualização.
O Doctor também pode reinstalar plugins baixáveis ausentes quando a configuração os referencia, mas o registro local de plugins não consegue encontrá-los. Exemplos incluem `plugins.entries` materiais, configurações de canal/provedor/busca configuradas e runtimes de agentes configurados. Durante atualizações de pacote, o doctor evita executar reparo de plugins pelo gerenciador de pacotes enquanto o pacote principal está sendo trocado; execute `openclaw doctor --fix` novamente após a atualização se um Plugin configurado ainda precisar de recuperação. A inicialização do Gateway e a recarga de configuração não executam gerenciadores de pacotes; instalações de plugins continuam sendo trabalho explícito de doctor/instalação/atualização.
</Accordion>
<Accordion title="8. Migrações de serviço do Gateway e dicas de limpeza">
O doctor detecta serviços legados do Gateway (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do Gateway. Ele também pode procurar serviços extras semelhantes ao Gateway e imprimir dicas de limpeza. Serviços do Gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras".
O Doctor detecta serviços de gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do Gateway. Ele também pode verificar serviços extras semelhantes a gateway e imprimir dicas de limpeza. Serviços de gateway OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras".
No Linux, se o serviço de Gateway em nível de usuário estiver ausente, mas existir um serviço de Gateway do OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep` e, em seguida, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor de sistema for responsável pelo ciclo de vida do Gateway.
No Linux, se o serviço de Gateway no nível do usuário estiver ausente, mas existir um serviço de Gateway OpenClaw no nível do sistema, o doctor não instala automaticamente um segundo serviço no nível do usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep`; depois, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor do sistema for responsável pelo ciclo de vida do Gateway.
</Accordion>
<Accordion title="8b. Migração de inicialização do Matrix">
Quando uma conta de canal Matrix tem uma migração de estado legado pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e então executa as etapas de migração de melhor esforço: migração de estado legado do Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é totalmente ignorada.
<Accordion title="8b. Migração da Matrix na inicialização">
Quando uma conta de canal Matrix tem uma migração de estado legada pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e então executa as etapas de migração de melhor esforço: migração de estado legada da Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), esta verificação é ignorada inteiramente.
</Accordion>
<Accordion title="8c. Pareamento de dispositivo e desvio de autenticação">
O doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de saúde.
O Doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de integridade.
O que ele relata:
O que ele informa:
- solicitações de pareamento inicial pendentes
- solicitações pendentes de primeiro pareamento
- upgrades de função pendentes para dispositivos já pareados
- upgrades de escopo pendentes para dispositivos já pareados
- reparos de incompatibilidade de chave pública em que o ID do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado
- reparos de incompatibilidade de chave pública em que o id do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado
- registros pareados sem um token ativo para uma função aprovada
- tokens pareados cujos escopos se desviaram da linha de base de pareamento aprovada
- entradas locais em cache de token de dispositivo para a máquina atual que são anteriores a uma rotação de token no lado do Gateway ou carregam metadados de escopo obsoletos
- tokens pareados cujos escopos se desviam da linha de base de pareamento aprovada
- entradas locais em cache de token de dispositivo para a máquina atual que antecedem uma rotação de token no lado do Gateway ou carregam metadados de escopo obsoletos
O doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas:
O Doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas:
- inspecione solicitações pendentes com `openclaw devices list`
- aprove a solicitação exata com `openclaw devices approve <requestId>`
- rotacione um token novo com `openclaw devices rotate --device <deviceId> --role <role>`
- remova e reaprove um registro obsoleto com `openclaw devices remove <deviceId>`
- remova e reprove um registro obsoleto com `openclaw devices remove <deviceId>`
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento necessário": agora o doctor distingue pareamento inicial de upgrades pendentes de função/escopo e de desvio de token/identidade do dispositivo obsoleto.
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo exigência de pareamento": o doctor agora diferencia o primeiro pareamento de upgrades pendentes de função/escopo e de desvios de token/identidade de dispositivo obsoletos.
</Accordion>
<Accordion title="9. Avisos de segurança">
O doctor emite avisos quando um provedor está aberto a DMs sem uma lista de permissão, ou quando uma política está configurada de forma perigosa.
O Doctor emite avisos quando um provedor está aberto a DMs sem uma lista de permissões ou quando uma política está configurada de forma perigosa.
</Accordion>
<Accordion title="10. Linger do systemd (Linux)">
Se estiver em execução como um serviço de usuário do systemd, o doctor garante que o linger esteja habilitado para que o Gateway permaneça ativo após o logout.
<Accordion title="10. systemd linger (Linux)">
Se estiver executando como um serviço de usuário systemd, o doctor garante que o linger esteja habilitado para que o gateway permaneça ativo após o logout.
</Accordion>
<Accordion title="11. Status do workspace (skills, plugins e diretórios legados)">
O doctor imprime um resumo do estado do workspace para o agente padrão:
<Accordion title="11. Status do workspace (Skills, plugins e diretórios legados)">
O Doctor imprime um resumo do estado do workspace para o agente padrão:
- **Status das Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas pela lista de permissão.
- **Diretórios legados do workspace**: avisa quando `~/openclaw` ou outros diretórios legados do workspace existem junto ao workspace atual.
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de plugins para quaisquer erros; relata capacidades de plugins de pacote.
- **Status de Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas por lista de permissões.
- **Diretórios legados de workspace**: avisa quando `~/openclaw` ou outros diretórios legados de workspace existem junto ao workspace atual.
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de Plugin para quaisquer erros; informa capacidades de plugins incluídos.
- **Avisos de compatibilidade de Plugin**: sinaliza plugins que têm problemas de compatibilidade com o runtime atual.
- **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros em tempo de carregamento emitidos pelo registro de plugins.
- **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros de tempo de carregamento emitidos pelo registro de plugins.
</Accordion>
<Accordion title="11b. Tamanho do arquivo de bootstrap">
O doctor verifica se os arquivos de bootstrap do workspace (por exemplo, `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele relata, por arquivo, contagens de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e o total de caracteres injetados como uma fração do orçamento total. Quando os arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
O Doctor verifica se os arquivos de bootstrap do workspace (por exemplo `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele informa, por arquivo, contagens de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e total de caracteres injetados como fração do orçamento total. Quando arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Limpeza de Plugin de canal obsoleto">
Quando `openclaw doctor --fix` remove um Plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse Plugin: entradas `channels.<id>`, destinos de Heartbeat que nomeavam o canal e substituições de `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal desapareceu, mas a configuração ainda solicita que o Gateway se vincule a ele.
Quando `openclaw doctor --fix` remove um Plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse Plugin: entradas `channels.<id>`, destinos de Heartbeat que nomeavam o canal e substituições `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal desapareceu, mas a configuração ainda pede que o gateway se vincule a ele.
</Accordion>
<Accordion title="11c. Completação do shell">
O doctor verifica se a completação por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
<Accordion title="11c. Completação de shell">
O Doctor verifica se a completação por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
- Se o perfil do shell usa um padrão lento de completação dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
- Se o perfil do shell usa um padrão lento de completação dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida com arquivo em cache.
- Se a completação está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
- Se nenhuma completação está configurada, o doctor solicita a instalação (somente modo interativo; ignorado com `--non-interactive`).
- Se nenhuma completação estiver configurada, o doctor solicita instalá-la (somente modo interativo; ignorado com `--non-interactive`).
Execute `openclaw completion --write-state` para regenerar o cache manualmente.
</Accordion>
<Accordion title="12. Verificações de autenticação do Gateway (token local)">
O doctor verifica a prontidão da autenticação por token do gateway local.
O Doctor verifica a prontidão da autenticação por token do Gateway local.
- Se o modo de token precisa de um token e nenhuma fonte de token existe, o doctor oferece gerar um.
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o substitui por texto simples.
- `openclaw doctor --generate-gateway-token` força a geração somente quando nenhum SecretRef de token está configurado.
- Se o modo de token precisar de um token e não existir nenhuma fonte de token, o doctor oferece gerar um.
- Se `gateway.auth.token` for gerenciado por SecretRef, mas estiver indisponível, o doctor avisa e não o sobrescreve com texto simples.
- `openclaw doctor --generate-gateway-token` força a geração apenas quando nenhum SecretRef de token está configurado.
</Accordion>
<Accordion title="12b. Reparos somente leitura cientes de SecretRef">
Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento fail-fast do runtime.
Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento de falha rápida do runtime.
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura dos comandos da família de status para reparos de configuração direcionados.
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar credenciais de bot configuradas quando disponíveis.
- Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho de comando atual, o doctor relata que a credencial está configurada, mas indisponível, e ignora a resolução automática em vez de travar ou relatar incorretamente o token como ausente.
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura que os comandos da família de status para reparos direcionados de configuração.
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar as credenciais configuradas do bot quando disponíveis.
- Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho do comando atual, o doctor informa que a credencial está configurada, mas indisponível, e pula a resolução automática em vez de travar ou informar incorretamente que o token está ausente.
</Accordion>
<Accordion title="13. Verificação de integridade do Gateway + reinicialização">
O Doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar saudável.
O doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar íntegro.
</Accordion>
<Accordion title="13b. Prontidão da busca de memória">
O Doctor verifica se o provedor de embeddings de busca de memória configurado está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
<Accordion title="13b. Prontidão da pesquisa de memória">
O doctor verifica se o provedor configurado de embeddings da pesquisa de memória está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção incluindo o pacote npm e uma opção de caminho manual para o binário.
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL de modelo remoto/baixável reconhecida. Se estiver ausente, sugere mudar para um provedor remoto.
- **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se uma chave de API está presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente.
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção, incluindo o pacote npm e uma opção de caminho manual para o binário.
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL reconhecida de modelo remoto/baixável. Se estiver ausente, sugere mudar para um provedor remoto.
- **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se há uma chave de API presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente.
- **Provedor automático**: verifica primeiro a disponibilidade do modelo local e depois tenta cada provedor remoto na ordem de seleção automática.
Quando há um resultado de sondagem do Gateway em cache disponível (o Gateway estava íntegro no momento da verificação), o Doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O Doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ao vivo do provedor.
Quando um resultado de sondagem do Gateway em cache está disponível (o Gateway estava íntegro no momento da verificação), o doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ao vivo do provedor.
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em tempo de execução.
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em runtime.
</Accordion>
<Accordion title="14. Avisos de status de canal">
Se o Gateway estiver íntegro, o Doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
Se o Gateway estiver íntegro, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
</Accordion>
<Accordion title="15. Auditoria + reparo da configuração do supervisor">
O Doctor verifica a configuração do supervisor instalada (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinicialização). Quando encontra uma incompatibilidade, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais.
O doctor verifica a configuração instalada do supervisor (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinício). Quando encontra uma divergência, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais.
Observações:
@ -463,39 +473,39 @@ Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto
- `openclaw doctor --yes` aceita as solicitações de reparo padrão.
- `openclaw doctor --repair` aplica as correções recomendadas sem solicitações.
- `openclaw doctor --repair --force` sobrescreve configurações personalizadas do supervisor.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o Doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não são de serviço, mas ignora instalação/início/reinício/bootstrap do serviço, reescritas da configuração do supervisor e limpeza de serviço legado porque um supervisor externo é dono desse ciclo de vida.
- No Linux, o Doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd correspondente do Gateway estiver ativa. Ele também ignora unidades extras inativas semelhantes ao Gateway que não sejam legadas durante a varredura de serviços duplicados, para que arquivos de serviço auxiliares não gerem ruído de limpeza.
- Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo Doctor valida o SecretRef, mas não persiste valores de token em texto simples resolvidos nos metadados de ambiente do serviço do supervisor.
- O Doctor detecta valores de ambiente de serviço gerenciados com suporte em `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Tarefa Agendada do Windows incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da origem de tempo de execução em vez da definição do supervisor.
- O Doctor detecta quando o comando de serviço ainda fixa uma `--port` antiga após alterações em `gateway.port` e reescreve os metadados do serviço para a porta atual.
- Se a autenticação por token exigir um token e o SecretRef de token configurado não puder ser resolvido, o Doctor bloqueia o caminho de instalação/reparo com orientação acionável.
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o Doctor bloqueia instalação/reparo até que o modo seja definido explicitamente.
- Para unidades user-systemd no Linux, as verificações de divergência de token do Doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
- Reparos de serviço pelo Doctor se recusam a reescrever, interromper ou reiniciar um serviço de Gateway de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não envolvem serviço, mas pula instalação/início/reinício/bootstrap de serviço, reescritas da configuração do supervisor e limpeza de serviços legados porque um supervisor externo controla esse ciclo de vida.
- No Linux, o doctor não reescreve metadados de comando/ponto de entrada enquanto a unidade systemd correspondente do Gateway está ativa. Ele também ignora unidades extras inativas e não legadas semelhantes ao Gateway durante a varredura de serviços duplicados, para que arquivos de serviço complementares não gerem ruído de limpeza.
- Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo doctor valida o SecretRef, mas não persiste valores de token em texto claro resolvidos nos metadados de ambiente do serviço do supervisor.
- O doctor detecta valores de ambiente de serviço gerenciados por `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Windows Scheduled Task incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da origem em runtime em vez da definição do supervisor.
- O doctor detecta quando o comando do serviço ainda fixa um `--port` antigo após alterações em `gateway.port` e reescreve os metadados do serviço para a porta atual.
- Se a autenticação por token exigir um token e o SecretRef de token configurado não for resolvido, o doctor bloqueia o caminho de instalação/reparo com orientações acionáveis.
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o doctor bloqueia a instalação/reparo até que o modo seja definido explicitamente.
- Para unidades user-systemd do Linux, as verificações de divergência de token do doctor agora incluem origens `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
- Os reparos de serviço do doctor se recusam a reescrever, parar ou reiniciar um serviço do Gateway a partir de um binário antigo do OpenClaw quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Você sempre pode forçar uma reescrita completa via `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Diagnósticos de tempo de execução + porta do Gateway">
O Doctor inspeciona o tempo de execução do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
<Accordion title="16. Diagnósticos de runtime + porta do Gateway">
O doctor inspeciona o runtime do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
</Accordion>
<Accordion title="17. Boas práticas de tempo de execução do Gateway">
O Doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho do Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega a inicialização do seu shell. O Doctor oferece migrar para uma instalação do Node do sistema quando disponível (Homebrew/apt/choco).
<Accordion title="17. Boas práticas de runtime do Gateway">
O doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho do Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega a inicialização do seu shell. O doctor oferece migrar para uma instalação de sistema do Node quando disponível (Homebrew/apt/choco).
LaunchAgents do macOS recém-instalados ou reparados usam um PATH canônico do sistema (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, de modo que Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alterem qual Node os processos filhos resolvem. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios fallback presumidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco.
LaunchAgents do macOS recém-instalados ou reparados usam um PATH de sistema canônico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, portanto Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alteram qual Node é resolvido por processos filhos. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios de fallback inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco.
</Accordion>
<Accordion title="18. Gravação de configuração + metadados do assistente">
O Doctor persiste quaisquer alterações de configuração e carimba metadados do assistente para registrar a execução do Doctor.
<Accordion title="18. Gravação da configuração + metadados do assistente">
O doctor persiste quaisquer alterações de configuração e marca os metadados do assistente para registrar a execução do doctor.
</Accordion>
<Accordion title="19. Dicas de workspace (backup + sistema de memória)">
O Doctor sugere um sistema de memória do workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
O doctor sugere um sistema de memória de workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre a estrutura do workspace e backup com git (GitHub ou GitLab privado recomendado).
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para ver um guia completo sobre estrutura de workspace e backup com git (recomendado GitHub ou GitLab privado).
</Accordion>
</AccordionGroup>
## Relacionado
## Relacionados
- [Runbook do Gateway](/pt-BR/gateway)
- [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting)

93
docs/pt-BR/gateway/logging.md
View File

@ -1,32 +1,43 @@
---
read_when:
- Alteração da saída ou dos formatos de logs
- Alterando a saída ou os formatos de log
- Depuração da saída da CLI ou do Gateway
summary: Superfícies de log, logs de arquivo, estilos de log WS e formatação do console
title: Logs do Gateway
summary: Superfícies de registro, registros em arquivo, estilos de registro WS e formatação do console
title: Registro do Gateway
x-i18n:
generated_at: "2026-05-02T05:47:08Z"
generated_at: "2026-05-05T01:46:33Z"
model: gpt-5.5
provider: openai
source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13
source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246
source_path: gateway/logging.md
workflow: 16
---
# Logs
# Logging
Para uma visão geral voltada ao usuário (CLI + UI de Controle + configuração), consulte [/logging](/pt-BR/logging).
Para uma visão geral voltada ao usuário (CLI + interface de controle + configuração), consulte [/logging](/pt-BR/logging).
OpenClaw tem duas “superfícies” de log:
O OpenClaw tem duas “superfícies” de log:
- **Saída do console** (o que você vê no terminal / UI de Depuração).
- **Logs em arquivo** (linhas JSON) gravados pelo logger do Gateway.
- **Saída do console** (o que você vê no terminal / interface de depuração).
- **Logs de arquivo** (linhas JSON) gravados pelo registrador do Gateway.
## Logger baseado em arquivo
Na inicialização, o Gateway registra o modelo de agente padrão resolvido junto com os
padrões de modo que afetam novas sessões, por exemplo:
```text
agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
```
`thinking` vem do agente padrão, dos parâmetros do modelo ou do padrão global do agente;
quando não está definido, o resumo de inicialização mostra `medium`. `fast` vem do
agente padrão ou dos parâmetros `fastMode` do modelo.
## Registrador baseado em arquivo
- O arquivo de log rotativo padrão fica em `/tmp/openclaw/` (um arquivo por dia): `openclaw-YYYY-MM-DD.log`
- A data usa o fuso horário local do host do Gateway.
- Arquivos de log ativos rotacionam em `logging.maxFileBytes` (padrão: 100 MB), mantendo
- Arquivos de log ativos são rotacionados em `logging.maxFileBytes` (padrão: 100 MB), mantendo
até cinco arquivos numerados e continuando a gravar em um novo arquivo ativo.
- O caminho e o nível do arquivo de log podem ser configurados via `~/.openclaw/openclaw.json`:
- `logging.file`
@ -34,7 +45,7 @@ OpenClaw tem duas “superfícies” de log:
O formato do arquivo é um objeto JSON por linha.
A aba Logs da UI de Controle acompanha esse arquivo via Gateway (`logs.tail`).
A aba Logs da interface de controle acompanha esse arquivo via Gateway (`logs.tail`).
A CLI pode fazer o mesmo:
```bash
@ -43,18 +54,18 @@ openclaw logs --follow
**Detalhado vs. níveis de log**
- **Logs em arquivo** são controlados exclusivamente por `logging.level`.
- **Logs de arquivo** são controlados exclusivamente por `logging.level`.
- `--verbose` afeta apenas a **verbosidade do console** (e o estilo de log WS); ele **não**
aumenta o nível dos logs em arquivo.
- Para capturar detalhes exclusivos do modo detalhado nos logs em arquivo, defina `logging.level` como `debug` ou
aumenta o nível de log do arquivo.
- Para capturar detalhes exclusivos do modo detalhado nos logs de arquivo, defina `logging.level` como `debug` ou
`trace`.
- O registro em log de rastreamento também inclui resumos de tempos de diagnóstico para caminhos críticos selecionados,
como a preparação de fábricas de ferramentas de Plugin. Consulte
- O registro em nível trace também inclui resumos de tempo de diagnóstico para caminhos críticos selecionados,
como a preparação de fábricas de ferramentas de Plugins. Consulte
[/tools/plugin#slow-plugin-tool-setup](/pt-BR/tools/plugin#slow-plugin-tool-setup).
## Captura do console
A CLI captura `console.log/info/warn/error/debug/trace` e os grava nos logs em arquivo,
A CLI captura `console.log/info/warn/error/debug/trace` e os grava nos logs de arquivo,
enquanto ainda imprime em stdout/stderr.
Você pode ajustar a verbosidade do console de forma independente via:
@ -64,20 +75,20 @@ Você pode ajustar a verbosidade do console de forma independente via:
## Redação
O OpenClaw pode mascarar tokens sensíveis antes que a saída de log ou transcrição saia do
processo. Essa política de redação de logs é aplicada nos destinos de texto de console, log em arquivo,
registro de log OTLP e transcrição de sessão, portanto valores de segredo correspondentes são
O OpenClaw pode mascarar tokens sensíveis antes que a saída de log ou de transcrição saia do
processo. Essa política de redação de logs é aplicada aos destinos de texto do console,
log de arquivo, registro de log OTLP e transcrição de sessão, para que valores secretos correspondentes sejam
mascarados antes que linhas JSONL ou mensagens sejam gravadas em disco.
- `logging.redactSensitive`: `off` | `tools` (padrão: `tools`)
- `logging.redactPatterns`: array de strings regex (substitui os padrões)
- Use strings regex brutas (auto `gi`), ou `/pattern/flags` se precisar de flags personalizadas.
- `logging.redactPatterns`: matriz de strings regex (substitui os padrões)
- Use strings regex brutas (`gi` automático), ou `/pattern/flags` se precisar de flags personalizadas.
- Correspondências são mascaradas mantendo os primeiros 6 + últimos 4 caracteres (comprimento >= 18), caso contrário `***`.
- Os padrões cobrem atribuições de chaves comuns, flags de CLI, campos JSON, cabeçalhos bearer, blocos PEM, prefixos populares de token e nomes de campos de credenciais de pagamento, como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento.
- Os padrões cobrem atribuições comuns de chaves, flags de CLI, campos JSON, cabeçalhos bearer, blocos PEM, prefixos populares de tokens e nomes de campos de credenciais de pagamento, como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento.
Alguns limites de segurança sempre fazem a redação, independentemente de `logging.redactSensitive`.
Isso inclui eventos de chamada de ferramenta da UI de Controle, saída da ferramenta `sessions_history`,
exportações de suporte de diagnóstico, observações de erro de provedores, exibição de comandos de aprovação exec
Alguns limites de segurança sempre fazem redação, independentemente de `logging.redactSensitive`.
Isso inclui eventos de chamadas de ferramentas da interface de controle, saída da ferramenta `sessions_history`,
exportações de suporte a diagnósticos, observações de erros de provedores, exibição de comandos de aprovação de exec
e logs do protocolo WebSocket do Gateway. Essas superfícies ainda podem usar
`logging.redactPatterns` como padrões adicionais, mas `redactSensitive: "off"`
não faz com que elas emitam segredos brutos.
@ -88,7 +99,7 @@ O Gateway imprime logs do protocolo WebSocket em dois modos:
- **Modo normal (sem `--verbose`)**: apenas resultados RPC “interessantes” são impressos:
- erros (`ok=false`)
- chamadas lentas (limite padrão: `>= 50ms`)
- chamadas lentas (limiar padrão: `>= 50ms`)
- erros de análise
- **Modo detalhado (`--verbose`)**: imprime todo o tráfego de solicitação/resposta WS.
@ -114,27 +125,27 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Formatação do console (log de subsistema)
## Formatação do console (registro por subsistema)
O formatador de console é **consciente de TTY** e imprime linhas consistentes e prefixadas.
Loggers de subsistema mantêm a saída agrupada e fácil de examinar.
O formatador do console é **compatível com TTY** e imprime linhas consistentes, com prefixos.
Registradores de subsistema mantêm a saída agrupada e fácil de examinar.
Comportamento:
- **Prefixos de subsistema** em todas as linhas (por exemplo, `[gateway]`, `[canvas]`, `[tailscale]`)
- **Prefixos de subsistema** em cada linha (por exemplo, `[gateway]`, `[canvas]`, `[tailscale]`)
- **Cores de subsistema** (estáveis por subsistema), além de coloração por nível
- **Cor quando a saída é um TTY ou o ambiente parece um terminal rico** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respeita `NO_COLOR`
- **Prefixos de subsistema encurtados**: descarta `gateway/` + `channels/` iniciais, mantém os últimos 2 segmentos (por exemplo, `whatsapp/outbound`)
- **Sub-loggers por subsistema** (prefixo automático + campo estruturado `{ subsystem }`)
- **Cor quando a saída é um TTY ou o ambiente parece um terminal avançado** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), respeita `NO_COLOR`
- **Prefixos de subsistema encurtados**: remove `gateway/` + `channels/` iniciais, mantém os últimos 2 segmentos (por exemplo, `whatsapp/outbound`)
- **Sub-registradores por subsistema** (prefixo automático + campo estruturado `{ subsystem }`)
- **`logRaw()`** para saída de QR/UX (sem prefixo, sem formatação)
- **Estilos de console** (por exemplo, `pretty | compact | json`)
- **Nível de log do console** separado do nível de log em arquivo (o arquivo mantém todos os detalhes quando `logging.level` está definido como `debug`/`trace`)
- **Nível de log do console** separado do nível de log do arquivo (o arquivo mantém detalhes completos quando `logging.level` está definido como `debug`/`trace`)
- **Corpos de mensagens do WhatsApp** são registrados em `debug` (use `--verbose` para vê-los)
Isso mantém os logs em arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar.
Isso mantém os logs de arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar.
## Relacionados
## Relacionado
- [Logs](/pt-BR/logging)
- [Logging](/pt-BR/logging)
- [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry)
- [Exportação de diagnóstico](/pt-BR/gateway/diagnostics)
- [Exportação de diagnósticos](/pt-BR/gateway/diagnostics)

147
docs/pt-BR/help/debugging.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Você precisa inspecionar a saída bruta do modelo em busca de vazamento de raciocínio
- Você quer executar o Gateway em modo watch enquanto itera
- Você precisa inspecionar a saída bruta do modelo para detectar vazamento de raciocínio
- Você quer executar o Gateway em modo de observação enquanto itera
- Você precisa de um fluxo de trabalho de depuração repetível
summary: 'Ferramentas de depuração: modo de monitoramento, streams brutos do modelo e rastreamento de vazamento de raciocínio'
summary: 'Ferramentas de depuração: modo de observação, fluxos brutos do modelo e rastreamento de vazamento de raciocínio'
title: Depuração
x-i18n:
generated_at: "2026-05-03T21:33:55Z"
generated_at: "2026-05-05T01:47:14Z"
model: gpt-5.5
provider: openai
source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc
source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec
source_path: help/debugging.md
workflow: 16
---
Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio no texto normal.
Auxiliares de depuração para saída de streaming, especialmente quando um provedor mistura raciocínio ao texto normal.
## Substituições de depuração em runtime
@ -36,7 +36,7 @@ Exemplos:
## Saída de rastreamento da sessão
Use `/trace` quando quiser ver linhas de rastreamento/depuração pertencentes ao Plugin em uma sessão
sem ativar o modo verboso completo.
sem ativar o modo detalhado completo.
Exemplos:
@ -46,16 +46,16 @@ Exemplos:
/trace off
```
Use `/trace` para diagnósticos de Plugin, como resumos de depuração do Active Memory.
Continue usando `/verbose` para saída verbosa normal de status/ferramentas, e continue usando
Use `/trace` para diagnósticos de Plugin, como resumos de depuração de Active Memory.
Continue usando `/verbose` para saída detalhada normal de status/ferramentas, e continue usando
`/debug` para substituições de configuração somente em runtime.
## Rastreamento do ciclo de vida do Plugin
Use `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` quando comandos de ciclo de vida de Plugin parecerem lentos
Use `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` quando os comandos de ciclo de vida do Plugin parecerem lentos
e você precisar de uma decomposição de fases integrada para metadados, descoberta, registro,
espelho de runtime, mutação de configuração e trabalho de atualização de plugins. O rastreamento é opcional e escreve
em stderr, então a saída JSON do comando continua analisável.
espelho de runtime, mutação de configuração e trabalho de atualização do Plugin. O rastreamento é opcional e escreve
em stderr, então a saída JSON do comando permanece analisável.
Exemplo:
@ -63,7 +63,7 @@ Exemplo:
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```
Exemplo de saída:
Saída de exemplo:
```text
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
@ -71,12 +71,12 @@ Exemplo de saída:
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```
Use isto para investigação de ciclo de vida de Plugin antes de recorrer a um profiler de CPU.
Se o comando estiver sendo executado a partir de um checkout do código-fonte, prefira medir o runtime
Use isso para investigação do ciclo de vida do Plugin antes de recorrer a um criador de perfil de CPU.
Se o comando estiver sendo executado a partir de um checkout de código-fonte, prefira medir o runtime
compilado com `node dist/entry.js ...` após `pnpm build`; `pnpm openclaw ...`
também mede a sobrecarga do executor de código-fonte.
## Inicialização da CLI e profiling de comandos
## Inicialização da CLI e criação de perfil de comandos
Use o benchmark de inicialização versionado quando um comando parecer lento:
@ -86,7 +86,7 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```
Para profiling avulso pelo executor de código-fonte normal, defina
Para criação de perfil pontual pelo executor de código-fonte normal, defina
`OPENCLAW_RUN_NODE_CPU_PROF_DIR`:
```bash
@ -94,11 +94,21 @@ OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```
O executor de código-fonte adiciona flags de perfil de CPU do Node e grava um `.cpuprofile` para o
comando. Use isto antes de adicionar instrumentação temporária ao código do comando.
comando. Use isso antes de adicionar instrumentação temporária ao código do comando.
## Modo watch do Gateway
Para travamentos de inicialização que parecem trabalho síncrono de sistema de arquivos ou carregador de módulos,
adicione a flag de rastreamento de E/S síncrona do Node pelo executor de código-fonte:
Para iteração rápida, execute o gateway sob o observador de arquivos:
```bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```
`pnpm gateway:watch` habilita essa flag por padrão para o filho Gateway observado.
Defina `OPENCLAW_TRACE_SYNC_IO=0` para suprimir a saída de rastreamento de E/S síncrona do Node no modo de observação.
## Modo de observação do Gateway
Para iteração rápida, execute o Gateway sob o observador de arquivos:
```bash
pnpm gateway:watch
@ -107,14 +117,14 @@ pnpm gateway:watch
Por padrão, isso inicia ou reinicia uma sessão tmux chamada
`openclaw-gateway-watch-main` (ou uma variante específica de perfil/porta, como
`openclaw-gateway-watch-dev-19001`) e anexa automaticamente a partir de terminais interativos.
Shells não interativos, CI e chamadas de execução de agentes permanecem desanexados e imprimem
instruções de anexação em vez disso. Anexe manualmente quando necessário:
Shells não interativos, CI e chamadas exec de agente permanecem desanexados e imprimem instruções
de anexação. Anexe manualmente quando necessário:
```bash
tmux attach -t openclaw-gateway-watch-main
```
O painel do tmux executa o observador bruto:
O painel tmux executa o observador bruto:
```bash
node scripts/watch-node.mjs gateway --force
@ -124,68 +134,73 @@ Use o modo em primeiro plano quando tmux não for desejado:
```bash
pnpm gateway:watch:raw
# or
# ou
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```
Desative a anexação automática mantendo o gerenciamento por tmux:
Desative a anexação automática mantendo o gerenciamento do tmux:
```bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```
Faça profiling do tempo de CPU do Gateway observado ao depurar hotspots de inicialização/runtime:
Crie perfil do tempo de CPU do Gateway observado ao depurar pontos críticos de inicialização/runtime:
```bash
pnpm gateway:watch --benchmark
```
O wrapper de watch consome `--benchmark` antes de invocar o Gateway e grava
um `.cpuprofile` V8 por saída de filho do Gateway em
O wrapper de observação consome `--benchmark` antes de invocar o Gateway e grava
um `.cpuprofile` V8 por saída de filho Gateway em
`.artifacts/gateway-watch-profiles/`. Pare ou reinicie o gateway observado para
descarregar o perfil atual, então abra-o com Chrome DevTools ou Speedscope:
descarregar o perfil atual, depois abra-o com Chrome DevTools ou Speedscope:
```bash
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```
Use `--benchmark-dir <path>` quando quiser perfis em outro lugar.
Use `--benchmark-no-force` quando quiser que o filho com benchmark pule a limpeza de porta
`--force` padrão e falhe rapidamente se a porta do Gateway já estiver em
Use `--benchmark-no-force` quando quiser que o filho sob benchmark ignore a
limpeza de porta padrão `--force` e falhe rapidamente se a porta do Gateway já estiver em
uso.
O modo benchmark suprime por padrão o excesso de rastreamento de E/S síncrona. Defina
`OPENCLAW_TRACE_SYNC_IO=1` com `--benchmark` quando quiser explicitamente perfis de CPU
e rastreamentos de pilha de E/S síncrona do Node. No modo benchmark, esses blocos de rastreamento
são gravados em `gateway-watch-output.log` no diretório do benchmark e
filtrados do painel do terminal; os logs normais do Gateway continuam visíveis.
O wrapper tmux leva seletores comuns de runtime não secretos, como
O wrapper tmux carrega seletores comuns de runtime não secretos, como
`OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`,
`OPENCLAW_GATEWAY_PORT` e `OPENCLAW_SKIP_CHANNELS`, para dentro do painel. Coloque
credenciais de provedor no seu perfil/configuração normal, ou use o modo bruto em primeiro plano
para segredos efêmeros avulsos.
para segredos efêmeros pontuais.
Se o Gateway observado sair durante a inicialização, o observador executa
`openclaw doctor --fix --non-interactive` uma vez e reinicia o filho do Gateway.
Use `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` quando quiser a falha de inicialização
original sem a etapa de reparo apenas de desenvolvimento.
O painel tmux gerenciado também usa logs coloridos do Gateway por padrão para legibilidade;
`openclaw doctor --fix --non-interactive` uma vez e reinicia o filho Gateway.
Use `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` quando quiser a falha original de inicialização
sem a passagem de reparo exclusiva de desenvolvimento.
O painel tmux gerenciado também usa por padrão logs coloridos do Gateway para legibilidade;
defina `FORCE_COLOR=0` ao iniciar `pnpm gateway:watch` para desativar a saída ANSI.
O observador reinicia em arquivos relevantes para build sob `src/`, arquivos-fonte de extensão,
O observador reinicia em arquivos relevantes para build em `src/`, arquivos de código-fonte de extensão,
metadados `package.json` e `openclaw.plugin.json` de extensão, `tsconfig.json`,
`package.json` e `tsdown.config.ts`. Alterações de metadados de extensão reiniciam o
gateway sem forçar uma rebuild de `tsdown`; alterações de código-fonte e configuração ainda
`package.json` e `tsdown.config.ts`. Alterações em metadados de extensão reiniciam o
gateway sem forçar uma recompilação `tsdown`; alterações de código-fonte e configuração ainda
recompilam `dist` primeiro.
Adicione quaisquer flags da CLI do gateway após `gateway:watch` e elas serão repassadas em
cada reinicialização. Executar novamente o mesmo comando de watch recria o painel tmux nomeado, e
o observador bruto ainda mantém seu bloqueio de observador único, de modo que pais observadores duplicados
Adicione quaisquer flags de CLI do gateway após `gateway:watch` e elas serão repassadas em
cada reinicialização. Reexecutar o mesmo comando de observação recria o painel tmux nomeado, e
o observador bruto ainda mantém seu bloqueio de observador único para que pais observadores duplicados
sejam substituídos em vez de se acumularem.
## Perfil de desenvolvimento + gateway de desenvolvimento (--dev)
Use o perfil de desenvolvimento para isolar o estado e iniciar uma configuração segura e descartável para
depuração. Existem **duas** flags `--dev`:
Use o perfil de desenvolvimento para isolar estado e iniciar uma configuração segura e descartável para
depuração. Há **duas** flags `--dev`:
- **`--dev` global (perfil):** isola o estado em `~/.openclaw-dev` e
define a porta padrão do gateway como `19001` (portas derivadas se deslocam junto com ela).
- **`gateway --dev`: diz ao Gateway para criar automaticamente uma configuração padrão +
workspace** quando ausentes (e pular BOOTSTRAP.md).
define a porta padrão do gateway como `19001` (portas derivadas mudam junto).
- **`gateway --dev`: informa ao Gateway para criar automaticamente uma configuração padrão +
workspace** quando ausentes (e ignorar BOOTSTRAP.md).
Fluxo recomendado (perfil de desenvolvimento + bootstrap de desenvolvimento):
@ -196,31 +211,31 @@ OPENCLAW_PROFILE=dev openclaw tui
Se você ainda não tiver uma instalação global, execute a CLI via `pnpm openclaw ...`.
O que isto faz:
O que isso faz:
1. **Isolamento de perfil** (`--dev` global)
- `OPENCLAW_PROFILE=dev`
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas se deslocam de acordo)
- `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas mudam de acordo)
2. **Bootstrap de desenvolvimento** (`gateway --dev`)
- Grava uma configuração mínima se ausente (`gateway.mode=local`, vincula a loopback).
- Define `agent.workspace` para o workspace de desenvolvimento.
- Define `agent.workspace` como o workspace de desenvolvimento.
- Define `agent.skipBootstrap=true` (sem BOOTSTRAP.md).
- Inicializa os arquivos do workspace se ausentes:
- Semeia os arquivos do workspace se ausentes:
`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.
- Identidade padrão: **C3‑PO** (droide de protocolo).
- Pula provedores de canal no modo de desenvolvimento (`OPENCLAW_SKIP_CHANNELS=1`).
- Ignora provedores de canal no modo de desenvolvimento (`OPENCLAW_SKIP_CHANNELS=1`).
Fluxo de reset (início limpo):
Fluxo de redefinição (começo limpo):
```bash
pnpm gateway:dev:reset
```
<Note>
`--dev` é uma flag de perfil **global** e é consumida por alguns executores. Se precisar escrevê-la explicitamente, use o formato de variável de ambiente:
`--dev` é uma flag de perfil **global** e é consumida por alguns executores. Se precisar escrevê-la explicitamente, use a forma de variável de ambiente:
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -229,10 +244,10 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
</Note>
`--reset` apaga configuração, credenciais, sessões e o workspace de desenvolvimento (usando
`trash`, não `rm`), então recria a configuração de desenvolvimento padrão.
`trash`, não `rm`), depois recria a configuração padrão de desenvolvimento.
<Tip>
Se um gateway que não seja de desenvolvimento já estiver em execução (launchd ou systemd), pare-o primeiro:
Se um gateway que não é de desenvolvimento já estiver em execução (launchd ou systemd), pare-o primeiro:
```bash
openclaw gateway stop
@ -243,16 +258,16 @@ openclaw gateway stop
## Registro de stream bruto (OpenClaw)
OpenClaw pode registrar o **stream bruto do assistente** antes de qualquer filtragem/formatação.
Esta é a melhor maneira de ver se o raciocínio está chegando como deltas de texto simples
Esta é a melhor forma de ver se o raciocínio está chegando como deltas de texto simples
(ou como blocos de pensamento separados).
Ative via CLI:
Habilite pela CLI:
```bash
pnpm gateway:watch --raw-stream
```
Substituição de caminho opcional:
Substituição opcional de caminho:
```bash
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
@ -269,9 +284,9 @@ Arquivo padrão:
`~/.openclaw/logs/raw-stream.jsonl`
## Registro de chunk bruto (pi-mono)
## Registro de fragmentos brutos (pi-mono)
Para capturar **chunks brutos compatíveis com OpenAI** antes de serem analisados em blocos,
Para capturar **fragmentos brutos compatíveis com OpenAI** antes que sejam analisados em blocos,
pi-mono expõe um logger separado:
```bash
@ -288,16 +303,16 @@ Arquivo padrão:
`~/.pi-mono/logs/raw-openai-completions.jsonl`
> Observação: isto é emitido apenas por processos que usam o provedor
> Observação: isso é emitido somente por processos que usam o provedor
> `openai-completions` do pi-mono.
## Notas de segurança
- Logs de stream bruto podem incluir prompts completos, saída de ferramentas e dados de usuário.
- Logs de stream bruto podem incluir prompts completos, saída de ferramentas e dados de usuários.
- Mantenha os logs locais e exclua-os após a depuração.
- Se você compartilhar logs, remova segredos e PII primeiro.
## Relacionado
## Relacionados
- [Solução de problemas](/pt-BR/help/troubleshooting)
- [FAQ](/pt-BR/help/faq)
- [Perguntas frequentes](/pt-BR/help/faq)

229
docs/pt-BR/help/faq-models.md
View File

@ -1,59 +1,59 @@
---
read_when:
- Escolher ou alternar modelos, configurar apelidos
- Depuração do failover de modelo / "Todos os modelos falharam"
- Entendendo os perfis de autenticação e como gerenciá-los
- Escolha ou troca de modelos, configuração de aliases
- Depuração da alternância de modelo em caso de falha / "Todos os modelos falharam"
- Entendendo perfis de autenticação e como gerenciá-los
sidebarTitle: Models FAQ
summary: 'Perguntas frequentes: padrões de modelo, seleção, apelidos, troca, alternância em caso de falha e perfis de autenticação'
title: 'Perguntas frequentes: modelos e autenticação'
x-i18n:
generated_at: "2026-05-02T05:49:13Z"
generated_at: "2026-05-05T01:47:30Z"
model: gpt-5.5
provider: openai
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
source_path: help/faq-models.md
workflow: 16
---
Perguntas e respostas sobre modelos e perfis de autenticação. Para configuração, sessões, gateway, canais e
solução de problemas, consulte o [FAQ](/pt-BR/help/faq) principal.
P&R sobre modelos e perfis de autenticação. Para configuração, sessões, gateway, canais e
solução de problemas, consulte a [FAQ](/pt-BR/help/faq) principal.
## Modelos: padrões, seleção, aliases, troca
<AccordionGroup>
<Accordion title='O que é o "modelo padrão"?'>
<Accordion title='What is the "default model"?'>
O modelo padrão do OpenClaw é o que você definir como:
```
agents.defaults.model.primary
```
Modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.5` ou `openai-codex/gpt-5.5`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato, e só então recorre ao provedor padrão configurado como um caminho de compatibilidade obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Ainda assim, você deve definir `provider/model` **explicitamente**.
Modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.5` ou `openai-codex/gpt-5.5`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para esse ID exato de modelo e só então recorre ao provedor padrão configurado como um caminho de compatibilidade obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Mesmo assim, você deve definir `provider/model` **explicitamente**.
</Accordion>
<Accordion title="Que modelo você recomenda?">
**Padrão recomendado:** use o modelo mais forte de última geração disponível na sua pilha de provedores.
**Para agentes com ferramentas habilitadas ou entrada não confiável:** priorize a capacidade do modelo em vez do custo.
**Para chat rotineiro/de baixo risco:** use modelos de fallback mais baratos e roteie por função do agente.
<Accordion title="What model do you recommend?">
**Padrão recomendado:** use o modelo de geração mais recente e mais forte disponível na sua pilha de provedores.
**Para agentes com ferramentas habilitadas ou entrada não confiável:** priorize a força do modelo em vez do custo.
**Para conversas rotineiras/de baixo risco:** use modelos de fallback mais baratos e roteie por função do agente.
MiniMax tem sua própria documentação: [MiniMax](/pt-BR/providers/minimax) e
O MiniMax tem sua própria documentação: [MiniMax](/pt-BR/providers/minimax) e
[Modelos locais](/pt-BR/gateway/local-models).
Regra prática: use o **melhor modelo que você puder pagar** para trabalho de alto risco e um modelo mais barato
para chat rotineiro ou resumos. Você pode rotear modelos por agente e usar subagentes para
Regra prática: use o **melhor modelo que você puder pagar** para trabalho de alto risco, e um modelo mais barato
para conversas rotineiras ou resumos. Você pode rotear modelos por agente e usar subagentes para
paralelizar tarefas longas (cada subagente consome tokens). Consulte [Modelos](/pt-BR/concepts/models) e
[Subagentes](/pt-BR/tools/subagents).
Aviso importante: modelos mais fracos ou excessivamente quantizados são mais vulneráveis a injeção de prompt
Aviso forte: modelos mais fracos/com quantização excessiva são mais vulneráveis a injeção de prompt
e comportamento inseguro. Consulte [Segurança](/pt-BR/gateway/security).
Mais contexto: [Modelos](/pt-BR/concepts/models).
</Accordion>
<Accordion title="Como troco de modelo sem apagar minha configuração?">
Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituições completas da configuração.
<Accordion title="How do I switch models without wiping my config?">
Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituições completas de configuração.
Opções seguras:
@ -63,20 +63,20 @@ x-i18n:
- edite `agents.defaults.model` em `~/.openclaw/openclaw.json`
Evite `config.apply` com um objeto parcial, a menos que você pretenda substituir toda a configuração.
Para edições por RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload de lookup fornece o caminho normalizado, documentação/restrições superficiais do schema e resumos dos filhos imediatos.
Para edições por RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload de lookup fornece o caminho normalizado, documentos/restrições rasos do esquema e resumos imediatos dos filhos.
para atualizações parciais.
Se você sobrescreveu a configuração, restaure a partir do backup ou execute novamente `openclaw doctor` para reparar.
Se você sobrescreveu a configuração, restaure a partir de um backup ou execute novamente `openclaw doctor` para reparar.
Documentação: [Modelos](/pt-BR/concepts/models), [Configurar](/pt-BR/cli/configure), [Configuração](/pt-BR/cli/config), [Doctor](/pt-BR/gateway/doctor).
</Accordion>
<Accordion title="Posso usar modelos auto-hospedados (llama.cpp, vLLM, Ollama)?">
<Accordion title="Can I use self-hosted models (llama.cpp, vLLM, Ollama)?">
Sim. Ollama é o caminho mais fácil para modelos locais.
Configuração mais rápida:
1. Instale o Ollama de `https://ollama.com/download`
1. Instale o Ollama a partir de `https://ollama.com/download`
2. Baixe um modelo local, como `ollama pull gemma4`
3. Se também quiser modelos em nuvem, execute `ollama signin`
4. Execute `openclaw onboard` e escolha `Ollama`
@ -84,13 +84,13 @@ x-i18n:
Observações:
- `Cloud + Local` fornece modelos em nuvem mais seus modelos Ollama locais
- modelos em nuvem como `kimi-k2.5:cloud` não precisam de download local
- `Cloud + Local` oferece modelos em nuvem mais seus modelos Ollama locais
- modelos em nuvem como `kimi-k2.5:cloud` não precisam de um download local
- para troca manual, use `openclaw models list` e `openclaw models set ollama/<model>`
Observação de segurança: modelos menores ou muito quantizados são mais vulneráveis a injeção de prompt.
Observação de segurança: modelos menores ou fortemente quantizados são mais vulneráveis a injeção de prompt.
Recomendamos fortemente **modelos grandes** para qualquer bot que possa usar ferramentas.
Se ainda quiser modelos pequenos, habilite sandboxing e allowlists rigorosas de ferramentas.
Se ainda quiser modelos pequenos, habilite sandboxing e allowlists estritas de ferramentas.
Documentação: [Ollama](/pt-BR/providers/ollama), [Modelos locais](/pt-BR/gateway/local-models),
[Provedores de modelo](/pt-BR/concepts/model-providers), [Segurança](/pt-BR/gateway/security),
@ -98,14 +98,14 @@ x-i18n:
</Accordion>
<Accordion title="Quais modelos OpenClaw, Flawd e Krill usam?">
- Essas implantações podem diferir e mudar ao longo do tempo; não há uma recomendação fixa de provedor.
- Verifique a configuração atual de runtime em cada gateway com `openclaw models status`.
- Para agentes sensíveis à segurança/com ferramentas habilitadas, use o modelo mais forte de última geração disponível.
<Accordion title="What do OpenClaw, Flawd, and Krill use for models?">
- Essas implantações podem diferir e mudar com o tempo; não há recomendação fixa de provedor.
- Verifique a configuração atual em tempo de execução em cada Gateway com `openclaw models status`.
- Para agentes sensíveis à segurança/com ferramentas habilitadas, use o modelo de geração mais recente e mais forte disponível.
</Accordion>
<Accordion title="Como troco de modelo em tempo real (sem reiniciar)?">
<Accordion title="How do I switch models on the fly (without restarting)?">
Use o comando `/model` como uma mensagem independente:
```
@ -118,9 +118,9 @@ x-i18n:
/model gemini-flash-lite
```
Esses são os aliases integrados. Aliases personalizados podem ser adicionados por meio de `agents.defaults.models`.
Estes são os aliases integrados. Aliases personalizados podem ser adicionados via `agents.defaults.models`.
Você pode listar os modelos disponíveis com `/model`, `/model list` ou `/model status`.
Você pode listar modelos disponíveis com `/model`, `/model list` ou `/model status`.
`/model` (e `/model list`) mostra um seletor compacto e numerado. Selecione por número:
@ -146,27 +146,27 @@ x-i18n:
/model anthropic/claude-opus-4-6
```
Se quiser voltar ao padrão, selecione-o em `/model` (ou envie `/model <default provider/model>`).
Se quiser voltar ao padrão, escolha-o em `/model` (ou envie `/model <default provider/model>`).
Use `/model status` para confirmar qual perfil de autenticação está ativo.
</Accordion>
<Accordion title="Posso usar GPT 5.5 para tarefas diárias e Codex 5.5 para programação?">
<Accordion title="Can I use GPT 5.5 for daily tasks and Codex 5.5 for coding?">
Sim. Trate a escolha do modelo e a escolha do runtime separadamente:
- **Agente de programação Codex nativo:** defina `agents.defaults.model.primary` como `openai/gpt-5.5` e `agents.defaults.agentRuntime.id` como `"codex"`. Faça login com `openclaw models auth login --provider openai-codex` quando quiser autenticação por assinatura ChatGPT/Codex.
- **Tarefas diretas da API da OpenAI por meio do PI:** use `/model openai/gpt-5.5` sem uma substituição de runtime Codex e configure `OPENAI_API_KEY`.
- **OAuth do Codex por meio do PI:** use `/model openai-codex/gpt-5.5` apenas quando você quiser intencionalmente o executor normal do PI com OAuth do Codex.
- **Subagentes:** roteie tarefas de programação para um agente exclusivo de Codex com seu próprio modelo e padrão de `agentRuntime`.
- **Agente de codificação Codex nativo:** defina `agents.defaults.model.primary` como `openai/gpt-5.5` e `agents.defaults.agentRuntime.id` como `"codex"`. Faça login com `openclaw models auth login --provider openai-codex` quando quiser autenticação de assinatura ChatGPT/Codex.
- **Tarefas diretas da API da OpenAI por meio do PI:** use `/model openai/gpt-5.5` sem substituição de runtime Codex e configure `OPENAI_API_KEY`.
- **OAuth do Codex por meio do PI:** use `/model openai-codex/gpt-5.5` apenas quando quiser intencionalmente o executor PI normal com OAuth do Codex.
- **Subagentes:** roteie tarefas de codificação para um agente exclusivo do Codex com seu próprio modelo e padrão de `agentRuntime`.
Consulte [Modelos](/pt-BR/concepts/models) e [Comandos de barra](/pt-BR/tools/slash-commands).
</Accordion>
<Accordion title="Como configuro o modo rápido para GPT 5.5?">
<Accordion title="How do I configure fast mode for GPT 5.5?">
Use uma alternância de sessão ou um padrão de configuração:
- **Por sessão:** envie `/fast on` enquanto a sessão estiver usando `openai/gpt-5.5` ou `openai-codex/gpt-5.5`.
- **Por sessão:** envie `/fast on` enquanto a sessão está usando `openai/gpt-5.5` ou `openai-codex/gpt-5.5`.
- **Padrão por modelo:** defina `agents.defaults.models["openai/gpt-5.5"].params.fastMode` ou `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` como `true`.
Exemplo:
@ -187,39 +187,42 @@ x-i18n:
}
```
Para OpenAI, o modo rápido mapeia para `service_tier = "priority"` em solicitações nativas Responses compatíveis. Substituições de sessão `/fast` têm precedência sobre padrões de configuração.
Para OpenAI, o modo rápido mapeia para `service_tier = "priority"` em solicitações Responses nativas compatíveis. Substituições de sessão `/fast` prevalecem sobre padrões de configuração.
Consulte [Pensamento e modo rápido](/pt-BR/tools/thinking) e [Modo rápido da OpenAI](/pt-BR/providers/openai#fast-mode).
</Accordion>
<Accordion title='Por que vejo "Model ... is not allowed" e depois nenhuma resposta?'>
<Accordion title='Why do I see "Model ... is not allowed" and then no reply?'>
Se `agents.defaults.models` estiver definido, ele se torna a **allowlist** para `/model` e quaisquer
substituições de sessão. Escolher um modelo que não esteja nessa lista retorna:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
Esse erro é retornado **em vez de** uma resposta normal. Correção: adicione o modelo a
`agents.defaults.models`, remova a allowlist ou escolha um modelo em `/model list`.
Se o comando também incluiu `--runtime codex`, adicione o modelo primeiro e tente novamente
o mesmo comando `/model provider/model --runtime codex`.
</Accordion>
<Accordion title='Por que vejo "Unknown model: minimax/MiniMax-M2.7"?'>
<Accordion title='Why do I see "Unknown model: minimax/MiniMax-M2.7"?'>
Isso significa que o **provedor não está configurado** (nenhuma configuração de provedor MiniMax ou perfil de autenticação
foi encontrado), então o modelo não pode ser resolvido.
Checklist de correção:
1. Atualize para uma versão atual do OpenClaw (ou execute a partir de `main` no código-fonte) e reinicie o gateway.
2. Certifique-se de que o MiniMax esteja configurado (assistente ou JSON), ou que a autenticação do MiniMax
exista no env/perfis de autenticação para que o provedor correspondente possa ser injetado
(`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` ou OAuth do MiniMax armazenado
1. Atualize para uma versão atual do OpenClaw (ou execute a partir do `main` do código-fonte) e reinicie o Gateway.
2. Certifique-se de que o MiniMax está configurado (assistente ou JSON), ou que a autenticação do MiniMax
existe em env/perfis de autenticação para que o provedor correspondente possa ser injetado
(`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` ou OAuth MiniMax armazenado
para `minimax-portal`).
3. Use o ID de modelo exato (diferencia maiúsculas de minúsculas) para seu caminho de autenticação:
`minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração com chave de API,
ou `minimax-portal/MiniMax-M2.7` /
3. Use o ID exato do modelo (diferencia maiúsculas de minúsculas) para o seu caminho de autenticação:
`minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração
com chave de API, ou `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` para configuração com OAuth.
4. Execute:
@ -227,13 +230,13 @@ x-i18n:
openclaw models list
```
e escolha na lista (ou `/model list` no chat).
e escolha a partir da lista (ou `/model list` no chat).
Consulte [MiniMax](/pt-BR/providers/minimax) e [Modelos](/pt-BR/concepts/models).
</Accordion>
<Accordion title="Posso usar MiniMax como padrão e OpenAI para tarefas complexas?">
<Accordion title="Can I use MiniMax as my default and OpenAI for complex tasks?">
Sim. Use **MiniMax como padrão** e troque de modelo **por sessão** quando necessário.
Fallbacks são para **erros**, não para "tarefas difíceis", então use `/model` ou um agente separado.
@ -270,7 +273,7 @@ x-i18n:
</Accordion>
<Accordion title="opus / sonnet / gpt são atalhos integrados?">
<Accordion title="Are opus / sonnet / gpt built-in shortcuts?">
Sim. O OpenClaw inclui alguns atalhos padrão (aplicados apenas quando o modelo existe em `agents.defaults.models`):
- `opus` → `anthropic/claude-opus-4-6`
@ -282,11 +285,11 @@ x-i18n:
- `gemini-flash` → `google/gemini-3-flash-preview`
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
Se você definir seu próprio alias com o mesmo nome, o seu valor prevalece.
Se você definir seu próprio alias com o mesmo nome, seu valor prevalece.
</Accordion>
<Accordion title="Como defino/substituo atalhos de modelo (aliases)?">
<Accordion title="How do I define/override model shortcuts (aliases)?">
Aliases vêm de `agents.defaults.models.<modelId>.alias`. Exemplo:
```json5
@ -308,8 +311,8 @@ x-i18n:
</Accordion>
<Accordion title="Como adiciono modelos de outros provedores, como OpenRouter ou Z.AI?">
OpenRouter (pagamento por token; muitos modelos):
<Accordion title="How do I add models from other providers like OpenRouter or Z.AI?">
OpenRouter (pague por token; muitos modelos):
```json5
{
@ -337,12 +340,12 @@ x-i18n:
}
```
Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`).
Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, você receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`).
**Nenhuma chave de API encontrada para o provedor após adicionar um novo agente**
Isso geralmente significa que o **novo agente** tem um armazenamento de autenticação vazio. A autenticação é por agente e
fica armazenada em:
armazenada em:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
@ -351,57 +354,57 @@ x-i18n:
Opções de correção:
- Execute `openclaw agents add <id>` e configure a autenticação durante o assistente.
- Ou copie apenas perfis portáveis estáticos de `api_key` / `token` do armazenamento de autenticação do agente principal para o armazenamento de autenticação do novo agente.
- Para perfis OAuth, entre a partir do novo agente quando ele precisar da própria conta; caso contrário, o OpenClaw pode ler o agente padrão/principal sem clonar tokens de atualização.
- Ou copie apenas perfis estáticos portáteis de `api_key` / `token` do armazenamento de autenticação do agente principal para o armazenamento de autenticação do novo agente.
- Para perfis OAuth, faça login a partir do novo agente quando ele precisar da própria conta; caso contrário, o OpenClaw pode ler o agente padrão/principal sem clonar tokens de atualização.
**Não** reutilize `agentDir` entre agentes; isso causa colisões de autenticação/sessão.
</Accordion>
</AccordionGroup>
## Failover de modelo e "Todos os modelos falharam"
## Failover de modelos e "Todos os modelos falharam"
<AccordionGroup>
<Accordion title="Como funciona o failover?">
<Accordion title="Como o failover funciona?">
O failover acontece em duas etapas:
1. **Rotação de perfil de autenticação** dentro do mesmo provedor.
1. **Rotação de perfis de autenticação** dentro do mesmo provedor.
2. **Fallback de modelo** para o próximo modelo em `agents.defaults.model.fallbacks`.
Cooldowns se aplicam a perfis com falha (backoff exponencial), então o OpenClaw pode continuar respondendo mesmo quando um provedor está com limite de taxa ou falhando temporariamente.
Cooldowns se aplicam aos perfis com falha (backoff exponencial), então o OpenClaw pode continuar respondendo mesmo quando um provedor está limitado por taxa ou falhando temporariamente.
O bucket de limite de taxa inclui mais do que respostas `429` simples. O OpenClaw
também trata mensagens como `Too many concurrent requests`,
`ThrottlingException`, `concurrency limit reached`,
`workers_ai ... quota limit exceeded`, `resource exhausted` e limites periódicos
de janela de uso (`weekly/monthly limit reached`) como limites de taxa
que justificam failover.
de janelas de uso (`weekly/monthly limit reached`) como limites de taxa
elegíveis para failover.
Algumas respostas que parecem cobrança não são `402`, e algumas respostas HTTP `402`
Algumas respostas que parecem de cobrança não são `402`, e algumas respostas HTTP `402`
também permanecem nesse bucket transitório. Se um provedor retornar
texto explícito de cobrança em `401` ou `403`, o OpenClaw ainda pode mantê-lo
na faixa de cobrança, mas correspondências de texto específicas de provedor permanecem limitadas ao
provedor que as possui (por exemplo, OpenRouter `Key limit exceeded`). Se uma mensagem `402`
parecer, em vez disso, uma janela de uso retentável ou
texto explícito de cobrança em `401` ou `403`, o OpenClaw ainda poderá manter isso na
faixa de cobrança, mas os correspondentes de texto específicos de provedor permanecem no escopo do
provedor ao qual pertencem (por exemplo, OpenRouter `Key limit exceeded`). Se uma mensagem `402`
parecer, em vez disso, uma janela de uso repetível ou
limite de gastos de organização/workspace (`daily limit reached, resets tomorrow`,
`organization spending limit exceeded`), o OpenClaw a trata como
`organization spending limit exceeded`), o OpenClaw a tratará como
`rate_limit`, não como uma desativação longa por cobrança.
Erros de estouro de contexto são diferentes: assinaturas como
`request_too_large`, `input exceeds the maximum number of tokens`,
`input token count exceeds the maximum number of input tokens`,
`input is too long for the model` ou `ollama error: context length
exceeded` permanecem no caminho de Compaction/nova tentativa em vez de avançar o
exceeded` permanecem no caminho de Compaction/tentativa novamente em vez de avançar o
fallback de modelo.
Texto genérico de erro de servidor é intencionalmente mais restrito do que "qualquer coisa com
unknown/error nele". O OpenClaw trata formas transitórias com escopo de provedor
como Anthropic puro `An unknown error occurred`, OpenRouter puro
`Provider returned error`, erros de motivo de parada como `Unhandled stop reason:
Texto genérico de erro do servidor é intencionalmente mais restrito do que "qualquer coisa com
unknown/error nele". O OpenClaw trata formatos transitórios com escopo de provedor
como o `An unknown error occurred` simples da Anthropic, o
`Provider returned error` simples do OpenRouter, erros de motivo de parada como `Unhandled stop reason:
error`, payloads JSON `api_error` com texto transitório de servidor
(`internal server error`, `unknown error, 520`, `upstream error`, `backend
error`) e erros de provedor ocupado como `ModelNotReadyException` como
sinais de timeout/sobrecarga que justificam failover quando o contexto do provedor
sinais de timeout/sobrecarga elegíveis para failover quando o contexto do provedor
corresponde.
Texto genérico de fallback interno como `LLM request failed with an unknown
error.` permanece conservador e não aciona fallback de modelo por si só.
@ -425,35 +428,35 @@ x-i18n:
**Checklist de correção para "No credentials found for profile anthropic"**
Isso significa que a execução está fixada em um perfil de autenticação Anthropic, mas o Gateway
Isso significa que a execução está fixada em um perfil de autenticação da Anthropic, mas o Gateway
não consegue encontrá-lo em seu armazenamento de autenticação.
- **Use Claude CLI**
- Execute `openclaw models auth login --provider anthropic --method cli --set-default` no host do Gateway.
- **Use a Claude CLI**
- Execute `openclaw models auth login --provider anthropic --method cli --set-default` no host do gateway.
- **Se você quiser usar uma chave de API em vez disso**
- Coloque `ANTHROPIC_API_KEY` em `~/.openclaw/.env` no **host do Gateway**.
- Coloque `ANTHROPIC_API_KEY` em `~/.openclaw/.env` no **host do gateway**.
- Limpe qualquer ordem fixada que force um perfil ausente:
```bash
openclaw models auth order clear --provider anthropic
```
- **Confirme que você está executando comandos no host do Gateway**
- No modo remoto, os perfis de autenticação ficam na máquina do Gateway, não no seu laptop.
- **Confirme que você está executando comandos no host do gateway**
- No modo remoto, perfis de autenticação ficam na máquina do gateway, não no seu laptop.
</Accordion>
<Accordion title="Por que ele também tentou o Google Gemini e falhou?">
Se sua configuração de modelo incluir Google Gemini como fallback (ou se você mudou para um atalho do Gemini), o OpenClaw o tentará durante o fallback de modelo. Se você não configurou credenciais do Google, verá `No API key found for provider "google"`.
Se sua configuração de modelo incluir Google Gemini como fallback (ou se você tiver mudado para uma forma abreviada do Gemini), o OpenClaw tentará usá-lo durante o fallback de modelo. Se você não tiver configurado credenciais do Google, verá `No API key found for provider "google"`.
Correção: forneça autenticação do Google ou remova/evite modelos do Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não seja roteado para lá.
Correção: forneça autenticação do Google ou remova/evite modelos do Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não direcione para lá.
**Solicitação LLM rejeitada: assinatura de thinking obrigatória (Google Antigravity)**
**Solicitação de LLM rejeitada: assinatura de pensamento necessária (Google Antigravity)**
Causa: o histórico da sessão contém **blocos de thinking sem assinaturas** (muitas vezes de
um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos de thinking.
Causa: o histórico da sessão contém **blocos de pensamento sem assinaturas** (muitas vezes de
um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos de pensamento.
Correção: o OpenClaw agora remove blocos de thinking não assinados para Google Antigravity Claude. Se ainda aparecer, inicie uma **nova sessão** ou defina `/thinking off` para esse agente.
Correção: o OpenClaw agora remove blocos de pensamento não assinados para o Google Antigravity Claude. Se ainda aparecer, inicie uma **nova sessão** ou defina `/thinking off` para esse agente.
</Accordion>
</AccordionGroup>
@ -463,78 +466,80 @@ x-i18n:
Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamento de tokens, padrões de várias contas)
<AccordionGroup>
<Accordion title="O que é um perfil de autenticação?">
<Accordion title="What is an auth profile?">
Um perfil de autenticação é um registro de credencial nomeado (OAuth ou chave de API) vinculado a um provedor. Os perfis ficam em:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
Para inspecionar perfis salvos sem expor segredos, execute `openclaw models auth list` (opcionalmente `--provider <id>` ou `--json`). Consulte [CLI de modelos](/pt-BR/cli/models#openclaw-models-auth-list) para obter detalhes.
</Accordion>
<Accordion title="Quais são IDs de perfil típicos?">
<Accordion title="What are typical profile IDs?">
O OpenClaw usa IDs prefixados por provedor, como:
- `anthropic:default` (comum quando não existe identidade de e-mail)
- `anthropic:default` (comum quando não existe identidade de email)
- `anthropic:<email>` para identidades OAuth
- IDs personalizados que você escolhe (por exemplo, `anthropic:work`)
</Accordion>
<Accordion title="Posso controlar qual perfil de autenticação é tentado primeiro?">
<Accordion title="Can I control which auth profile is tried first?">
Sim. A configuração aceita metadados opcionais para perfis e uma ordenação por provedor (`auth.order.<provider>`). Isso **não** armazena segredos; mapeia IDs para provedor/modo e define a ordem de rotação.
O OpenClaw pode ignorar temporariamente um perfil se ele estiver em um **cooldown** curto (limites de taxa/timeouts/falhas de autenticação) ou em um estado **desativado** mais longo (cobrança/créditos insuficientes). Para inspecionar isso, execute `openclaw models status --json` e verifique `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`.
Cooldowns de limite de taxa podem ter escopo de modelo. Um perfil em cooldown
Cooldowns de limite de taxa podem ter escopo por modelo. Um perfil que está em cooldown
para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor,
enquanto janelas de cobrança/desativação ainda bloqueiam o perfil inteiro.
Você também pode definir uma substituição de ordem **por agente** (armazenada no `auth-state.json` desse agente) via CLI:
Você também pode definir uma substituição de ordem **por agente** (armazenada no `auth-state.json` desse agente) pela CLI:
```bash
# Defaults to the configured default agent (omit --agent)
# Usa como padrão o agente padrão configurado (omita --agent)
openclaw models auth order get --provider anthropic
# Lock rotation to a single profile (only try this one)
# Bloquear a rotação em um único perfil (tentar apenas este)
openclaw models auth order set --provider anthropic anthropic:default
# Or set an explicit order (fallback within provider)
# Ou definir uma ordem explícita (fallback dentro do provedor)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default
# Clear override (fall back to config auth.order / round-robin)
# Limpar substituição (voltar para config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
```
Para direcionar a um agente específico:
Para apontar para um agente específico:
```bash
openclaw models auth order set --provider anthropic --agent main anthropic:default
```
Para verificar o que realmente será tentado, use:
Para verificar o que será realmente tentado, use:
```bash
openclaw models status --probe
```
Se um perfil armazenado for omitido da ordem explícita, o probe reportará
`excluded_by_auth_order` para esse perfil em vez de tentá-lo silenciosamente.
Se um perfil armazenado for omitido da ordem explícita, a sondagem relata
`excluded_by_auth_order` para esse perfil em vez de tentar silenciosamente.
</Accordion>
<Accordion title="OAuth vs chave de API - qual é a diferença?">
<Accordion title="OAuth vs API key - what is the difference?">
O OpenClaw aceita ambos:
- **OAuth** geralmente aproveita acesso por assinatura (quando aplicável).
- **OAuth** muitas vezes aproveita o acesso por assinatura (quando aplicável).
- **Chaves de API** usam cobrança por token.
O assistente oferece suporte explicitamente ao Anthropic Claude CLI, OpenAI Codex OAuth e chaves de API.
O assistente oferece suporte explicitamente à Anthropic Claude CLI, ao OpenAI Codex OAuth e a chaves de API.
</Accordion>
</AccordionGroup>
## Relacionado
## Relacionados
- [FAQ](/pt-BR/help/faq) — a FAQ principal
- [FAQ — início rápido e configuração da primeira execução](/pt-BR/help/faq-first-run)

183
docs/pt-BR/help/testing-updates-plugins.md
View File

@ -1,44 +1,44 @@
---
read_when:
- Alterar o comportamento de atualização, doctor, aceitação de pacote ou instalação de Plugin do OpenClaw
- Preparando ou aprovando uma versão candidata a lançamento
- Depuração de regressões de atualização de pacote, limpeza de dependências de Plugin ou instalação de Plugin
- Preparar ou aprovar uma versão candidata a lançamento
- Depuração de regressões em atualizações de pacote, limpeza de dependências de Plugin ou instalação de Plugin
sidebarTitle: Update and plugin tests
summary: Como o OpenClaw valida caminhos de atualização, migrações de pacotes e o comportamento de instalação/atualização de Plugin
title: 'Testes: atualizações e plugins'
x-i18n:
generated_at: "2026-05-03T21:34:18Z"
generated_at: "2026-05-05T01:47:46Z"
model: gpt-5.5
provider: openai
source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
source_path: help/testing-updates-plugins.md
workflow: 16
---
Esta é a checklist dedicada para validação de atualização e Plugin. O objetivo é
simples: provar que o pacote instalável consegue atualizar o estado real do usuário, reparar estado
legado obsoleto por meio de `doctor` e ainda instalar, carregar, atualizar e desinstalar
Plugins das fontes compatíveis.
simples: provar que o pacote instalável consegue atualizar o estado real do
usuário, reparar estado legado obsoleto por meio de `doctor` e ainda instalar,
carregar, atualizar e desinstalar Plugins a partir das fontes compatíveis.
Para o mapa mais amplo do executor de testes, consulte [Testes](/pt-BR/help/testing). Para chaves de provedores
ao vivo e suítes que acessam a rede, consulte [Testes ao vivo](/pt-BR/help/testing-live).
ao vivo e suítes que tocam a rede, consulte [Testes ao vivo](/pt-BR/help/testing-live).
## O que protegemos
Os testes de atualização e Plugin protegem estes contratos:
- Um tarball de pacote está completo, tem um `dist/postinstall-inventory.json` válido
e não depende de arquivos de repositório não empacotados.
- Um tarball de pacote está completo, tem um `dist/postinstall-inventory.json`
válido e não depende de arquivos descompactados do repositório.
- Um usuário pode migrar de um pacote publicado mais antigo para o pacote candidato
sem perder configuração, agentes, sessões, workspaces, allowlists de Plugin ou
configuração de canal.
- `openclaw doctor --fix --non-interactive` é responsável pelos caminhos de limpeza e reparo
legados. A inicialização não deve acumular migrações ocultas de compatibilidade para estado
legados. A inicialização não deve ganhar migrações de compatibilidade ocultas para estado
obsoleto de Plugin.
- Instalações de Plugin funcionam a partir de diretórios locais, repositórios git, pacotes npm e do
- Instalações de Plugin funcionam a partir de diretórios locais, repositórios git, pacotes npm e o
caminho de registro do ClawHub.
- Dependências npm de Plugin são instaladas na raiz npm gerenciada, verificadas antes
da confiança e removidas por meio do npm durante a desinstalação para que dependências içadas não
da confiança e removidas pelo npm durante a desinstalação para que dependências içadas não
permaneçam.
- A atualização de Plugin é estável quando nada mudou: registros de instalação, fonte
resolvida, layout de dependências instaladas e estado habilitado permanecem intactos.
@ -54,30 +54,30 @@ pnpm test:changed
```
Para alterações de instalação, desinstalação, dependência ou inventário de pacote de Plugin, também
execute os testes focados que cobrem o ponto editado:
execute os testes focados que cobrem a interface editada:
```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
```
Antes que qualquer lane Docker de pacote consuma um tarball, prove o artefato do pacote:
Antes que qualquer pista Docker de pacote consuma um tarball, prove o artefato do pacote:
```bash
pnpm release:check
```
`release:check` executa verificações de drift de configuração/docs/API, grava o inventário de distribuição
`release:check` executa verificações de divergência de configuração/docs/API, grava o inventário de dist
do pacote, executa `npm pack --dry-run`, rejeita arquivos empacotados proibidos, instala
o tarball em um prefixo temporário, executa postinstall e testa superficialmente os entrypoints de canais
o tarball em um prefixo temporário, executa postinstall e faz smoke de entrypoints de canais
incluídos.
## Lanes Docker
## Pistas Docker
As lanes Docker são a prova em nível de produto. Elas instalam ou atualizam um pacote real
dentro de contêineres Linux e verificam o comportamento por meio de comandos CLI,
inicialização do Gateway, probes HTTP, status RPC e estado do sistema de arquivos.
As pistas Docker são a prova em nível de produto. Elas instalam ou atualizam um pacote real
dentro de contêineres Linux e verificam o comportamento por meio de comandos da CLI,
inicialização do Gateway, sondas HTTP, status RPC e estado do sistema de arquivos.
Use lanes focadas durante a iteração:
Use pistas focadas durante a iteração:
```bash
pnpm test:docker:plugins
@ -88,36 +88,36 @@ pnpm test:docker:published-upgrade-survivor
pnpm test:docker:update-migration
```
Lanes importantes:
Pistas importantes:
- `test:docker:plugins` valida smoke de instalação de Plugin, instalações de pasta local,
comportamento de ignorar atualização de pasta local, pastas locais com
dependências pré-instaladas, instalações de pacote `file:`, instalações git com execução de CLI, atualizações de
referência móvel git, instalações de registro npm com dependências transitivas
içadas, no-ops de atualização npm, instalações de fixture local do ClawHub e no-ops de atualização,
comportamento de atualização do marketplace e habilitação/inspeção do pacote Claude. Defina
comportamento de ignorar atualização de pasta local, pastas locais com dependências
pré-instaladas, instalações de pacote `file:`, instalações git com execução via CLI, atualizações
de referência móvel git, instalações de registro npm com dependências transitivas
içadas, no-ops de atualização npm, instalações de fixture local do ClawHub e no-ops de
atualização, comportamento de atualização do marketplace e habilitação/inspeção de pacote Claude. Defina
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0` para manter o bloco do ClawHub hermético/offline.
- `test:docker:plugin-lifecycle-matrix` instala o pacote candidato em um contêiner
vazio, executa um Plugin npm por instalação, inspeção, desabilitação, habilitação,
upgrade explícito, downgrade explícito e desinstalação após excluir o código do Plugin.
Ele registra métricas de RSS e CPU para cada fase.
- `test:docker:plugin-update` valida que um Plugin instalado sem alterações não
reinstala nem perde metadados de instalação durante `openclaw plugins update`.
- `test:docker:upgrade-survivor` instala o tarball candidato sobre uma fixture de usuário antigo
suja, executa atualização de pacote mais doctor não interativo, depois inicia
- `test:docker:plugin-update` valida que um Plugin instalado inalterado não
é reinstalado nem perde metadados de instalação durante `openclaw plugins update`.
- `test:docker:upgrade-survivor` instala o tarball candidato sobre uma fixture
suja de usuário antigo, executa atualização de pacote mais doctor não interativo e então inicia
um Gateway de loopback e verifica a preservação de estado.
- `test:docker:published-upgrade-survivor` primeiro instala uma baseline publicada,
configura-a por meio de uma receita `openclaw config set` embutida, atualiza-a para o
tarball candidato, executa doctor, verifica a limpeza legada, inicia o Gateway e
testa `/healthz`, `/readyz` e status RPC.
- `test:docker:update-migration` é a lane de atualização publicada com muita limpeza. Ela
começa a partir de um estado de usuário configurado no estilo Discord/Telegram, executa o
doctor da baseline para que dependências de Plugin configuradas tenham a chance de se materializar, semeia
detritos legados de dependências de Plugin para um Plugin empacotado configurado, atualiza para
tarball candidato, executa doctor, verifica limpeza legada, inicia o Gateway e
sonda `/healthz`, `/readyz` e status RPC.
- `test:docker:update-migration` é a pista de atualização publicada com forte foco em limpeza. Ela
começa com um estado de usuário configurado no estilo Discord/Telegram, executa doctor
da baseline para que dependências de Plugin configurado tenham chance de se materializar, semeia
resíduos legados de dependências de Plugin para um Plugin empacotado configurado, atualiza para
o tarball candidato e exige que o doctor pós-atualização remova as raízes legadas
de dependência.
de dependências.
Variantes úteis do survivor de upgrade publicado:
Variantes úteis de published-upgrade survivor:
```bash
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
@ -130,15 +130,15 @@ pnpm test:docker:published-upgrade-survivor
```
Os cenários disponíveis são `base`, `feishu-channel`, `bootstrap-persona`,
`plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path` e
`versioned-runtime-deps`. Em execuções agregadas,
`plugin-deps-cleanup`, `configured-plugin-installs`,
`stale-source-plugin-shadow`, `tilde-log-path` e `versioned-runtime-deps`. Em execuções agregadas,
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` expande para todos os cenários
com formato de issues reportadas, incluindo a migração de instalação de Plugin configurado.
com formato de problemas relatados, incluindo a migração de instalação de Plugin configurado.
A migração completa de atualização é intencionalmente separada da CI de Release Completa. Use o
workflow manual `Update Migration` quando a pergunta de release for "cada
release estável publicado desde 2026.4.23 em diante consegue atualizar para este candidato e
limpar detritos de dependências de Plugin?":
A migração completa de atualização é intencionalmente separada da CI de Full Release. Use o
workflow manual `Update Migration` quando a pergunta de release for "toda
release estável publicada a partir de 2026.4.23 consegue atualizar para este candidato e
limpar resíduos de dependências de Plugin?":
```bash
gh workflow run update-migration.yml \
@ -152,24 +152,24 @@ gh workflow run update-migration.yml \
## Package Acceptance
Package Acceptance é o gate de pacote nativo do GitHub. Ele resolve um pacote
candidato em um tarball `package-under-test`, registra versão e SHA-256, depois
executa lanes Docker E2E reutilizáveis contra esse tarball exato. A ref do harness de workflow
é separada da ref de origem do pacote, então a lógica de teste atual pode validar
releases confiáveis mais antigos.
candidato em um tarball `package-under-test`, registra versão e SHA-256 e então
executa pistas Docker E2E reutilizáveis contra esse tarball exato. O ref do harness
do workflow é separado do ref de origem do pacote, para que a lógica de teste atual possa validar
releases confiáveis mais antigas.
Fontes candidatas:
- `source=npm`: validar `openclaw@beta`, `openclaw@latest` ou uma versão
publicada exata.
- `source=ref`: empacotar um branch, tag ou commit confiável com o harness atual
- `source=npm`: valida `openclaw@beta`, `openclaw@latest` ou uma versão publicada
exata.
- `source=ref`: empacota uma branch, tag ou commit confiável com o harness atual
selecionado.
- `source=url`: validar um tarball HTTPS com `package_sha256` obrigatório.
- `source=artifact`: reutilizar um tarball enviado por outra execução do Actions.
- `source=url`: valida um tarball HTTPS com `package_sha256` obrigatório.
- `source=artifact`: reutiliza um tarball enviado por outra execução do Actions.
Full Release Validation usa `source=artifact` por padrão, criado a partir do
SHA de release resolvido. Para prova pós-publicação, passe
`package_acceptance_package_spec=openclaw@YYYY.M.D` para que a mesma matriz de upgrade
tenha como alvo o pacote npm entregue.
mire o pacote npm entregue.
As verificações de release chamam Package Acceptance com o conjunto de pacote/atualização/Plugin:
@ -187,15 +187,14 @@ telegram_mode=mock-openai
Isso mantém migração de pacote, troca de canal de atualização, limpeza de dependências
obsoletas de Plugin, cobertura offline de Plugin, comportamento de atualização de Plugin e QA de pacote
do Telegram no mesmo artefato resolvido.
Telegram no mesmo artefato resolvido.
`all-since-2026.4.23` é a amostra de upgrade da CI de Release Completa: todo release estável publicado no npm de `2026.4.23` até `latest`. Para cobertura exaustiva de migração de atualização
publicada, use `all-since-2026.4.23` no workflow Update
Migration separado em vez da CI de Release Completa. `release-history` permanece
disponível para amostragem manual mais ampla quando você também quiser a âncora
legada anterior à data.
`all-since-2026.4.23` é a amostra de upgrade da CI de Full Release: todas as releases estáveis publicadas no npm de `2026.4.23` até `latest`. Para cobertura exaustiva de migração de
atualização publicada, use `all-since-2026.4.23` no workflow separado Update
Migration em vez da CI de Full Release. `release-history` permanece
disponível para amostragem manual mais ampla quando você também quiser a âncora legada anterior à data.
Execute um perfil de pacote manualmente ao validar um candidato antes do release:
Execute um perfil de pacote manualmente ao validar um candidato antes da release:
```bash
gh workflow run package-acceptance.yml \
@ -210,58 +209,56 @@ gh workflow run package-acceptance.yml \
```
Use `suite_profile=product` quando a pergunta de release incluir canais MCP,
limpeza de cron/subagente, pesquisa web da OpenAI ou OpenWebUI. Use `suite_profile=full`
somente quando precisar de cobertura completa do caminho de release Docker.
limpeza de cron/subagente, busca web da OpenAI ou OpenWebUI. Use `suite_profile=full`
somente quando precisar de cobertura completa de caminho de release Docker.
## Padrão de release
Para candidatos a release, a pilha de prova padrão é:
Para candidatas a release, a pilha de prova padrão é:
1. `pnpm check:changed` e `pnpm test:changed` para regressões em nível de código-fonte.
2. `pnpm release:check` para integridade do artefato de pacote.
3. Perfil Package Acceptance `package` ou as lanes customizadas de pacote
3. Perfil `package` do Package Acceptance ou as pistas customizadas de pacote
de release-check para contratos de instalação/atualização/Plugin.
4. Verificações de release entre sistemas operacionais para instalador, onboarding e comportamento
de plataforma específicos de OS.
5. Suítes ao vivo somente quando a superfície alterada toca comportamento de provedor ou serviço
hospedado.
4. Verificações de release entre sistemas operacionais para comportamento específico de instalador, onboarding e plataforma.
5. Suítes ao vivo somente quando a superfície alterada toca comportamento de provedor ou serviço hospedado.
Em máquinas de mantenedores, gates amplos e prova de produto Docker/pacote devem executar
no Testbox, a menos que a prova local esteja sendo feita explicitamente.
Em máquinas de mantenedores, gates amplos e prova de produto Docker/pacote devem ser executados
no Testbox, salvo prova local explícita.
## Compatibilidade legada
A leniência de compatibilidade é restrita e temporária:
A tolerância de compatibilidade é restrita e com prazo definido:
- Pacotes até `2026.4.25`, incluindo `2026.4.25-beta.*`, podem tolerar
lacunas de metadados de pacote já entregues no Package Acceptance.
- O pacote `2026.4.26` publicado pode emitir avisos para arquivos de carimbo de metadados
- O pacote publicado `2026.4.26` pode alertar sobre arquivos de carimbo de metadados
de build local já entregues.
- Pacotes posteriores devem satisfazer contratos modernos. As mesmas lacunas falham em vez de
avisar ou pular.
gerar alerta ou serem ignoradas.
Não adicione novas migrações de inicialização para esses formatos antigos. Adicione ou estenda um reparo
de doctor, depois prove-o com `upgrade-survivor` ou `published-upgrade-survivor`.
de doctor e então prove com `upgrade-survivor` ou `published-upgrade-survivor`.
## Adicionando cobertura
Ao alterar comportamento de atualização ou Plugin, adicione cobertura na camada mais baixa que
possa falhar pelo motivo correto:
possa falhar pelo motivo certo:
- Lógica pura de caminho ou metadados: teste unitário ao lado do código-fonte.
- Comportamento de inventário de pacote ou arquivo empacotado: teste `package-dist-inventory` ou do verificador
de tarball.
- Comportamento de instalação/atualização da CLI: asserção ou fixture de lane Docker.
- Comportamento de migração de release publicado: cenário `published-upgrade-survivor`.
- Comportamento de registro/fonte de pacote: fixture `test:docker:plugins` ou servidor de fixture
do ClawHub.
- Inventário de pacote ou comportamento de arquivos empacotados: `package-dist-inventory` ou teste
de verificador de tarball.
- Comportamento de instalação/atualização da CLI: asserção ou fixture de pista Docker.
- Comportamento de migração de release publicada: cenário `published-upgrade-survivor`.
- Comportamento de fonte de registro/pacote: fixture `test:docker:plugins` ou servidor
de fixture do ClawHub.
- Comportamento de layout ou limpeza de dependências: verifique tanto a execução em runtime quanto a
fronteira do sistema de arquivos. Dependências npm podem ser içadas sob a raiz npm gerenciada,
então os testes devem provar que a raiz é verificada/limpa em vez de assumir uma árvore
fronteira do sistema de arquivos. Dependências npm podem ser içadas sob a raiz npm
gerenciada, então os testes devem provar que a raiz é verificada/limpa em vez de assumir uma árvore
`node_modules` local ao pacote.
Mantenha novas fixtures Docker herméticas por padrão. Use registros de fixture locais e
pacotes falsos, a menos que o ponto do teste seja o comportamento de registro ao vivo.
Mantenha novas fixtures Docker herméticas por padrão. Use registros de fixtures locais e
pacotes falsos, a menos que o objetivo do teste seja comportamento de registro ao vivo.
## Triagem de falhas
@ -270,10 +267,10 @@ Comece pela identidade do artefato:
- Resumo `resolve_package` do Package Acceptance: fonte, versão, SHA-256 e
nome do artefato.
- Artefatos Docker: `.artifacts/docker-tests/**/summary.json`,
`failures.json`, logs de lane e comandos de nova execução.
- Resumo do upgrade survivor: `.artifacts/upgrade-survivor/summary.json`,
incluindo versão da baseline, versão candidata, cenário, tempos de fase e
`failures.json`, logs de pista e comandos de nova execução.
- Resumo de upgrade survivor: `.artifacts/upgrade-survivor/summary.json`,
incluindo versão baseline, versão candidata, cenário, tempos de fase e
etapas da receita.
Prefira executar novamente a lane exata que falhou com o mesmo artefato de pacote em vez de
Prefira executar novamente a pista exata com falha com o mesmo artefato de pacote em vez de
executar novamente todo o guarda-chuva de release.

737
docs/pt-BR/help/testing.md
View File

File diff suppressed because it is too large Load Diff

186
docs/pt-BR/plugins/bundles.md
View File

@ -6,36 +6,36 @@ read_when:
summary: Instale e use pacotes do Codex, Claude e Cursor como plugins do OpenClaw
title: Pacotes de Plugin
x-i18n:
generated_at: "2026-05-02T05:51:39Z"
generated_at: "2026-05-05T01:47:57Z"
model: gpt-5.5
provider: openai
source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157
source_path: plugins/bundles.md
workflow: 16
---
OpenClaw pode instalar plugins de três ecossistemas externos: **Codex**, **Claude**
e **Cursor**. Eles são chamados de **bundles** — pacotes de conteúdo e metadados que
OpenClaw pode instalar plugins de três ecossistemas externos: **Codex**, **Claude**,
e **Cursor**. Eles são chamados de **pacotes** — pacotes de conteúdo e metadados que
o OpenClaw mapeia para recursos nativos como Skills, hooks e ferramentas MCP.
<Info>
Bundles **não** são o mesmo que plugins nativos do OpenClaw. Plugins nativos são executados
no processo e podem registrar qualquer capacidade. Bundles são pacotes de conteúdo com
Pacotes **não** são a mesma coisa que plugins nativos do OpenClaw. Plugins nativos rodam
no processo e podem registrar qualquer capacidade. Pacotes são conjuntos de conteúdo com
mapeamento seletivo de recursos e um limite de confiança mais restrito.
</Info>
## Por que bundles existem
## Por que os pacotes existem
Muitos plugins úteis são publicados no formato Codex, Claude ou Cursor. Em vez
de exigir que autores os reescrevam como plugins nativos do OpenClaw, o OpenClaw
detecta esses formatos e mapeia o conteúdo compatível deles para o conjunto de
recursos nativo. Isso significa que você pode instalar um pacote de comandos Claude ou um bundle de Skills Codex
detecta esses formatos e mapeia o conteúdo compatível para o conjunto de recursos
nativo. Isso significa que você pode instalar um pacote de comandos Claude ou um pacote de Skills do Codex
e usá-lo imediatamente.
## Instalar um bundle
## Instalar um pacote
<Steps>
<Step title="Instale de um diretório, arquivo compactado ou marketplace">
<Step title="Instalar de um diretório, arquivo ou marketplace">
```bash
# Local directory
openclaw plugins install ./my-bundle
@ -50,17 +50,17 @@ e usá-lo imediatamente.
</Step>
<Step title="Verifique a detecção">
<Step title="Verificar detecção">
```bash
openclaw plugins list
openclaw plugins inspect <id>
```
Bundles aparecem como `Format: bundle` com um subtipo `codex`, `claude` ou `cursor`.
Pacotes aparecem como `Format: bundle` com um subtipo `codex`, `claude` ou `cursor`.
</Step>
<Step title="Reinicie e use">
<Step title="Reiniciar e usar">
```bash
openclaw gateway restart
```
@ -70,51 +70,51 @@ e usá-lo imediatamente.
</Step>
</Steps>
## O que o OpenClaw mapeia de bundles
## O que o OpenClaw mapeia de pacotes
Nem todo recurso de bundle é executado no OpenClaw hoje. Veja o que funciona e o que
Nem todos os recursos de pacote rodam no OpenClaw hoje. Veja o que funciona e o que
é detectado, mas ainda não está conectado.
### Compatível agora
### Com suporte agora
| Recurso | Como é mapeado | Aplica-se a |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Conteúdo de Skills | Raízes de Skills do bundle são carregadas como Skills normais do OpenClaw | Todos os formatos |
| Conteúdo de Skill | Raízes de Skills do pacote carregam como Skills normais do OpenClaw | Todos os formatos |
| Comandos | `commands/` e `.cursor/commands/` tratados como raízes de Skills | Claude, Cursor |
| Pacotes de hooks | Layouts no estilo OpenClaw com `HOOK.md` + `handler.ts` | Codex |
| Ferramentas MCP | Configuração MCP do bundle mesclada às configurações incorporadas do Pi; servidores stdio e HTTP compatíveis carregados | Todos os formatos |
| Servidores LSP | `.lsp.json` do Claude e `lspServers` declarados no manifesto mesclados aos padrões LSP incorporados do Pi | Claude |
| Configurações | `settings.json` do Claude importado como padrões incorporados do Pi | Claude |
| Ferramentas MCP | Configuração MCP do pacote mesclada nas configurações embarcadas do Pi; servidores stdio e HTTP compatíveis carregados | Todos os formatos |
| Servidores LSP | `.lsp.json` do Claude e `lspServers` declarados no manifesto mesclados aos padrões LSP embarcados do Pi | Claude |
| Configurações | `settings.json` do Claude importado como padrões embarcados do Pi | Claude |
#### Conteúdo de Skills
#### Conteúdo de Skill
- raízes de Skills do bundle são carregadas como raízes normais de Skills do OpenClaw
- raízes `commands` do Claude são tratadas como raízes adicionais de Skills
- raízes `.cursor/commands` do Cursor são tratadas como raízes adicionais de Skills
- raízes de Skills do pacote carregam como raízes de Skills normais do OpenClaw
- raízes `commands` do Claude são tratadas como raízes de Skills adicionais
- raízes `.cursor/commands` do Cursor são tratadas como raízes de Skills adicionais
Isso significa que arquivos de comando markdown do Claude funcionam pelo carregador
Isso significa que arquivos de comando Markdown do Claude funcionam pelo carregador
normal de Skills do OpenClaw. Markdown de comandos do Cursor funciona pelo mesmo caminho.
#### Pacotes de hooks
- raízes de hooks do bundle funcionam **somente** quando usam o layout normal
de pacote de hooks do OpenClaw. Hoje, esse é principalmente o caso compatível com Codex:
- raízes de hooks de pacote funcionam **somente** quando usam o layout normal de pacote de hooks
do OpenClaw. Hoje, esse é principalmente o caso compatível com Codex:
- `HOOK.md`
- `handler.ts` ou `handler.js`
#### MCP para Pi
- bundles habilitados podem contribuir com configuração de servidor MCP
- o OpenClaw mescla a configuração MCP do bundle às configurações incorporadas efetivas do Pi como
- pacotes habilitados podem contribuir configuração de servidor MCP
- o OpenClaw mescla a configuração MCP do pacote nas configurações embarcadas efetivas do Pi como
`mcpServers`
- o OpenClaw expõe ferramentas MCP compatíveis do bundle durante turnos do agente Pi incorporado
iniciando servidores stdio ou conectando-se a servidores HTTP
- os perfis de ferramentas `coding` e `messaging` incluem ferramentas MCP de bundle por
padrão; use `tools.deny: ["bundle-mcp"]` para desativar para um agente ou Gateway
- configurações locais de projeto do Pi ainda se aplicam depois dos padrões do bundle, então configurações
de workspace podem sobrescrever entradas MCP do bundle quando necessário
- catálogos de ferramentas MCP de bundle são ordenados deterministicamente antes do registro, para que
mudanças na ordem de `listTools()` upstream não recriem blocos de ferramentas do cache de prompts
- o OpenClaw expõe ferramentas MCP de pacote compatíveis durante turnos do agente Pi embarcado ao
iniciar servidores stdio ou conectar a servidores HTTP
- os perfis de ferramenta `coding` e `messaging` incluem ferramentas MCP de pacote por
padrão; use `tools.deny: ["bundle-mcp"]` para optar por não usar em um agente ou Gateway
- configurações locais de projeto do Pi ainda se aplicam depois dos padrões do pacote, então as
configurações do workspace podem substituir entradas MCP do pacote quando necessário
- catálogos de ferramentas MCP de pacote são ordenados deterministamente antes do registro, para que
alterações na ordem upstream de `listTools()` não agitem blocos de ferramentas do cache de prompt
##### Transportes
@ -136,7 +136,7 @@ Servidores MCP podem usar transporte stdio ou HTTP:
}
```
**HTTP** conecta-se a um servidor MCP em execução por `sse` por padrão, ou `streamable-http` quando solicitado:
**HTTP** conecta a um servidor MCP em execução por `sse` por padrão, ou `streamable-http` quando solicitado:
```json
{
@ -160,15 +160,15 @@ Servidores MCP podem usar transporte stdio ou HTTP:
- somente esquemas de URL `http:` e `https:` são permitidos
- valores de `headers` aceitam interpolação `${ENV_VAR}`
- uma entrada de servidor com `command` e `url` é rejeitada
- credenciais de URL (userinfo e parâmetros de consulta) são redigidas de descrições
de ferramentas e logs
- `connectionTimeoutMs` substitui o tempo limite padrão de conexão de 30 segundos para
- credenciais de URL (userinfo e parâmetros de consulta) são redigidas de descrições de ferramentas
e logs
- `connectionTimeoutMs` substitui o tempo limite de conexão padrão de 30 segundos para
transportes stdio e HTTP
##### Nomenclatura de ferramentas
##### Nomeação de ferramentas
O OpenClaw registra ferramentas MCP de bundle com nomes seguros para provedores no formato
`serverName__toolName`. Por exemplo, um servidor com a chave `"vigil-harbor"` que expõe uma ferramenta
O OpenClaw registra ferramentas MCP de pacote com nomes seguros para provedores no formato
`serverName__toolName`. Por exemplo, um servidor com chave `"vigil-harbor"` que expõe uma ferramenta
`memory_search` é registrado como `vigil-harbor__memory_search`.
- caracteres fora de `A-Za-z0-9_-` são substituídos por `-`
@ -176,16 +176,16 @@ O OpenClaw registra ferramentas MCP de bundle com nomes seguros para provedores
- nomes completos de ferramentas são limitados a 64 caracteres
- nomes de servidor vazios usam `mcp` como fallback
- nomes sanitizados conflitantes são desambiguados com sufixos numéricos
- a ordem final de ferramentas expostas é determinística por nome seguro para manter turnos
repetidos do Pi estáveis para cache
- a filtragem de perfis trata todas as ferramentas de um servidor MCP de bundle como pertencentes ao plugin
`bundle-mcp`, então allowlists e deny lists de perfil podem incluir nomes
individuais de ferramentas expostas ou a chave de plugin `bundle-mcp`
- a ordem final de ferramentas expostas é determinística por nome seguro para manter turnos repetidos do Pi
estáveis em cache
- a filtragem de perfis trata todas as ferramentas de um servidor MCP de pacote como pertencentes ao plugin
`bundle-mcp`, então listas de permissão e negação de perfil podem incluir tanto
nomes individuais de ferramentas expostas quanto a chave de plugin `bundle-mcp`
#### Configurações incorporadas do Pi
#### Configurações embarcadas do Pi
- `settings.json` do Claude é importado como configurações incorporadas padrão do Pi quando o
bundle está habilitado
- `settings.json` do Claude é importado como configurações embarcadas padrão do Pi quando o
pacote está habilitado
- o OpenClaw sanitiza chaves de substituição de shell antes de aplicá-las
Chaves sanitizadas:
@ -193,13 +193,13 @@ Chaves sanitizadas:
- `shellPath`
- `shellCommandPrefix`
#### LSP incorporado do Pi
#### LSP embarcado do Pi
- bundles Claude habilitados podem contribuir com configuração de servidor LSP
- pacotes Claude habilitados podem contribuir configuração de servidor LSP
- o OpenClaw carrega `.lsp.json` mais quaisquer caminhos `lspServers` declarados no manifesto
- a configuração LSP do bundle é mesclada aos padrões LSP incorporados efetivos do Pi
- somente servidores LSP compatíveis baseados em stdio são executáveis hoje; transportes
incompatíveis ainda aparecem em `openclaw plugins inspect <id>`
- a configuração LSP do pacote é mesclada aos padrões LSP embarcados efetivos do Pi
- somente servidores LSP com suporte baseados em stdio podem ser executados hoje; transportes
sem suporte ainda aparecem em `openclaw plugins inspect <id>`
### Detectado, mas não executado
@ -209,20 +209,20 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec
- `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` do Cursor
- metadados inline/de app do Codex além do relatório de capacidades
## Formatos de bundle
## Formatos de pacote
<AccordionGroup>
<Accordion title="Bundles Codex">
<Accordion title="Pacotes Codex">
Marcadores: `.codex-plugin/plugin.json`
Conteúdo opcional: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
Bundles Codex se encaixam melhor no OpenClaw quando usam raízes de Skills e diretórios
de pacotes de hooks no estilo OpenClaw (`HOOK.md` + `handler.ts`).
Pacotes Codex se encaixam melhor no OpenClaw quando usam raízes de Skills e diretórios
de pacote de hooks no estilo OpenClaw (`HOOK.md` + `handler.ts`).
</Accordion>
<Accordion title="Bundles Claude">
<Accordion title="Pacotes Claude">
Dois modos de detecção:
- **Baseado em manifesto:** `.claude-plugin/plugin.json`
@ -230,22 +230,22 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec
Comportamento específico do Claude:
- `commands/` é tratado como conteúdo de Skills
- `settings.json` é importado para configurações incorporadas do Pi (chaves de substituição de shell são sanitizadas)
- `.mcp.json` expõe ferramentas stdio compatíveis para o Pi incorporado
- `.lsp.json` mais caminhos `lspServers` declarados no manifesto são carregados nos padrões LSP incorporados do Pi
- `commands/` é tratado como conteúdo de Skill
- `settings.json` é importado para as configurações embarcadas do Pi (chaves de substituição de shell são sanitizadas)
- `.mcp.json` expõe ferramentas stdio compatíveis ao Pi embarcado
- `.lsp.json` mais caminhos `lspServers` declarados no manifesto carregam nos padrões LSP embarcados do Pi
- `hooks/hooks.json` é detectado, mas não executado
- Caminhos de componentes personalizados no manifesto são aditivos (eles estendem os padrões, não os substituem)
- caminhos de componentes personalizados no manifesto são aditivos (estendem os padrões, não os substituem)
</Accordion>
<Accordion title="Bundles Cursor">
<Accordion title="Pacotes Cursor">
Marcadores: `.cursor-plugin/plugin.json`
Conteúdo opcional: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
- `.cursor/commands/` é tratado como conteúdo de Skills
- `.cursor/rules/`, `.cursor/agents/` e `.cursor/hooks.json` são somente detectados
- `.cursor/commands/` é tratado como conteúdo de Skill
- `.cursor/rules/`, `.cursor/agents/` e `.cursor/hooks.json` são somente detecção
</Accordion>
</AccordionGroup>
@ -255,55 +255,55 @@ Estes são reconhecidos e exibidos em diagnósticos, mas o OpenClaw não os exec
O OpenClaw verifica primeiro o formato de plugin nativo:
1. `openclaw.plugin.json` ou `package.json` válido com `openclaw.extensions` — tratado como **plugin nativo**
2. Marcadores de bundle (`.codex-plugin/`, `.claude-plugin/` ou layout padrão Claude/Cursor) — tratados como **bundle**
2. Marcadores de pacote (`.codex-plugin/`, `.claude-plugin/` ou layout padrão do Claude/Cursor) — tratados como **pacote**
Se um diretório contiver ambos, o OpenClaw usa o caminho nativo. Isso impede que
pacotes de formato duplo sejam instalados parcialmente como bundles.
Se um diretório contiver ambos, o OpenClaw usa o caminho nativo. Isso evita
que pacotes de formato duplo sejam parcialmente instalados como pacotes.
## Dependências de runtime e limpeza
- Bundles compatíveis de terceiros não recebem reparo `npm install` na inicialização. Eles
devem ser instalados por `openclaw plugins install` e incluir tudo
- Pacotes compatíveis de terceiros não recebem reparo de `npm install` na inicialização. Eles
devem ser instalados por meio de `openclaw plugins install` e incluir tudo
de que precisam no diretório de plugin instalado.
- Plugins empacotados pertencentes ao OpenClaw são enviados de forma leve no core ou
- Plugins empacotados pertencentes ao OpenClaw são enviados de forma leve no núcleo ou
baixáveis pelo instalador de plugins. A inicialização do Gateway nunca executa um
gerenciador de pacotes para eles.
- `openclaw doctor --fix` remove diretórios legados de dependências preparadas e pode
instalar plugins baixáveis configurados que estão ausentes do índice local
de plugins.
recuperar plugins baixáveis ausentes do índice local de plugins quando
a configuração os referencia.
## Segurança
Bundles têm um limite de confiança mais restrito que plugins nativos:
Pacotes têm um limite de confiança mais restrito que plugins nativos:
- o OpenClaw **não** carrega módulos arbitrários de runtime do bundle no processo
- caminhos de Skills e pacotes de hooks devem permanecer dentro da raiz do plugin (verificados por limite)
- arquivos de configurações são lidos com as mesmas verificações de limite
- o OpenClaw **não** carrega módulos arbitrários de runtime de pacote no processo
- caminhos de Skills e de pacotes de hooks devem permanecer dentro da raiz do plugin (com verificação de limite)
- arquivos de configuração são lidos com as mesmas verificações de limite
- servidores MCP stdio compatíveis podem ser iniciados como subprocessos
Isso torna bundles mais seguros por padrão, mas você ainda deve tratar bundles
de terceiros como conteúdo confiável para os recursos que eles expõem.
Isso torna pacotes mais seguros por padrão, mas você ainda deve tratar pacotes de terceiros
como conteúdo confiável para os recursos que eles expõem.
## Solução de problemas
<AccordionGroup>
<Accordion title="O bundle é detectado, mas as capacidades não são executadas">
<Accordion title="O pacote é detectado, mas as capacidades não rodam">
Execute `openclaw plugins inspect <id>`. Se uma capacidade estiver listada, mas marcada como
não conectada, isso é uma limitação do produto — não uma instalação quebrada.
não conectada, isso é um limite do produto — não uma instalação quebrada.
</Accordion>
<Accordion title="Arquivos de comando Claude não aparecem">
Verifique se o bundle está habilitado e se os arquivos markdown estão dentro de uma raiz
Verifique se o pacote está habilitado e se os arquivos Markdown estão dentro de uma raiz
`commands/` ou `skills/` detectada.
</Accordion>
<Accordion title="Configurações Claude não se aplicam">
Somente configurações incorporadas do Pi de `settings.json` são compatíveis. O OpenClaw não
trata configurações de bundle como patches de configuração bruta.
<Accordion title="Configurações do Claude não se aplicam">
Somente configurações embarcadas do Pi de `settings.json` têm suporte. O OpenClaw não
trata configurações de pacote como patches de configuração bruta.
</Accordion>
<Accordion title="Hooks Claude não são executados">
`hooks/hooks.json` é somente detectado. Se você precisa de hooks executáveis, use o
<Accordion title="Hooks do Claude não executam">
`hooks/hooks.json` é somente detecção. Se você precisa de hooks executáveis, use o
layout de pacote de hooks do OpenClaw ou envie um plugin nativo.
</Accordion>
</AccordionGroup>

753
docs/pt-BR/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

109
docs/pt-BR/plugins/dependency-resolution.md
View File

@ -1,50 +1,51 @@
---
read_when:
- Você está depurando instalações de pacotes de Plugin
- Você está alterando o comportamento de inicialização de Plugin, do doctor ou de instalação do gerenciador de pacotes
- Você está mantendo instalações empacotadas do OpenClaw ou manifestos de Plugin incluídos
- Você está alterando o comportamento de inicialização do Plugin, do doctor ou de instalação do gerenciador de pacotes
- Você está mantendo instalações empacotadas do OpenClaw ou manifestos de plugins incluídos
sidebarTitle: Dependencies
summary: Como o OpenClaw instala pacotes de Plugin e resolve dependências de Plugin
title: Resolução de dependências de Plugin
x-i18n:
generated_at: "2026-05-03T21:35:46Z"
generated_at: "2026-05-05T01:48:22Z"
model: gpt-5.5
provider: openai
source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d
source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20
source_path: plugins/dependency-resolution.md
workflow: 16
---
# Resolução de dependências de Plugin
O OpenClaw mantém o trabalho de dependências de plugin no momento de instalação/atualização. O carregamento em runtime
não executa gerenciadores de pacotes, repara árvores de dependências nem modifica o diretório de pacote do OpenClaw.
OpenClaw mantém o trabalho de dependências de plugins no momento da instalação/atualização. O carregamento em runtime
não executa gerenciadores de pacotes, repara árvores de dependências nem modifica o diretório do pacote
OpenClaw.
## Divisão de responsabilidades
Os pacotes de plugin são responsáveis pelo próprio grafo de dependências:
Pacotes de Plugin são responsáveis pelo próprio grafo de dependências:
- dependências de runtime ficam em `dependencies` ou
`optionalDependencies` do pacote de plugin
- importações do SDK/core são peers ou importações fornecidas pelo OpenClaw
`optionalDependencies` do pacote de Plugin
- importações de SDK/core são pares ou importações fornecidas pelo OpenClaw
- plugins de desenvolvimento local trazem suas próprias dependências já instaladas
- plugins npm e git são instalados em raízes de pacote pertencentes ao OpenClaw
O OpenClaw é responsável apenas pelo ciclo de vida do plugin:
OpenClaw é responsável apenas pelo ciclo de vida do Plugin:
- descobrir a origem do plugin
- descobrir a origem do Plugin
- instalar ou atualizar o pacote quando solicitado explicitamente
- registrar os metadados de instalação
- carregar o entrypoint do plugin
- falhar com um erro acionável quando faltarem dependências
- carregar o ponto de entrada do Plugin
- falhar com um erro acionável quando dependências estiverem ausentes
## Raízes de instalação
O OpenClaw usa raízes estáveis por origem:
OpenClaw usa raízes estáveis por origem:
- pacotes npm são instalados em `~/.openclaw/npm`
- pacotes git são clonados em `~/.openclaw/git`
- instalações locais/por caminho/arquivo são copiadas ou referenciadas sem reparo de dependências
- instalações locais/de caminho/de arquivo são copiadas ou referenciadas sem reparo de dependências
Instalações npm são executadas na raiz npm com:
@ -52,38 +53,38 @@ Instalações npm são executadas na raiz npm com:
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```
O npm pode içar dependências transitivas para `~/.openclaw/npm/node_modules` ao lado
do pacote de plugin. O OpenClaw examina a raiz npm gerenciada antes de confiar na
instalação e usa npm para remover pacotes gerenciados por npm durante a desinstalação, então dependências
de runtime içadas permanecem dentro do limite de limpeza gerenciado.
O npm pode elevar dependências transitivas para `~/.openclaw/npm/node_modules` ao lado
do pacote de Plugin. OpenClaw verifica a raiz npm gerenciada antes de confiar na
instalação e usa npm para remover pacotes gerenciados por npm durante a desinstalação, para que dependências
de runtime elevadas permaneçam dentro do limite de limpeza gerenciado.
Instalações git clonam ou atualizam o repositório e depois executam:
Instalações git clonam ou atualizam o repositório e então executam:
```bash
npm install --omit=dev --ignore-scripts --no-audit --no-fund
```
O plugin instalado então é carregado a partir desse diretório de pacote, então a resolução
em `node_modules` local ao pacote e pai funciona da mesma forma que em um pacote
O Plugin instalado então carrega a partir desse diretório de pacote, então a resolução
de `node_modules` local ao pacote e pai funciona da mesma forma que em um pacote
Node normal.
## Plugins locais
Plugins locais são tratados como diretórios controlados pelo desenvolvedor. O OpenClaw não
Plugins locais são tratados como diretórios controlados pelo desenvolvedor. OpenClaw não
executa `npm install`, `pnpm install` nem reparo de dependências para eles. Se um
plugin local tiver dependências, instale-as nesse plugin antes de carregá-lo.
Plugin local tiver dependências, instale-as nesse Plugin antes de carregá-lo.
Plugins locais TypeScript de terceiros podem usar o caminho emergencial Jiti. Plugins
JavaScript empacotados e plugins internos incluídos carregam por import/require
nativo em vez de Jiti.
JavaScript empacotados e plugins internos incluídos carregam por
import/require nativo em vez de Jiti.
## Inicialização e recarregamento
A inicialização do Gateway e o recarregamento de configuração nunca instalam dependências de plugin. Eles leem
os registros de instalação do plugin, calculam o entrypoint e o carregam.
A inicialização do Gateway e o recarregamento de configuração nunca instalam dependências de Plugin. Eles leem
os registros de instalação de Plugin, calculam o ponto de entrada e o carregam.
Se uma dependência estiver ausente em runtime, o plugin falha ao carregar e o erro
deve apontar o operador para uma correção explícita:
Se uma dependência estiver ausente em runtime, o Plugin falha ao carregar e o erro
deve indicar ao operador uma correção explícita:
```bash
openclaw plugins update <id>
@ -91,44 +92,44 @@ openclaw plugins install <source>
openclaw doctor --fix
```
`doctor --fix` pode limpar estado legado de dependências gerado pelo OpenClaw e instalar
plugins baixáveis configurados que estejam ausentes dos registros de instalação locais.
Ele não repara dependências de um plugin local já instalado.
`doctor --fix` pode limpar estado de dependências legado gerado pelo OpenClaw e recuperar
plugins baixáveis que estão ausentes dos registros de instalação locais quando a configuração
os referencia. Doctor não repara dependências de um Plugin local já instalado.
## Plugins incluídos
Plugins incluídos leves e críticos para o core são enviados como parte do OpenClaw.
Plugins incluídos leves e críticos para o core são distribuídos como parte do OpenClaw.
Eles devem não ter uma árvore pesada de dependências de runtime ou ser movidos para um
pacote baixável no ClawHub/npm.
Para a lista gerada atual de plugins enviados no pacote core, instalados
externamente ou mantidos apenas como fonte, consulte [Inventário de plugins](/pt-BR/plugins/plugin-inventory).
Para a lista gerada atual de plugins que são distribuídos no pacote core, instalados
externamente ou permanecem apenas como código-fonte, consulte [Inventário de Plugin](/pt-BR/plugins/plugin-inventory).
Manifestos de plugins incluídos não devem solicitar staging de dependências. Funcionalidade grande ou opcional
de plugin deve ser empacotada como um plugin normal e instalada pelo
Manifestos de Plugin incluídos não devem solicitar preparação de dependências. Funcionalidade
de Plugin grande ou opcional deve ser empacotada como um Plugin normal e instalada pelo
mesmo caminho npm/git/ClawHub que plugins de terceiros.
Em checkouts de código-fonte, o OpenClaw trata o repositório como um monorepo pnpm. Depois de
`pnpm install`, plugins incluídos carregam de `extensions/<id>`, então dependências
workspace locais ao pacote ficam disponíveis e edições são aplicadas diretamente. O desenvolvimento em
checkout de código-fonte é somente pnpm; `npm install` simples na raiz do repositório não é
uma forma compatível de preparar dependências de plugins incluídos.
Em checkouts de código-fonte, OpenClaw trata o repositório como um monorepo pnpm. Após
`pnpm install`, plugins incluídos carregam a partir de `extensions/<id>`, para que dependências
de workspace locais ao pacote fiquem disponíveis e edições sejam capturadas diretamente. O desenvolvimento
em checkout de código-fonte é somente pnpm; `npm install` simples na raiz do repositório
não é uma forma compatível de preparar dependências de Plugin incluído.
| Forma de instalação | Local do plugin incluído | Responsável pelas dependências |
| Formato de instalação | Local do Plugin incluído | Responsável pela dependência |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Árvore de runtime construída dentro do pacote | Pacote OpenClaw e fluxos explícitos de instalação/atualização/doctor de plugins |
| Checkout git mais `pnpm install` | Pacotes workspace em `extensions/<id>` | O workspace pnpm, incluindo as dependências próprias de cada pacote de plugin |
| `openclaw plugins install ...` | Raiz gerenciada de plugin npm/git/ClawHub | O fluxo de instalação/atualização de plugin |
| `npm install -g openclaw` | Árvore de runtime criada dentro do pacote | Pacote OpenClaw e fluxos explícitos de instalação/atualização/doctor de Plugin |
| Checkout git mais `pnpm install` | Pacotes de workspace `extensions/<id>` | O workspace pnpm, incluindo as dependências próprias de cada pacote de Plugin |
| `openclaw plugins install ...` | Raiz gerenciada de Plugin npm/git/ClawHub | O fluxo de instalação/atualização de Plugin |
## Limpeza legada
Versões antigas do OpenClaw geravam raízes de dependências de plugins incluídos na inicialização ou
durante reparo do doctor. A limpeza atual do doctor remove esses diretórios obsoletos e
symlinks quando `--fix` é usado, incluindo antigas raízes `plugin-runtime-deps`, symlinks de pacote
do prefixo global do Node que apontam para destinos `plugin-runtime-deps` podados,
manifestos `.openclaw-runtime-deps*`, `node_modules` de plugin gerados, diretórios de estágio
Versões antigas do OpenClaw geravam raízes de dependências de Plugin incluído na inicialização ou
durante o reparo do doctor. A limpeza atual do doctor remove esses diretórios e
symlinks obsoletos quando `--fix` é usado, incluindo raízes antigas `plugin-runtime-deps`, symlinks
de pacotes de prefixo global do Node que apontam para destinos `plugin-runtime-deps` removidos,
manifestos `.openclaw-runtime-deps*`, `node_modules` de Plugin gerado, diretórios de estágio
de instalação e stores pnpm locais ao pacote. O postinstall empacotado também
remove esses symlinks globais antes de podar as raízes de destino legadas para que upgrades
não deixem importações de pacotes ESM pendentes.
remove esses symlinks globais antes de remover as raízes de destino legadas para que atualizações
não deixem importações pendentes de pacotes ESM.
Esses caminhos são apenas resíduos legados. Novas instalações não devem criá-los.

81
docs/pt-BR/plugins/manage-plugins.md
View File

@ -1,22 +1,21 @@
---
read_when:
- Você quer exemplos rápidos para instalar, listar, atualizar ou desinstalar Plugin
- Você quer escolher entre a distribuição de plugins pelo ClawHub e pelo npm
- Você quer exemplos rápidos de instalação, listagem, atualização ou desinstalação de Plugin
- Você quer escolher entre o ClawHub e a distribuição de Plugin via npm
- Você está publicando um pacote de Plugin
sidebarTitle: Manage plugins
summary: Exemplos rápidos de instalação, listagem, desinstalação, atualização e publicação de plugins do OpenClaw
summary: Exemplos rápidos para instalar, listar, desinstalar, atualizar e publicar plugins do OpenClaw
title: Gerenciar plugins
x-i18n:
generated_at: "2026-05-02T22:19:53Z"
generated_at: "2026-05-05T01:48:46Z"
model: gpt-5.5
provider: openai
source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
source_path: plugins/manage-plugins.md
workflow: 16
---
A maioria dos fluxos de trabalho de plugins envolve alguns comandos: pesquisar, instalar, reiniciar o Gateway,
verificar e desinstalar quando você não precisar mais do plugin.
A maioria dos fluxos de trabalho de plugin envolve alguns comandos: pesquisar, instalar, reiniciar o Gateway, verificar e desinstalar quando você não precisar mais do plugin.
## Listar plugins
@ -27,39 +26,35 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
Use `--json` em scripts. Ele inclui diagnósticos do registro e o
`dependencyStatus` estático de cada plugin quando o pacote do plugin declara `dependencies` ou
`optionalDependencies`.
Use `--json` para scripts. Ele inclui diagnósticos de registro e o `dependencyStatus` estático de cada plugin quando o pacote do plugin declara `dependencies` ou `optionalDependencies`.
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` é uma verificação de inventário a frio. Ele mostra o que o OpenClaw consegue descobrir
a partir da configuração, dos manifestos e do registro de plugins; ele não prova que um
processo do Gateway já em execução importou o runtime do plugin.
`plugins list` é uma verificação fria de inventário. Ele mostra o que o OpenClaw consegue descobrir a partir da configuração, dos manifestos e do registro de plugins; ele não prova que um processo do Gateway já em execução importou o runtime do plugin.
## Instalar plugins
```bash
# Search ClawHub for plugin packages.
# Pesquise pacotes de plugin no ClawHub.
openclaw plugins search "calendar"
# Bare package specs try ClawHub first, then npm fallback.
# Especificações de pacote simples tentam o ClawHub primeiro, depois fallback para npm.
openclaw plugins install <package>
# Force one source.
# Force uma origem.
openclaw plugins install clawhub:<package>
openclaw plugins install npm:<package>
# Install a specific version or dist-tag.
# Instale uma versão específica ou dist-tag.
openclaw plugins install clawhub:<package>@1.2.3
openclaw plugins install clawhub:<package>@beta
openclaw plugins install npm:@scope/openclaw-plugin@1.2.3
openclaw plugins install npm:@openclaw/codex
# Install from git or a local development checkout.
# Instale a partir do git ou de um checkout de desenvolvimento local.
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
@ -72,9 +67,7 @@ openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
Use `inspect --runtime` quando precisar de prova de que o plugin registrou superfícies de runtime
como ferramentas, hooks, serviços, métodos do Gateway ou comandos de CLI
pertencentes ao plugin.
Use `inspect --runtime` quando precisar de prova de que o plugin registrou superfícies de runtime, como ferramentas, hooks, serviços, métodos do Gateway ou comandos de CLI pertencentes ao plugin.
## Atualizar plugins
@ -84,22 +77,16 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
Se um plugin foi instalado a partir de uma dist-tag do npm, como `@beta`, chamadas posteriores a
`update <plugin-id>` reutilizam essa tag registrada. Passar uma especificação explícita do npm
altera a instalação rastreada para essa especificação em atualizações futuras.
Se um plugin foi instalado a partir de uma dist-tag do npm, como `@beta`, chamadas posteriores de `update <plugin-id>` reutilizam essa tag registrada. Passar uma especificação npm explícita troca a instalação rastreada para essa especificação em atualizações futuras.
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
O segundo comando move um plugin de volta para a linha de lançamento padrão do registro
quando ele estava anteriormente fixado em uma versão exata ou tag.
O segundo comando move um plugin de volta para a linha de lançamento padrão do registro quando ele estava anteriormente fixado em uma versão exata ou tag.
Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub
da linha padrão tentam primeiro o lançamento `@beta` correspondente do plugin. Se esse lançamento
beta não existir, o OpenClaw volta para a especificação padrão/mais recente registrada.
Versões exatas e tags explícitas, como `@rc` ou `@beta`, são preservadas.
Quando `openclaw update` é executado no canal beta, registros de plugin npm e ClawHub da linha padrão tentam primeiro a versão `@beta` correspondente do plugin. Se essa versão beta não existir, o OpenClaw faz fallback para a especificação padrão/latest registrada. Para plugins npm, o OpenClaw também faz fallback quando o pacote beta existe, mas falha na validação de instalação. Versões exatas e tags explícitas, como `@rc` ou `@beta`, são preservadas.
## Desinstalar plugins
@ -110,20 +97,15 @@ openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
A desinstalação remove a entrada de configuração do plugin, o registro de índice do plugin, entradas
de lista de permissão/negação e caminhos de carregamento vinculados quando aplicável. Diretórios de instalação
gerenciados são removidos, a menos que você passe `--keep-files`.
A desinstalação remove a entrada de configuração do plugin, o registro de índice do plugin, entradas de lista de permissão/negação e caminhos de carregamento vinculados quando aplicável. Diretórios de instalação gerenciados são removidos, a menos que você passe `--keep-files`.
## Publicar plugins
Você pode publicar plugins externos no [ClawHub](https://clawhub.ai), npmjs.com ou
ambos.
Você pode publicar plugins externos no [ClawHub](https://clawhub.ai), no npmjs.com ou em ambos.
### Publicar no ClawHub
O ClawHub é a principal superfície pública de descoberta para plugins do OpenClaw. Ele oferece
aos usuários metadados pesquisáveis, histórico de versões e resultados de varredura do registro antes
da instalação.
O ClawHub é a principal superfície pública de descoberta para plugins do OpenClaw. Ele oferece aos usuários metadados pesquisáveis, histórico de versões e resultados de varredura do registro antes da instalação.
```bash
npm i -g clawhub
@ -144,8 +126,7 @@ A forma simples ainda verifica o ClawHub primeiro.
### Publicar no npmjs.com
Plugins npm nativos devem incluir um manifesto de plugin e metadados de ponto de entrada
do OpenClaw no `package.json`.
Plugins npm nativos devem incluir um manifesto de plugin e metadados de ponto de entrada do OpenClaw no `package.json`.
```json package.json
{
@ -162,7 +143,7 @@ do OpenClaw no `package.json`.
npm publish --access public
```
Os usuários instalam apenas pelo npm com:
Os usuários instalam apenas via npm com:
```bash
openclaw plugins install npm:@acme/openclaw-plugin
@ -170,20 +151,16 @@ openclaw plugins install npm:@acme/openclaw-plugin@beta
openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
```
Se o mesmo pacote também estiver disponível no ClawHub, `npm:` ignora a consulta ao ClawHub e
força a resolução pelo npm.
Se o mesmo pacote também estiver disponível no ClawHub, `npm:` ignora a consulta ao ClawHub e força a resolução via npm.
## Escolha da origem
## Escolha de origem
- **ClawHub**: use quando quiser descoberta nativa do OpenClaw, resumos de varredura,
versões e dicas de instalação.
- **npmjs.com**: use quando você já distribui pacotes JavaScript ou precisa de fluxos de trabalho de
dist-tags do npm/registro privado.
- **Git**: use quando quiser instalar diretamente de uma branch, tag ou commit.
- **Caminho local**: use quando estiver desenvolvendo ou testando um plugin na mesma
máquina.
- **ClawHub**: use quando quiser descoberta nativa do OpenClaw, resumos de varredura, versões e dicas de instalação.
- **npmjs.com**: use quando você já distribui pacotes JavaScript ou precisa de fluxos de trabalho de dist-tags/registro privado do npm.
- **Git**: use quando quiser instalar diretamente a partir de um branch, tag ou commit.
- **Caminho local**: use quando você estiver desenvolvendo ou testando um plugin na mesma máquina.
## Relacionados
## Relacionado
- [Plugins](/pt-BR/tools/plugin) - visão geral e solução de problemas
- [`openclaw plugins`](/pt-BR/cli/plugins) - referência completa da CLI

109
docs/pt-BR/providers/openrouter.md
View File

@ -1,34 +1,35 @@
---
read_when:
- Você quer uma única chave de API para vários LLMs
- Você quer executar modelos via OpenRouter no OpenClaw
- Você quer uma única chave de API para muitos LLMs
- Você quer executar modelos por meio do OpenRouter no OpenClaw
- Você quer usar o OpenRouter para geração de imagens
- Você quer usar o OpenRouter para geração de vídeo
summary: Use a API unificada da OpenRouter para acessar vários modelos no OpenClaw
- Você quer usar o OpenRouter para geração de vídeos
summary: Use a API unificada do OpenRouter para acessar muitos modelos no OpenClaw
title: OpenRouter
x-i18n:
generated_at: "2026-05-04T05:54:34Z"
generated_at: "2026-05-05T01:48:53Z"
model: gpt-5.5
provider: openai
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
source_path: providers/openrouter.md
workflow: 16
---
OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único endpoint e uma única chave de API. Ela é compatível com a OpenAI, então a maioria dos SDKs da OpenAI funciona ao trocar a URL base.
OpenRouter fornece uma **API unificada** que roteia solicitações para muitos modelos por trás de um único
endpoint e chave de API. Ela é compatível com OpenAI, portanto a maioria dos SDKs da OpenAI funciona ao trocar a URL base.
## Primeiros passos
<Steps>
<Step title="Get your API key">
<Step title="Obtenha sua chave de API">
Crie uma chave de API em [openrouter.ai/keys](https://openrouter.ai/keys).
</Step>
<Step title="Run onboarding">
<Step title="Execute o onboarding">
```bash
openclaw onboard --auth-choice openrouter-api-key
```
</Step>
<Step title="(Optional) Switch to a specific model">
<Step title="(Opcional) Mude para um modelo específico">
O onboarding usa `openrouter/auto` por padrão. Escolha um modelo concreto depois:
```bash
@ -51,16 +52,16 @@ OpenRouter fornece uma **API unificada** que roteia solicitações para muitos m
}
```
## Referências de modelos
## Referências de modelo
<Note>
Refs de modelo seguem o padrão `openrouter/<provider>/<model>`. Para a lista completa de
As refs de modelo seguem o padrão `openrouter/<provider>/<model>`. Para ver a lista completa de
provedores e modelos disponíveis, consulte [/concepts/model-providers](/pt-BR/concepts/model-providers).
</Note>
Exemplos de fallback incluídos:
| Ref. do modelo | Observações |
| Ref de modelo | Observações |
| --------------------------------- | ---------------------------- |
| `openrouter/auto` | Roteamento automático do OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI |
@ -83,7 +84,7 @@ OpenRouter também pode respaldar a ferramenta `image_generate`. Use um modelo d
}
```
O OpenClaw envia solicitações de imagem para a API de imagens de conclusões de chat do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas compatíveis de `aspectRatio` e `resolution` por meio do `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem mais lentos do OpenRouter; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda tem precedência.
OpenClaw envia solicitações de imagem para a API de imagens de chat completions do OpenRouter com `modalities: ["image", "text"]`. Modelos de imagem Gemini recebem dicas de `aspectRatio` e `resolution` compatíveis por meio de `image_config` do OpenRouter. Use `agents.defaults.imageGenerationModel.timeoutMs` para modelos de imagem do OpenRouter mais lentos; o parâmetro `timeoutMs` por chamada da ferramenta `image_generate` ainda prevalece.
## Geração de vídeo
@ -102,20 +103,20 @@ OpenRouter também pode respaldar a ferramenta `video_generate` por meio de sua
}
```
O OpenClaw envia trabalhos de texto para vídeo e imagem para vídeo ao OpenRouter, consulta
a `polling_url` retornada e baixa o vídeo concluído de
OpenClaw envia trabalhos de texto para vídeo e imagem para vídeo para o OpenRouter, faz polling
da `polling_url` retornada e baixa o vídeo concluído a partir de
`unsigned_urls` do OpenRouter ou do endpoint documentado de conteúdo do trabalho.
Imagens de referência são enviadas como imagens do primeiro/último quadro por padrão; imagens
Imagens de referência são enviadas por padrão como imagens do primeiro/último quadro; imagens
marcadas com `reference_image` são enviadas como referências de entrada do OpenRouter. O padrão
incluído `google/veo-3.1-fast` anuncia as durações atualmente compatíveis de 4/6/8
segundos, resoluções `720P`/`1080P` e proporções de aspecto `16:9`/`9:16`.
Vídeo para vídeo não é registrado para o OpenRouter porque a API upstream
de geração de vídeo atualmente aceita texto e referências de imagem.
Vídeo para vídeo não é registrado para o OpenRouter porque a API upstream de
geração de vídeo atualmente aceita texto e referências de imagem.
## Texto para fala
OpenRouter também pode ser usado como provedor de TTS por meio de seu endpoint
`/audio/speech` compatível com a OpenAI.
`/audio/speech` compatível com OpenAI.
```json5
{
@ -135,14 +136,14 @@ OpenRouter também pode ser usado como provedor de TTS por meio de seu endpoint
}
```
Se `messages.tts.providers.openrouter.apiKey` for omitido, o TTS reutiliza
Se `messages.tts.providers.openrouter.apiKey` for omitido, TTS reutiliza
`models.providers.openrouter.apiKey` e depois `OPENROUTER_API_KEY`.
## Autenticação e cabeçalhos
OpenRouter usa um token Bearer com sua chave de API internamente.
OpenRouter usa um token Bearer com sua chave de API por baixo dos panos.
Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), o OpenClaw também adiciona
Em solicitações reais ao OpenRouter (`https://openrouter.ai/api/v1`), OpenClaw também adiciona
os cabeçalhos documentados de atribuição de app do OpenRouter:
| Cabeçalho | Valor |
@ -152,14 +153,14 @@ os cabeçalhos documentados de atribuição de app do OpenRouter:
| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
<Warning>
Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, o OpenClaw
**não** injeta esses cabeçalhos específicos do OpenRouter nem marcadores de cache da Anthropic.
Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base, OpenClaw
**não** injetará esses cabeçalhos específicos do OpenRouter nem marcadores de cache da Anthropic.
</Warning>
## Configuração avançada
<AccordionGroup>
<Accordion title="Response caching">
<Accordion title="Cache de respostas">
O cache de respostas do OpenRouter é opcional. Habilite-o por modelo do OpenRouter com
parâmetros de modelo:
@ -180,60 +181,62 @@ Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base,
}
```
O OpenClaw envia `X-OpenRouter-Cache: true` e, quando configurado,
OpenClaw envia `X-OpenRouter-Cache: true` e, quando configurado,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` força uma atualização para
a solicitação atual e armazena a resposta substituta. Aliases em snake_case
(`response_cache`, `response_cache_ttl_seconds` e
`response_cache_clear`) também são aceitos.
Isso é separado do cache de prompt do provedor e dos marcadores
Anthropic `cache_control` do OpenRouter. Ele é aplicado apenas em rotas
Anthropic `cache_control` do OpenRouter. Ele só é aplicado em rotas
`openrouter.ai` verificadas, não em URLs base de proxy personalizadas.
</Accordion>
<Accordion title="Anthropic cache markers">
<Accordion title="Marcadores de cache Anthropic">
Em rotas verificadas do OpenRouter, refs de modelo Anthropic mantêm os
marcadores Anthropic `cache_control` específicos do OpenRouter que o OpenClaw usa para
melhor reutilização do cache de prompt em blocos de prompt de sistema/desenvolvedor.
</Accordion>
<Accordion title="Anthropic reasoning prefill">
<Accordion title="Pré-preenchimento de raciocínio Anthropic">
Em rotas verificadas do OpenRouter, refs de modelo Anthropic com raciocínio habilitado
removem turnos finais de preenchimento prévio do assistente antes que a solicitação chegue ao OpenRouter,
correspondendo à exigência da Anthropic de que conversas de raciocínio terminem com um
turno do usuário.
removem turnos finais de pré-preenchimento do assistente antes que a solicitação chegue ao OpenRouter,
correspondendo ao requisito da Anthropic de que conversas com raciocínio terminem com um turno
de usuário.
</Accordion>
<Accordion title="Thinking / reasoning injection">
Em rotas não `auto` compatíveis, o OpenClaw mapeia o nível de pensamento selecionado para
payloads de raciocínio do proxy OpenRouter. Dicas de modelo não compatíveis e
<Accordion title="Injeção de pensamento / raciocínio">
Em rotas não `auto` compatíveis, OpenClaw mapeia o nível de pensamento selecionado para
payloads de raciocínio de proxy do OpenRouter. Dicas de modelo não compatíveis e
`openrouter/auto` ignoram essa injeção de raciocínio. Hunter Alpha também ignora
o raciocínio de proxy para refs de modelo configuradas obsoletas porque o OpenRouter poderia
retornar texto de resposta final em campos de raciocínio para essa rota descontinuada.
raciocínio de proxy para refs de modelo configuradas obsoletas porque o OpenRouter poderia
retornar texto de resposta final em campos de raciocínio para essa rota aposentada.
</Accordion>
<Accordion title="DeepSeek V4 reasoning replay">
<Accordion title="Replay de raciocínio DeepSeek V4">
Em rotas verificadas do OpenRouter, `openrouter/deepseek/deepseek-v4-flash` e
`openrouter/deepseek/deepseek-v4-pro` preenchem `reasoning_content` ausente em
turnos de assistente reproduzidos para que conversas com pensamento/ferramentas mantenham o formato
de acompanhamento exigido pelo DeepSeek V4.
turnos de assistente reproduzidos para que conversas de pensamento/ferramenta mantenham o
formato de acompanhamento exigido pelo DeepSeek V4. OpenClaw envia valores de
`reasoning_effort` compatíveis com o OpenRouter para essas rotas; `xhigh` é o nível mais alto anunciado,
e substituições `max` obsoletas são mapeadas para `xhigh`.
</Accordion>
<Accordion title="OpenAI-only request shaping">
OpenRouter ainda passa pelo caminho compatível com OpenAI no estilo proxy, então
a modelagem de solicitação nativa apenas da OpenAI, como `serviceTier`, `store` de Responses,
payloads compatíveis com raciocínio da OpenAI e dicas de cache de prompt, não é encaminhada.
<Accordion title="Formatação de solicitação apenas para OpenAI">
OpenRouter ainda passa pelo caminho em estilo proxy compatível com OpenAI, portanto
formatações de solicitação nativas apenas da OpenAI, como `serviceTier`, Responses `store`,
payloads de compatibilidade com raciocínio da OpenAI e dicas de cache de prompt não são encaminhadas.
</Accordion>
<Accordion title="Gemini-backed routes">
Refs do OpenRouter respaldadas por Gemini permanecem no caminho proxy-Gemini: o OpenClaw mantém
a sanitização de assinatura de pensamento Gemini lá, mas não habilita a validação nativa de reprodução
Gemini nem reescritas de bootstrap.
<Accordion title="Rotas com backend Gemini">
Refs do OpenRouter com backend Gemini permanecem no caminho proxy-Gemini: OpenClaw mantém
a higienização de assinatura de pensamento do Gemini ali, mas não habilita a validação de replay
nativa do Gemini nem reescritas de bootstrap.
</Accordion>
<Accordion title="Provider routing metadata">
Se você passar roteamento de provedor do OpenRouter em parâmetros de modelo, o OpenClaw o encaminha
<Accordion title="Metadados de roteamento de provedor">
Se você passar roteamento de provedor do OpenRouter nos parâmetros de modelo, OpenClaw o encaminha
como metadados de roteamento do OpenRouter antes que os wrappers de stream compartilhados sejam executados.
</Accordion>
</AccordionGroup>
@ -241,10 +244,10 @@ Se você redirecionar o provedor OpenRouter para algum outro proxy ou URL base,
## Relacionado
<CardGroup cols={2}>
<Card title="Model selection" href="/pt-BR/concepts/model-providers" icon="layers">
<Card title="Seleção de modelo" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, refs de modelo e comportamento de failover.
</Card>
<Card title="Configuration reference" href="/pt-BR/gateway/configuration-reference" icon="gear">
<Card title="Referência de configuração" href="/pt-BR/gateway/configuration-reference" icon="gear">
Referência completa de configuração para agentes, modelos e provedores.
</Card>
</CardGroup>

642
docs/pt-BR/reference/RELEASING.md
View File

@ -1,188 +1,172 @@
---
read_when:
- Procurando definições de canais de lançamento públicos
- Executando a validação de release ou a aceitação de pacote
- Buscando nomenclatura e cadência de versões
summary: Faixas de lançamento, lista de verificação do operador, caixas de validação, nomenclatura de versões e cadência
- Procurando definições de canais públicos de lançamento
- Executando validação de release ou aceitação de pacote
- Procurando nomenclatura e cadência de versões
summary: Faixas de lançamento, checklist do operador, caixas de validação, nomenclatura de versões e cadência
title: Política de lançamento
x-i18n:
generated_at: "2026-05-04T07:03:56Z"
generated_at: "2026-05-05T01:49:02Z"
model: gpt-5.5
provider: openai
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw tem três canais públicos de release:
OpenClaw tem três canais públicos de lançamento:
- estável: releases marcadas que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente
- beta: tags de pré-release que publicam no npm `beta`
- dev: o head móvel de `main`
- stable: lançamentos com tag que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente
- beta: tags de pré-lançamento que publicam no npm `beta`
- dev: o ponto mais recente em movimento de `main`
## Nomenclatura de versões
- Versão de release estável: `YYYY.M.D`
- Tag Git: `vYYYY.M.D`
- Versão de release de correção estável: `YYYY.M.D-N`
- Tag Git: `vYYYY.M.D-N`
- Versão de pré-release beta: `YYYY.M.D-beta.N`
- Tag Git: `vYYYY.M.D-beta.N`
- Não preencha mês ou dia com zero à esquerda
- `latest` significa o release npm estável promovido atual
- Versão de lançamento estável: `YYYY.M.D`
- Tag do Git: `vYYYY.M.D`
- Versão de lançamento estável de correção: `YYYY.M.D-N`
- Tag do Git: `vYYYY.M.D-N`
- Versão beta de pré-lançamento: `YYYY.M.D-beta.N`
- Tag do Git: `vYYYY.M.D-beta.N`
- Não adicione zeros à esquerda ao mês ou ao dia
- `latest` significa a versão estável atual promovida no npm
- `beta` significa o destino atual de instalação beta
- Releases estáveis e releases de correção estáveis publicam no npm `beta` por padrão; operadores de release podem direcionar para `latest` explicitamente, ou promover uma build beta validada posteriormente
- Todo release estável do OpenClaw entrega o pacote npm e o app macOS juntos;
releases beta normalmente validam e publicam primeiro o caminho npm/pacote, com
build/assinatura/notarização do app Mac reservados para estável, salvo solicitação explícita
- Lançamentos estáveis e lançamentos estáveis de correção publicam no npm `beta` por padrão; operadores de lançamento podem direcionar explicitamente para `latest` ou promover uma compilação beta validada posteriormente
- Todo lançamento estável do OpenClaw entrega o pacote npm e o app para macOS juntos;
lançamentos beta normalmente validam e publicam primeiro o caminho npm/pacote, com
compilação/assinatura/notarização do app para Mac reservadas para stable, salvo solicitação explícita
## Cadência de release
## Cadência de lançamentos
- Releases avançam primeiro para beta
- Estável vem somente depois que a beta mais recente é validada
- Mantenedores normalmente criam releases a partir de uma branch `release/YYYY.M.D` criada
a partir da `main` atual, para que validação e correções de release não bloqueiem novo
desenvolvimento na `main`
- Se uma tag beta tiver sido enviada ou publicada e precisar de correção, mantenedores criam
- Lançamentos seguem primeiro para beta
- Stable vem somente depois que o beta mais recente é validado
- Mantenedores normalmente criam lançamentos a partir de uma branch `release/YYYY.M.D` criada
a partir da `main` atual, para que a validação e as correções de lançamento não bloqueiem novos
desenvolvimentos em `main`
- Se uma tag beta tiver sido enviada ou publicada e precisar de correção, os mantenedores criam
a próxima tag `-beta.N` em vez de excluir ou recriar a tag beta antiga
- Procedimento detalhado de release, aprovações, credenciais e notas de recuperação são
apenas para mantenedores
- O procedimento detalhado de lançamento, aprovações, credenciais e notas de recuperação são
exclusivos para mantenedores
## Checklist do operador de release
## Lista de verificação do operador de lançamento
Este checklist é o formato público do fluxo de release. Credenciais privadas,
Esta lista de verificação é o formato público do fluxo de lançamento. Credenciais privadas,
assinatura, notarização, recuperação de dist-tag e detalhes de rollback de emergência ficam no
runbook de release restrito a mantenedores.
runbook de lançamento exclusivo para mantenedores.
1. Comece pela `main` atual: puxe a versão mais recente, confirme que o commit de destino foi enviado,
e confirme que o CI da `main` atual está verde o suficiente para criar uma branch a partir dele.
1. Comece pela `main` atual: baixe as alterações mais recentes, confirme que o commit de destino foi enviado
e confirme que o CI atual da `main` está verde o suficiente para criar uma branch a partir dela.
2. Reescreva a seção superior de `CHANGELOG.md` a partir do histórico real de commits com
`/changelog`, mantenha as entradas voltadas ao usuário, faça commit, envie, e faça rebase/pull
mais uma vez antes de criar a branch.
3. Revise os registros de compatibilidade de release em
3. Revise os registros de compatibilidade de lançamento em
`src/plugins/compat/registry.ts` e
`src/commands/doctor/shared/deprecation-compat.ts`. Remova compatibilidade expirada
somente quando o caminho de upgrade continuar coberto, ou registre por que ela está
somente quando o caminho de atualização continuar coberto, ou registre por que ela está
sendo mantida intencionalmente.
4. Crie `release/YYYY.M.D` a partir da `main` atual; não faça trabalho normal de release
diretamente na `main`.
5. Atualize todas as localizações de versão exigidas para a tag pretendida, execute
`pnpm plugins:sync` para que os pacotes de Plugin publicáveis compartilhem a versão
de release e os metadados de compatibilidade, depois execute o preflight determinístico local:
4. Crie `release/YYYY.M.D` a partir da `main` atual; não faça o trabalho normal de lançamento
diretamente em `main`.
5. Atualize todos os locais de versão necessários para a tag pretendida, execute
`pnpm plugins:sync` para que os pacotes de Plugin publicáveis compartilhem a versão de lançamento
e os metadados de compatibilidade, depois execute o preflight determinístico local:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` e
`pnpm release:check`.
6. Execute `OpenClaw NPM Release` com `preflight_only=true`. Antes de existir uma tag,
um SHA completo de 40 caracteres da branch de release é permitido para preflight
6. Execute `OpenClaw NPM Release` com `preflight_only=true`. Antes de uma tag existir,
um SHA completo de 40 caracteres da branch de lançamento é permitido para preflight
apenas de validação. Salve o `preflight_run_id` bem-sucedido.
7. Inicie todos os testes de pré-release com `Full Release Validation` para a
branch de release, tag ou SHA completo do commit. Este é o único ponto de entrada manual
para as quatro grandes caixas de teste de release: Vitest, Docker, QA Lab e Package.
8. Se a validação falhar, corrija na branch de release e reexecute o menor
7. Inicie todos os testes de pré-lançamento com `Full Release Validation` para a
branch de lançamento, tag ou SHA de commit completo. Este é o único ponto de entrada manual
para as quatro grandes caixas de teste de lançamento: Vitest, Docker, QA Lab e Package.
8. Se a validação falhar, corrija na branch de lançamento e execute novamente o menor
arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo com falha que
comprove a correção. Reexecute o guarda-chuva completo somente quando a superfície alterada tornar
comprove a correção. Execute novamente o guarda-chuva completo somente quando a superfície alterada tornar
as evidências anteriores obsoletas.
9. Para beta, marque `vYYYY.M.D-beta.N`, depois execute `OpenClaw Release Publish` a partir
9. Para beta, crie a tag `vYYYY.M.D-beta.N` e execute `OpenClaw Release Publish` a partir
da branch `release/YYYY.M.D` correspondente. Ele verifica `pnpm plugins:sync:check`,
publica primeiro todos os pacotes de Plugin publicáveis no npm, publica o mesmo
conjunto no ClawHub em segundo lugar como tarballs ClawPack npm-pack, e então promove o
conjunto no ClawHub em seguida como tarballs ClawPack npm-pack e então promove o
artefato de preflight npm preparado do OpenClaw com a dist-tag correspondente. Após
publicar, execute a aceitação de pacote pós-publicação
contra o pacote publicado `openclaw@YYYY.M.D-beta.N` ou
`openclaw@beta`. Se uma pré-release enviada ou publicada precisar de correção,
crie o próximo número de pré-release correspondente; não exclua nem reescreva a pré-release
antiga.
10. Para estável, continue somente depois que a beta validada ou o release candidate tiver as
evidências de validação exigidas. A publicação npm estável também passa por
publicar, execute a aceitação de pacote pós-publicação contra o pacote
`openclaw@YYYY.M.D-beta.N` ou `openclaw@beta` publicado. Se um pré-lançamento enviado ou publicado precisar de correção,
crie o próximo número de pré-lançamento correspondente; não exclua nem reescreva o pré-lançamento antigo.
10. Para stable, continue somente depois que o beta validado ou candidato a lançamento tiver as
evidências de validação exigidas. A publicação npm stable também passa por
`OpenClaw Release Publish`, reutilizando o artefato de preflight bem-sucedido via
`preflight_run_id`; a prontidão do release macOS estável também exige os
`.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado na `main`.
`preflight_run_id`; a prontidão do lançamento stable para macOS também exige o
`.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado em `main`.
11. Após publicar, execute o verificador npm pós-publicação, o E2E opcional do Telegram
usando npm publicado independente quando precisar de prova de canal pós-publicação,
promoção de dist-tag quando necessário, notas de release/pré-release do GitHub a partir da
seção completa correspondente de `CHANGELOG.md`, e as etapas de anúncio de release.
standalone publicado no npm quando você precisar de comprovação de canal pós-publicação,
a promoção de dist-tag quando necessário, notas de release/pré-release do GitHub a partir da
seção completa correspondente de `CHANGELOG.md` e as etapas de anúncio do lançamento.
## Preflight de release
## Preflight de lançamento
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript de teste continue coberto fora do gate local mais rápido `pnpm check`
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript de teste permaneça coberto fora do gate local mais rápido `pnpm check`
- Execute `pnpm check:architecture` antes do preflight de release para que as verificações mais amplas de ciclos de importação e limites de arquitetura fiquem verdes fora do gate local mais rápido
- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados em `dist/*` e o bundle da Control UI existam para a etapa de validação do pack
- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de criar a tag. Ele atualiza versões de pacotes de plugins publicáveis, metadados de compatibilidade de peer/API do OpenClaw, metadados de build e stubs de changelog dos plugins para corresponder à versão de release do core. `pnpm plugins:sync:check` é o guardião de release não mutável; o workflow de publicação falha antes de qualquer mutação no registry se esta etapa tiver sido esquecida.
- Execute o workflow manual `Full Release Validation` antes da aprovação de release para iniciar todas as caixas de teste pré-release a partir de um único ponto de entrada. Ele aceita uma branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release do Docker, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e faixas do Telegram. Com `release_profile=full` e `rerun_group=all`, ele também executa o E2E de pacote do Telegram contra o artefato `release-package-under-test` das verificações de release. Forneça `npm_telegram_package_spec` depois da publicação quando o mesmo E2E do Telegram também precisar comprovar o pacote npm publicado. Forneça `package_acceptance_package_spec` depois da publicação quando Package Acceptance precisar executar sua matriz de pacote/atualização contra o pacote npm entregue em vez do artefato criado a partir do SHA. Forneça `evidence_package_spec` quando o relatório privado de evidências precisar comprovar que a validação corresponde a um pacote npm publicado sem forçar E2E do Telegram. Exemplo:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Execute o workflow manual `Package Acceptance` quando quiser prova por canal lateral para um candidato de pacote enquanto o trabalho de release continua. Use `source=npm` para `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` para empacotar uma branch/tag/SHA `package_ref` confiável com o harness `workflow_ref` atual; `source=url` para um tarball HTTPS com SHA-256 obrigatório; ou `source=artifact` para um tarball enviado por outra execução do GitHub Actions. O workflow resolve o candidato para `package-under-test`, reutiliza o agendador de release Docker E2E contra esse tarball e pode executar QA do Telegram contra o mesmo tarball com `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as faixas Docker selecionadas incluem `published-upgrade-survivor`, o artefato do pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a linha de base publicada.
- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados em `dist/*` e o bundle da Control UI existam para a etapa de validação do pacote
- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de criar a tag. Ele atualiza as versões de pacotes de plugins publicáveis, os metadados de compatibilidade de peer/API do OpenClaw, os metadados de build e os stubs de changelog dos plugins para corresponder à versão de release do núcleo. `pnpm plugins:sync:check` é a proteção de release não mutável; o workflow de publicação falha antes de qualquer mutação de registry se essa etapa tiver sido esquecida.
- Execute o workflow manual `Full Release Validation` antes da aprovação do release para iniciar todas as caixas de teste pré-release a partir de um único ponto de entrada. Ele aceita um branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para install smoke, aceitação de pacote, verificações de pacote entre sistemas operacionais, paridade do QA Lab, Matrix e lanes do Telegram. Execuções estáveis/padrão mantêm o soak exaustivo live/E2E e do caminho de release do Docker atrás de `run_release_soak=true`; `release_profile=full` força o soak. Com `release_profile=full` e `rerun_group=all`, ele também executa E2E de pacote do Telegram contra o artefato `release-package-under-test` das verificações de release. Forneça `npm_telegram_package_spec` após a publicação quando o mesmo E2E do Telegram também deve provar o pacote npm publicado. Forneça `package_acceptance_package_spec` após a publicação quando Package Acceptance deve executar sua matriz de pacote/atualização contra o pacote npm enviado em vez do artefato criado a partir do SHA. Forneça `evidence_package_spec` quando o relatório de evidências privado deve provar que a validação corresponde a um pacote npm publicado sem forçar o E2E do Telegram. Exemplo: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Execute o workflow manual `Package Acceptance` quando quiser uma prova por canal lateral para um candidato de pacote enquanto o trabalho de release continua. Use `source=npm` para `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` para empacotar um branch/tag/SHA confiável de `package_ref` com o harness atual de `workflow_ref`; `source=url` para um tarball HTTPS com SHA-256 obrigatório; ou `source=artifact` para um tarball enviado por outra execução do GitHub Actions. O workflow resolve o candidato para `package-under-test`, reutiliza o agendador de release Docker E2E contra esse tarball e pode executar QA do Telegram contra o mesmo tarball com `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as lanes Docker selecionadas incluem `published-upgrade-survivor`, o artefato de pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a baseline publicada.
Exemplo: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Perfis comuns:
- `smoke`: faixas de instalação/canal/agente, rede do Gateway e recarregamento de configuração
- `package`: faixas nativas de artefato para pacote/atualização/plugin sem OpenWebUI ou ClawHub live
- `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente,
busca web da OpenAI e OpenWebUI
- `smoke`: lanes de instalação/canal/agente, rede do Gateway e recarregamento de configuração
- `package`: lanes nativas de artefato para pacote/atualização/plugin sem OpenWebUI ou ClawHub live
- `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente, busca na web da OpenAI e OpenWebUI
- `full`: partes do caminho de release Docker com OpenWebUI
- `custom`: seleção exata de `docker_lanes` para uma reexecução focada
- Execute o workflow manual `CI` diretamente quando você só precisar da cobertura completa normal de CI para o candidato de release. Disparos manuais de CI ignoram o escopo por alterações e forçam as shards Linux Node, shards de plugins agrupados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills em Python, Windows, macOS, Android e faixas de i18n da Control UI.
- Execute o workflow manual `CI` diretamente quando precisar apenas da cobertura completa normal de CI para o candidato de release. Disparos manuais de CI ignoram o escopo por alterações e forçam as shards Linux Node, shards de plugins empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e lanes de i18n da Control UI.
Exemplo: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Execute `pnpm qa:otel:smoke` ao validar telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans de trace exportados, atributos limitados e redação de conteúdo/identificadores sem exigir Opik, Langfuse ou outro coletor externo.
- Execute `pnpm release:check` antes de toda release com tag
- Execute `OpenClaw Release Publish` para a sequência de publicação mutável depois que a tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma tag alcançável por main), passe a tag de release e o `preflight_run_id` npm do OpenClaw bem-sucedido, e mantenha o escopo padrão de publicação de plugins `all-publishable`, a menos que você esteja executando deliberadamente um reparo focado. O workflow serializa a publicação npm de plugins, a publicação ClawHub de plugins e a publicação npm do OpenClaw para que o pacote core não seja publicado antes dos seus plugins externalizados.
- As verificações de release agora são executadas em um workflow manual separado:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` também executa a faixa de paridade mock do QA Lab mais o perfil Matrix live rápido e a faixa QA do Telegram antes da aprovação de release. As faixas live usam o ambiente `qa-live-shared`; o Telegram também usa concessões de credenciais CI do Convex. Execute o workflow manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte Matrix, mídia e E2EE em paralelo.
- A validação de runtime de instalação e atualização entre sistemas operacionais faz parte dos workflows públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o workflow reutilizável `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Essa divisão é intencional: manter o caminho real de release npm curto, determinístico e focado em artefatos, enquanto verificações live mais lentas permanecem na própria faixa para não atrasarem nem bloquearem a publicação
- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release Validation` ou a partir do ref de workflow `main`/release para que a lógica do workflow e os segredos permaneçam controlados
- `OpenClaw Release Checks` aceita uma branch, tag ou SHA completo de commit desde que o commit resolvido seja alcançável a partir de uma branch OpenClaw ou tag de release
- O preflight apenas de validação de `OpenClaw NPM Release` também aceita o SHA completo de 40 caracteres do commit atual da branch do workflow sem exigir uma tag enviada
- Esse caminho por SHA é apenas de validação e não pode ser promovido para uma publicação real
- Execute `pnpm qa:otel:smoke` ao validar telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans de trace exportados, atributos limitados e redação de conteúdo/identificador sem exigir Opik, Langfuse ou outro coletor externo.
- Execute `pnpm release:check` antes de cada release com tag
- Execute `OpenClaw Release Publish` para a sequência mutável de publicação depois que a tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma tag alcançável por main), passe a tag de release e o `preflight_run_id` bem-sucedido do npm do OpenClaw, e mantenha o escopo padrão de publicação de plugins `all-publishable`, a menos que esteja executando deliberadamente um reparo focado. O workflow serializa a publicação npm de plugins, a publicação de plugins no ClawHub e a publicação npm do OpenClaw para que o pacote central não seja publicado antes de seus plugins externalizados.
- As verificações de release agora são executadas em um workflow manual separado: `OpenClaw Release Checks`
- `OpenClaw Release Checks` também executa a lane de paridade mock do QA Lab, além do perfil rápido live do Matrix e da lane de QA do Telegram antes da aprovação do release. As lanes live usam o ambiente `qa-live-shared`; o Telegram também usa leases de credenciais de CI do Convex. Execute o workflow manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte, mídia e E2EE do Matrix em paralelo.
- A validação de runtime de instalação e upgrade entre sistemas operacionais faz parte dos workflows públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o workflow reutilizável `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Essa divisão é intencional: manter o caminho real de release npm curto, determinístico e focado em artefatos, enquanto verificações live mais lentas permanecem em sua própria lane para que não atrasem nem bloqueiem a publicação
- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release Validation` ou a partir da ref de workflow `main`/release para que a lógica do workflow e os segredos permaneçam controlados
- `OpenClaw Release Checks` aceita um branch, tag ou SHA completo de commit desde que o commit resolvido seja alcançável a partir de um branch do OpenClaw ou tag de release
- O preflight somente de validação de `OpenClaw NPM Release` também aceita o SHA completo atual de 40 caracteres do commit do branch de workflow sem exigir uma tag enviada
- Esse caminho de SHA é somente de validação e não pode ser promovido para uma publicação real
- No modo SHA, o workflow sintetiza `v<package.json version>` apenas para a verificação de metadados do pacote; a publicação real ainda exige uma tag de release real
- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação não mutável pode usar os runners Linux maiores do Blacksmith
- Esse workflow executa
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
usando os segredos de workflow `OPENAI_API_KEY` e `ANTHROPIC_API_KEY`
- O preflight de release npm não espera mais pela faixa separada de verificações de release
- Execute `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(ou a tag beta/correção correspondente) antes da aprovação
- Depois da publicação npm, execute
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(ou a versão beta/correção correspondente) para verificar o caminho de instalação pelo registry publicado em um prefixo temporário novo
- Depois de uma publicação beta, execute `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
para verificar onboarding do pacote instalado, configuração do Telegram e E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais alugadas do Telegram. Execuções pontuais locais de mantenedores podem omitir as vars do Convex e passar diretamente as três credenciais de env `OPENCLAW_QA_TELEGRAM_*`.
- Para executar o smoke beta pós-publicação completo a partir de uma máquina de mantenedor, use `pnpm release:beta-smoke -- --beta betaN`. O helper executa validação de atualização npm/fresh-target do Parallels, dispara `NPM Telegram Beta E2E`, consulta a execução exata do workflow, baixa o artefato e imprime o relatório do Telegram.
- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions por meio do workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não roda em todo merge.
- A automação de release de mantenedores agora usa preflight-depois-promote:
- a publicação npm real deve passar um `preflight_run_id` npm bem-sucedido
- a publicação npm real deve ser disparada a partir da mesma branch `main` ou
`release/YYYY.M.D` da execução de preflight bem-sucedida
- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação não mutável pode usar os runners Linux maiores da Blacksmith
- Esse workflow executa `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` usando os segredos de workflow `OPENAI_API_KEY` e `ANTHROPIC_API_KEY`
- O preflight de release npm não espera mais pela lane separada de verificações de release
- Execute `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (ou a tag beta/correção correspondente) antes da aprovação
- Após a publicação npm, execute `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (ou a versão beta/correção correspondente) para verificar o caminho de instalação no registry publicado em um prefixo temporário novo
- Após uma publicação beta, execute `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` para verificar onboarding do pacote instalado, configuração do Telegram e E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais alugadas do Telegram. Execuções pontuais locais de mantenedores podem omitir as vars do Convex e passar diretamente as três credenciais de env `OPENCLAW_QA_TELEGRAM_*`.
- Para executar o smoke beta completo pós-publicação a partir da máquina de um mantenedor, use `pnpm release:beta-smoke -- --beta betaN`. O helper executa validação de atualização npm/fresh-target no Parallels, dispara `NPM Telegram Beta E2E`, faz polling da execução exata do workflow, baixa o artefato e imprime o relatório do Telegram.
- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions por meio do workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não executa a cada merge.
- A automação de release dos mantenedores agora usa preflight-then-promote:
- a publicação npm real deve passar por um `preflight_run_id` npm bem-sucedido
- a publicação npm real deve ser disparada a partir do mesmo branch `main` ou `release/YYYY.M.D` da execução de preflight bem-sucedida
- releases npm estáveis usam `beta` por padrão
- a publicação npm estável pode mirar `latest` explicitamente via input do workflow
- a mutação de dist-tag npm baseada em token agora vive em
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN`, enquanto o repo público mantém publicação somente com OIDC
- `macOS Release` público é apenas validação; quando uma tag existe apenas em uma
branch de release, mas o workflow é disparado a partir de `main`, defina
`public_release_branch=release/YYYY.M.D`
- a publicação privada real do mac deve passar por `preflight_run_id` e `validate_run_id` privados de mac bem-sucedidos
- a publicação npm estável pode mirar explicitamente `latest` via input do workflow
- a mutação de dist-tag npm baseada em token agora fica em `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN`, enquanto o repositório público mantém publicação somente por OIDC
- `macOS Release` público é somente de validação; quando uma tag existe apenas em um branch de release, mas o workflow é disparado a partir de `main`, defina `public_release_branch=release/YYYY.M.D`
- a publicação privada real para mac deve passar por `preflight_run_id` e `validate_run_id` privados de mac bem-sucedidos
- os caminhos reais de publicação promovem artefatos preparados em vez de reconstruí-los novamente
- Para releases de correção estáveis como `YYYY.M.D-N`, o verificador pós-publicação também checa o mesmo caminho de atualização com prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, para que correções de release não deixem silenciosamente instalações globais antigas no payload estável base
- O preflight de release npm falha fechado, a menos que o tarball inclua tanto `dist/control-ui/index.html` quanto um payload não vazio em `dist/control-ui/assets/`, para que não entreguemos novamente um dashboard de navegador vazio
- A verificação pós-publicação também checa se os entrypoints de plugins publicados e os metadados de pacote estão presentes no layout instalado do registry. Uma release que entrega payloads de runtime de plugins ausentes falha no verificador postpublish e não pode ser promovida para `latest`.
- `pnpm test:install:smoke` também impõe o orçamento de `unpackedSize` do pack npm no tarball candidato de atualização, para que o e2e do instalador detecte crescimento acidental do pack antes do caminho de publicação de release
- Se o trabalho de release tocou planejamento de CI, manifests de timing de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard`, de propriedade do planejador, a partir de `.github/workflows/plugin-prerelease.yml` antes da aprovação para que as notas de release não descrevam um layout de CI obsoleto
- A prontidão de release estável do macOS também inclui as superfícies do atualizador:
- a release do GitHub deve acabar com os `.zip`, `.dmg` e `.dSYM.zip` empacotados
- `appcast.xml` em `main` deve apontar para o novo zip estável depois da publicação
- Para releases estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação também verifica o mesmo caminho de upgrade em prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, para que correções de release não deixem silenciosamente instalações globais antigas no payload estável base
- O preflight de release npm falha fechado a menos que o tarball inclua tanto `dist/control-ui/index.html` quanto um payload não vazio em `dist/control-ui/assets/`, para que não enviemos novamente um dashboard de navegador vazio
- A verificação pós-publicação também verifica que entrypoints de plugins publicados e metadados de pacote estão presentes no layout instalado do registry. Um release que envia payloads de runtime de plugins ausentes falha no verificador pós-publicação e não pode ser promovido para `latest`.
- `pnpm test:install:smoke` também impõe o orçamento de `unpackedSize` do pacote npm no tarball candidato de atualização, para que o e2e do instalador capture bloat acidental de pacote antes do caminho de publicação do release
- Se o trabalho de release tocou planejamento de CI, manifests de timing de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard` pertencentes ao planner em `.github/workflows/plugin-prerelease.yml` antes da aprovação, para que as notas de release não descrevam um layout de CI obsoleto
- A prontidão de release estável para macOS também inclui as superfícies de atualizador:
- o release do GitHub deve terminar com os pacotes `.zip`, `.dmg` e `.dSYM.zip`
- `appcast.xml` em `main` deve apontar para o novo zip estável após a publicação
- o app empacotado deve manter um bundle id não debug, uma URL de feed Sparkle não vazia e um `CFBundleVersion` igual ou superior ao piso canônico de build do Sparkle para essa versão de release
## Caixas de teste de release
`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Para uma prova de commit fixado em uma branch de movimentação rápida, use o helper para que todo workflow filho rode a partir de uma branch temporária fixada no SHA de destino:
`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Para uma prova de commit fixado em um branch que se move rapidamente, use o helper para que cada workflow filho execute a partir de um branch temporário fixado no SHA alvo:
```bash
pnpm ci:full-release --sha <full-sha>
```
O helper envia `release-ci/<sha>-...`, dispara `Full Release Validation` a partir dessa branch com `ref=<sha>`, verifica se todo `headSha` de workflow filho corresponde ao alvo e então exclui a branch temporária. Isso evita comprovar por acidente uma execução filha de `main` mais nova.
O helper envia `release-ci/<sha>-...`, dispara `Full Release Validation` a partir desse branch com `ref=<sha>`, verifica que cada `headSha` de workflow filho corresponde ao alvo e então exclui o branch temporário. Isso evita provar acidentalmente uma execução filha de `main` mais nova.
Para validação de branch ou tag de release, execute a partir do ref de workflow confiável `main` e passe a branch ou tag de release como `ref`:
Para validação de branch de release ou tag, execute-a a partir da ref confiável de workflow `main` e passe o branch de release ou tag como `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -194,52 +178,52 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
O fluxo de trabalho resolve a ref de destino, despacha o `CI` manual com
`target_ref=<release-ref>`, despacha `OpenClaw Release Checks`, prepara um
artefato pai `release-package-under-test` para verificações voltadas a pacotes e
despacha o E2E independente do pacote Telegram quando `release_profile=full` com
`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. Em
seguida, `OpenClaw Release Checks` distribui smoke de instalação, verificações de
lançamento entre sistemas operacionais, cobertura do caminho de lançamento
live/E2E em Docker, Package Acceptance com QA do pacote Telegram, paridade do QA
Lab, Matrix live e Telegram live. Uma execução completa só é aceitável quando o
resumo de `Full Release Validation` mostra `normal_ci` e `release_checks` como
bem-sucedidos. No modo full/all, o filho `npm_telegram` também deve ser
bem-sucedido; fora de full/all, ele é ignorado, a menos que um
`npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final do
verificador inclui tabelas dos jobs mais lentos para cada execução filha, para
que o gerente de lançamento possa ver o caminho crítico atual sem baixar logs.
Consulte [Validação completa de lançamento](/pt-BR/reference/full-release-validation)
para ver a matriz de estágios completa, os nomes exatos dos jobs de workflow, as
diferenças entre os perfis stable e full, artefatos e identificadores de nova
execução focada.
Os workflows filhos são despachados a partir da ref confiável que executa
`Full Release Validation`, normalmente `--ref main`, mesmo quando a `ref` de
destino aponta para um branch ou tag de lançamento mais antigo. Não há uma
entrada separada de ref do workflow Full Release Validation; escolha o harness
confiável escolhendo a ref da execução do workflow. Não use `--ref main -f
ref=<sha>` para prova de commit exata em uma `main` móvel; SHAs brutos de commit
não podem ser refs de despacho de workflow, então use `pnpm ci:full-release
--sha <sha>` para criar o branch temporário fixado.
O workflow resolve a ref de destino, dispara o `CI` manual com
`target_ref=<release-ref>`, dispara `OpenClaw Release Checks`, prepara um
artefato pai `release-package-under-test` para verificações voltadas a pacote e
dispara o E2E autônomo do pacote Telegram quando `release_profile=full` com
`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. `OpenClaw Release
Checks` então distribui para install smoke, verificações de release entre SOs, cobertura live/E2E Docker
do caminho de release quando o soak está habilitado, Package Acceptance com QA do pacote Telegram, paridade QA Lab, Matrix live e Telegram live. Uma execução completa só é aceitável quando o
resumo de `Full Release Validation`
mostra `normal_ci` e `release_checks` como bem-sucedidos. No modo full/all,
o filho `npm_telegram` também deve ser bem-sucedido; fora de full/all, ele é ignorado
a menos que um `npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final do
verificador inclui tabelas dos jobs mais lentos para cada execução filha, para que o gerente de release
possa ver o caminho crítico atual sem baixar logs.
Consulte [Validação completa de release](/pt-BR/reference/full-release-validation) para a
matriz completa de etapas, os nomes exatos dos jobs do workflow, diferenças entre perfis stable e full,
artefatos e identificadores de reexecução focada.
Workflows filhos são disparados a partir da ref confiável que executa `Full Release
Validation`, normalmente `--ref main`, mesmo quando a `ref` de destino aponta para uma
branch ou tag de release mais antiga. Não há uma entrada separada de ref do workflow Full Release Validation;
escolha o harness confiável escolhendo a ref da execução do workflow.
Não use `--ref main -f ref=<sha>` para prova de commit exato em `main` móvel;
SHAs brutos de commit não podem ser refs de dispatch de workflow, então use
`pnpm ci:full-release --sha <sha>` para criar a branch temporária fixada.
Use `release_profile` para selecionar a amplitude live/de provedor:
Use `release_profile` para selecionar a abrangência live/provedor:
- `minimum`: caminho live e Docker mais rápido, crítico para lançamento, de OpenAI/core
- `stable`: minimum mais cobertura estável de provedor/backend para aprovação de lançamento
- `full`: stable mais cobertura ampla de provedores/mídia consultiva
- `minimum`: caminho Docker e live OpenAI/core crítico de release mais rápido
- `stable`: minimum mais cobertura estável de provedor/backend para aprovação de release
- `full`: stable mais cobertura ampla de provedor/mídia consultiva
`OpenClaw Release Checks` usa a ref confiável do workflow para resolver a ref de
destino uma vez como `release-package-under-test` e reutiliza esse artefato tanto
nas verificações Docker do caminho de lançamento quanto no Package Acceptance.
Isso mantém todas as caixas voltadas a pacotes nos mesmos bytes e evita builds de
pacote repetidos. O smoke de instalação OpenAI entre sistemas operacionais usa
`OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a variável de repo/org está definida;
caso contrário, usa `openai/gpt-5.4`, porque esta lane prova a instalação do
pacote, onboarding, inicialização do Gateway e uma interação live de agente, em
vez de fazer benchmark do modelo padrão mais lento. A matriz live mais ampla de
provedores continua sendo o lugar para cobertura específica por modelo.
Use `run_release_soak=true` com `stable` quando as lanes bloqueantes de release estiverem
verdes e você quiser a varredura exaustiva live/E2E, do caminho de release Docker e
upgrade-survivor all-since-2026.4.23 antes da promoção. `full` implica
`run_release_soak=true`.
Use estas variantes dependendo do estágio de lançamento:
`OpenClaw Release Checks` usa a ref confiável do workflow para resolver a ref de destino
uma vez como `release-package-under-test` e reutiliza esse artefato em verificações entre SOs,
Package Acceptance e verificações Docker do caminho de release quando o soak executa. Isso mantém
todas as máquinas voltadas a pacote nos mesmos bytes e evita builds de pacote repetidos.
O install smoke OpenAI entre SOs usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a
variável de repo/org está definida; caso contrário, `openai/gpt-5.4`, porque esta lane está
provando instalação do pacote, onboarding, inicialização do Gateway e uma rodada de agente live,
em vez de comparar o modelo padrão mais lento. A matriz live de provedores mais ampla
continua sendo o lugar para cobertura específica de modelo.
Use estas variantes dependendo da etapa de release:
```bash
# Validate an unpublished release candidate branch.
@ -269,47 +253,43 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Não use o guarda-chuva completo como a primeira nova execução após uma correção
focada. Se uma caixa falhar, use o workflow filho, job, lane Docker, perfil de
pacote, provedor de modelo ou lane de QA que falhou para a próxima prova.
Execute o guarda-chuva completo novamente somente quando a correção tiver
alterado a orquestração compartilhada de lançamento ou tornado obsoleta a
evidência anterior de todas as caixas. O verificador final do guarda-chuva
reverifica os ids registrados das execuções de workflows filhos; portanto, depois
que um workflow filho for reexecutado com sucesso, reexecute apenas o job pai
Não use o guarda-chuva completo como a primeira reexecução após uma correção focada. Se uma máquina
falhar, use o workflow filho, job, lane Docker, perfil de pacote, provedor de modelo
ou lane QA que falhou para a próxima prova. Execute o guarda-chuva completo novamente somente quando
a correção alterou a orquestração de release compartilhada ou tornou obsoleta a evidência anterior
de todas as máquinas. O verificador final do guarda-chuva verifica novamente os ids registrados das execuções de workflow
filhas, então, depois que um workflow filho for reexecutado com sucesso, reexecute somente o job pai
`Verify full validation` que falhou.
Para recuperação limitada, passe `rerun_group` ao guarda-chuva. `all` é a
execução real do candidato a lançamento, `ci` executa apenas o filho de CI normal,
`plugin-prerelease` executa apenas o filho de plugin exclusivo de lançamento,
`release-checks` executa todas as caixas de lançamento, e os grupos de lançamento
mais estreitos são `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`,
`qa-parity`, `qa-live` e `npm-telegram`. Novas execuções focadas de
`npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all com
`release_profile=full` usam o artefato de pacote de release-checks.
Para recuperação delimitada, passe `rerun_group` ao guarda-chuva. `all` é a execução real
do candidato a release, `ci` executa somente o filho de CI normal, `plugin-prerelease`
executa somente o filho de Plugin exclusivo de release, `release-checks` executa todas as máquinas de release,
e os grupos de release mais estreitos são `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` e `npm-telegram`.
Reexecuções focadas de `npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all
com `release_profile=full` usam o artefato de pacote de release-checks. Reexecuções focadas
entre SOs podem adicionar `cross_os_suite_filter=windows/packaged-upgrade` ou
outro filtro de SO/suíte. Falhas QA de release-checks são consultivas; uma falha somente em QA
não bloqueia a validação de release.
### Vitest
A caixa Vitest é o workflow filho `CI` manual. O CI manual ignora
intencionalmente o escopo por mudanças e força o grafo de testes normal para o
candidato a lançamento: shards Linux Node, shards de plugins agrupados,
contratos de canais, compatibilidade com Node 22, `check`, `check-additional`,
smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e
i18n da Control UI.
A máquina Vitest é o workflow filho `CI` manual. O CI manual intencionalmente
ignora o escopo de alterações e força o grafo de testes normal para o candidato a release:
shards Linux Node, shards de Plugins empacotados, contratos de canal, compatibilidade Node 22,
`check`, `check-additional`, build smoke, verificações de docs, Skills Python, Windows, macOS, Android e i18n da Control UI.
Use esta caixa para responder "a árvore de código-fonte passou na suíte completa
normal de testes?" Ela não é a mesma coisa que validação de produto no caminho de
lançamento. Evidências a manter:
Use esta máquina para responder "a árvore de código-fonte passou na suíte normal completa de testes?"
Ela não é o mesmo que validação de produto no caminho de release. Evidências a manter:
- resumo de `Full Release Validation` mostrando a URL da execução `CI` despachada
- execução `CI` verde no SHA de destino exato
- resumo de `Full Release Validation` mostrando a URL da execução de `CI` disparada
- execução de `CI` verde no SHA de destino exato
- nomes de shards com falha ou lentos dos jobs de CI ao investigar regressões
- artefatos de temporização do Vitest, como `.artifacts/vitest-shard-timings.json`, quando
uma execução precisa de análise de desempenho
Execute o CI manual diretamente somente quando o lançamento precisar de CI normal
determinístico, mas não das caixas Docker, QA Lab, live, entre sistemas
operacionais ou de pacote:
Execute o CI manual diretamente somente quando o release precisar de CI normal determinístico, mas
não das máquinas Docker, QA Lab, live, entre SOs ou de pacote:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -317,18 +297,18 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
A caixa Docker fica em `OpenClaw Release Checks` por meio de
`openclaw-live-and-e2e-checks-reusable.yml`, além do workflow `install-smoke` em
modo de lançamento. Ela valida o candidato a lançamento por meio de ambientes
Docker empacotados, em vez de apenas testes em nível de código-fonte.
A máquina Docker vive em `OpenClaw Release Checks` por meio de
`openclaw-live-and-e2e-checks-reusable.yml`, além do workflow `install-smoke`
em modo release. Ela valida o candidato a release por meio de ambientes Docker
empacotados, em vez de apenas testes em nível de código-fonte.
A cobertura Docker de lançamento inclui:
A cobertura Docker de release inclui:
- smoke completo de instalação com o smoke lento de instalação global Bun habilitado
- preparação/reutilização da imagem smoke do Dockerfile raiz por SHA de destino, com QR,
raiz/Gateway e jobs de smoke de instalador/Bun executando como shards separados de install-smoke
- lanes E2E do repositório
- chunks Docker do caminho de lançamento: `core`, `package-update-openai`,
- install smoke completo com o smoke de instalação global Bun lento habilitado
- preparação/reutilização de imagem smoke do Dockerfile raiz por SHA de destino, com jobs de QR,
root/gateway e installer/Bun smoke executando como shards install-smoke separados
- lanes E2E de repositório
- chunks Docker de caminho de release: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
`plugins-runtime-services`,
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
@ -336,98 +316,91 @@ A cobertura Docker de lançamento inclui:
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
`plugins-runtime-install-g` e `plugins-runtime-install-h`
- cobertura OpenWebUI dentro do chunk `plugins-runtime-services` quando solicitada
- lanes divididas de instalação/desinstalação de plugin agrupado,
de `bundled-plugin-install-uninstall-0` até
- lanes divididas de instalação/desinstalação de Plugin empacotado
`bundled-plugin-install-uninstall-0` até
`bundled-plugin-install-uninstall-23`
- suítes live/E2E de provedores e cobertura de modelo live em Docker quando as verificações
de lançamento incluem suítes live
- suítes live/E2E de provedores e cobertura de modelo Docker live quando release checks
incluem suítes live
Use os artefatos Docker antes de reexecutar. O agendador do caminho de lançamento
envia `.artifacts/docker-tests/` com logs de lanes, `summary.json`,
`failures.json`, temporizações de fases, JSON do plano do agendador e comandos de
nova execução. Para recuperação focada, use `docker_lanes=<lane[,lane]>` no
workflow reutilizável live/E2E em vez de reexecutar todos os chunks de
lançamento. Comandos gerados de nova execução incluem o
`package_artifact_run_id` anterior e entradas preparadas de imagem Docker quando
disponíveis, para que uma lane com falha possa reutilizar o mesmo tarball e as
mesmas imagens GHCR.
Use artefatos Docker antes de reexecutar. O agendador de caminho de release envia
`.artifacts/docker-tests/` com logs de lane, `summary.json`, `failures.json`,
temporizações de fase, JSON do plano do agendador e comandos de reexecução. Para recuperação focada,
use `docker_lanes=<lane[,lane]>` no workflow live/E2E reutilizável em vez de
reexecutar todos os chunks de release. Comandos de reexecução gerados incluem
`package_artifact_run_id` anterior e entradas de imagem Docker preparadas quando disponíveis, para que uma
lane com falha possa reutilizar o mesmo tarball e as imagens GHCR.
### QA Lab
A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de
lançamento de comportamento agentivo e em nível de canal, separado do Vitest e
dos mecanismos de pacote do Docker.
A máquina QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de release de
comportamento agêntico e em nível de canal, separado da mecânica de pacote Vitest e Docker.
A cobertura QA Lab de lançamento inclui:
A cobertura QA Lab de release inclui:
- lane de paridade mock comparando a lane candidata OpenAI com a baseline Opus 4.6
usando o pacote de paridade agentiva
- perfil rápido de QA Matrix live usando o ambiente `qa-live-shared`
- lane de QA Telegram live usando locações de credenciais CI do Convex
- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de prova local explícita
- lane de paridade mock comparando a lane candidata OpenAI contra a linha de base Opus 4.6
usando o pacote de paridade agêntica
- perfil QA Matrix live rápido usando o ambiente `qa-live-shared`
- lane QA Telegram live usando leases de credenciais CI do Convex
- `pnpm qa:otel:smoke` quando a telemetria de release precisa de prova local explícita
Use esta caixa para responder "o lançamento se comporta corretamente em cenários
de QA e fluxos live de canal?" Mantenha as URLs de artefatos para as lanes de
paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura Matrix completa
continua disponível como uma execução QA-Lab manual em shards, em vez da lane
padrão crítica para lançamento.
Use esta máquina para responder "o release se comporta corretamente em cenários QA e
fluxos de canais live?" Mantenha as URLs de artefatos das lanes de paridade, Matrix e Telegram
ao aprovar o release. A cobertura Matrix completa continua disponível como uma execução QA-Lab
manual em shards, em vez da lane padrão crítica de release.
### Pacote
A caixa Pacote é o gate do produto instalável. Ela é apoiada por
A máquina Package é o gate do produto instalável. Ela é respaldada por
`Package Acceptance` e pelo resolvedor
`scripts/resolve-openclaw-package-candidate.mjs`. O resolvedor normaliza um
candidato no tarball `package-under-test` consumido pelo Docker E2E, valida o
inventário do pacote, registra a versão do pacote e o SHA-256, e mantém a ref do
harness do workflow separada da ref do código-fonte do pacote.
candidato no tarball `package-under-test` consumido pelo Docker E2E, valida
o inventário do pacote, registra a versão do pacote e SHA-256 e mantém a
ref do harness do workflow separada da ref de origem do pacote.
Fontes de candidato compatíveis:
- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw
- `source=ref`: empacota um branch, tag ou SHA completo de commit de `package_ref` confiável
- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de release do OpenClaw
- `source=ref`: empacotar uma branch, tag ou SHA completo de commit `package_ref` confiável
com o harness `workflow_ref` selecionado
- `source=url`: baixa um `.tgz` HTTPS com `package_sha256` obrigatório
- `source=artifact`: reutiliza um `.tgz` enviado por outra execução do GitHub Actions
- `source=url`: baixar um `.tgz` HTTPS com `package_sha256` obrigatório
- `source=artifact`: reutilizar um `.tgz` enviado por outra execução do GitHub Actions
`OpenClaw Release Checks` executa Package Acceptance com `source=artifact`, o
artefato de pacote de lançamento preparado, `suite_profile=custom`,
artefato de pacote de release preparado, `suite_profile=custom`,
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
`published_upgrade_survivor_scenarios=reported-issues` e
`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização,
limpeza de dependências obsoletas de plugin, fixtures de plugin offline,
atualização de plugin e QA de pacote Telegram contra o mesmo tarball resolvido. A
matriz de upgrade cobre todas as baselines estáveis publicadas no npm de
`2026.4.23` até `latest`; use Package Acceptance com `source=npm` para um
candidato já enviado, ou `source=ref`/`source=artifact` para um tarball npm local
com base em SHA antes da publicação. Ele é o substituto nativo do GitHub para a
maior parte da cobertura de pacote/atualização que antes exigia Parallels. As
verificações de lançamento entre sistemas operacionais ainda importam para
onboarding, instalador e comportamento de plataforma específicos de SO, mas a
validação de produto de pacote/atualização deve preferir Package Acceptance.
`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização, limpeza de
dependências obsoletas de Plugin, fixtures de Plugin offline, atualização de Plugin e QA de pacote
Telegram contra o mesmo tarball resolvido. Verificações bloqueantes de release usam a
linha de base padrão do pacote publicado latest; `run_release_soak=true` ou
`release_profile=full` expande para todas as linhas de base estáveis publicadas no npm de
`2026.4.23` até `latest`, além de fixtures de problemas reportados. Use
Package Acceptance com `source=npm` para um candidato já enviado, ou
`source=ref`/`source=artifact` para um tarball npm local respaldado por SHA antes da
publicação. Ele é a substituição nativa do GitHub para a maior parte da cobertura de
pacote/atualização que anteriormente exigia Parallels. Verificações de release entre SOs ainda importam
para onboarding, instalador e comportamento de plataforma específicos de SO, mas a validação de produto
de pacote/atualização deve preferir Package Acceptance.
A checklist canônica para validação de atualização e plugin é
[Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins). Use-a ao
decidir qual lane local, Docker, Package Acceptance ou de release-check prova uma
instalação/atualização de plugin, limpeza pelo doctor ou mudança de migração de
pacote publicado. A migração exaustiva de atualização publicada a partir de cada
pacote estável `2026.4.23+` é um workflow manual separado `Update Migration`, não
parte do Full Release CI.
O checklist canônico para atualização e validação de Plugin é
[Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins). Use-o ao
decidir qual lane local, Docker, Package Acceptance ou release-check prova uma
instalação/atualização de Plugin, limpeza do doctor ou alteração de migração de pacote publicado.
A migração exaustiva de atualização publicada de todo pacote estável `2026.4.23+` é
um workflow manual `Update Migration` separado, não parte do Full Release CI.
A leniência legada de package-acceptance é intencionalmente limitada no tempo.
Pacotes até `2026.4.25` podem usar o caminho de compatibilidade para lacunas de
metadados já publicadas no npm: entradas privadas de inventário de QA ausentes no
tarball, `gateway install --wrapper` ausente, arquivos de patch ausentes no
fixture git derivado do tarball, `update.channel` persistido ausente, locais
legados de registro de instalação de plugin, persistência ausente de registro de
instalação do marketplace e migração de metadados de configuração durante
`plugins update`. O pacote `2026.4.26` publicado pode avisar sobre arquivos de
carimbo de metadados de build local que já foram enviados. Pacotes posteriores
devem satisfazer os contratos modernos de pacote; essas mesmas lacunas fazem a
validação de lançamento falhar.
A tolerância legada de package-acceptance é intencionalmente limitada no tempo. Pacotes até
`2026.4.25` podem usar o caminho de compatibilidade para lacunas de metadados já publicadas
no npm: entradas privadas de inventário QA ausentes do tarball, ausência de
`gateway install --wrapper`, arquivos de patch ausentes na fixture git derivada do tarball,
ausência de `update.channel` persistido, locais legados de registros de instalação de Plugin,
ausência de persistência de registro de instalação do marketplace e migração de metadados
de configuração durante `plugins update`. O pacote `2026.4.26` publicado pode avisar
sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores
devem satisfazer os contratos modernos de pacote; essas mesmas lacunas falham na validação
de release.
Use perfis Package Acceptance mais amplos quando a pergunta de lançamento for
sobre um pacote instalável real:
Use perfis Package Acceptance mais amplos quando a pergunta de release for sobre um
pacote instalável real:
```bash
gh workflow run package-acceptance.yml \
@ -441,33 +414,33 @@ gh workflow run package-acceptance.yml \
Perfis comuns de pacote:
- `smoke`: faixas rápidas de instalação de pacote/canal/agente, rede do Gateway e
- `smoke`: lanes rápidas de instalação de pacote/canal/agente, rede do Gateway e
recarregamento de configuração
- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o
padrão de verificação de lançamento
- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa web da OpenAI
e OpenWebUI
- `full`: partes do caminho de lançamento Docker com OpenWebUI
- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o padrão
da verificação de release
- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa
web da OpenAI e OpenWebUI
- `full`: partes do caminho de release do Docker com OpenWebUI
- `custom`: lista exata de `docker_lanes` para reexecuções focadas
Para prova do Telegram com pacote candidato, habilite `telegram_mode=mock-openai` ou
`telegram_mode=live-frontier` em Package Acceptance. O workflow passa o tarball
resolvido de `package-under-test` para a faixa do Telegram; o workflow avulso do
Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação.
Para prova de Telegram de candidato a pacote, habilite `telegram_mode=mock-openai` ou
`telegram_mode=live-frontier` no Package Acceptance. O workflow passa o tarball
`package-under-test` resolvido para a lane do Telegram; o workflow independente
do Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação.
## Automação de publicação de lançamento
## Automação de publicação de release
`OpenClaw Release Publish` é o ponto de entrada mutável normal de publicação. Ele
orquestra os workflows de publicador confiável na ordem exigida pelo lançamento:
orquestra os workflows de publicador confiável na ordem que o release exige:
1. Fazer checkout da tag de lançamento e resolver seu SHA de commit.
1. Fazer checkout da tag de release e resolver seu SHA de commit.
2. Verificar se a tag é alcançável a partir de `main` ou `release/*`.
3. Executar `pnpm plugins:sync:check`.
4. Disparar `Plugin NPM Release` com `publish_scope=all-publishable` e
`ref=<release-sha>`.
5. Disparar `Plugin ClawHub Release` com o mesmo escopo e SHA.
6. Disparar `OpenClaw NPM Release` com a tag de lançamento, a dist-tag npm e o
`preflight_run_id` salvo.
6. Disparar `OpenClaw NPM Release` com a tag de release, a dist-tag npm e
o `preflight_run_id` salvo.
Exemplo de publicação beta:
@ -500,19 +473,19 @@ gh workflow run openclaw-release-publish.yml \
```
Use os workflows de nível mais baixo `Plugin NPM Release` e `Plugin ClawHub Release`
apenas para trabalhos focados de reparo ou republicação. Para um reparo de Plugin
selecionado, passe `plugin_publish_scope=selected` e `plugins=@openclaw/name` para
`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o pacote
OpenClaw não deve ser publicado.
somente para trabalho focado de reparo ou republicação. Para um reparo de Plugin selecionado, passe
`plugin_publish_scope=selected` e `plugins=@openclaw/name` para
`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o
pacote OpenClaw não deve ser publicado.
## Entradas do workflow NPM
`OpenClaw NPM Release` aceita estas entradas controladas pelo operador:
- `tag`: tag de lançamento obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou
- `tag`: tag de release obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou
`v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA de commit
completo de 40 caracteres do branch do workflow atual para preflight apenas de validação
- `preflight_only`: `true` apenas para validação/build/pacote, `false` para o
completo de 40 caracteres da branch de workflow atual para preflight somente de validação
- `preflight_only`: `true` somente para validação/build/pacote, `false` para o
caminho real de publicação
- `preflight_run_id`: obrigatório no caminho real de publicação para que o workflow reutilize
o tarball preparado da execução de preflight bem-sucedida
@ -520,70 +493,73 @@ OpenClaw não deve ser publicado.
`OpenClaw Release Publish` aceita estas entradas controladas pelo operador:
- `tag`: tag de lançamento obrigatória; já deve existir
- `preflight_run_id`: id da execução de preflight bem-sucedida de `OpenClaw NPM Release`;
- `tag`: tag de release obrigatória; já deve existir
- `preflight_run_id`: id de execução de preflight bem-sucedida de `OpenClaw NPM Release`;
obrigatório quando `publish_openclaw_npm=true`
- `npm_dist_tag`: tag npm de destino para o pacote OpenClaw
- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` apenas
- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` somente
para trabalho focado de reparo
- `plugins`: nomes de pacotes `@openclaw/*` separados por vírgula quando
`plugin_publish_scope=selected`
- `publish_openclaw_npm`: o padrão é `true`; defina como `false` apenas ao usar o
workflow como orquestrador de reparo somente de Plugins
- `publish_openclaw_npm`: o padrão é `true`; defina como `false` somente ao usar o
workflow como orquestrador de reparo somente de Plugin
`OpenClaw Release Checks` aceita estas entradas controladas pelo operador:
- `ref`: branch, tag ou SHA de commit completo a validar. Verificações que carregam segredos
exigem que o commit resolvido seja alcançável a partir de um branch do OpenClaw ou
tag de lançamento.
- `ref`: branch, tag ou SHA de commit completo a validar. Verificações com segredos
exigem que o commit resolvido seja alcançável a partir de uma branch OpenClaw ou
tag de release.
- `run_release_soak`: opta por soak exaustivo ao vivo/E2E, caminho de release do Docker e
soak de sobrevivente de upgrade all-since em verificações de release estável/padrão. Ele é forçado
por `release_profile=full`.
Regras:
- Tags estáveis e de correção podem publicar em `beta` ou `latest`
- Tags beta de pré-lançamento podem publicar apenas em `beta`
- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida apenas quando
- Tags beta de pré-release podem publicar somente em `beta`
- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida somente quando
`preflight_only=true`
- `OpenClaw Release Checks` e `Full Release Validation` são sempre
apenas de validação
somente de validação
- O caminho real de publicação deve usar o mesmo `npm_dist_tag` usado durante o preflight;
o workflow verifica esses metadados antes de a publicação continuar
## Sequência de lançamento npm estável
## Sequência de release npm estável
Ao preparar um lançamento npm estável:
Ao cortar um release npm estável:
1. Execute `OpenClaw NPM Release` com `preflight_only=true`
- Antes de uma tag existir, você pode usar o SHA de commit completo do branch do workflow atual
para uma execução simulada apenas de validação do workflow de preflight
2. Escolha `npm_dist_tag=beta` para o fluxo normal beta primeiro, ou `latest` apenas
quando você quiser intencionalmente uma publicação estável direta
3. Execute `Full Release Validation` no branch de lançamento, tag de lançamento ou SHA de
commit completo quando quiser CI normal mais cobertura de cache de prompt ao vivo,
Docker, QA Lab, Matrix e Telegram em um único workflow manual
4. Se você intencionalmente precisar apenas do grafo de testes normal determinístico, execute o
workflow manual `CI` na ref de lançamento
- Antes de existir uma tag, você pode usar o SHA de commit completo da branch de workflow atual
para um ensaio somente de validação do workflow de preflight
2. Escolha `npm_dist_tag=beta` para o fluxo normal beta-primeiro, ou `latest` somente
quando você intencionalmente quiser uma publicação estável direta
3. Execute `Full Release Validation` na branch de release, tag de release ou SHA de
commit completo quando quiser CI normal mais cobertura de cache de prompt ao vivo, Docker, QA Lab,
Matrix e Telegram a partir de um único workflow manual
4. Se você intencionalmente só precisar do grafo normal determinístico de testes, execute o
workflow manual `CI` na ref de release em vez disso
5. Salve o `preflight_run_id` bem-sucedido
6. Execute `OpenClaw Release Publish` com a mesma `tag`, o mesmo `npm_dist_tag`
e o `preflight_run_id` salvo; ele publica Plugins externalizados no npm
e no ClawHub antes de promover o pacote npm do OpenClaw
7. Se o lançamento chegou a `beta`, use o workflow privado
e no ClawHub antes de promover o pacote npm OpenClaw
7. Se o release foi lançado em `beta`, use o workflow privado
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
para promover essa versão estável de `beta` para `latest`
8. Se o lançamento foi publicado intencionalmente diretamente em `latest` e `beta`
8. Se o release foi publicado intencionalmente diretamente em `latest` e `beta`
deve seguir a mesma build estável imediatamente, use esse mesmo workflow privado
para apontar ambas as dist-tags para a versão estável, ou deixe a sincronização
autorreparadora agendada mover `beta` depois
auto-reparadora agendada dele mover `beta` depois
A mutação de dist-tag fica no repositório privado por segurança, porque ainda
exige `NPM_TOKEN`, enquanto o repositório público mantém publicação apenas com OIDC.
A mutação de dist-tag fica no repo privado por segurança porque ela ainda
exige `NPM_TOKEN`, enquanto o repo público mantém publicação somente por OIDC.
Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção beta primeiro
Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção beta-primeiro
documentados e visíveis ao operador.
Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos da CLI
do 1Password (`op`) apenas dentro de uma sessão tmux dedicada. Não chame `op`
diretamente do shell principal do agente; mantê-lo dentro do tmux torna prompts,
alertas e o manuseio de OTP observáveis e evita alertas repetidos no host.
Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos
da CLI (`op`) do 1Password somente dentro de uma sessão tmux dedicada. Não chame `op`
diretamente a partir do shell principal do agente; mantê-lo dentro do tmux torna prompts,
alertas e tratamento de OTP observáveis e evita alertas repetidos do host.
## Referências públicas
@ -597,10 +573,10 @@ alertas e o manuseio de OTP observáveis e evita alertas repetidos no host.
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
Mantenedores usam os documentos privados de lançamento em
Mantenedores usam a documentação privada de release em
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
para o runbook real.
## Relacionado
- [Canais de lançamento](/pt-BR/install/development-channels)
- [Canais de release](/pt-BR/install/development-channels)

224
docs/pt-BR/reference/full-release-validation.md
View File

@ -2,25 +2,25 @@
read_when:
- Executando ou reexecutando a validação completa de lançamento
- Comparando os perfis de validação de lançamento estável e completo
- Depurando falhas na etapa de validação de lançamento
summary: Estágios de Validação Completa de Lançamento, fluxos de trabalho filhos, perfis de lançamento, identificadores de reexecução e evidências
title: Validação completa de lançamento
- Depuração de falhas no estágio de validação de lançamento
summary: Etapas, fluxos de trabalho filhos, perfis de lançamento, identificadores de reexecução e evidências da Validação completa de lançamento
title: Validação completa do lançamento
x-i18n:
generated_at: "2026-05-03T21:37:22Z"
generated_at: "2026-05-05T01:49:17Z"
model: gpt-5.5
provider: openai
source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7
source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` é o guarda-chuva da release. Ele é o único ponto de entrada
manual para prova pré-release, mas a maior parte do trabalho acontece em workflows
filhos para que uma caixa com falha possa ser executada novamente sem reiniciar a
release inteira.
`Full Release Validation` é o guarda-chuva de validação de lançamento. Ele é o único
ponto de entrada manual para a comprovação de pré-lançamento, mas a maior parte do
trabalho acontece em fluxos de trabalho filhos, para que uma caixa com falha possa
ser executada novamente sem reiniciar todo o lançamento.
Execute-o a partir de uma ref de workflow confiável, normalmente `main`, e passe a branch
de release, a tag ou o SHA completo do commit como `ref`:
Execute-o a partir de uma referência de fluxo de trabalho confiável, normalmente `main`, e passe a branch de lançamento,
tag ou SHA completo do commit como `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -31,103 +31,108 @@ gh workflow run full-release-validation.yml \
-f release_profile=stable
```
Os workflows filhos usam a ref de workflow confiável para o harness e o `ref`
de entrada para o candidato em teste. Isso mantém a nova lógica de validação
disponível ao validar uma branch ou tag de release mais antiga.
Os fluxos de trabalho filhos usam a referência de fluxo de trabalho confiável para o harness e a entrada
`ref` para o candidato em teste. Isso mantém a nova lógica de validação disponível
ao validar uma branch ou tag de lançamento mais antiga.
A Aceitação de Pacote normalmente cria o tarball candidato a partir do `ref`
resolvido, incluindo execuções com SHA completo disparadas com `pnpm ci:full-release`.
Após a publicação, passe `package_acceptance_package_spec=openclaw@YYYY.M.D` (ou
`openclaw@beta`/`openclaw@latest`) para executar a mesma matriz de pacote/atualização
contra o pacote npm entregue.
Por padrão, `release_profile=stable` executa as faixas bloqueadoras de lançamento e ignora
o soak live/Docker exaustivo. Passe `run_release_soak=true` para incluir as
faixas de soak em uma execução estável. `release_profile=full` sempre habilita as faixas de soak, para que
o perfil consultivo amplo nunca perca cobertura silenciosamente.
Package Acceptance normalmente compila o tarball candidato a partir do
`ref` resolvido, incluindo execuções com SHA completo disparadas com `pnpm ci:full-release`. Após
a publicação, passe `package_acceptance_package_spec=openclaw@YYYY.M.D` (ou
`openclaw@beta`/`openclaw@latest`) para executar a mesma matriz de pacote/atualização contra
o pacote npm publicado.
## Estágios de nível superior
| Estágio | Detalhes |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resolução do alvo | **Job:** `Resolve target ref`<br />**Workflow filho:** nenhum<br />**Comprova:** resolve a branch de release, a tag ou o SHA completo do commit e registra as entradas selecionadas.<br />**Nova execução:** execute novamente o guarda-chuva se isso falhar. |
| Vitest e CI normal | **Job:** `Run normal full CI`<br />**Workflow filho:** `CI`<br />**Comprova:** grafo de CI completo manual contra a ref alvo, incluindo lanes Linux Node, shards de Plugin empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, i18n da Control UI e Android pelo guarda-chuva.<br />**Nova execução:** `rerun_group=ci`. |
| Pré-release de Plugin | **Job:** `Run plugin prerelease validation`<br />**Workflow filho:** `Plugin Prerelease`<br />**Comprova:** verificações estáticas de Plugin exclusivas de release, cobertura agêntica de Plugin, shards do lote completo de extensões e lanes Docker de pré-release de Plugin.<br />**Nova execução:** `rerun_group=plugin-prerelease`. |
| Verificações de release | **Job:** `Run release/live/Docker/QA validation`<br />**Workflow filho:** `OpenClaw Release Checks`<br />**Comprova:** smoke de instalação, verificações de pacote entre sistemas operacionais, suítes live/E2E, chunks do caminho de release Docker, Aceitação de Pacote, paridade do QA Lab, Matrix live e Telegram live.<br />**Nova execução:** `rerun_group=release-checks` ou um handle mais restrito de release-checks. |
| Artefato de pacote | **Job:** `Prepare release package artifact`<br />**Workflow filho:** nenhum<br />**Comprova:** cria o tarball pai `release-package-under-test` cedo o suficiente para verificações voltadas a pacote que não precisam esperar por `OpenClaw Release Checks`.<br />**Nova execução:** execute novamente o guarda-chuva ou forneça `npm_telegram_package_spec` para `rerun_group=npm-telegram`. |
| Pacote Telegram | **Job:** `Run package Telegram E2E`<br />**Workflow filho:** `NPM Telegram Beta E2E`<br />**Comprova:** prova de pacote Telegram baseada no artefato pai para `rerun_group=all` com `release_profile=full`, ou prova de Telegram com pacote publicado quando `npm_telegram_package_spec` está definido.<br />**Nova execução:** `rerun_group=npm-telegram` com `npm_telegram_package_spec`. |
| Verificador do guarda-chuva | **Job:** `Verify full validation`<br />**Workflow filho:** nenhum<br />**Comprova:** verifica novamente as conclusões registradas das execuções filhas e anexa tabelas dos jobs mais lentos dos workflows filhos.<br />**Nova execução:** execute novamente apenas este job depois de reexecutar um filho com falha até ficar verde. |
| Estágio | Detalhes |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resolução do alvo | **Job:** `Resolve target ref`<br />**Fluxo de trabalho filho:** nenhum<br />**Comprova:** resolve a branch de lançamento, tag ou SHA completo do commit e registra as entradas selecionadas.<br />**Executar novamente:** execute o guarda-chuva novamente se isso falhar. |
| Vitest e CI normal | **Job:** `Run normal full CI`<br />**Fluxo de trabalho filho:** `CI`<br />**Comprova:** grafo manual completo de CI contra o ref alvo, incluindo faixas Linux Node, shards de Plugin agrupados, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, i18n da Control UI e Android via guarda-chuva.<br />**Executar novamente:** `rerun_group=ci`. |
| Pré-lançamento de Plugin | **Job:** `Run plugin prerelease validation`<br />**Fluxo de trabalho filho:** `Plugin Prerelease`<br />**Comprova:** verificações estáticas de Plugin somente de lançamento, cobertura agentic de Plugin, shards completos de lote de extensão e faixas Docker de pré-lançamento de Plugin.<br />**Executar novamente:** `rerun_group=plugin-prerelease`. |
| Verificações de lançamento | **Job:** `Run release/live/Docker/QA validation`<br />**Fluxo de trabalho filho:** `OpenClaw Release Checks`<br />**Comprova:** smoke de instalação, verificações de pacote entre OSs, Package Acceptance, paridade do QA Lab, Matrix live e Telegram live. Com `run_release_soak=true` ou `release_profile=full`, também executa suítes live/E2E exaustivas e chunks de caminho de lançamento Docker.<br />**Executar novamente:** `rerun_group=release-checks` ou um identificador release-checks mais restrito. |
| Artefato de pacote | **Job:** `Prepare release package artifact`<br />**Fluxo de trabalho filho:** nenhum<br />**Comprova:** cria o tarball pai `release-package-under-test` cedo o suficiente para verificações voltadas a pacote que não precisam aguardar `OpenClaw Release Checks`.<br />**Executar novamente:** execute o guarda-chuva novamente ou forneça `npm_telegram_package_spec` para `rerun_group=npm-telegram`. |
| Package Telegram | **Job:** `Run package Telegram E2E`<br />**Fluxo de trabalho filho:** `NPM Telegram Beta E2E`<br />**Comprova:** comprovação de pacote Telegram baseada em artefato pai para `rerun_group=all` com `release_profile=full`, ou comprovação de Telegram de pacote publicado quando `npm_telegram_package_spec` está definido.<br />**Executar novamente:** `rerun_group=npm-telegram` com `npm_telegram_package_spec`. |
| Verificador do guarda-chuva | **Job:** `Verify full validation`<br />**Fluxo de trabalho filho:** nenhum<br />**Comprova:** verifica novamente as conclusões registradas das execuções filhas e anexa tabelas dos jobs mais lentos dos fluxos de trabalho filhos.<br />**Executar novamente:** execute novamente apenas este job depois de reexecutar um filho com falha até ficar verde. |
Para `ref=main` e `rerun_group=all`, um guarda-chuva mais novo substitui um mais antigo.
Quando o pai é cancelado, seu monitor cancela qualquer workflow filho que ele já
tenha disparado. Execuções de validação de branch e tag de release não se cancelam
Quando o pai é cancelado, seu monitor cancela qualquer fluxo de trabalho filho que ele já
tenha disparado. Execuções de validação de branch e tag de lançamento não se cancelam
por padrão.
## Estágios das verificações de release
## Estágios de verificações de lançamento
`OpenClaw Release Checks` é o maior workflow filho. Ele resolve o alvo uma vez
e prepara um artefato compartilhado `release-package-under-test` quando estágios
`OpenClaw Release Checks` é o maior fluxo de trabalho filho. Ele resolve o alvo
uma vez e prepara um artefato compartilhado `release-package-under-test` quando estágios
voltados a pacote ou Docker precisam dele.
| Estágio | Detalhes |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alvo da release | **Job:** `Resolve target ref`<br />**Workflow de apoio:** nenhum<br />**Testa:** ref selecionada, SHA esperado opcional, perfil, grupo de nova execução e filtro focado da suíte live.<br />**Nova execução:** `rerun_group=release-checks`. |
| Artefato de pacote | **Job:** `Prepare release package artifact`<br />**Workflow de apoio:** nenhum<br />**Testa:** empacota ou resolve um tarball candidato e envia `release-package-under-test` para verificações downstream voltadas a pacote.<br />**Nova execução:** o grupo de pacote, cross-OS ou live/E2E afetado. |
| Smoke de instalação | **Job:** `Run install smoke`<br />**Workflow de apoio:** `Install Smoke`<br />**Testa:** caminho completo de instalação com reutilização da imagem smoke do Dockerfile raiz, instalação de pacote QR, smokes Docker de raiz e Gateway, testes Docker do instalador, smoke de provider de imagem com instalação global Bun e E2E rápido de instalação/desinstalação de Plugin empacotado.<br />**Nova execução:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**Workflow de apoio:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Testa:** lanes novas e de upgrade em Linux, Windows e macOS para o provider e modo selecionados, usando o tarball candidato mais um pacote de baseline.<br />**Nova execução:** `rerun_group=cross-os`. |
| Repo e E2E live | **Job:** `Run repo/live E2E validation`<br />**Workflow de apoio:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testa:** E2E do repositório, cache live, streaming websocket da OpenAI, provider live nativo e shards de Plugin, e harnesses live com Docker para modelo/backend/Gateway selecionados por `release_profile`.<br />**Nova execução:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. |
| Caminho de release Docker | **Job:** `Run Docker release-path validation`<br />**Workflow de apoio:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testa:** chunks Docker do caminho de release contra o artefato de pacote compartilhado.<br />**Nova execução:** `rerun_group=live-e2e`. |
| Aceitação de Pacote | **Job:** `Run package acceptance`<br />**Workflow de apoio:** `Package Acceptance`<br />**Testa:** fixtures offline de pacote de Plugin, atualização de Plugin, aceitação de pacote Telegram com mock da OpenAI e verificações de sobrevivência de upgrade publicado a partir de toda release npm estável em ou após `2026.4.23` contra o mesmo tarball.<br />**Nova execução:** `rerun_group=package`. |
| Paridade de QA | **Job:** `Run QA Lab parity lane` e `Run QA Lab parity report`<br />**Workflow de apoio:** jobs diretos<br />**Testa:** pacotes de paridade agêntica do candidato e do baseline, depois o relatório de paridade.<br />**Nova execução:** `rerun_group=qa-parity` ou `rerun_group=qa`. |
| Matrix live de QA | **Job:** `Run QA Lab live Matrix lane`<br />**Workflow de apoio:** job direto<br />**Testa:** perfil rápido de QA live Matrix no ambiente `qa-live-shared`.<br />**Nova execução:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Telegram live de QA | **Job:** `Run QA Lab live Telegram lane`<br />**Workflow de apoio:** job direto<br />**Testa:** QA live do Telegram com leases de credenciais Convex CI.<br />**Nova execução:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Verificador de release | **Job:** `Verify release checks`<br />**Workflow de apoio:** nenhum<br />**Testa:** jobs de release-check obrigatórios para o grupo de nova execução selecionado.<br />**Nova execução:** execute novamente depois que os jobs filhos focados passarem. |
| Etapa | Detalhes |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alvo de release | **Job:** `Resolve target ref`<br />**Workflow de suporte:** nenhum<br />**Testes:** ref selecionada, SHA esperado opcional, perfil, grupo de reexecução e filtro de suíte live focada.<br />**Reexecução:** `rerun_group=release-checks`. |
| Artefato de pacote | **Job:** `Prepare release package artifact`<br />**Workflow de suporte:** nenhum<br />**Testes:** empacota ou resolve um tarball candidato e faz upload de `release-package-under-test` para verificações downstream voltadas a pacotes.<br />**Reexecução:** o pacote afetado, grupo cross-OS ou live/E2E. |
| Smoke de instalação | **Job:** `Run install smoke`<br />**Workflow de suporte:** `Install Smoke`<br />**Testes:** caminho completo de instalação com reutilização da imagem smoke do Dockerfile raiz, instalação de pacote QR, smokes Docker raiz e Gateway, testes Docker do instalador, smoke de provedor de imagem com instalação global Bun e E2E rápido de instalação/desinstalação de Plugin empacotado.<br />**Reexecução:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**Workflow de suporte:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Testes:** lanes novas e de upgrade no Linux, Windows e macOS para o provedor e modo selecionados, usando o tarball candidato mais um pacote de linha de base.<br />**Reexecução:** `rerun_group=cross-os`. |
| Repo e E2E live | **Job:** `Run repo/live E2E validation`<br />**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testes:** E2E do repositório, cache live, streaming websocket OpenAI, provedor live nativo e shards de Plugin, além de harnesses de modelo/backend/Gateway live com Docker selecionados por `release_profile`.<br />**Execuções:** `run_release_soak=true`, `release_profile=full` ou `rerun_group=live-e2e` focado.<br />**Reexecução:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. |
| Caminho de release Docker | **Job:** `Run Docker release-path validation`<br />**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testes:** chunks Docker do caminho de release contra o artefato de pacote compartilhado.<br />**Execuções:** `run_release_soak=true`, `release_profile=full` ou `rerun_group=live-e2e` focado.<br />**Reexecução:** `rerun_group=live-e2e`. |
| Aceitação de pacote | **Job:** `Run package acceptance`<br />**Workflow de suporte:** `Package Acceptance`<br />**Testes:** fixtures offline de pacote de Plugin, atualização de Plugin, aceitação de pacote Telegram com OpenAI simulada e verificações de sobrevivência de upgrade publicado contra o mesmo tarball. Verificações de release bloqueantes usam a linha de base publicada mais recente padrão; verificações soak expandem para cada release npm estável em ou após `2026.4.23` mais fixtures de problemas reportados.<br />**Reexecução:** `rerun_group=package`. |
| Paridade de QA | **Job:** `Run QA Lab parity lane` e `Run QA Lab parity report`<br />**Workflow de suporte:** jobs diretos<br />**Testes:** pacotes de paridade agêntica do candidato e da linha de base, depois o relatório de paridade.<br />**Reexecução:** `rerun_group=qa-parity` ou `rerun_group=qa`. |
| Matriz live de QA | **Job:** `Run QA Lab live Matrix lane`<br />**Workflow de suporte:** job direto<br />**Testes:** perfil rápido de QA live Matrix no ambiente `qa-live-shared`.<br />**Reexecução:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Telegram live de QA | **Job:** `Run QA Lab live Telegram lane`<br />**Workflow de suporte:** job direto<br />**Testes:** QA live Telegram com concessões de credenciais do Convex CI.<br />**Reexecução:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Verificador de release | **Job:** `Verify release checks`<br />**Workflow de suporte:** nenhum<br />**Testes:** jobs obrigatórios de verificação de release para o grupo de reexecução selecionado.<br />**Reexecução:** reexecute depois que os jobs filhos focados passarem. |
## Chunks do caminho de release Docker
O estágio do caminho de release Docker executa estes chunks quando `live_suite_filter` está
A etapa do caminho de release Docker executa estes chunks quando `live_suite_filter` está
vazio:
| Chunk | Cobertura |
| --------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `core` | Lanes smoke do caminho de release Docker do Core. |
| `package-update-openai` | Comportamento de instalação e atualização do pacote OpenAI. |
| `package-update-anthropic` | Comportamento de instalação e atualização do pacote Anthropic. |
| `package-update-core` | Comportamento de pacote e atualização neutro em relação a provider. |
| `plugins-runtime-plugins` | Lanes de runtime de Plugin que exercitam comportamento de Plugin. |
| `plugins-runtime-services` | Lanes de runtime de Plugin apoiadas por serviço; inclui OpenWebUI quando solicitado. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Lotes de instalação/runtime de Plugin divididos para validação de release paralela. |
| Chunk | Cobertura |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Lanes smoke centrais do caminho de release Docker. |
| `package-update-openai` | Comportamento de instalação e atualização de pacote OpenAI. |
| `package-update-anthropic` | Comportamento de instalação e atualização de pacote Anthropic. |
| `package-update-core` | Comportamento de pacote e atualização neutro em relação a provedor. |
| `plugins-runtime-plugins` | Lanes de runtime de Plugin que exercitam o comportamento de Plugin. |
| `plugins-runtime-services` | Lanes de runtime de Plugin com suporte por serviço; inclui OpenWebUI quando solicitado. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Lotes de instalação/runtime de Plugin divididos para validação paralela de release. |
Use `docker_lanes=<lane[,lane]>` direcionado no workflow reutilizável live/E2E quando
apenas uma lane do Docker falhar. Os artefatos de release incluem comandos de
reexecução por lane com entradas de reutilização de artefato de pacote e imagem
quando disponíveis.
Use `docker_lanes=<lane[,lane]>` direcionado no workflow live/E2E reutilizável quando
apenas uma lane Docker falhar. Os artefatos de release incluem comandos de
reexecução por lane com entradas de artefato de pacote e reutilização de imagem quando disponíveis.
## Perfis de release
`release_profile` controla principalmente a abrangência live/provedor dentro das verificações de release.
Ele não remove a CI completa normal, Pré-lançamento de Plugin, smoke de instalação, aceitação de
pacote, QA Lab nem blocos do caminho de release do Docker. `full` também faz a
execução agregadora rodar o E2E do Telegram do pacote contra o artefato de pacote de release pai quando
`rerun_group=all`, então um candidato completo de pré-publicação não pula silenciosamente essa
lane de pacote do Telegram.
`release_profile` controla principalmente a amplitude live/provedor dentro das verificações de release.
Ele não remove CI completa normal, pré-lançamento de Plugin, smoke de instalação, aceitação de
pacote ou QA Lab. Para `stable`, E2E repo/live exaustivo e chunks de
caminho de release Docker são cobertura soak e são executados quando `run_release_soak=true`.
`full` força a cobertura soak e também faz a execução guarda-chuva executar o E2E Telegram de pacote
contra o artefato de pacote de release pai quando `rerun_group=all`, para que um candidato completo
de pré-publicação não pule silenciosamente essa lane de pacote Telegram.
| Perfil | Uso pretendido | Cobertura live/provedor incluída |
| Perfil | Uso pretendido | Cobertura live/provedor incluída |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Smoke crítico de release mais rápido. | Caminho live OpenAI/core, modelos live do Docker para OpenAI, núcleo do gateway nativo, perfil de gateway OpenAI nativo, plugin OpenAI nativo e gateway live OpenAI do Docker. |
| `stable` | Perfil padrão de aprovação de release. | `minimum` mais smoke do Anthropic, Google, MiniMax, backend, harness de teste live nativo, backend de CLI live do Docker, bind ACP do Docker, harness Codex do Docker e um shard de smoke OpenCode Go. |
| `full` | Varredura consultiva ampla. | `stable` mais provedores consultivos, shards live de plugins e shards live de mídia. |
| `minimum` | Smoke mais rápido crítico para release. | Caminho live OpenAI/core, modelos live Docker para OpenAI, core do Gateway nativo, perfil de Gateway OpenAI nativo, Plugin OpenAI nativo e Gateway live Docker OpenAI. |
| `stable` | Perfil padrão de aprovação de release. | `minimum` mais smoke Anthropic, Google, MiniMax, backend, harness de teste live nativo, backend de CLI live Docker, bind ACP Docker, harness Codex Docker e um shard smoke OpenCode Go. |
| `full` | Varredura consultiva ampla. | `stable` mais provedores consultivos, shards live de Plugin e shards live de mídia. |
## Adições apenas de full
## Adições apenas do full
Estas suítes são puladas por `stable` e incluídas por `full`:
Estas suítes são ignoradas por `stable` e incluídas por `full`:
| Área | Cobertura apenas de full |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Modelos live do Docker | OpenCode Go, OpenRouter, xAI, Z.ai e Fireworks. |
| Gateway live do Docker | Provedores consultivos divididos em shards DeepSeek/Fireworks, OpenCode Go/OpenRouter e xAI/Z.ai. |
| Perfis de provedor do gateway nativo | Shards completos Anthropic Opus e Sonnet/Haiku, Fireworks, DeepSeek, shards completos de modelos OpenCode Go, OpenRouter, xAI e Z.ai. |
| Shards live de plugins nativos | Plugins A-K, L-N, O-Z outros, Moonshot e xAI. |
| Shards live de mídia nativos | Áudio, música do Google, música do MiniMax e grupos de vídeo A-D. |
| Área | Cobertura apenas do full |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Modelos live Docker | OpenCode Go, OpenRouter, xAI, Z.ai e Fireworks. |
| Gateway live Docker | Provedores consultivos divididos em shards DeepSeek/Fireworks, OpenCode Go/OpenRouter e xAI/Z.ai. |
| Perfis de provedor do Gateway nativo | Shards Anthropic completos Opus e Sonnet/Haiku, Fireworks, DeepSeek, shards completos de modelo OpenCode Go, OpenRouter, xAI e Z.ai. |
| Shards live de Plugin nativo | Plugins A-K, L-N, O-Z outros, Moonshot e xAI. |
| Shards live de mídia nativa | Áudio, música Google, música MiniMax e grupos de vídeo A-D. |
`stable` inclui `native-live-src-gateway-profiles-anthropic-smoke` e
`native-live-src-gateway-profiles-opencode-go-smoke`; `full` usa os shards mais amplos
de modelos Anthropic e OpenCode Go em vez disso. Reexecuções focadas ainda podem usar os
`native-live-src-gateway-profiles-opencode-go-smoke`; `full` usa os shards
mais amplos de modelos Anthropic e OpenCode Go em vez disso. Reexecuções focadas ainda podem usar os
identificadores agregados `native-live-src-gateway-profiles-anthropic` ou
`native-live-src-gateway-profiles-opencode-go`.
@ -137,42 +142,53 @@ Use `rerun_group` para evitar repetir caixas de release não relacionadas:
| Identificador | Escopo |
| ------------------- | --------------------------------------------------------------------- |
| `all` | Todos os estágios de Validação Completa de Release. |
| `ci` | Apenas filho de CI completa manual. |
| `plugin-prerelease` | Apenas filho de Pré-lançamento de Plugin. |
| `release-checks` | Todos os estágios de Verificações de Release do OpenClaw. |
| `install-smoke` | Smoke de instalação por meio das verificações de release. |
| `cross-os` | Verificações de release entre sistemas operacionais. |
| `live-e2e` | Validação E2E do repo/live e do caminho de release do Docker. |
| `package` | Aceitação de Pacote. |
| `qa` | Paridade de QA mais lanes live de QA. |
| `all` | Todos os estágios da Validação Completa de Lançamento. |
| `ci` | Apenas o filho manual de CI completa. |
| `plugin-prerelease` | Apenas o filho de pré-lançamento de Plugin. |
| `release-checks` | Todos os estágios das Verificações de Lançamento do OpenClaw. |
| `install-smoke` | Smoke de instalação até as verificações de lançamento. |
| `cross-os` | Verificações de lançamento entre sistemas operacionais. |
| `live-e2e` | Validação de E2E ao vivo do repositório e do caminho de lançamento do Docker. |
| `package` | Aceitação do pacote. |
| `qa` | Paridade de QA mais lanes de QA ao vivo. |
| `qa-parity` | Apenas lanes e relatório de paridade de QA. |
| `qa-live` | Apenas Matrix live de QA e Telegram. |
| `npm-telegram` | E2E do Telegram de pacote publicado; exige `npm_telegram_package_spec`. |
| `qa-live` | Apenas Matrix e Telegram de QA ao vivo. |
| `npm-telegram` | E2E do Telegram com pacote publicado; requer `npm_telegram_package_spec`. |
Use `live_suite_filter` com `rerun_group=live-e2e` quando uma suíte live falhar.
IDs de filtro válidos são definidos no workflow reutilizável live/E2E, incluindo
Use `live_suite_filter` com `rerun_group=live-e2e` quando uma suíte ao vivo falhar.
Os ids de filtro válidos são definidos no workflow reutilizável ao vivo/E2E, incluindo
`docker-live-models`, `live-gateway-docker`,
`live-gateway-anthropic-docker`, `live-gateway-google-docker`,
`live-gateway-minimax-docker`, `live-gateway-advisory-docker`,
`live-cli-backend-docker`, `live-acp-bind-docker` e
`live-codex-harness-docker`.
O identificador `live-gateway-advisory-docker` é um identificador de reexecução agregada para seus
três shards de provedor, então ele ainda se expande para todos os jobs consultivos de gateway Docker.
O identificador `live-gateway-advisory-docker` é um identificador agregado de reexecução para seus
três shards de provedor, então ele ainda se espalha para todos os jobs de Gateway Docker de advisories.
## Evidências a manter
Use `cross_os_suite_filter` com `rerun_group=cross-os` quando uma lane entre sistemas operacionais
falhar. O filtro aceita um id de sistema operacional, um id de suíte ou um par sistema operacional/suíte, por
exemplo `windows/packaged-upgrade`, `windows` ou `packaged-fresh`. Os
resumos entre sistemas operacionais incluem tempos por fase para lanes de upgrade empacotado, e comandos
de longa duração imprimem linhas de Heartbeat para que uma atualização do Windows travada fique visível antes do
tempo limite do job.
Mantenha o resumo de `Full Release Validation` como o índice em nível de release. Ele vincula
IDs de execuções filhas e inclui tabelas dos jobs mais lentos. Para falhas, inspecione primeiro o workflow filho
e depois reexecute o menor identificador correspondente acima.
As lanes de verificações de lançamento de QA são consultivas. Uma falha apenas de QA é relatada como aviso
e não bloqueia o verificador de verificações de lançamento; reexecute `rerun_group=qa`,
`qa-parity` ou `qa-live` quando precisar de evidência de QA atualizada.
## Evidência a manter
Mantenha o resumo de `Full Release Validation` como o índice no nível do lançamento. Ele vincula
ids de execução filhos e inclui tabelas dos jobs mais lentos. Para falhas, inspecione primeiro o workflow
filho e depois reexecute o menor identificador correspondente acima.
Artefatos úteis:
- `release-package-under-test` do pai de Validação Completa de Release e `OpenClaw Release Checks`
- Artefatos do caminho de release do Docker em `.artifacts/docker-tests/`
- `package-under-test` da Aceitação de Pacote e artefatos de aceitação do Docker
- Artefatos de verificação de release entre sistemas operacionais para cada SO e suíte
- `release-package-under-test` do pai da Validação Completa de Lançamento e `OpenClaw Release Checks`
- Artefatos do caminho de lançamento do Docker em `.artifacts/docker-tests/`
- `package-under-test` da Aceitação do Pacote e artefatos de aceitação do Docker
- Artefatos de verificação de lançamento entre sistemas operacionais para cada sistema operacional e suíte
- Artefatos de paridade de QA, Matrix e Telegram
## Arquivos de workflow

112
docs/pt-BR/reference/test.md
View File

@ -1,63 +1,63 @@
---
read_when:
- Executar ou corrigir testes
- Executando ou corrigindo testes
summary: Como executar testes localmente (vitest) e quando usar os modos force/coverage
title: Testes
x-i18n:
generated_at: "2026-05-02T21:04:13Z"
generated_at: "2026-05-05T01:49:14Z"
model: gpt-5.5
provider: openai
source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
source_path: reference/test.md
workflow: 16
---
- Kit completo de testes (suítes, ao vivo, Docker): [Testes](/pt-BR/help/testing)
- Validação de atualizações e pacote de plugin: [Testes de atualizações e plugins](/pt-BR/help/testing-updates-plugins)
- Validação de atualizações e pacotes de Plugin: [Testando atualizações e Plugins](/pt-BR/help/testing-updates-plugins)
- `pnpm test:force`: Encerra qualquer processo Gateway remanescente que esteja ocupando a porta de controle padrão e, em seguida, executa a suíte Vitest completa com uma porta Gateway isolada para que os testes de servidor não entrem em conflito com uma instância em execução. Use isto quando uma execução anterior do Gateway deixou a porta 18789 ocupada.
- `pnpm test:coverage`: Executa a suíte unitária com cobertura V8 (via `vitest.unit.config.ts`). Este é um gate de cobertura unitária de arquivos carregados, não uma cobertura de todos os arquivos do repositório inteiro. Os limites são 70% para linhas/funções/instruções e 55% para branches. Como `coverage.all` é falso, o gate mede os arquivos carregados pela suíte de cobertura unitária em vez de tratar cada arquivo-fonte de lane dividida como descoberto.
- `pnpm test:coverage:changed`: Executa cobertura unitária apenas para arquivos alterados desde `origin/main`.
- `pnpm test:changed`: execução barata e inteligente de testes alterados. Ela executa alvos precisos de edições diretas em testes, arquivos `*.test.ts` irmãos, mapeamentos explícitos de código-fonte e o grafo de importação local. Alterações amplas de configuração/pacote são ignoradas, a menos que sejam mapeadas para testes precisos.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: execução ampla explícita de testes alterados. Use quando uma edição de harness/configuração/pacote de teste deve recorrer ao comportamento mais amplo de testes alterados do Vitest.
- `pnpm test:force`: Encerra qualquer processo Gateway remanescente que esteja ocupando a porta de controle padrão e, em seguida, executa a suíte Vitest completa com uma porta de Gateway isolada para que os testes de servidor não colidam com uma instância em execução. Use isto quando uma execução anterior do Gateway deixou a porta 18789 ocupada.
- `pnpm test:coverage`: Executa a suíte de unidade com cobertura V8 (via `vitest.unit.config.ts`). Este é um gate de cobertura de unidade por arquivos carregados, não cobertura de todos os arquivos do repositório inteiro. Os limites são 70% para linhas/funções/instruções e 55% para branches. Como `coverage.all` é false, o gate mede os arquivos carregados pela suíte de cobertura de unidade em vez de tratar cada arquivo-fonte de lane dividida como não coberto.
- `pnpm test:coverage:changed`: Executa cobertura de unidade apenas para arquivos alterados desde `origin/main`.
- `pnpm test:changed`: execução barata de testes alterados inteligentes. Ela executa alvos precisos a partir de edições diretas de teste, arquivos irmãos `*.test.ts`, mapeamentos explícitos de código-fonte e o grafo de imports local. Alterações amplas de configuração/pacote são ignoradas, a menos que mapeiem para testes precisos.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: execução explícita ampla de testes alterados. Use quando uma edição de harness/configuração/pacote de teste deve recorrer ao comportamento mais amplo de testes alterados do Vitest.
- `pnpm changed:lanes`: mostra as lanes arquiteturais acionadas pelo diff contra `origin/main`.
- `pnpm check:changed`: executa o gate inteligente de verificação de alterações para o diff contra `origin/main`. Ele executa typecheck, lint e comandos de guarda para as lanes arquiteturais afetadas, mas não executa testes Vitest. Use `pnpm test:changed` ou `pnpm test <target>` explícito para comprovação de testes.
- `pnpm test`: roteia alvos explícitos de arquivo/diretório por lanes Vitest com escopo. Execuções sem alvo usam grupos de shards fixos e se expandem para configurações folha para execução paralela local; o grupo de extensões sempre se expande para as configurações de shard por extensão em vez de um processo gigante de projeto raiz.
- Execuções do wrapper de teste terminam com um resumo curto `[test] passed|failed|skipped ... in ...`. A própria linha de duração do Vitest continua sendo o detalhe por shard.
- Estado de teste compartilhado do OpenClaw: use `src/test-utils/openclaw-test-state.ts` a partir do Vitest quando um teste precisar de `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture de configuração, workspace, diretório de agente ou armazenamento de perfis de autenticação isolados.
- Helpers de E2E de processo: use `test/helpers/openclaw-test-instance.ts` quando um teste E2E em nível de processo do Vitest precisar de um Gateway em execução, ambiente de CLI, captura de logs e limpeza em um só lugar.
- Helpers de E2E Docker/Bash: lanes que usam `scripts/lib/docker-e2e-image.sh` como fonte podem passar `docker_e2e_test_state_shell_b64 <label> <scenario>` para dentro do contêiner e decodificá-lo com `scripts/lib/openclaw-e2e-instance.sh`; scripts multi-home podem passar `docker_e2e_test_state_function_b64` e chamar `openclaw_test_state_create <label> <scenario>` em cada fluxo. Chamadores de nível mais baixo podem usar `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` para um snippet de shell dentro do contêiner, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` para um arquivo de ambiente do host que possa ser carregado por `source`. O `--` antes de `create` impede que runtimes Node mais novos tratem `--env-file` como uma flag do Node. Lanes Docker/Bash que iniciam um Gateway podem carregar `scripts/lib/openclaw-e2e-instance.sh` dentro do contêiner para resolução de entrypoint, inicialização simulada da OpenAI, inicialização do Gateway em primeiro plano/segundo plano, probes de prontidão, exportação de ambiente de estado, dumps de log e limpeza de processos.
- Execuções de shards completas, de extensão e com padrão de inclusão atualizam dados locais de timing em `.artifacts/vitest-shard-timings.json`; execuções posteriores de configuração inteira usam esses timings para equilibrar shards lentos e rápidos. Shards de CI com padrão de inclusão acrescentam o nome do shard à chave de timing, o que mantém timings de shards filtrados visíveis sem substituir dados de timing de configuração inteira. Defina `OPENCLAW_TEST_PROJECTS_TIMINGS=0` para ignorar o artefato de timing local.
- Arquivos de teste `plugin-sdk` e `commands` selecionados agora são roteados por lanes leves dedicadas que mantêm apenas `test/setup.ts`, deixando os casos pesados de runtime em suas lanes existentes.
- Arquivos-fonte com testes irmãos são mapeados para esse irmão antes de recorrer a globs de diretório mais amplos. Edições de helpers em `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` e `src/plugins/contracts` usam um grafo de importação local para executar testes que importam esses helpers em vez de executar amplamente todos os shards quando o caminho da dependência é preciso.
- `auto-reply` agora também é dividido em três configurações dedicadas (`core`, `top-level`, `reply`) para que o harness de resposta não domine os testes mais leves de status/token/helper de nível superior.
- A configuração base do Vitest agora usa por padrão `pool: "threads"` e `isolate: false`, com o runner compartilhado não isolado habilitado nas configurações do repositório.
- `pnpm check:changed`: executa o gate inteligente de verificação de alterações para o diff contra `origin/main`. Ele executa comandos de typecheck, lint e guard para as lanes arquiteturais afetadas, mas não executa testes Vitest. Use `pnpm test:changed` ou `pnpm test <target>` explícito para prova de teste.
- `pnpm test`: roteia alvos explícitos de arquivo/diretório por lanes Vitest escopadas. Execuções sem alvo usam grupos de shards fixos e se expandem para configs folha para execução paralela local; o grupo de extensões sempre se expande para as configs de shard por extensão em vez de um único processo gigante de projeto raiz.
- Execuções do wrapper de teste terminam com um breve resumo `[test] passed|failed|skipped ... in ...`. A própria linha de duração do Vitest permanece como o detalhe por shard.
- Estado de teste compartilhado do OpenClaw: use `src/test-utils/openclaw-test-state.ts` a partir do Vitest quando um teste precisar de `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture de configuração, workspace, diretório de agente ou armazenamento de perfis de autenticação isolado.
- Helpers de E2E de processo: use `test/helpers/openclaw-test-instance.ts` quando um teste E2E em nível de processo do Vitest precisar de um Gateway em execução, ambiente CLI, captura de logs e limpeza em um só lugar.
- Helpers de E2E Docker/Bash: lanes que fazem source de `scripts/lib/docker-e2e-image.sh` podem passar `docker_e2e_test_state_shell_b64 <label> <scenario>` para dentro do contêiner e decodificá-lo com `scripts/lib/openclaw-e2e-instance.sh`; scripts multi-home podem passar `docker_e2e_test_state_function_b64` e chamar `openclaw_test_state_create <label> <scenario>` em cada fluxo. Chamadores de nível mais baixo podem usar `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` para um snippet de shell dentro do contêiner, ou `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` para um arquivo de ambiente do host que pode receber source. O `--` antes de `create` impede runtimes Node mais novos de tratarem `--env-file` como uma flag do Node. Lanes Docker/Bash que iniciam um Gateway podem fazer source de `scripts/lib/openclaw-e2e-instance.sh` dentro do contêiner para resolução de entrypoint, inicialização simulada da OpenAI, inicialização do Gateway em foreground/background, probes de prontidão, exportação de ambiente de estado, dumps de logs e limpeza de processos.
- Execuções de shards completas, de extensão e por padrão de inclusão atualizam dados de temporização locais em `.artifacts/vitest-shard-timings.json`; execuções posteriores de config inteira usam esses tempos para balancear shards lentos e rápidos. Shards de CI por padrão de inclusão acrescentam o nome do shard à chave de temporização, o que mantém os tempos de shards filtrados visíveis sem substituir os dados de temporização de config inteira. Defina `OPENCLAW_TEST_PROJECTS_TIMINGS=0` para ignorar o artefato de temporização local.
- Arquivos de teste selecionados de `plugin-sdk` e `commands` agora são roteados por lanes leves dedicadas que mantêm apenas `test/setup.ts`, deixando casos pesados de runtime nas lanes existentes.
- Arquivos-fonte com testes irmãos mapeiam para esse irmão antes de recorrer a globs de diretório mais amplos. Edições de helpers em `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers` e `src/plugins/contracts` usam um grafo de imports local para executar testes que importam esses helpers em vez de executar amplamente todos os shards quando o caminho de dependência é preciso.
- `auto-reply` agora também se divide em três configs dedicadas (`core`, `top-level`, `reply`) para que o harness de resposta não domine os testes mais leves de status/token/helper de nível superior.
- A configuração base do Vitest agora usa por padrão `pool: "threads"` e `isolate: false`, com o runner não isolado compartilhado habilitado em todas as configs do repositório.
- `pnpm test:channels` executa `vitest.channels.config.ts`.
- `pnpm test:extensions` e `pnpm test extensions` executam todos os shards de extensão/Plugin. Plugins de canal pesados, o Plugin de navegador e OpenAI são executados como shards dedicados; outros grupos de Plugin permanecem em lote. Use `pnpm test extensions/<id>` para uma lane de um Plugin integrado.
- `pnpm test:perf:imports`: habilita relatórios de duração de importação + detalhamento de importação do Vitest, ainda usando roteamento de lane com escopo para alvos explícitos de arquivo/diretório.
- `pnpm test:perf:imports:changed`: o mesmo perfilamento de importação, mas apenas para arquivos alterados desde `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` mede o desempenho do caminho roteado de modo alterado em comparação com a execução nativa do projeto raiz para o mesmo diff git confirmado.
- `pnpm test:perf:changed:bench -- --worktree` mede o desempenho do conjunto de alterações atual da worktree sem fazer commit antes.
- `pnpm test:perf:profile:main`: grava um perfil de CPU da thread principal do Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: grava perfis de CPU + heap do runner unitário (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: executa serialmente cada configuração folha do Vitest da suíte completa e grava dados de duração agrupados, além de artefatos JSON/log por configuração. O Test Performance Agent usa isso como sua linha de base antes de tentar correções de testes lentos.
- `pnpm test:extensions` e `pnpm test extensions` executam todos os shards de extensão/plugin. Plugins de canal pesados, o plugin de navegador e OpenAI executam como shards dedicados; outros grupos de plugins permanecem em lote. Use `pnpm test extensions/<id>` para uma lane de um plugin agrupado.
- `pnpm test:perf:imports`: habilita relatórios de duração de imports + detalhamento de imports do Vitest, ainda usando roteamento por lane escopada para alvos explícitos de arquivo/diretório.
- `pnpm test:perf:imports:changed`: o mesmo profiling de imports, mas apenas para arquivos alterados desde `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` mede o desempenho do caminho roteado de modo alterado contra a execução nativa de projeto raiz para o mesmo diff git commitado.
- `pnpm test:perf:changed:bench -- --worktree` mede o desempenho do conjunto de alterações atual do worktree sem commitá-lo antes.
- `pnpm test:perf:profile:main`: grava um perfil de CPU para a thread principal do Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: grava perfis de CPU + heap para o runner de unidade (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: executa cada config folha do Vitest da suíte completa serialmente e grava dados de duração agrupados mais artefatos JSON/log por config. O Test Performance Agent usa isto como baseline antes de tentar correções de testes lentos.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: compara relatórios agrupados após uma alteração focada em desempenho.
- Integração com Gateway: adesão via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e`: Executa testes smoke end-to-end do Gateway (emparelhamento multi-instância WS/HTTP/node). O padrão é `threads` + `isolate: false` com workers adaptativos em `vitest.e2e.config.ts`; ajuste com `OPENCLAW_E2E_WORKERS=<n>` e defina `OPENCLAW_E2E_VERBOSE=1` para logs detalhados.
- `pnpm test:live`: Executa testes live de provedores (minimax/zai). Exige chaves de API e `LIVE=1` (ou `*_LIVE_TEST=1` específico do provedor) para deixar de pular.
- `pnpm test:docker:all`: Compila a imagem compartilhada de testes live, empacota o OpenClaw uma vez como um tarball npm, compila/reutiliza uma imagem runner Node/Git básica mais uma imagem funcional que instala esse tarball em `/app` e, em seguida, executa lanes smoke Docker com `OPENCLAW_SKIP_DOCKER_BUILD=1` por meio de um agendador ponderado. A imagem básica (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) é usada para lanes de instalador/atualização/dependência de Plugin; essas lanes montam o tarball pré-compilado em vez de usar fontes copiadas do repositório. A imagem funcional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) é usada para lanes normais de funcionalidade do app compilado. `scripts/package-openclaw-for-docker.mjs` é o empacotador único local/CI e valida o tarball mais `dist/postinstall-inventory.json` antes que o Docker o consuma. As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`; a lógica do planner fica em `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executa o plano selecionado. `node scripts/test-docker-all.mjs --plan-json` emite o plano de CI controlado pelo agendador para lanes selecionadas, tipos de imagem, necessidades de pacote/imagem live, cenários de estado e verificações de credenciais sem compilar ou executar Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` controla slots de processo e o padrão é 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` controla o pool final sensível a provedor e o padrão é 10. Os limites de lanes pesadas usam por padrão `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` e `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; os limites de provedor usam por padrão uma lane pesada por provedor via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` e `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Use `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` para hosts maiores. Se uma lane exceder o peso efetivo ou o limite de recursos em um host com baixo paralelismo, ela ainda pode iniciar a partir de um pool vazio e será executada sozinha até liberar capacidade. Os inícios de lanes são espaçados por 2 segundos por padrão para evitar tempestades de criação no daemon Docker local; substitua com `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. O runner faz preflight do Docker por padrão, limpa contêineres E2E OpenClaw obsoletos, emite status de lanes ativas a cada 30 segundos, compartilha caches de ferramentas CLI de provedores entre lanes compatíveis, tenta novamente falhas transitórias de provedores live uma vez por padrão (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) e armazena timings de lanes em `.artifacts/docker-tests/lane-timings.json` para ordenação do mais longo primeiro em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto de lanes sem executar Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` para ajustar a saída de status ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` para desabilitar a reutilização de timing. Use `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` apenas para lanes determinísticas/locais ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` apenas para lanes de provedor live; os aliases de pacote são `pnpm test:docker:local:all` e `pnpm test:docker:live:all`. O modo somente live mescla as lanes live principais e finais em um único pool do mais longo primeiro para que buckets de provedor possam agrupar o trabalho de Claude, Codex e Gemini juntos. O runner para de agendar novas lanes agrupadas após a primeira falha, a menos que `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` esteja definido, e cada lane tem um timeout fallback de 120 minutos substituível por `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lanes live/finais selecionadas usam limites por lane mais rígidos. Comandos de configuração Docker do backend da CLI têm seu próprio timeout via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (padrão 180). Logs por lane, `summary.json`, `failures.json` e timings de fase são gravados em `.artifacts/docker-tests/<run-id>/`; use `pnpm test:docker:timings <summary.json>` para inspecionar lanes lentas e `pnpm test:docker:rerun <run-id|summary.json|failures.json>` para imprimir comandos baratos de reexecução direcionada.
- `pnpm test:docker:browser-cdp-snapshot`: Compila um contêiner E2E de origem com Chromium, inicia CDP bruto mais um Gateway isolado, executa `browser doctor --deep` e verifica que snapshots de função CDP incluem URLs de links, clicáveis promovidos por cursor, referências de iframe e metadados de frame.
- Probes Docker live de backend da CLI podem ser executados como lanes focadas, por exemplo `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude e Gemini têm aliases `:resume` e `:mcp` correspondentes.
- `pnpm test:docker:openwebui`: Inicia OpenClaw + Open WebUI dockerizados, faz login pelo Open WebUI, verifica `/api/models` e, em seguida, executa um chat real com proxy por `/api/chat/completions`. Exige uma chave de modelo live utilizável (por exemplo OpenAI em `~/.profile`), baixa uma imagem externa do Open WebUI e não se espera que seja estável em CI como as suítes unitárias/e2e normais.
- `pnpm test:docker:mcp-channels`: Inicia um contêiner Gateway semeado e um segundo contêiner cliente que gera `openclaw mcp serve`; em seguida, verifica descoberta de conversas roteadas, leituras de transcritos, metadados de anexos, comportamento de fila de eventos live, roteamento de envio de saída e notificações de canal + permissão no estilo Claude pela ponte stdio real. A asserção de notificação Claude lê diretamente os frames MCP stdio brutos para que o smoke reflita o que a ponte realmente emite.
- `pnpm test:docker:upgrade-survivor`: Instala o tarball empacotado do OpenClaw sobre uma fixture antiga de usuário com alterações, executa a atualização do pacote mais o `doctor` não interativo sem chaves de provedor ou canal em tempo real, então inicia um Gateway em loopback e verifica se agentes, configuração de canal, listas de permissão de plugins, arquivos de workspace/sessão, estado obsoleto de dependências de plugins legados, inicialização e status RPC sobrevivem.
- `pnpm test:docker:published-upgrade-survivor`: Instala `openclaw@latest` por padrão, semeia arquivos realistas de usuário existente sem chaves de provedor ou canal em tempo real, configura essa linha de base com uma receita de comando `openclaw config set` embutida, atualiza essa instalação publicada para o tarball empacotado do OpenClaw, executa o `doctor` não interativo, grava `.artifacts/upgrade-survivor/summary.json`, então inicia um Gateway em loopback e verifica se intents configurados, arquivos de workspace/sessão, configuração obsoleta de plugin e estado de dependências legadas, inicialização, `/healthz`, `/readyz` e status RPC sobrevivem ou são reparados corretamente. Substitua uma linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, expanda uma matriz exata com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, como `all-since-2026.4.23`, ou adicione fixtures de cenário com `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; o conjunto `reported-issues` inclui `configured-plugin-installs` para verificar se plugins externos do OpenClaw configurados são instalados automaticamente durante a atualização. Package Acceptance expõe esses valores como `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` e `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Executa o harness de sobrevivência de atualização publicada no cenário `plugin-deps-cleanup`, pesado em limpeza, começando por `openclaw@2026.4.23` por padrão. O workflow separado `Update Migration` expande essa lane com `baselines=all-since-2026.4.23`, para que todo pacote estável publicado a partir da `.23` seja atualizado para o candidato e comprove a limpeza de dependências de plugins configurados fora do CI de Full Release.
- `pnpm test:docker:plugins`: Executa smoke de instalação/atualização para caminho local, `file:`, pacotes do registro npm com dependências içadas, refs móveis do git, fixtures do ClawHub, atualizações do marketplace e habilitação/inspeção do pacote Claude.
- Integração do Gateway: opt-in via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e`: Executa testes smoke end-to-end do Gateway (emparelhamento multi-instância WS/HTTP/node). Usa por padrão `threads` + `isolate: false` com workers adaptativos em `vitest.e2e.config.ts`; ajuste com `OPENCLAW_E2E_WORKERS=<n>` e defina `OPENCLAW_E2E_VERBOSE=1` para logs detalhados.
- `pnpm test:live`: Executa testes live de provedores (minimax/zai). Requer chaves de API e `LIVE=1` (ou `*_LIVE_TEST=1` específico do provedor) para deixar de pular.
- `pnpm test:docker:all`: Cria a imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm, cria/reutiliza uma imagem runner básica Node/Git mais uma imagem funcional que instala esse tarball em `/app` e, em seguida, executa lanes smoke Docker com `OPENCLAW_SKIP_DOCKER_BUILD=1` por meio de um agendador ponderado. A imagem básica (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) é usada para lanes de instalador/atualização/dependência de plugin; essas lanes montam o tarball pré-criado em vez de usar fontes copiadas do repositório. A imagem funcional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) é usada para lanes normais de funcionalidade de aplicativo criado. `scripts/package-openclaw-for-docker.mjs` é o único empacotador de pacote local/CI e valida o tarball mais `dist/postinstall-inventory.json` antes que o Docker o consuma. As definições de lanes Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`; a lógica de planner fica em `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` executa o plano selecionado. `node scripts/test-docker-all.mjs --plan-json` emite o plano de CI controlado pelo agendador para lanes selecionadas, tipos de imagem, necessidades de pacote/imagem live, cenários de estado e verificações de credenciais sem criar nem executar Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` controla slots de processo e usa 10 por padrão; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` controla o pool final sensível a provedor e usa 10 por padrão. Os limites de lanes pesadas usam por padrão `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` e `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; os limites de provedor usam por padrão uma lane pesada por provedor via `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` e `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Use `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` para hosts maiores. Se uma lane exceder o limite efetivo de peso ou recurso em um host com baixo paralelismo, ela ainda pode iniciar a partir de um pool vazio e será executada sozinha até liberar capacidade. Inícios de lanes são escalonados por 2 segundos por padrão para evitar tempestades de criação no daemon Docker local; substitua com `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. O runner faz preflight do Docker por padrão, limpa contêineres E2E obsoletos do OpenClaw, emite status de lanes ativas a cada 30 segundos, compartilha caches de ferramentas CLI de provedor entre lanes compatíveis, tenta novamente falhas transitórias de provedores live uma vez por padrão (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`) e armazena tempos de lanes em `.artifacts/docker-tests/lane-timings.json` para ordenação do mais longo para o mais curto em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto de lanes sem executar Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` para ajustar a saída de status ou `OPENCLAW_DOCKER_ALL_TIMINGS=0` para desabilitar a reutilização de tempos. Use `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` apenas para lanes determinísticas/locais ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` apenas para lanes de provedores live; os aliases de pacote são `pnpm test:docker:local:all` e `pnpm test:docker:live:all`. O modo somente live mescla lanes live principais e finais em um único pool do mais longo para o mais curto para que buckets de provedor possam empacotar trabalho de Claude, Codex e Gemini juntos. O runner para de agendar novas lanes em pool após a primeira falha, a menos que `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` seja definido, e cada lane tem um timeout fallback de 120 minutos substituível com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lanes live/finais selecionadas usam limites por lane mais restritos. Comandos de configuração Docker de backend CLI têm seu próprio timeout via `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (padrão 180). Logs por lane, `summary.json`, `failures.json` e tempos de fases são gravados em `.artifacts/docker-tests/<run-id>/`; use `pnpm test:docker:timings <summary.json>` para inspecionar lanes lentas e `pnpm test:docker:rerun <run-id|summary.json|failures.json>` para imprimir comandos baratos de reexecução direcionada.
- `pnpm test:docker:browser-cdp-snapshot`: Cria um contêiner E2E de código-fonte com Chromium, inicia CDP bruto mais um Gateway isolado, executa `browser doctor --deep` e verifica que snapshots de função CDP incluem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame.
- Probes Docker live de backend CLI podem ser executados como lanes focadas, por exemplo `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` ou `pnpm test:docker:live-cli-backend:codex:mcp`. Claude e Gemini têm aliases `:resume` e `:mcp` correspondentes.
- `pnpm test:docker:openwebui`: Inicia OpenClaw + Open WebUI em Docker, faz login pelo Open WebUI, verifica `/api/models` e então executa um chat real proxied por `/api/chat/completions`. Requer uma chave de modelo live utilizável (por exemplo OpenAI em `~/.profile`), baixa uma imagem externa do Open WebUI e não se espera que seja estável em CI como as suítes normais de unidade/e2e.
- `pnpm test:docker:mcp-channels`: Inicia um contêiner Gateway semeado e um segundo contêiner cliente que gera `openclaw mcp serve`; então verifica descoberta de conversas roteadas, leituras de transcrições, metadados de anexos, comportamento de fila de eventos live, roteamento de envio de saída e notificações de canal + permissão no estilo Claude pela ponte stdio real. A asserção de notificação Claude lê os frames MCP stdio brutos diretamente para que o smoke reflita o que a ponte realmente emite.
- `pnpm test:docker:upgrade-survivor`: Instala o tarball empacotado do OpenClaw sobre uma fixture suja de usuário antigo, executa a atualização do pacote mais o doctor não interativo sem chaves de provedor ao vivo ou de canal, depois inicia um Gateway de loopback e verifica se agentes, configuração de canal, listas de permissões de plugins, arquivos de workspace/sessão, estado obsoleto de dependências de plugin legado, inicialização e status RPC sobrevivem.
- `pnpm test:docker:published-upgrade-survivor`: Instala `openclaw@latest` por padrão, semeia arquivos realistas de usuário existente sem chaves de provedor ao vivo ou de canal, configura essa linha de base com uma receita integrada do comando `openclaw config set`, atualiza essa instalação publicada para o tarball empacotado do OpenClaw, executa o doctor não interativo, grava `.artifacts/upgrade-survivor/summary.json`, depois inicia um Gateway de loopback e verifica se intents configuradas, arquivos de workspace/sessão, configuração obsoleta de plugin e estado de dependências legado, inicialização, `/healthz`, `/readyz` e status RPC sobrevivem ou são reparados corretamente. Substitua uma linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, expanda uma matriz exata com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` como `all-since-2026.4.23`, ou adicione fixtures de cenário com `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; o conjunto de issues relatadas inclui `configured-plugin-installs` para verificar se plugins externos configurados do OpenClaw são instalados automaticamente durante a atualização e `stale-source-plugin-shadow` para impedir que sombras de plugins somente de código-fonte quebrem a inicialização. Package Acceptance expõe isso como `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` e `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Executa o harness de sobrevivência de atualização publicada no cenário `plugin-deps-cleanup`, com limpeza pesada, começando em `openclaw@2026.4.23` por padrão. O workflow separado `Update Migration` expande esta lane com `baselines=all-since-2026.4.23` para que cada pacote estável publicado desde `.23` em diante atualize para o candidato e comprove a limpeza de dependências de plugins configurados fora do Full Release CI.
- `pnpm test:docker:plugins`: Executa um smoke de instalação/atualização para caminho local, `file:`, pacotes do registro npm com dependências içadas, refs móveis de git, fixtures do ClawHub, atualizações do marketplace e habilitação/inspeção de bundle do Claude.
## Gate local de PR
## Verificação local de PR
Para verificações locais de integração/gate de PR, execute:
Para verificações locais de integração/validação de PR, execute:
- `pnpm check:changed`
- `pnpm check`
@ -66,12 +66,12 @@ Para verificações locais de integração/gate de PR, execute:
- `pnpm test`
- `pnpm check:docs`
Se `pnpm test` apresentar falha intermitente em um host carregado, execute novamente uma vez antes de tratar como regressão e, em seguida, isole com `pnpm test <path/to/test>`. Para hosts com pouca memória, use:
Se `pnpm test` apresentar falhas intermitentes em uma máquina com carga alta, execute novamente uma vez antes de tratar como regressão e depois isole com `pnpm test <path/to/test>`. Para máquinas com restrição de memória, use:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Benchmark de latência de modelo (chaves locais)
## Benchmark de latência de modelos (chaves locais)
Script: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
@ -83,8 +83,8 @@ Uso:
Última execução (2025-12-31, 20 execuções):
- mediana do minimax 1279ms (mín. 1114, máx. 2431)
- mediana do opus 2454ms (mín. 1224, máx. 3170)
- mediana minimax 1279ms (mín. 1114, máx. 2431)
- mediana opus 2454ms (mín. 1224, máx. 3170)
## Benchmark de inicialização da CLI
@ -114,35 +114,35 @@ Predefinições:
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: ambas as predefinições
A saída inclui `sampleCount`, média, p50, p95, mín./máx., distribuição de código de saída/sinal e resumos de RSS máximo para cada comando. Os opcionais `--cpu-prof-dir` / `--heap-prof-dir` gravam perfis V8 por execução, para que a medição de tempo e a captura de perfil usem o mesmo harness.
A saída inclui `sampleCount`, média, p50, p95, mín./máx., distribuição de código de saída/sinal e resumos de RSS máximo para cada comando. As opções opcionais `--cpu-prof-dir` / `--heap-prof-dir` gravam perfis V8 por execução, para que a medição de tempo e a captura de perfil usem o mesmo harness.
Convenções de saída salva:
- `pnpm test:startup:bench:smoke` grava o artefato de smoke direcionado em `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` grava o artefato da suíte completa em `.artifacts/cli-startup-bench-all.json` usando `runs=5` e `warmup=1`
- `pnpm test:startup:bench:update` atualiza a fixture de baseline versionada em `test/fixtures/cli-startup-bench.json` usando `runs=5` e `warmup=1`
- `pnpm test:startup:bench:update` atualiza o fixture de baseline versionado em `test/fixtures/cli-startup-bench.json` usando `runs=5` e `warmup=1`
Fixture versionada:
Fixture versionado:
- `test/fixtures/cli-startup-bench.json`
- Atualize com `pnpm test:startup:bench:update`
- Compare os resultados atuais com a fixture usando `pnpm test:startup:bench:check`
- Compare os resultados atuais com o fixture usando `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
## E2E de onboarding (Docker)
Docker é opcional; isto só é necessário para testes smoke de onboarding em contêiner.
Docker é opcional; isto só é necessário para testes smoke de onboarding conteinerizados.
Fluxo completo de inicialização a frio em um contêiner Linux limpo:
Fluxo completo de cold start em um contêiner Linux limpo:
```bash
scripts/e2e/onboard-docker.sh
```
Este script conduz o assistente interativo por meio de um pseudo-tty, verifica arquivos de config/workspace/sessão e, em seguida, inicia o Gateway e executa `openclaw health`.
Este script conduz o assistente interativo por meio de uma pseudo-tty, verifica arquivos de configuração/workspace/sessão, depois inicia o Gateway e executa `openclaw health`.
## Smoke de importação de QR (Docker)
Garante que o auxiliar de runtime QR mantido carregue nos runtimes Docker Node compatíveis (Node 24 padrão, Node 22 compatível):
Garante que o helper de runtime QR mantido seja carregado nos runtimes Docker Node compatíveis (Node 24 por padrão, Node 22 compatível):
```bash
pnpm test:docker:qr
@ -151,5 +151,5 @@ pnpm test:docker:qr
## Relacionados
- [Testes](/pt-BR/help/testing)
- [Testes live](/pt-BR/help/testing-live)
- [Testes ao vivo](/pt-BR/help/testing-live)
- [Testes de atualizações e plugins](/pt-BR/help/testing-updates-plugins)

162
docs/pt-BR/reference/transcript-hygiene.md
View File

@ -1,77 +1,77 @@
---
read_when:
- Você está depurando rejeições de solicitações do provedor relacionadas ao formato da transcrição
- Você está alterando a sanitização da transcrição ou a lógica de reparo de chamadas de ferramenta
- Você está investigando incompatibilidades de IDs de chamadas de ferramenta entre provedores
summary: 'Referência: regras por provedor para sanitização e reparo de transcrições'
- Você está depurando rejeições de solicitações de provedor relacionadas ao formato da transcrição
- Você está alterando a sanitização de transcrições ou a lógica de reparo de chamadas de ferramentas
- Você está investigando divergências de IDs de chamadas de ferramenta entre provedores
summary: 'Referência: regras de sanitização e reparo de transcrição específicas do provedor'
title: Higiene da transcrição
x-i18n:
generated_at: "2026-05-03T05:54:42Z"
generated_at: "2026-05-05T01:49:40Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
O OpenClaw aplica **correções específicas por provedor** aos transcripts antes de uma execução (ao construir o contexto do modelo). A maioria delas são ajustes **em memória** usados para atender a requisitos rigorosos dos provedores. Uma etapa separada de reparo do arquivo de sessão também pode reescrever o JSONL armazenado antes que a sessão seja carregada, mas apenas para linhas malformadas ou turnos persistidos que sejam registros duráveis inválidos. As respostas entregues pelo assistente são preservadas em disco; a remoção de prefill de assistente específica do provedor ocorre somente durante a construção dos payloads de saída. Quando ocorre um reparo, o arquivo original é copiado como backup junto ao arquivo de sessão.
OpenClaw aplica **correções específicas de provedor** a transcritos antes de uma execução (ao construir o contexto do modelo). A maioria delas são ajustes **em memória** usados para satisfazer requisitos rigorosos de provedores. Uma etapa separada de reparo de arquivo de sessão também pode reescrever o JSONL armazenado antes que a sessão seja carregada, mas apenas para linhas malformadas ou turnos persistidos que sejam registros duráveis inválidos. Respostas entregues pelo assistente são preservadas em disco; a remoção de prefill do assistente específica de provedor acontece apenas durante a construção de payloads de saída. Quando ocorre um reparo, o arquivo original recebe backup ao lado do arquivo de sessão.
O escopo inclui:
- Contexto de prompt apenas em tempo de execução que fica fora dos turnos de transcript visíveis ao usuário
- Contexto de prompt apenas em runtime ficando fora dos turnos de transcrito visíveis ao usuário
- Sanitização de id de chamada de ferramenta
- Validação de entrada de chamada de ferramenta
- Reparo de pareamento de resultado de ferramenta
- Validação / ordenação de turnos
- Limpeza de assinatura de pensamento
- Limpeza de assinatura de raciocínio
- Limpeza de assinatura de thinking
- Sanitização de payload de imagem
- Limpeza de blocos de texto em branco antes da reprodução pelo provedor
- Limpeza de blocos de texto vazios antes do replay do provedor
- Marcação de proveniência de entrada do usuário (para prompts roteados entre sessões)
- Reparo de turno de erro de assistente vazio para reprodução do Bedrock Converse
- Reparo de turno de erro vazio do assistente para replay do Bedrock Converse
Se você precisar de detalhes sobre armazenamento de transcript, consulte:
Se você precisar de detalhes de armazenamento de transcritos, veja:
- [Visão aprofundada do gerenciamento de sessão](/pt-BR/reference/session-management-compaction)
- [Análise detalhada de gerenciamento de sessões](/pt-BR/reference/session-management-compaction)
---
## Regra global: contexto de runtime não é transcript do usuário
## Regra global: contexto de runtime não é transcrito do usuário
O contexto de runtime/sistema pode ser adicionado ao prompt do modelo para um turno, mas ele
não é conteúdo criado pelo usuário final. O OpenClaw mantém um corpo de prompt separado,
voltado ao transcript, para respostas do Gateway, followups enfileirados, ACP, CLI e execuções
Pi incorporadas. Turnos visíveis de usuário armazenados usam esse corpo de transcript em vez do
Contexto de runtime/sistema pode ser adicionado ao prompt do modelo para um turno, mas ele
não é conteúdo criado pelo usuário final. OpenClaw mantém um corpo de prompt separado voltado ao transcrito
para respostas do Gateway, acompanhamentos enfileirados, ACP, CLI e execuções de Pi
embutidas. Turnos visíveis de usuário armazenados usam esse corpo de transcrito em vez do
prompt enriquecido em runtime.
Para sessões legadas que já persistiram wrappers de runtime, as superfícies de histórico do Gateway
aplicam uma projeção de exibição antes de retornar mensagens a clientes WebChat,
Para sessões legadas que já persistiram wrappers de runtime, superfícies de histórico do Gateway
aplicam uma projeção de exibição antes de retornar mensagens para clientes WebChat,
TUI, REST ou SSE.
---
## Onde isso é executado
## Onde isso executa
Toda a higiene de transcript é centralizada no executor incorporado:
Toda a higiene de transcritos é centralizada no runner embutido:
- Seleção de política: `src/agents/transcript-policy.ts`
- Aplicação de sanitização/reparo: `sanitizeSessionHistory` em `src/agents/pi-embedded-runner/replay-history.ts`
A política usa `provider`, `modelApi` e `modelId` para decidir o que aplicar.
Separadamente da higiene de transcript, os arquivos de sessão são reparados (se necessário) antes do carregamento:
Separadamente da higiene de transcritos, arquivos de sessão são reparados (se necessário) antes do carregamento:
- `repairSessionFileIfNeeded` em `src/agents/session-file-repair.ts`
- Chamado a partir de `run/attempt.ts` e `compact.ts` (executor incorporado)
- Chamado a partir de `run/attempt.ts` e `compact.ts` (runner embutido)
---
## Regra global: sanitização de imagens
Payloads de imagem são sempre sanitizados para evitar rejeição do lado do provedor devido a limites
de tamanho (redução de escala/recompressão de imagens base64 grandes demais).
Payloads de imagem são sempre sanitizados para evitar rejeição pelo provedor devido a limites
de tamanho (redimensionar/recomprimir imagens base64 grandes demais).
Isso também ajuda a controlar a pressão de tokens causada por imagens em modelos compatíveis com visão.
Isso também ajuda a controlar a pressão de tokens causada por imagens para modelos com capacidade de visão.
Dimensões máximas menores geralmente reduzem o uso de tokens; dimensões maiores preservam detalhes.
Implementação:
@ -79,16 +79,16 @@ Implementação:
- `sanitizeSessionMessagesImages` em `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` em `src/agents/tool-images.ts`
- O lado máximo da imagem é configurável via `agents.defaults.imageMaxDimensionPx` (padrão: `1200`).
- Blocos de texto em branco são removidos enquanto essa etapa percorre o conteúdo de reprodução. Turnos de assistente
que ficam vazios são descartados da cópia de reprodução; turnos de usuário e de resultado de ferramenta
- Blocos de texto vazios são removidos enquanto esta etapa percorre o conteúdo de replay. Turnos de assistente
que ficam vazios são removidos da cópia de replay; turnos de usuário e de resultado de ferramenta
que ficam vazios recebem um placeholder não vazio de conteúdo omitido.
---
## Regra global: chamadas de ferramenta malformadas
Blocos de chamada de ferramenta do assistente sem `input` nem `arguments` são descartados
antes que o contexto do modelo seja construído. Isso evita rejeições de provedor causadas por chamadas de ferramenta
Blocos de chamada de ferramenta do assistente que não têm `input` nem `arguments` são removidos
antes de o contexto do modelo ser construído. Isso evita rejeições de provedor por chamadas de ferramenta
parcialmente persistidas (por exemplo, após uma falha por limite de taxa).
Implementação:
@ -101,18 +101,18 @@ Implementação:
## Regra global: proveniência de entrada entre sessões
Quando um agente envia um prompt para outra sessão via `sessions_send` (incluindo
etapas de resposta/anúncio entre agentes), o OpenClaw persiste o turno de usuário criado com:
etapas de resposta/anúncio de agente para agente), OpenClaw persiste o turno de usuário criado com:
- `message.provenance.kind = "inter_session"`
O OpenClaw também prefixa um marcador no mesmo turno `[Inter-session message ... isUser=false]`
antes do texto do prompt roteado para que a chamada ativa do modelo possa distinguir
a saída de sessão externa de instruções externas do usuário final. Esse marcador inclui
a sessão de origem, o canal e a ferramenta quando disponíveis. O transcript ainda usa
`role: "user"` por compatibilidade com provedores, mas o texto visível e os metadados
OpenClaw também prefixa um marcador `[Inter-session message ... isUser=false]`
no mesmo turno antes do texto do prompt roteado para que a chamada ativa ao modelo consiga distinguir
saída de sessão externa de instruções externas do usuário final. Esse marcador inclui
a sessão de origem, o canal e a ferramenta quando disponíveis. O transcrito ainda usa
`role: "user"` para compatibilidade com provedores, mas o texto visível e os metadados
de proveniência marcam o turno como dados entre sessões.
Durante a reconstrução de contexto, o OpenClaw aplica o mesmo marcador a turnos de usuário
Durante a reconstrução de contexto, OpenClaw aplica o mesmo marcador a turnos de usuário
entre sessões persistidos mais antigos que têm apenas metadados de proveniência.
---
@ -122,72 +122,74 @@ entre sessões persistidos mais antigos que têm apenas metadados de proveniênc
**OpenAI / OpenAI Codex**
- Apenas sanitização de imagens.
- Descarta assinaturas de raciocínio órfãs (itens de raciocínio independentes sem um bloco de conteúdo subsequente) para transcripts OpenAI Responses/Codex, e descarta raciocínio OpenAI reproduzível após uma troca de rota de modelo.
- Preserva payloads de itens de raciocínio reproduzíveis do OpenAI Responses, incluindo itens criptografados de resumo vazio, para que a reprodução manual/WebSocket mantenha o estado `rs_*` obrigatório pareado com itens de saída do assistente.
- Remove assinaturas de raciocínio órfãs (itens de raciocínio autônomos sem um bloco de conteúdo seguinte) para transcritos OpenAI Responses/Codex, e remove raciocínio OpenAI reproduzível após uma troca de rota de modelo.
- Preserva payloads de itens de raciocínio reproduzíveis do OpenAI Responses, incluindo itens criptografados com resumo vazio, para que o replay manual/WebSocket mantenha o estado `rs_*` necessário pareado com itens de saída do assistente.
- Native ChatGPT Codex Responses segue paridade de fio do Codex ao reproduzir payloads anteriores de raciocínio/mensagem/função de Responses sem IDs de itens anteriores, preservando `prompt_cache_key` da sessão.
- Sem sanitização de id de chamada de ferramenta.
- O reparo de pareamento de resultado de ferramenta pode mover saídas reais correspondentes e sintetizar saídas `aborted` no estilo Codex para chamadas de ferramenta ausentes.
- Sem validação ou reordenação de turnos.
- Saídas de ferramenta ausentes da família OpenAI Responses são sintetizadas como `aborted` para corresponder à normalização de reprodução do Codex.
- Saídas de ferramenta ausentes da família OpenAI Responses são sintetizadas como `aborted` para corresponder à normalização de replay do Codex.
- Sem remoção de assinatura de pensamento.
**Gemma 4 compatível com OpenAI**
- Blocos históricos de pensamento/raciocínio do assistente são removidos antes da reprodução para que servidores
Gemma 4 locais compatíveis com OpenAI não recebam conteúdo de raciocínio de turnos anteriores.
- Blocos históricos de thinking/raciocínio do assistente são removidos antes do replay para que servidores locais
Gemma 4 compatíveis com OpenAI não recebam conteúdo de raciocínio de turnos anteriores.
- Continuações de chamada de ferramenta no mesmo turno atual mantêm o bloco de raciocínio do assistente
anexado à chamada de ferramenta até que o resultado da ferramenta tenha sido reproduzido.
**Google (Generative AI / Gemini CLI / Antigravity)**
- Sanitização de id de chamada de ferramenta: alfanumérico estrito.
- Sanitização de id de chamada de ferramenta: alfanumérica estrita.
- Reparo de pareamento de resultado de ferramenta e resultados de ferramenta sintéticos.
- Validação de turnos (alternância de turnos no estilo Gemini).
- Correção de ordenação de turnos do Google (prefixa um pequeno bootstrap de usuário se o histórico começar com assistente).
- Antigravity Claude: normaliza assinaturas de raciocínio; descarta blocos de raciocínio não assinados.
- Antigravity Claude: normaliza assinaturas de thinking; remove blocos de thinking sem assinatura.
**Anthropic / Minimax (compatível com Anthropic)**
- Reparo de pareamento de resultado de ferramenta e resultados de ferramenta sintéticos.
- Validação de turnos (mescla turnos de usuário consecutivos para satisfazer alternância estrita).
- Turnos finais de prefill do assistente são removidos dos payloads Anthropic Messages
de saída quando o raciocínio está habilitado, incluindo rotas do Cloudflare AI Gateway.
- Blocos de raciocínio com assinaturas de reprodução ausentes, vazias ou em branco são removidos
antes da conversão do provedor. Se isso esvaziar um turno de assistente, o OpenClaw mantém
- Validação de turnos (mescla turnos consecutivos de usuário para satisfazer alternância estrita).
- Turnos finais de prefill do assistente são removidos de payloads Anthropic Messages
de saída quando thinking está habilitado, incluindo rotas Cloudflare AI Gateway.
- Blocos de thinking com assinaturas de replay ausentes, vazias ou em branco são removidos
antes da conversão do provedor. Se isso esvaziar um turno de assistente, OpenClaw mantém
o formato do turno com texto não vazio de raciocínio omitido.
- Turnos de assistente mais antigos somente com raciocínio que precisam ser removidos são substituídos por
texto não vazio de raciocínio omitido para que os adaptadores de provedor não descartem o turno de reprodução.
- Turnos de assistente mais antigos apenas com thinking que precisam ser removidos são substituídos por
texto não vazio de raciocínio omitido para que adaptadores de provedor não removam o turno
de replay.
**Amazon Bedrock (Converse API)**
- Turnos de erro de stream do assistente vazios são reparados para um bloco de texto fallback não vazio
antes da reprodução. O Bedrock Converse rejeita mensagens de assistente com `content: []`, então
- Turnos vazios de erro de stream do assistente são reparados para um bloco de texto fallback não vazio
antes do replay. Bedrock Converse rejeita mensagens de assistente com `content: []`, então
turnos de assistente persistidos com `stopReason: "error"` e conteúdo vazio também são
reparados em disco antes do carregamento.
- Turnos de erro de stream do assistente que contêm apenas blocos de texto em branco são descartados
da cópia de reprodução em memória em vez de reproduzir um bloco em branco inválido.
- Blocos de raciocínio Claude com assinaturas de reprodução ausentes, vazias ou em branco são
removidos antes da reprodução do Converse. Se isso esvaziar um turno de assistente, o OpenClaw
- Turnos de erro de stream do assistente que contêm apenas blocos de texto em branco são removidos
da cópia de replay em memória em vez de reproduzir um bloco em branco inválido.
- Blocos de thinking do Claude com assinaturas de replay ausentes, vazias ou em branco são
removidos antes do replay do Converse. Se isso esvaziar um turno de assistente, OpenClaw
mantém o formato do turno com texto não vazio de raciocínio omitido.
- Turnos de assistente mais antigos somente com raciocínio que precisam ser removidos são substituídos por
texto não vazio de raciocínio omitido para que a reprodução do Converse mantenha o formato estrito dos turnos.
- A reprodução filtra turnos de assistente de espelho de entrega do OpenClaw e injetados pelo gateway.
- Turnos de assistente mais antigos apenas com thinking que precisam ser removidos são substituídos por
texto não vazio de raciocínio omitido para que o replay do Converse mantenha o formato estrito de turnos.
- O replay filtra turnos de assistente de espelho de entrega do OpenClaw e injetados pelo gateway.
- A sanitização de imagens se aplica pela regra global.
**Mistral (incluindo detecção baseada em model-id)**
- Sanitização de id de chamada de ferramenta: strict9 (alfanumérico com comprimento 9).
- Sanitização de id de chamada de ferramenta: strict9 (alfanumérica com comprimento 9).
**OpenRouter Gemini**
- Limpeza de assinatura de pensamento: remove valores `thought_signature` que não sejam base64 (mantém base64).
- Limpeza de assinatura de pensamento: remove valores `thought_signature` que não são base64 (mantém base64).
**OpenRouter Anthropic**
- Turnos finais de prefill do assistente são removidos de payloads de modelos Anthropic verificados
compatíveis com OpenAI no OpenRouter quando o raciocínio está habilitado, correspondendo
ao comportamento de reprodução direta da Anthropic e da Cloudflare Anthropic.
- Turnos finais de prefill do assistente são removidos de payloads de modelos Anthropic
compatíveis com OpenAI verificados do OpenRouter quando raciocínio está habilitado, correspondendo
ao comportamento de replay direto do Anthropic e Cloudflare Anthropic.
**Todo o restante**
**Todo o resto**
- Apenas sanitização de imagens.
@ -195,22 +197,22 @@ entre sessões persistidos mais antigos que têm apenas metadados de proveniênc
## Comportamento histórico (pré-2026.1.22)
Antes da versão 2026.1.22, o OpenClaw aplicava várias camadas de higiene de transcript:
Antes da versão 2026.1.22, OpenClaw aplicava várias camadas de higiene de transcritos:
- Uma **extensão transcript-sanitize** era executada em toda construção de contexto e podia:
- Uma **extensão de sanitização de transcrito** executava em toda construção de contexto e podia:
- Reparar pareamento de uso/resultado de ferramenta.
- Sanitizar ids de chamada de ferramenta (incluindo um modo não estrito que preservava `_`/`-`).
- O executor também realizava sanitização específica por provedor, o que duplicava trabalho.
- Mutações adicionais ocorriam fora da política do provedor, incluindo:
- Remover tags `<final>` do texto do assistente antes da persistência.
- Descartar turnos de erro de assistente vazios.
- Aparar conteúdo de assistente após chamadas de ferramenta.
- O runner também realizava sanitização específica de provedor, o que duplicava trabalho.
- Mutações adicionais ocorriam fora da política de provedor, incluindo:
- Remoção de tags `<final>` do texto do assistente antes da persistência.
- Remoção de turnos vazios de erro do assistente.
- Corte do conteúdo do assistente após chamadas de ferramenta.
Essa complexidade causou regressões entre provedores (notadamente o pareamento
`call_id|fc_id` de `openai-responses`). A limpeza de 2026.1.22 removeu a extensão, centralizou
a lógica no executor e tornou a OpenAI **sem alterações** além da sanitização de imagens.
Essa complexidade causou regressões entre provedores (notavelmente pareamento
`call_id|fc_id` do `openai-responses`). A limpeza da versão 2026.1.22 removeu a extensão, centralizou
a lógica no runner e tornou OpenAI **sem toque** além da sanitização de imagens.
## Relacionado
## Relacionados
- [Gerenciamento de sessão](/pt-BR/concepts/session)
- [Poda de sessão](/pt-BR/concepts/session-pruning)
- [Gerenciamento de sessões](/pt-BR/concepts/session)
- [Poda de sessões](/pt-BR/concepts/session-pruning)

107
docs/pt-BR/security/network-proxy.md
View File

@ -1,69 +1,70 @@
---
read_when:
- Você quer defesa em profundidade contra ataques de SSRF e de reassociação de DNS
- Configurar um proxy direto externo para o tráfego de runtime do OpenClaw
summary: Como rotear o tráfego HTTP e WebSocket do tempo de execução do OpenClaw por meio de um proxy de filtragem gerenciado pelo operador
- Você quer uma defesa em profundidade contra ataques de SSRF e de reassociação de DNS
- Configurando um proxy direto externo para o tráfego em tempo de execução do OpenClaw
summary: Como rotear o tráfego HTTP e WebSocket do ambiente de execução do OpenClaw por meio de um proxy de filtragem gerenciado pelo operador
title: Proxy de rede
x-i18n:
generated_at: "2026-05-04T18:24:29Z"
generated_at: "2026-05-05T01:49:42Z"
model: gpt-5.5
provider: openai
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
source_path: security/network-proxy.md
workflow: 16
---
# Proxy de Rede
# Proxy de rede
O OpenClaw pode rotear tráfego HTTP e WebSocket em tempo de execução por meio de um proxy de encaminhamento gerenciado pelo operador. Esta é uma defesa em profundidade opcional para implantações que desejam controle central de saída, proteção SSRF mais forte e melhor auditabilidade de rede.
O OpenClaw pode rotear tráfego HTTP e WebSocket em tempo de execução por meio de um proxy direto gerenciado pelo operador. Esta é uma defesa em profundidade opcional para implantações que desejam controle central de egresso, proteção mais forte contra SSRF e melhor auditabilidade de rede.
O OpenClaw não fornece, baixa, inicia, configura nem certifica um proxy. Você executa a tecnologia de proxy adequada ao seu ambiente, e o OpenClaw roteia clientes HTTP e WebSocket normais, locais ao processo, por meio dele.
O OpenClaw não fornece, baixa, inicia, configura nem certifica um proxy. Você executa a tecnologia de proxy que se ajusta ao seu ambiente, e o OpenClaw roteia clientes HTTP e WebSocket normais, locais ao processo, por meio dele.
## Por Que Usar um Proxy?
## Por que usar um proxy?
Um proxy dá aos operadores um único ponto de controle de rede para tráfego HTTP e WebSocket de saída. Isso pode ser útil mesmo fora do endurecimento contra SSRF:
Um proxy dá aos operadores um ponto único de controle de rede para tráfego HTTP e WebSocket de saída. Isso pode ser útil mesmo fora do endurecimento contra SSRF:
- Política central: mantenha uma política de saída em vez de depender de cada ponto de chamada HTTP da aplicação para acertar as regras de rede.
- Política central: mantenha uma política de egresso em vez de depender de cada ponto de chamada HTTP da aplicação para acertar as regras de rede.
- Verificações no momento da conexão: avalie o destino após a resolução DNS e imediatamente antes de o proxy abrir a conexão upstream.
- Defesa contra DNS rebinding: reduza a lacuna entre uma verificação DNS no nível da aplicação e a conexão de saída real.
- Cobertura JavaScript mais ampla: roteie `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch e clientes semelhantes comuns pelo mesmo caminho.
- Auditabilidade: registre destinos permitidos e negados no limite de saída.
- Controle operacional: aplique regras de destino, segmentação de rede, limites de taxa ou listas de permissão de saída sem recompilar o OpenClaw.
- Cobertura JavaScript mais ampla: roteie clientes comuns como `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch e similares pelo mesmo caminho.
- Auditabilidade: registre destinos permitidos e negados no limite de egresso.
- Controle operacional: imponha regras de destino, segmentação de rede, limites de taxa ou listas de permissão de saída sem recompilar o OpenClaw.
O roteamento por proxy é uma barreira de proteção em nível de processo para saída HTTP e WebSocket normal. Ele oferece aos operadores um caminho que falha fechado para rotear clientes HTTP JavaScript compatíveis por meio de seu próprio proxy de filtragem, mas não é uma sandbox de rede em nível de SO e não faz o OpenClaw certificar a política de destino do proxy.
O roteamento por proxy é uma proteção em nível de processo para egresso HTTP e WebSocket normal. Ele dá aos operadores um caminho fail-closed para rotear clientes HTTP JavaScript compatíveis por meio do seu próprio proxy de filtragem, mas não é uma sandbox de rede em nível de sistema operacional e não faz o OpenClaw certificar a política de destino do proxy.
## Como o OpenClaw Roteia o Tráfego
## Como o OpenClaw roteia tráfego
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos de tempo de execução protegidos, como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local`, roteiam saída HTTP e WebSocket normal pelo proxy configurado:
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos protegidos em tempo de execução, como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local`, roteiam egresso HTTP e WebSocket normal por meio do proxy configurado:
```text
Processo do OpenClaw
Processo OpenClaw
fetch -> proxy de filtragem gerenciado pelo operador -> internet pública
node:http e https -> proxy de filtragem gerenciado pelo operador -> internet pública
Clientes WebSocket -> proxy de filtragem gerenciado pelo operador -> internet pública
```
O contrato público é o comportamento de roteamento, não os ganchos internos do Node usados para implementá-lo. Clientes WebSocket do plano de controle do OpenClaw Gateway usam um caminho direto estreito para tráfego RPC do Gateway em local loopback quando a URL do Gateway usa `localhost` ou um IP de loopback literal, como `127.0.0.1` ou `[::1]`. Esse caminho do plano de controle precisa conseguir alcançar Gateways de loopback mesmo quando o proxy do operador bloqueia destinos de loopback. Requisições HTTP e WebSocket normais em tempo de execução ainda usam o proxy configurado.
O contrato público é o comportamento de roteamento, não os hooks internos do Node usados para implementá-lo. Clientes WebSocket do plano de controle do OpenClaw Gateway usam um caminho direto restrito para tráfego RPC do Gateway via local loopback quando a URL do Gateway usa `localhost` ou um IP literal de loopback, como `127.0.0.1` ou `[::1]`. Esse caminho do plano de controle precisa conseguir alcançar Gateways em loopback mesmo quando o proxy do operador bloqueia destinos de loopback. Requisições HTTP e WebSocket normais em tempo de execução ainda usam o proxy configurado.
Internamente, o OpenClaw usa dois ganchos de roteamento em nível de processo para este recurso:
Internamente, o OpenClaw usa dois hooks de roteamento em nível de processo para este recurso:
- O roteamento de dispatcher do Undici cobre `fetch`, clientes baseados em undici e transportes que fornecem seu próprio dispatcher undici.
- O roteamento de `global-agent` cobre chamadores do núcleo do Node `node:http` e `node:https`, incluindo muitas bibliotecas sobrepostas a `http.request`, `https.request`, `http.get` e `https.get`. O modo de proxy gerenciado força esse agente global para que agentes HTTP explícitos do Node não ignorem acidentalmente o proxy do operador.
- O roteamento por dispatcher do Undici cobre `fetch`, clientes baseados em undici e transportes que fornecem seu próprio dispatcher undici.
- O roteamento por `global-agent` cobre chamadores do núcleo do Node `node:http` e `node:https`, incluindo muitas bibliotecas em camadas sobre `http.request`, `https.request`, `http.get` e `https.get`. O modo de proxy gerenciado força esse agente global para que agentes HTTP explícitos do Node não contornem acidentalmente o proxy do operador.
Alguns plugins possuem transportes personalizados que precisam de configuração explícita de proxy mesmo quando existe roteamento em nível de processo. Por exemplo, o transporte da Bot API do Telegram usa seu próprio dispatcher undici HTTP/1 e, portanto, respeita o ambiente de proxy do processo mais o fallback gerenciado `OPENCLAW_PROXY_URL` nesse caminho de transporte específico do proprietário.
Alguns plugins possuem transportes personalizados que precisam de configuração explícita de proxy mesmo quando existe roteamento em nível de processo. Por exemplo, o transporte da Bot API do Telegram usa seu próprio dispatcher HTTP/1 do undici e, portanto, respeita o ambiente de proxy do processo mais o fallback gerenciado `OPENCLAW_PROXY_URL` nesse caminho de transporte específico do proprietário.
A própria URL do proxy deve usar `http://`. Destinos HTTPS ainda são compatíveis por meio do proxy com HTTP `CONNECT`; isso significa apenas que o OpenClaw espera um listener de proxy de encaminhamento HTTP simples, como `http://127.0.0.1:3128`.
A URL do proxy em si deve usar `http://`. Destinos HTTPS ainda são compatíveis por meio do proxy com HTTP `CONNECT`; isso significa apenas que o OpenClaw espera um listener de proxy direto HTTP simples, como `http://127.0.0.1:3128`.
Enquanto o proxy está ativo, o OpenClaw limpa `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Essas listas de bypass são baseadas em destino, então deixar `localhost` ou `127.0.0.1` nelas permitiria que alvos SSRF de alto risco ignorassem o proxy de filtragem.
No desligamento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento em cache do processo.
No desligamento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento de processo em cache.
## Termos Relacionados a Proxy
## Termos de proxy relacionados
- `proxy.enabled` / `proxy.proxyUrl`: roteamento de proxy de encaminhamento de saída para a saída em tempo de execução do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso de entrada com reconhecimento de identidade para acesso ao Gateway. Consulte [autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- `proxy.enabled` / `proxy.proxyUrl`: roteamento de proxy direto de saída para egresso em tempo de execução do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso com identidade para acesso ao Gateway. Consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- `openclaw proxy`: proxy local de depuração e inspetor de captura para desenvolvimento e suporte. Consulte [openclaw proxy](/pt-BR/cli/proxy).
- Configurações de proxy específicas de canal ou provedor: substituições específicas do proprietário para um transporte específico. Prefira o proxy de rede gerenciado quando o objetivo for controle central de saída em todo o tempo de execução.
- `tools.web.fetch.useTrustedEnvProxy`: adesão opcional para `web_fetch` permitir que um proxy HTTP(S) de ambiente controlado pelo operador resolva DNS, mantendo a fixação DNS estrita padrão e a política de hostname. Consulte [Web fetch](/pt-BR/tools/web-fetch#trusted-env-proxy).
- Configurações de proxy específicas de canal ou provedor: substituições específicas do proprietário para um transporte específico. Prefira o proxy de rede gerenciado quando o objetivo for controle central de egresso em todo o runtime.
## Configuração
@ -73,7 +74,7 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
Você também pode fornecer a URL por meio do ambiente, mantendo `proxy.enabled=true` na configuração:
Você também pode fornecer a URL pelo ambiente, mantendo `proxy.enabled=true` na configuração:
```bash
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` tem precedência sobre `OPENCLAW_PROXY_URL`.
Se `enabled=true`, mas nenhuma URL de proxy válida estiver configurada, os comandos protegidos falharão na inicialização em vez de voltar para acesso direto à rede.
Se `enabled=true`, mas nenhuma URL de proxy válida estiver configurada, comandos protegidos falham na inicialização em vez de recorrer ao acesso direto à rede.
Para serviços de Gateway gerenciados iniciados com `openclaw gateway start`, prefira armazenar a URL na configuração:
Para serviços de gateway gerenciados iniciados com `openclaw gateway start`, prefira armazenar a URL na configuração:
```bash
openclaw config set proxy.enabled true
@ -92,30 +93,30 @@ openclaw gateway install --force
openclaw gateway start
```
O fallback de ambiente é mais adequado para execuções em primeiro plano. Se você usá-lo com um serviço instalado, coloque `OPENCLAW_PROXY_URL` no ambiente durável do serviço, como `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, depois reinstale o serviço para que launchd, systemd ou Tarefas Agendadas iniciem o gateway com esse valor.
O fallback de ambiente é melhor para execuções em primeiro plano. Se você o usar com um serviço instalado, coloque `OPENCLAW_PROXY_URL` no ambiente durável do serviço, como `$OPENCLAW_STATE_DIR/.env` ou `~/.openclaw/.env`, então reinstale o serviço para que launchd, systemd ou Scheduled Tasks inicie o gateway com esse valor.
Para comandos `openclaw --container ...`, o OpenClaw encaminha `OPENCLAW_PROXY_URL` para a CLI filha destinada ao contêiner quando ele está definido. A URL deve ser acessível de dentro do contêiner; `127.0.0.1` se refere ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy de loopback para comandos destinados a contêiner, a menos que você substitua explicitamente essa verificação de segurança.
Para comandos `openclaw --container ...`, o OpenClaw encaminha `OPENCLAW_PROXY_URL` para a CLI filha direcionada ao contêiner quando ela está definida. A URL deve ser alcançável de dentro do contêiner; `127.0.0.1` se refere ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy em loopback para comandos direcionados a contêiner, a menos que você substitua explicitamente essa verificação de segurança.
## Requisitos do Proxy
## Requisitos do proxy
A política do proxy é o limite de segurança. O OpenClaw não consegue verificar se o proxy bloqueia os alvos corretos.
Configure o proxy para:
- Vincular apenas ao loopback ou a uma interface privada confiável.
- Vincular somente a loopback ou a uma interface privada confiável.
- Restringir o acesso para que apenas o processo, host, contêiner ou conta de serviço do OpenClaw possa usá-lo.
- Resolver destinos por conta própria e bloquear IPs de destino após a resolução DNS.
- Resolver os destinos por conta própria e bloquear IPs de destino após a resolução DNS.
- Aplicar a política no momento da conexão tanto para requisições HTTP simples quanto para túneis HTTPS `CONNECT`.
- Rejeitar bypasses baseados em destino para intervalos de loopback, privados, link-local, metadados, multicast, reservados ou de documentação.
- Evitar listas de permissão de nomes de host, a menos que você confie totalmente no caminho de resolução DNS.
- Evitar listas de permissão de hostname, a menos que você confie totalmente no caminho de resolução DNS.
- Registrar destino, decisão, status e motivo sem registrar corpos de requisição, cabeçalhos de autorização, cookies ou outros segredos.
- Manter a política do proxy sob controle de versão e revisar alterações como configuração sensível à segurança.
## Destinos Bloqueados Recomendados
## Destinos bloqueados recomendados
Use esta lista de negação como ponto de partida para qualquer proxy de encaminhamento, firewall ou política de saída.
Use esta lista de bloqueio como ponto de partida para qualquer proxy direto, firewall ou política de egresso.
A lógica de classificação em nível de aplicação do OpenClaw vive em `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Os ganchos de paridade relevantes são `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e o tratamento de sentinela IPv4 incorporado para NAT64, 6to4, Teredo, ISATAP e formas IPv4 mapeadas. Esses arquivos são referências úteis ao manter uma política de proxy externa, mas o OpenClaw não exporta nem aplica automaticamente essas regras no seu proxy.
A lógica classificadora em nível de aplicação do OpenClaw fica em `src/infra/net/ssrf.ts` e `src/shared/net/ip.ts`. Os hooks de paridade relevantes são `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` e o tratamento de sentinela IPv4 incorporado para NAT64, 6to4, Teredo, ISATAP e formas IPv4 mapeadas. Esses arquivos são referências úteis ao manter uma política de proxy externa, mas o OpenClaw não exporta nem impõe automaticamente essas regras no seu proxy.
| Intervalo ou host | Por que bloquear |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
@ -123,8 +124,8 @@ A lógica de classificação em nível de aplicação do OpenClaw vive em `src/i
| `::1/128` | Loopback IPv6 |
| `0.0.0.0/8`, `::/128` | Endereços não especificados e desta rede |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Redes privadas RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Endereços link-local e caminhos comuns de metadados de nuvem |
| `169.254.169.254`, `metadata.google.internal` | Serviços de metadados de nuvem |
| `169.254.0.0/16`, `fe80::/10` | Endereços link-local e caminhos comuns de metadados em nuvem |
| `169.254.169.254`, `metadata.google.internal` | Serviços de metadados em nuvem |
| `100.64.0.0/10` | Espaço de endereços compartilhado de NAT de operadora |
| `198.18.0.0/15`, `2001:2::/48` | Intervalos de benchmark |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Intervalos de uso especial e documentação |
@ -136,7 +137,7 @@ A lógica de classificação em nível de aplicação do OpenClaw vive em `src/i
| `2002::/16`, `2001::/32` | 6to4 e Teredo com IPv4 incorporado |
| `::/96`, `::ffff:0:0/96` | IPv6 compatível com IPv4 e IPv6 mapeado para IPv4 |
Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou intervalos reservados adicionais, adicione-os também.
Se o seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou intervalos reservados adicionais, adicione-os também.
## Validação
@ -146,9 +147,9 @@ Valide o proxy a partir do mesmo host, contêiner ou conta de serviço que execu
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
Por padrão, quando nenhum destino personalizado é fornecido, o comando verifica se `https://example.com/` tem sucesso e inicia um canário de loopback temporário que o proxy não deve alcançar. A verificação negada padrão passa quando o proxy retorna uma resposta de negação não 2xx ou bloqueia o canário com uma falha de transporte; ela falha se uma resposta bem-sucedida chegar ao canário. Se nenhum proxy estiver habilitado e configurado, a validação relata um problema de configuração; use `--proxy-url` para uma pré-verificação pontual antes de alterar a configuração. Use `--allowed-url` e `--denied-url` para testar expectativas específicas da implantação. Adicione `--apns-reachable` para também verificar se a entrega direta HTTP/2 do APNs consegue abrir um túnel CONNECT pelo proxy e receber uma resposta de sandbox do APNs; a sondagem usa um token de provedor intencionalmente inválido, então `403 InvalidProviderToken` é esperado e conta como acessível. Destinos negados personalizados falham fechados: qualquer resposta HTTP significa que o destino estava acessível pelo proxy, e qualquer erro de transporte é relatado como inconclusivo porque o OpenClaw não consegue provar que o proxy bloqueou uma origem acessível. Em caso de falha de validação, o comando sai com código 1.
Por padrão, quando nenhum destino personalizado é fornecido, o comando verifica se `https://example.com/` tem sucesso e inicia um canário temporário em loopback que o proxy não deve alcançar. A verificação negada padrão passa quando o proxy retorna uma resposta de negação não 2xx ou bloqueia o canário com uma falha de transporte; ela falha se uma resposta bem-sucedida alcançar o canário. Se nenhum proxy estiver habilitado e configurado, a validação relata um problema de configuração; use `--proxy-url` para uma pré-verificação pontual antes de alterar a configuração. Use `--allowed-url` e `--denied-url` para testar expectativas específicas da implantação. Adicione `--apns-reachable` para também verificar se a entrega direta HTTP/2 do APNs consegue abrir um túnel CONNECT pelo proxy e receber uma resposta sandbox do APNs; a sondagem usa um token de provedor intencionalmente inválido, então `403 InvalidProviderToken` é esperado e conta como alcançável. Destinos negados personalizados são fail-closed: qualquer resposta HTTP significa que o destino ficou alcançável por meio do proxy, e qualquer erro de transporte é relatado como inconclusivo porque o OpenClaw não consegue provar que o proxy bloqueou uma origem alcançável. Em caso de falha de validação, o comando sai com o código 1.
Use `--json` para automação. A saída JSON contém o resultado geral, a origem efetiva da configuração de proxy, quaisquer erros de configuração e cada verificação de destino. Credenciais de URL de proxy são redigidas na saída de texto e JSON:
Use `--json` para automação. A saída JSON contém o resultado geral, a origem efetiva da configuração de proxy, quaisquer erros de configuração e cada verificação de destino. As credenciais da URL do proxy são redigidas na saída de texto e JSON:
```json
{
@ -184,7 +185,7 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
A solicitação pública deve ser bem-sucedida. As solicitações de loopback e de metadados devem ser bloqueadas pelo proxy. Para `openclaw proxy validate`, o canário de loopback integrado consegue distinguir uma negação do proxy de uma origem acessível. As verificações personalizadas de `--denied-url` não têm esse canário, portanto trate tanto respostas HTTP quanto falhas ambíguas de transporte como falhas de validação, a menos que seu proxy exponha um sinal de negação específico da implantação que você possa verificar separadamente.
A solicitação pública deve ser bem-sucedida. As solicitações de loopback e de metadados devem ser bloqueadas pelo proxy. Para `openclaw proxy validate`, o canário de loopback integrado pode distinguir uma negação do proxy de uma origem acessível. Verificações personalizadas com `--denied-url` não têm esse canário, portanto trate respostas HTTP e falhas de transporte ambíguas como falhas de validação, a menos que seu proxy exponha um sinal de negação específico da implantação que você possa verificar separadamente.
Em seguida, habilite o roteamento de proxy do OpenClaw:
@ -204,11 +205,11 @@ proxy:
## Limites
- O proxy melhora a cobertura para clientes HTTP e WebSocket JavaScript locais ao processo, mas não é um sandbox de rede no nível do sistema operacional.
- Soquetes brutos `net`, `tls` e `http2`, addons nativos e processos filhos podem contornar o roteamento de proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy.
- IRC é um canal TCP/TLS bruto fora do roteamento de proxy de encaminhamento gerenciado pelo operador. Em implantações que exigem que todo egresso passe por esse proxy de encaminhamento, defina `channels.irc.enabled=false`, a menos que o egresso IRC direto seja aprovado explicitamente.
- O proxy de depuração local é uma ferramenta de diagnóstico, e seu encaminhamento upstream direto para solicitações de proxy e túneis CONNECT fica desabilitado por padrão enquanto o modo de proxy gerenciado está ativo; habilite o encaminhamento direto somente para diagnósticos locais aprovados.
- WebUIs locais do usuário e servidores de modelo locais devem ser adicionados à lista de permissões na política de proxy do operador quando necessário; o OpenClaw não expõe um bypass geral para rede local para eles.
- O bypass de proxy do plano de controle do Gateway é intencionalmente limitado a `localhost` e URLs de IP de loopback literais. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` para conexões diretas locais do plano de controle do Gateway; outros nomes de host são roteados como tráfego comum baseado em nome de host.
- O proxy melhora a cobertura para clientes JavaScript HTTP e WebSocket locais ao processo, mas não é um sandbox de rede no nível do sistema operacional.
- Sockets brutos `net`, `tls` e `http2`, addons nativos e processos filhos podem contornar o roteamento de proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy.
- IRC é um canal TCP/TLS bruto fora do roteamento de proxy de encaminhamento gerenciado pelo operador. Em implantações que exigem que toda a saída passe por esse proxy de encaminhamento, defina `channels.irc.enabled=false`, a menos que a saída direta de IRC seja explicitamente aprovada.
- O proxy de depuração local é uma ferramenta de diagnóstico, e seu encaminhamento direto para upstream em solicitações de proxy e túneis CONNECT fica desabilitado por padrão enquanto o modo de proxy gerenciado está ativo; habilite o encaminhamento direto somente para diagnósticos locais aprovados.
- WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissões da política de proxy do operador quando necessário; o OpenClaw não expõe um bypass geral de rede local para eles.
- O bypass de proxy do plano de controle do Gateway é intencionalmente limitado a `localhost` e URLs de IP de loopback literais. Use `ws://127.0.0.1:18789`, `ws://[::1]:18789` ou `ws://localhost:18789` para conexões locais diretas do plano de controle do Gateway; outros nomes de host são roteados como tráfego comum baseado em nome de host.
- O OpenClaw não inspeciona, testa nem certifica sua política de proxy.
- Trate alterações na política de proxy como alterações operacionais sensíveis à segurança.

71
docs/pt-BR/tools/loop-detection.md
View File

@ -1,29 +1,29 @@
---
read_when:
- Um usuário relata que os agentes ficam presos repetindo chamadas de ferramenta
- Um usuário relata que agentes ficam presos repetindo chamadas de ferramentas
- Você precisa ajustar a proteção contra chamadas repetitivas
- Você está editando políticas de ferramentas/tempo de execução de agentes
- Você está editando políticas de ferramentas/tempo de execução do agente
summary: Como habilitar e ajustar proteções que detectam loops repetitivos de chamadas de ferramentas
title: Detecção de loop de ferramentas
x-i18n:
generated_at: "2026-05-03T21:39:13Z"
generated_at: "2026-05-05T01:49:53Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw pode evitar que agentes fiquem presos em padrões repetidos de chamadas de ferramenta.
OpenClaw pode impedir que agentes fiquem presos em padrões repetidos de chamadas de ferramentas.
A proteção é **desativada por padrão**.
Ative-a somente onde necessário, porque ela pode bloquear chamadas repetidas legítimas com configurações estritas.
Habilite-a apenas onde necessário, porque ela pode bloquear chamadas repetidas legítimas com configurações rígidas.
## Por que isso existe
- Detectar sequências repetitivas que não fazem progresso.
- Detectar loops de alta frequência sem resultado (mesma ferramenta, mesmas entradas, erros repetidos).
- Detectar padrões específicos de chamadas repetidas para ferramentas conhecidas de sondagem.
- Detectar padrões específicos de chamadas repetidas para ferramentas de polling conhecidas.
## Bloco de configuração
@ -72,43 +72,66 @@ Substituição por agente (opcional):
### Comportamento dos campos
- `enabled`: chave principal. `false` significa que nenhuma detecção de loop é realizada.
- `historySize`: número de chamadas de ferramenta recentes mantidas para análise.
- `historySize`: número de chamadas recentes de ferramentas mantidas para análise.
- `warningThreshold`: limite antes de classificar um padrão apenas como aviso.
- `criticalThreshold`: limite para bloquear padrões de loop repetitivos.
- `globalCircuitBreakerThreshold`: limite global do disjuntor sem progresso.
- `globalCircuitBreakerThreshold`: limite global do disjuntor de ausência de progresso.
- `detectors.genericRepeat`: detecta padrões repetidos de mesma ferramenta + mesmos parâmetros.
- `detectors.knownPollNoProgress`: detecta padrões conhecidos semelhantes a sondagem sem mudança de estado.
- `detectors.pingPong`: detecta padrões alternados de pingue-pongue.
- `detectors.knownPollNoProgress`: detecta padrões conhecidos semelhantes a polling sem alteração de estado.
- `detectors.pingPong`: detecta padrões alternados de ping-pong.
Para `exec`, verificações sem progresso comparam resultados estáveis de comandos e ignoram metadados voláteis de runtime, como duração, PID, ID de sessão e diretório de trabalho.
Quando um ID de execução está disponível, o histórico recente de chamadas de ferramenta é avaliado somente dentro dessa execução, para que ciclos agendados de Heartbeat e execuções novas não herdem contagens de loop obsoletas de execuções anteriores.
Para `exec`, as verificações de ausência de progresso comparam resultados estáveis de comandos e ignoram metadados voláteis de runtime, como duração, PID, ID da sessão e diretório de trabalho.
Quando um ID de execução está disponível, o histórico recente de chamadas de ferramentas é avaliado apenas dentro dessa execução, para que ciclos de Heartbeat agendados e execuções novas não herdem contagens de loop antigas de execuções anteriores.
## Configuração recomendada
- Para modelos menores, comece com `enabled: true`, sem alterar os padrões. Modelos de ponta raramente precisam de detecção de loop e podem deixá-la desativada.
- Para modelos menores, comece com `enabled: true`, mantendo os padrões inalterados. Modelos flagship raramente precisam de detecção de loop e podem deixá-la desativada.
- Mantenha os limites ordenados como `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Se ocorrerem falsos positivos:
- aumente `warningThreshold` e/ou `criticalThreshold`
- (opcionalmente) aumente `globalCircuitBreakerThreshold`
- desative somente o detector que está causando problemas
- reduza `historySize` para um contexto histórico menos estrito
- desative apenas o detector que está causando problemas
- reduza `historySize` para um contexto histórico menos rígido
## Proteção pós-Compaction
Quando o executor conclui uma nova tentativa de Compaction automática (após um estouro de contexto), ele arma uma proteção de janela curta que observa as próximas chamadas de ferramentas. Se o agente emitir a _mesma_ tripla `(toolName, args, result)` várias vezes dentro dessa janela, a proteção conclui que a Compaction não quebrou o loop e aborta a execução com um erro `compaction_loop_persisted`.
Este é um caminho de código separado dos detectores globais de `tools.loopDetection`. Ele é configurável de forma independente:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: número de chamadas de ferramentas pós-Compaction durante as quais a proteção permanece armada _e_ a contagem de triplas idênticas (ferramenta, argumentos, resultado) que aciona um aborto.
A proteção nunca aborta quando os resultados estão mudando, apenas quando os resultados são idênticos byte a byte em toda a janela. Ela é intencionalmente estreita: dispara apenas no momento imediatamente posterior a uma nova tentativa de Compaction.
## Logs e comportamento esperado
Quando um loop é detectado, o OpenClaw relata um evento de loop e bloqueia ou suaviza o próximo ciclo de ferramenta dependendo da severidade.
Isso protege usuários contra gasto descontrolado de tokens e travamentos, preservando o acesso normal às ferramentas.
Quando um loop é detectado, o OpenClaw relata um evento de loop e bloqueia ou atenua o próximo ciclo de ferramentas, dependendo da severidade.
Isso protege os usuários contra gasto descontrolado de tokens e travamentos, preservando o acesso normal às ferramentas.
- Prefira primeiro aviso e supressão temporária.
- Escale somente quando evidências repetidas se acumularem.
- Prefira primeiro avisos e supressão temporária.
- Escale apenas quando evidências repetidas se acumularem.
## Observações
- `tools.loopDetection` é mesclado com substituições em nível de agente.
- A configuração por agente substitui ou estende completamente os valores globais.
- Se não existir configuração, as proteções permanecem desativadas.
- `tools.loopDetection` é mesclado com substituições no nível do agente.
- A configuração por agente substitui ou estende totalmente os valores globais.
- Se nenhuma configuração existir, as proteções permanecem desativadas.
## Relacionado
- [Aprovações de exec](/pt-BR/tools/exec-approvals)
- [Níveis de pensamento](/pt-BR/tools/thinking)
- [Níveis de raciocínio](/pt-BR/tools/thinking)
- [Subagentes](/pt-BR/tools/subagents)

136
docs/pt-BR/tools/media-overview.md
View File

@ -5,114 +5,115 @@ read_when:
- Entendendo como funciona a geração assíncrona de mídia
sidebarTitle: Media overview
summary: Visão geral dos recursos de imagem, vídeo, música, fala e compreensão de mídia
title: Visão geral da mídia
title: Visão geral de mídia
x-i18n:
generated_at: "2026-04-30T10:12:18Z"
generated_at: "2026-05-05T01:50:36Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
O OpenClaw gera imagens, vídeos e música, entende mídia recebida
OpenClaw gera imagens, vídeos e música, entende mídias recebidas
(imagens, áudio, vídeo) e fala respostas em voz alta com conversão de texto em fala. Todos
os recursos de mídia são orientados por ferramentas: o agente decide quando usá-los com base
na conversa, e cada ferramenta só aparece quando pelo menos um provedor de suporte
está configurado.
## Capacidades
## Recursos
<CardGroup cols={2}>
<Card title="Geração de imagens" href="/pt-BR/tools/image-generation" icon="image">
Crie e edite imagens a partir de prompts de texto ou imagens de referência via
`image_generate`. Síncrono — conclui em linha com a resposta.
</Card>
<Card title="Geração de vídeos" href="/pt-BR/tools/video-generation" icon="video">
<Card title="Geração de vídeo" href="/pt-BR/tools/video-generation" icon="video">
Texto para vídeo, imagem para vídeo e vídeo para vídeo via `video_generate`.
Assíncrono — executa em segundo plano e publica o resultado quando estiver pronto.
</Card>
<Card title="Geração de música" href="/pt-BR/tools/music-generation" icon="music">
Gere música ou faixas de áudio via `music_generate`. Assíncrono em provedores
compartilhados; o caminho de workflow do ComfyUI executa de forma síncrona.
Gere músicas ou faixas de áudio via `music_generate`. Assíncrono em provedores
compartilhados; o caminho de fluxo de trabalho do ComfyUI é executado de forma síncrona.
</Card>
<Card title="Texto para fala" href="/pt-BR/tools/tts" icon="microphone">
Converta respostas enviadas em áudio falado via a ferramenta `tts` mais a
Converta respostas de saída em áudio falado via a ferramenta `tts` mais a
configuração `messages.tts`. Síncrono.
</Card>
<Card title="Compreensão de mídia" href="/pt-BR/nodes/media-understanding" icon="eye">
Resuma imagens, áudio e vídeo recebidos usando provedores de modelo com visão
e plugins dedicados de compreensão de mídia.
Resuma imagens, áudio e vídeo recebidos usando provedores de modelo
com capacidade de visão e plugins dedicados de compreensão de mídia.
</Card>
<Card title="Fala para texto" href="/pt-BR/nodes/audio" icon="ear-listen">
Transcreva mensagens de voz recebidas por meio de STT em lote ou provedores de
STT de streaming do Voice Call.
Transcreva mensagens de voz recebidas por meio de provedores de STT em lote ou
STT de streaming para Voice Call.
</Card>
</CardGroup>
## Matriz de capacidades por provedor
## Matriz de recursos por provedor
| Provedor | Imagem | Vídeo | Música | TTS | STT | Voz em tempo real | Compreensão de mídia |
| ----------- | :----: | :---: | :----: | :-: | :-: | :---------------: | :------------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
| ----------- | :----: | :---: | :-----: | :-: | :-: | :---------------: | :------------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| CLI local | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
A compreensão de mídia usa qualquer modelo com visão ou compatível com áudio registrado
A compreensão de mídia usa qualquer modelo com capacidade de visão ou áudio registrado
na sua configuração de provedor. A matriz acima lista provedores com suporte dedicado
a compreensão de mídia; a maioria dos provedores de LLM multimodal (Anthropic, Google,
OpenAI etc.) também consegue entender mídia recebida quando configurada como o modelo de
resposta ativo.
OpenAI etc.) também consegue entender mídia recebida quando configurada como o modelo
ativo de resposta.
</Note>
## Assíncrono versus síncrono
## Assíncrono vs. síncrono
| Capacidade | Modo | Motivo |
| ---------------- | ----------- | ----------------------------------------------------------------- |
| Recurso | Modo | Por quê |
| ---------------- | ----------- | ------------------------------------------------------------------ |
| Imagem | Síncrono | As respostas do provedor retornam em segundos; conclui em linha com a resposta. |
| Texto para fala | Síncrono | As respostas do provedor retornam em segundos; anexadas ao áudio da resposta. |
| Vídeo | Assíncrono | O processamento do provedor leva de 30 s a vários minutos. |
| Música (compartilhada) | Assíncrono | A mesma característica de processamento do provedor que vídeo. |
| Música (ComfyUI) | Síncrono | O workflow local executa em linha no servidor ComfyUI configurado. |
| Vídeo | Assíncrono | O processamento do provedor leva de 30 s a vários minutos. |
| Música (compartilhado) | Assíncrono | Mesma característica de processamento do provedor que vídeo. |
| Música (ComfyUI) | Síncrono | O fluxo de trabalho local é executado em linha contra o servidor ComfyUI configurado. |
Para ferramentas assíncronas, o OpenClaw envia a solicitação ao provedor, retorna um id de tarefa
imediatamente e rastreia o trabalho no livro-razão de tarefas. O agente continua
respondendo a outras mensagens enquanto o trabalho executa. Quando o provedor termina,
o OpenClaw acorda o agente para que ele possa publicar a mídia concluída de volta no
canal original.
imediatamente e acompanha o trabalho no livro-razão de tarefas. O agente continua
respondendo a outras mensagens enquanto o trabalho é executado. Quando o provedor termina,
o OpenClaw desperta o agente com os caminhos de mídia gerados para que ele possa avisar o
usuário e, quando exigido pela política de entrega da origem, retransmitir o resultado por meio
da ferramenta de mensagem.
## Fala para texto e Voice Call
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio e xAI podem transcrever
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio e xAI conseguem transcrever
áudio recebido pelo caminho em lote `tools.media.audio` quando configurados.
Plugins de canal que fazem preflight de uma nota de voz para filtragem por menção ou análise
de comando marcam o anexo transcrito no contexto de entrada, para que a etapa compartilhada
de compreensão de mídia reutilize essa transcrição em vez de fazer uma segunda chamada
STT para o mesmo áudio.
Plugins de canal que fazem uma pré-verificação de uma nota de voz para gating de menção ou análise
de comandos marcam o anexo transcrito no contexto recebido, então a etapa compartilhada
de compreensão de mídia reutiliza essa transcrição em vez de fazer uma segunda
chamada STT para o mesmo áudio.
Deepgram, ElevenLabs, Mistral, OpenAI e xAI também registram provedores de STT de
streaming do Voice Call, para que áudio telefônico ao vivo possa ser encaminhado ao fornecedor
selecionado sem esperar por uma gravação concluída.
Deepgram, ElevenLabs, Mistral, OpenAI e xAI também registram provedores de STT de streaming
para Voice Call, para que áudio telefônico ao vivo possa ser encaminhado ao fornecedor selecionado
sem esperar por uma gravação concluída.
## Mapeamentos de provedores (como os fornecedores se dividem entre superfícies)
@ -122,27 +123,28 @@ selecionado sem esperar por uma gravação concluída.
compreensão de mídia.
</Accordion>
<Accordion title="OpenAI">
Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT de streaming do Voice Call,
voz em tempo real de backend e embeddings de memória.
Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT de streaming para Voice Call, voz em tempo real de backend
e embeddings de memória.
</Accordion>
<Accordion title="DeepInfra">
Superfícies de chat/roteamento de modelo, geração/edição de imagens, texto para vídeo,
TTS em lote, STT em lote, compreensão de mídia de imagem e embeddings de memória.
Roteamento de chat/modelo, geração/edição de imagens, texto para vídeo, TTS em lote,
STT em lote, compreensão de mídia de imagem e superfícies de embeddings de memória.
Modelos nativos da DeepInfra de rerank/classificação/detecção de objetos não são
registrados até que o OpenClaw tenha contratos de provedor dedicados para essas
categorias.
</Accordion>
<Accordion title="xAI">
Imagem, vídeo, pesquisa, execução de código, TTS em lote, STT em lote e STT de streaming do Voice
Call. Voz em tempo real da xAI é uma capacidade upstream, mas não é registrada no OpenClaw até
que o contrato compartilhado de voz em tempo real possa representá-la.
Imagem, vídeo, busca, execução de código, TTS em lote, STT em lote e STT de streaming para Voice
Call. A voz em tempo real da xAI é um recurso upstream, mas não é
registrada no OpenClaw até que o contrato compartilhado de voz em tempo real consiga
representá-la.
</Accordion>
</AccordionGroup>
## Relacionado
## Relacionados
- [Geração de imagens](/pt-BR/tools/image-generation)
- [Geração de vídeos](/pt-BR/tools/video-generation)
- [Geração de vídeo](/pt-BR/tools/video-generation)
- [Geração de música](/pt-BR/tools/music-generation)
- [Texto para fala](/pt-BR/tools/tts)
- [Compreensão de mídia](/pt-BR/nodes/media-understanding)

174
docs/pt-BR/tools/music-generation.md
View File

@ -4,43 +4,44 @@ read_when:
- Configuração de provedores e modelos de geração de música
- Entendendo os parâmetros da ferramenta music_generate
sidebarTitle: Music generation
summary: Gere música por meio de music_generate em fluxos de trabalho do Google Lyria, MiniMax e ComfyUI
summary: Gere música com music_generate em fluxos de trabalho do Google Lyria, MiniMax e ComfyUI
title: Geração de música
x-i18n:
generated_at: "2026-05-02T21:06:00Z"
generated_at: "2026-05-05T01:50:41Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
A ferramenta `music_generate` permite que o agente crie música ou áudio por meio da
capacidade compartilhada de geração de música com provedores configurados — Google,
MiniMax e ComfyUI configurado por workflow atualmente.
MiniMax e ComfyUI configurado por fluxo de trabalho atualmente.
Para execuções de agente com suporte de sessão, o OpenClaw inicia a geração de música como uma
tarefa em segundo plano, a rastreia no livro-razão de tarefas e depois desperta o agente novamente
quando a faixa está pronta, para que o agente possa publicar o áudio finalizado de volta no
canal original.
Para execuções de agente com sessão, o OpenClaw inicia a geração de música como uma
tarefa em segundo plano, rastreia-a no registro de tarefas e então desperta o agente novamente
quando a faixa estiver pronta, para que o agente possa avisar o usuário e anexar o
áudio finalizado. Em chats de grupo/canal que usam entrega visível apenas por ferramenta
de mensagem, o agente retransmite o resultado pela ferramenta de mensagem.
<Note>
A ferramenta compartilhada integrada só aparece quando pelo menos um provedor de geração de música
está disponível. Se você não vir `music_generate` nas ferramentas do seu agente,
configure `agents.defaults.musicGenerationModel` ou configure uma chave de API de
provedor.
configure `agents.defaults.musicGenerationModel` ou configure uma
chave de API de provedor.
</Note>
## Início rápido
<Tabs>
<Tab title="Shared provider-backed">
<Tab title="Com provedor compartilhado">
<Steps>
<Step title="Configure auth">
<Step title="Configure a autenticação">
Defina uma chave de API para pelo menos um provedor — por exemplo
`GEMINI_API_KEY` ou `MINIMAX_API_KEY`.
</Step>
<Step title="Pick a default model (optional)">
<Step title="Escolha um modelo padrão (opcional)">
```json5
{
agents: {
@ -53,30 +54,30 @@ provedor.
}
```
</Step>
<Step title="Ask the agent">
_"Generate an upbeat synthpop track about a night drive through a
neon city."_
<Step title="Peça ao agente">
_"Gere uma faixa synthpop animada sobre um passeio noturno de carro por uma
cidade neon."_
O agente chama `music_generate` automaticamente. Nenhuma lista de
permissão de ferramentas é necessária.
O agente chama `music_generate` automaticamente. Não é necessário
colocar a ferramenta em uma lista de permissões.
</Step>
</Steps>
Para contextos síncronos diretos sem uma execução de agente com suporte de sessão,
Para contextos síncronos diretos sem uma execução de agente com sessão,
a ferramenta integrada ainda recorre à geração inline e retorna
o caminho da mídia final no resultado da ferramenta.
o caminho final da mídia no resultado da ferramenta.
</Tab>
<Tab title="ComfyUI workflow">
<Tab title="Fluxo de trabalho ComfyUI">
<Steps>
<Step title="Configure the workflow">
Configure `plugins.entries.comfy.config.music` com um workflow
<Step title="Configure o fluxo de trabalho">
Configure `plugins.entries.comfy.config.music` com um fluxo de trabalho
JSON e nós de prompt/saída.
</Step>
<Step title="Cloud auth (optional)">
Para o Comfy Cloud, defina `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`.
<Step title="Autenticação na nuvem (opcional)">
Para Comfy Cloud, defina `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY`.
</Step>
<Step title="Call the tool">
<Step title="Chame a ferramenta">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -97,18 +98,18 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## Provedores compatíveis
| Provedor | Modelo padrão | Entradas de referência | Controles compatíveis | Autenticação |
| -------- | ---------------------- | ---------------------- | -------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Até 1 imagem | Música ou áudio definido pelo workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Até 10 imagens | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Nenhuma | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` ou OAuth do MiniMax |
| Provedor | Modelo padrão | Entradas de referência | Controles compatíveis | Autenticação |
| -------- | ---------------------- | ---------------------- | ---------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Até 1 imagem | Música ou áudio definido pelo fluxo de trabalho | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Até 10 imagens | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Nenhuma | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` ou OAuth do MiniMax |
### Matriz de capacidades
O contrato de modo explícito usado por `music_generate`, testes de contrato e pela
varredura ao vivo compartilhada:
O contrato de modo explícito usado por `music_generate`, testes de contrato e a
varredura live compartilhada:
| Provedor | `generate` | `edit` | Limite de edição | Faixas ao vivo compartilhadas |
| Provedor | `generate` | `edit` | Limite de edição | Lanes live compartilhadas |
| -------- | :--------: | :----: | ---------------- | --------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 imagem | Não está na varredura compartilhada; coberto por `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 imagens | `generate`, `edit` |
@ -121,7 +122,7 @@ tempo de execução:
/tool music_generate action=list
```
Use `action: "status"` para inspecionar a tarefa de música ativa com suporte de sessão:
Use `action: "status"` para inspecionar a tarefa de música ativa com sessão:
```text
/tool music_generate action=status
@ -146,10 +147,10 @@ Exemplo de geração direta:
`comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
Letras opcionais quando o provedor dá suporte a entrada explícita de letra.
Letras opcionais quando o provedor oferece suporte a entrada explícita de letras.
</ParamField>
<ParamField path="instrumental" type="boolean">
Solicita saída apenas instrumental quando o provedor dá suporte a isso.
Solicita saída apenas instrumental quando o provedor oferece suporte.
</ParamField>
<ParamField path="image" type="string">
Caminho ou URL de uma única imagem de referência.
@ -158,53 +159,53 @@ Exemplo de geração direta:
Várias imagens de referência (até 10 em provedores compatíveis).
</ParamField>
<ParamField path="durationSeconds" type="number">
Duração-alvo em segundos quando o provedor dá suporte a dicas de duração.
Duração-alvo em segundos quando o provedor oferece suporte a dicas de duração.
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
Dica de formato de saída quando o provedor dá suporte a isso.
Dica de formato de saída quando o provedor oferece suporte.
</ParamField>
<ParamField path="filename" type="string">Dica de nome de arquivo de saída.</ParamField>
<ParamField path="timeoutMs" type="number">Tempo limite opcional de solicitação ao provedor em milissegundos. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta.</ParamField>
<ParamField path="timeoutMs" type="number">Timeout opcional da requisição ao provedor em milissegundos. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta.</ParamField>
<Note>
Nem todos os provedores dão suporte a todos os parâmetros. O OpenClaw ainda valida limites
rígidos, como contagens de entrada, antes do envio. Quando um provedor dá suporte a
Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw ainda valida limites
rígidos, como contagens de entrada, antes do envio. Quando um provedor oferece suporte a
duração, mas usa um máximo menor que o valor solicitado, o OpenClaw
limita à duração compatível mais próxima. Dicas opcionais realmente incompatíveis
são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue honrá-las.
limita para a duração compatível mais próxima. Dicas opcionais realmente sem suporte
são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue atendê-las.
Os resultados da ferramenta informam as configurações aplicadas; `details.normalization`
captura qualquer mapeamento de solicitado para aplicado.
</Note>
## Comportamento assíncrono
A geração de música com suporte de sessão é executada como uma tarefa em segundo plano:
A geração de música com sessão é executada como uma tarefa em segundo plano:
- **Tarefa em segundo plano:** `music_generate` cria uma tarefa em segundo plano, retorna uma
resposta de iniciada/tarefa imediatamente e publica a faixa finalizada depois em
resposta iniciada/de tarefa imediatamente e publica a faixa finalizada depois em
uma mensagem de acompanhamento do agente.
- **Prevenção de duplicatas:** enquanto uma tarefa está `queued` ou `running`, chamadas posteriores de
`music_generate` na mesma sessão retornam o status da tarefa em vez de
iniciar outra geração. Use `action: "status"` para verificar explicitamente.
- **Consulta de status:** `openclaw tasks list` ou `openclaw tasks show <taskId>`
inspeciona status em fila, em execução e terminal.
- **Despertar na conclusão:** o OpenClaw injeta um evento interno de conclusão de volta
na mesma sessão para que o modelo possa escrever por conta própria o acompanhamento
inspeciona status em fila, em execução e terminais.
- **Despertar de conclusão:** o OpenClaw injeta um evento interno de conclusão de volta
na mesma sessão para que o modelo possa escrever ele mesmo o acompanhamento
voltado ao usuário.
- **Dica de prompt:** turnos posteriores de usuário/manuais na mesma sessão recebem uma pequena
dica de runtime quando uma tarefa de música já está em andamento, para que o modelo
não chame `music_generate` novamente às cegas.
não chame `music_generate` novamente sem critério.
- **Fallback sem sessão:** contextos diretos/locais sem uma sessão real de agente
executam inline e retornam o resultado final de áudio no mesmo turno.
### Ciclo de vida da tarefa
| Estado | Significado |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | Tarefa criada, aguardando o provedor aceitá-la. |
| `running` | O provedor está processando (normalmente 30 segundos a 3 minutos, dependendo do provedor e da duração). |
| `succeeded` | Faixa pronta; o agente desperta e a publica na conversa. |
| `failed` | Erro ou tempo limite do provedor; o agente desperta com detalhes do erro. |
| Estado | Significado |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `queued` | Tarefa criada, aguardando o provedor aceitá-la. |
| `running` | O provedor está processando (normalmente de 30 segundos a 3 minutos, dependendo do provedor e da duração). |
| `succeeded` | Faixa pronta; o agente desperta e a publica na conversa. |
| `failed` | Erro ou timeout do provedor; o agente desperta com detalhes do erro. |
Verifique o status pela CLI:
@ -238,9 +239,9 @@ O OpenClaw tenta provedores nesta ordem:
1. Parâmetro `model` da chamada da ferramenta (se o agente especificar um).
2. `musicGenerationModel.primary` da configuração.
3. `musicGenerationModel.fallbacks` em ordem.
4. Detecção automática usando apenas padrões de provedor com autenticação:
4. Detecção automática usando apenas padrões de provedores com autenticação:
- provedor padrão atual primeiro;
- provedores restantes de geração de música registrados em ordem de ID de provedor.
- demais provedores registrados de geração de música em ordem de id de provedor.
Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos
falharem, o erro inclui detalhes de cada tentativa.
@ -252,40 +253,40 @@ entradas explícitas de `model`, `primary` e `fallbacks`.
<AccordionGroup>
<Accordion title="ComfyUI">
Orientado por workflow e depende do grafo configurado mais o mapeamento de nós
para campos de prompt/saída. O plugin `comfy` incluído se conecta à
Orientado por fluxo de trabalho e depende do grafo configurado mais o mapeamento de nós
para campos de prompt/saída. O Plugin `comfy` integrado se conecta à
ferramenta compartilhada `music_generate` por meio do registro de provedores de
geração de música.
</Accordion>
<Accordion title="Google (Lyria 3)">
Usa geração em lote do Lyria 3. O fluxo incluído atual oferece suporte a
Usa geração em lote do Lyria 3. O fluxo integrado atual oferece suporte a
prompt, texto opcional de letras e imagens de referência opcionais.
</Accordion>
<Accordion title="MiniMax">
Usa o endpoint em lote `music_generation`. Oferece suporte a prompt, letras
opcionais, modo instrumental, direcionamento de duração e saída mp3 por meio
de autenticação por chave de API `minimax` ou OAuth `minimax-portal`.
opcionais, modo instrumental, direcionamento de duração e saída mp3 por meio de
autenticação por chave de API `minimax` ou OAuth `minimax-portal`.
</Accordion>
</AccordionGroup>
## Escolhendo o caminho certo
- **Com suporte de provedor compartilhado** quando você quer seleção de modelo, failover de
provedor e o fluxo integrado assíncrono de tarefa/status.
- **Caminho de plugin (ComfyUI)** quando você precisa de um grafo de workflow personalizado ou de um
provedor que não faz parte da capacidade musical compartilhada incluída.
- **Com provedor compartilhado** quando você quer seleção de modelo, failover de provedor
e o fluxo assíncrono integrado de tarefa/status.
- **Caminho de Plugin (ComfyUI)** quando você precisa de um grafo de fluxo de trabalho personalizado ou de um
provedor que não faz parte da capacidade compartilhada integrada de música.
Se você estiver depurando comportamento específico do ComfyUI, consulte
[ComfyUI](/pt-BR/providers/comfy). Se você estiver depurando comportamento de provedor
compartilhado, comece com [Google (Gemini)](/pt-BR/providers/google) ou
compartilhado, comece por [Google (Gemini)](/pt-BR/providers/google) ou
[MiniMax](/pt-BR/providers/minimax).
## Modos de capacidade do provedor
O contrato compartilhado de geração de música oferece suporte a declarações explícitas de modo:
- `generate` para geração apenas por prompt.
- `edit` quando a solicitação inclui uma ou mais imagens de referência.
- `generate` para geração somente por prompt.
- `edit` quando a requisição inclui uma ou mais imagens de referência.
Novas implementações de provedor devem preferir blocos de modo explícitos:
@ -306,14 +307,14 @@ capabilities: {
```
Campos planos legados, como `maxInputImages`, `supportsLyrics` e
`supportsFormat`, **não** bastam para anunciar suporte a edição. Provedores
devem declarar `generate` e `edit` explicitamente para que testes ao vivo, testes de contrato
e a ferramenta compartilhada `music_generate` possam validar o suporte a modos
de forma determinística.
`supportsFormat`, **não** são suficientes para anunciar suporte a edição. Provedores
devem declarar `generate` e `edit` explicitamente para que testes live, testes de contrato
e a ferramenta compartilhada `music_generate` possam validar suporte de modo
deterministicamente.
## Testes ao vivo
## Testes live
Cobertura ao vivo opcional para os provedores compartilhados incluídos:
Cobertura live opcional para os provedores compartilhados integrados:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -325,29 +326,30 @@ Wrapper do repositório:
pnpm test:live:media music
```
Este arquivo ao vivo carrega variáveis de ambiente de provedor ausentes de `~/.profile`, prefere
chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa tanto
a cobertura de `generate` quanto a de `edit` declarado quando o provedor habilita o modo
de edição. Cobertura hoje:
Este arquivo live carrega variáveis de ambiente de provedor ausentes de `~/.profile`, prefere
chaves de API live/env antes de perfis de autenticação armazenados por padrão e executa tanto
a cobertura de `generate` quanto a de `edit` declarada quando o provedor habilita o modo
de edição. Cobertura atual:
- `google`: `generate` mais `edit`
- `minimax`: apenas `generate`
- `comfy`: cobertura ao vivo separada do Comfy, não a varredura compartilhada de provedores
- `comfy`: cobertura live separada do Comfy, não a varredura de provedores compartilhados
Cobertura ao vivo opcional para o caminho de música ComfyUI incluído:
Cobertura live opcional para o caminho de música ComfyUI integrado:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
O arquivo live do Comfy também cobre fluxos de trabalho de imagem e vídeo do Comfy quando essas seções estão configuradas.
O arquivo live do Comfy também cobre fluxos de trabalho de imagem e vídeo do Comfy quando essas
seções estão configuradas.
## Relacionados
## Relacionado
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para execuções destacadas de `music_generate`
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para execuções `music_generate` desanexadas
- [ComfyUI](/pt-BR/providers/comfy)
- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults) — configuração `musicGenerationModel`
- [Google (Gemini)](/pt-BR/providers/google)
- [MiniMax](/pt-BR/providers/minimax)
- [Modelos](/pt-BR/concepts/models) — configuração de modelos e tolerância a falhas
- [Modelos](/pt-BR/concepts/models) — configuração de modelos e alternância em caso de falha
- [Visão geral das ferramentas](/pt-BR/tools)

478
docs/pt-BR/tools/plugin.md
View File

@ -1,31 +1,31 @@
---
read_when:
- Instalando ou configurando plugins
- Entendendo a descoberta de Plugins e as regras de carregamento
- Entendendo as regras de descoberta e carregamento de Plugin
- Trabalhando com pacotes de Plugin compatíveis com Codex/Claude
sidebarTitle: Install and Configure
summary: Instale, configure e gerencie os plugins do OpenClaw
summary: Instale, configure e gerencie plugins do OpenClaw
title: Plugins
x-i18n:
generated_at: "2026-05-03T21:39:20Z"
generated_at: "2026-05-05T01:50:56Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
Plugins estendem o OpenClaw com novos recursos: canais, provedores de modelo,
Plugins estendem o OpenClaw com novas capacidades: canais, provedores de modelo,
arneses de agente, ferramentas, Skills, fala, transcrição em tempo real, voz em
tempo real, compreensão de mídia, geração de imagem, geração de vídeo, busca na
web, pesquisa na web e muito mais. Alguns plugins são **core** (incluídos no OpenClaw), outros
tempo real, compreensão de mídia, geração de imagens, geração de vídeo, busca na web,
pesquisa na web e muito mais. Alguns plugins são **core** (incluídos com o OpenClaw), outros
são **externos**. A maioria dos plugins externos é publicada e descoberta por meio do
[ClawHub](/pt-BR/tools/clawhub). O npm continua com suporte para instalações diretas e para um
[ClawHub](/pt-BR/tools/clawhub). O npm continua compatível para instalações diretas e para um
conjunto temporário de pacotes de plugin pertencentes ao OpenClaw enquanto essa migração é concluída.
## Início rápido
Para exemplos de instalação, listagem, desinstalação, atualização e publicação para copiar e colar, consulte
Para exemplos de copiar e colar de instalação, listagem, desinstalação, atualização e publicação, consulte
[Gerenciar plugins](/pt-BR/plugins/manage-plugins).
<Steps>
@ -61,15 +61,15 @@ Para exemplos de instalação, listagem, desinstalação, atualização e public
openclaw gateway restart
```
Em seguida, configure em `plugins.entries.\<id\>.config` no seu arquivo de configuração.
Depois configure em `plugins.entries.\<id\>.config` no seu arquivo de configuração.
</Step>
<Step title="Gerenciamento nativo do chat">
Em um Gateway em execução, `/plugins enable` e `/plugins disable`, exclusivos do proprietário,
Em um Gateway em execução, `/plugins enable` e `/plugins disable` exclusivos do proprietário
acionam o recarregador de configuração do Gateway. O Gateway recarrega as superfícies de runtime
do plugin no processo, e novas rodadas de agente reconstroem sua lista de ferramentas a partir do
registro atualizado. `/plugins install` altera o código-fonte do plugin, portanto o
do plugin no processo, e novas rodadas do agente reconstroem sua lista de ferramentas a partir do
registro atualizado. `/plugins install` altera o código-fonte do plugin, então o
Gateway solicita uma reinicialização em vez de fingir que o processo atual pode
recarregar com segurança módulos já importados.
@ -84,8 +84,8 @@ Para exemplos de instalação, listagem, desinstalação, atualização e public
```
Use `--runtime` quando precisar comprovar ferramentas registradas, serviços, métodos de gateway,
hooks ou comandos de CLI pertencentes ao plugin. `inspect` simples é uma verificação fria
de manifesto/registro e evita intencionalmente importar o runtime do plugin.
hooks ou comandos de CLI pertencentes ao plugin. O `inspect` simples é uma verificação fria de
manifesto/registro e evita intencionalmente importar o runtime do plugin.
</Step>
</Steps>
@ -98,85 +98,85 @@ Se você preferir controle nativo do chat, habilite `commands.plugins: true` e u
/plugin enable <plugin-id>
```
O caminho de instalação usa o mesmo resolvedor da CLI: caminho/arquivo local, `clawhub:<pkg>`
explícito, `npm:<pkg>` explícito, `git:<repo>` explícito ou especificação de pacote simples
por meio do npm.
O caminho de instalação usa o mesmo resolvedor que a CLI: caminho/arquivo local, `clawhub:<pkg>` explícito,
`npm:<pkg>` explícito, `git:<repo>` explícito ou especificação de pacote simples
via npm.
Se a configuração for inválida, a instalação normalmente falha fechada e direciona você para
Se a configuração for inválida, a instalação normalmente falha em modo fechado e direciona você para
`openclaw doctor --fix`. A única exceção de recuperação é um caminho estreito de reinstalação de plugin incluído
para plugins que optam por
`openclaw.install.allowInvalidConfigRecovery`.
Durante a inicialização do Gateway, configuração de plugin inválida falha fechada como qualquer outra configuração inválida.
Execute `openclaw doctor --fix` para colocar em quarentena a configuração incorreta do plugin,
desabilitando essa entrada de plugin e removendo sua carga de configuração inválida; o backup
normal da configuração mantém os valores anteriores.
Quando uma configuração de canal referencia um plugin que não é mais descobrível, mas o
mesmo id de plugin obsoleto permanece na configuração do plugin ou nos registros de instalação, a inicialização do Gateway
Durante a inicialização do Gateway, configuração inválida de plugin falha em modo fechado como qualquer outra configuração inválida.
Execute `openclaw doctor --fix` para colocar em quarentena a configuração incorreta do plugin
desabilitando essa entrada de plugin e removendo sua carga de configuração inválida; o backup normal
da configuração mantém os valores anteriores.
Quando uma configuração de canal referencia um plugin que não é mais detectável, mas o
mesmo id de plugin obsoleto permanece na configuração de plugin ou nos registros de instalação, a inicialização do Gateway
registra avisos e ignora esse canal em vez de bloquear todos os outros canais.
Execute `openclaw doctor --fix` para remover as entradas obsoletas de canal/plugin; chaves de
canal desconhecidas sem evidência de plugin obsoleto ainda falham na validação para que erros de digitação permaneçam
visíveis.
Se `plugins.enabled: false` estiver definido, referências obsoletas a plugins serão tratadas como inertes:
a inicialização do Gateway ignora o trabalho de descoberta/carregamento de plugins e `openclaw doctor` preserva
a configuração desabilitada do plugin em vez de removê-la automaticamente. Reabilite plugins antes de
executar a limpeza do doctor se quiser que ids de plugin obsoletos sejam removidos.
Se `plugins.enabled: false` estiver definido, referências obsoletas de plugin serão tratadas como inertes:
a inicialização do Gateway ignora o trabalho de descoberta/carregamento de plugin e `openclaw doctor` preserva
a configuração de plugin desabilitada em vez de removê-la automaticamente. Reabilite plugins antes de
executar a limpeza do doctor se quiser remover ids de plugin obsoletos.
A instalação de dependências de plugin acontece somente durante fluxos explícitos de instalação/atualização ou
reparo do doctor. A inicialização do Gateway, o recarregamento de configuração e a inspeção de runtime
não executam gerenciadores de pacotes nem reparam árvores de dependências. Plugins locais já devem
A instalação de dependências de plugin acontece apenas durante fluxos explícitos de instalação/atualização ou
reparo do doctor. Inicialização do Gateway, recarregamento de configuração e inspeção de runtime não
executam gerenciadores de pacote nem reparam árvores de dependências. Plugins locais já devem
ter suas dependências instaladas, enquanto plugins npm, git e ClawHub são
instalados nas raízes de plugins gerenciadas pelo OpenClaw. Dependências npm podem ser içadas
dentro da raiz npm gerenciada do OpenClaw; instalação/atualização verifica essa raiz gerenciada antes da
confiança, e a desinstalação remove pacotes gerenciados por npm por meio do npm. Plugins externos
instalados nas raízes de plugin gerenciadas pelo OpenClaw. Dependências npm podem ser içadas
dentro da raiz npm gerenciada pelo OpenClaw; install/update verifica essa raiz gerenciada antes
da confiança, e uninstall remove pacotes gerenciados por npm por meio do npm. Plugins externos
e caminhos de carregamento personalizados ainda devem ser instalados por meio de `openclaw plugins install`.
Use `openclaw plugins list --json` para ver o `dependencyStatus` estático de cada
plugin visível sem importar código de runtime nem reparar dependências.
Consulte [Resolução de dependências de Plugin](/pt-BR/plugins/dependency-resolution) para o
ciclo de vida em tempo de instalação.
ciclo de vida no momento da instalação.
Para instalações npm, seletores mutáveis como `latest` ou uma dist-tag são resolvidos
antes da instalação e então fixados na versão exata verificada na raiz npm
gerenciada do OpenClaw. Depois que o npm termina, o OpenClaw verifica se a entrada
`package-lock.json` instalada ainda corresponde à versão e à integridade resolvidas. Se
o npm gravar metadados de pacote diferentes, a instalação falhará e o pacote gerenciado
será revertido em vez de aceitar um artefato de plugin diferente.
gerenciada pelo OpenClaw. Depois que o npm termina, o OpenClaw verifica se a entrada instalada de
`package-lock.json` ainda corresponde à versão resolvida e à integridade. Se
o npm gravar metadados de pacote diferentes, a instalação falha e o pacote gerenciado
é revertido em vez de aceitar um artefato de plugin diferente.
Checkouts de código-fonte são workspaces pnpm. Se você clonar o OpenClaw para trabalhar em plugins incluídos,
execute `pnpm install`; então o OpenClaw carrega plugins incluídos de
`extensions/<id>` para que edições e dependências locais do pacote sejam usadas diretamente.
Instalações simples na raiz via npm são para o OpenClaw empacotado, não para desenvolvimento
em checkout de código-fonte.
Checkouts de código-fonte são workspaces pnpm. Se você clonar o OpenClaw para trabalhar em plugins
incluídos, execute `pnpm install`; então o OpenClaw carrega plugins incluídos a partir de
`extensions/<id>` para que edições e dependências locais ao pacote sejam usadas diretamente.
Instalações npm simples na raiz são para OpenClaw empacotado, não para desenvolvimento em checkout
de código-fonte.
## Tipos de Plugin
O OpenClaw reconhece dois formatos de plugin:
| Formato | Como funciona | Exemplos |
| Formato | Como funciona | Exemplos |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade |
| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade |
| **Pacote** | Layout compatível com Codex/Claude/Cursor; mapeado para recursos do OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Ambos aparecem em `openclaw plugins list`. Consulte [Pacotes de Plugin](/pt-BR/plugins/bundles) para detalhes sobre pacotes.
Ambos aparecem em `openclaw plugins list`. Consulte [Pacotes de Plugin](/pt-BR/plugins/bundles) para detalhes de pacote.
Se você estiver escrevendo um plugin nativo, comece com [Criar Plugins](/pt-BR/plugins/building-plugins)
Se você está escrevendo um plugin nativo, comece com [Criação de Plugins](/pt-BR/plugins/building-plugins)
e a [Visão geral do SDK de Plugin](/pt-BR/plugins/sdk-overview).
## Pontos de entrada de pacote
Pacotes npm de plugin nativo devem declarar `openclaw.extensions` em `package.json`.
Cada entrada deve permanecer dentro do diretório do pacote e resolver para um arquivo de
runtime legível, ou para um arquivo-fonte TypeScript com um par JavaScript compilado inferido,
runtime legível, ou para um arquivo de origem TypeScript com um par JavaScript compilado inferido,
como `src/index.ts` para `dist/index.js`.
Instalações empacotadas devem incluir essa saída de runtime JavaScript. O fallback de
código-fonte TypeScript é para checkouts de código-fonte e caminhos de desenvolvimento local, não para
pacotes npm instalados na raiz de plugins gerenciada do OpenClaw.
Instalações empacotadas devem incluir essa saída JavaScript de runtime. O fallback de
origem TypeScript é para checkouts de código-fonte e caminhos de desenvolvimento local, não para
pacotes npm instalados na raiz de plugin gerenciada pelo OpenClaw.
Use `openclaw.runtimeExtensions` quando os arquivos de runtime publicados não estiverem nos
mesmos caminhos das entradas de código-fonte. Quando presente, `runtimeExtensions` deve conter
Use `openclaw.runtimeExtensions` quando arquivos de runtime publicados não estiverem nos
mesmos caminhos das entradas de origem. Quando presente, `runtimeExtensions` deve conter
exatamente uma entrada para cada entrada de `extensions`. Listas incompatíveis fazem a instalação e
a descoberta de plugins falharem em vez de voltar silenciosamente para caminhos de código-fonte. Se você também
publicar `openclaw.setupEntry`, use `openclaw.runtimeSetupEntry` para seu par
JavaScript compilado; esse arquivo é obrigatório quando declarado.
a descoberta de plugin falharem em vez de recorrer silenciosamente aos caminhos de origem. Se você também
publicar `openclaw.setupEntry`, use `openclaw.runtimeSetupEntry` para seu par JavaScript
compilado; esse arquivo é obrigatório quando declarado.
```json
{
@ -192,17 +192,17 @@ JavaScript compilado; esse arquivo é obrigatório quando declarado.
### Pacotes npm pertencentes ao OpenClaw durante a migração
ClawHub é o caminho principal de distribuição para a maioria dos plugins. Versões empacotadas atuais
do OpenClaw já incluem muitos plugins oficiais, portanto eles não precisam de
ClawHub é o caminho principal de distribuição para a maioria dos plugins. As versões empacotadas
atuais do OpenClaw já incluem muitos plugins oficiais, então eles não precisam de
instalações npm separadas em configurações normais. Até que todos os plugins pertencentes ao OpenClaw
tenham migrado para o ClawHub, o OpenClaw ainda distribui alguns pacotes de plugin `@openclaw/*` no
tenham migrado para o ClawHub, o OpenClaw ainda publica alguns pacotes de plugin `@openclaw/*` no
npm para instalações mais antigas/personalizadas e fluxos de trabalho npm diretos.
Se o npm relatar um pacote de plugin `@openclaw/*` como descontinuado, essa versão do pacote
vem de uma linha mais antiga de pacotes externos. Use o plugin incluído do
Se o npm relatar um pacote de plugin `@openclaw/*` como obsoleto, essa versão do pacote
vem de uma linha antiga de pacotes externos. Use o plugin incluído do
OpenClaw atual ou um checkout local até que um pacote npm mais novo seja publicado.
| Plugin | Pacote | Documentação |
| Plugin | Pacote | Documentação |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/pt-BR/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/pt-BR/channels/discord) |
@ -218,7 +218,7 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public
| Zalo | `@openclaw/zalo` | [Zalo](/pt-BR/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/pt-BR/plugins/zalouser) |
### Core (incluído no OpenClaw)
### Core (incluídos com o OpenClaw)
<AccordionGroup>
<Accordion title="Provedores de modelo (habilitados por padrão)">
@ -230,11 +230,11 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public
</Accordion>
<Accordion title="Plugins de memória">
- `memory-core` — busca de memória incluída (padrão via `plugins.slots.memory`)
- `memory-lancedb` — memória de longo prazo baseada em LanceDB com recuperação/captura automática (defina `plugins.slots.memory = "memory-lancedb"`)
- `memory-core` — pesquisa de memória incluída (padrão via `plugins.slots.memory`)
- `memory-lancedb` — memória de longo prazo baseada em LanceDB com rechamada/captura automática (defina `plugins.slots.memory = "memory-lancedb"`)
Consulte [Memory LanceDB](/pt-BR/plugins/memory-lancedb) para configuração de
embeddings compatíveis com OpenAI, exemplos do Ollama, limites de recuperação e solução de problemas.
embeddings compatível com OpenAI, exemplos de Ollama, limites de rechamada e solução de problemas.
</Accordion>
@ -243,7 +243,7 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public
</Accordion>
<Accordion title="Outros">
- `browser` — plugin de navegador incluído para a ferramenta de navegador, CLI `openclaw browser`, método de gateway `browser.request`, runtime de navegador e serviço padrão de controle de navegador (habilitado por padrão; desabilite antes de substituí-lo)
- `browser` — plugin de navegador incluído para a ferramenta de navegador, CLI `openclaw browser`, método de gateway `browser.request`, runtime de navegador e serviço padrão de controle do navegador (habilitado por padrão; desabilite antes de substituí-lo)
- `copilot-proxy` — ponte do VS Code Copilot Proxy (desabilitada por padrão)
</Accordion>
@ -267,39 +267,47 @@ Procurando plugins de terceiros? Consulte [Plugins da comunidade](/pt-BR/plugins
}
```
| Campo | Descrição |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Alternância principal (padrão: `true`) |
| `allow` | Lista de permissões de Plugin (opcional) |
| `deny` | Lista de bloqueio de Plugin (opcional; bloqueio vence) |
| `load.paths` | Arquivos/diretórios extras de plugin |
| `slots` | Seletores de slot exclusivos (por exemplo, `memory`, `contextEngine`) |
| `entries.\<id\>` | Alternâncias + configuração por plugin |
| Campo | Descrição |
| ------------------ | --------------------------------------------------------- |
| `enabled` | Alternância principal (padrão: `true`) |
| `allow` | Allowlist de plugins (opcional) |
| `bundledDiscovery` | Modo de descoberta de plugins empacotados (`allowlist` por padrão) |
| `deny` | Denylist de plugins (opcional; deny vence) |
| `load.paths` | Arquivos/diretórios extras de plugins |
| `slots` | Seletores de slots exclusivos (ex.: `memory`, `contextEngine`) |
| `entries.\<id\>` | Alternâncias + configuração por plugin |
`plugins.allow` é exclusivo. Quando não está vazio, somente os plugins listados podem carregar
ou expor ferramentas, mesmo que `tools.allow` contenha `"*"` ou um nome específico de ferramenta
pertencente a um plugin. Se uma lista de permissões de ferramentas referenciar ferramentas de plugin, adicione os ids dos plugins proprietários
a `plugins.allow` ou remova `plugins.allow`; `openclaw doctor` alerta sobre esse
ou expor ferramentas, mesmo que `tools.allow` contenha `"*"` ou o nome específico
de uma ferramenta pertencente a um plugin. Se uma allowlist de ferramentas referenciar ferramentas de plugin, adicione os ids dos plugins proprietários
a `plugins.allow` ou remova `plugins.allow`; `openclaw doctor` avisa sobre esse
formato.
Alterações de configuração feitas por meio de `/plugins enable` ou `/plugins disable` acionam um
recarregamento de plugin do Gateway no processo. Novos turnos de agente reconstroem sua lista de ferramentas a partir
do registro de plugins atualizado. Operações que alteram a origem, como instalar,
atualizar e desinstalar, ainda reiniciam o processo do Gateway porque módulos de plugin já importados
não podem ser substituídos com segurança no local.
`plugins.bundledDiscovery` usa `"allowlist"` como padrão para novas configurações, então um
inventário restritivo em `plugins.allow` também bloqueia plugins provedores empacotados
omitidos, incluindo a descoberta em runtime de provedores de pesquisa na web. O Doctor marca configurações antigas
de allowlist restritiva com `"compat"` durante a migração para que upgrades mantenham
o comportamento legado de provedores empacotados até que o operador opte pelo modo mais rigoroso.
Um `plugins.allow` vazio ainda é tratado como não definido/aberto.
Alterações de configuração feitas por `/plugins enable` ou `/plugins disable` acionam um
recarregamento de plugins do Gateway dentro do processo. Novos turnos de agente recompõem sua lista de ferramentas a partir
do registro de plugins atualizado. Operações que alteram a fonte, como instalar,
atualizar e desinstalar, ainda reiniciam o processo do Gateway porque módulos de
plugin já importados não podem ser substituídos com segurança no lugar.
`openclaw plugins list` é um snapshot local do registro/configuração de plugins. Um plugin
`enabled` ali significa que o registro persistido e a configuração atual permitem que o
plugin participe. Isso não prova que um Gateway remoto já em execução
tenha recarregado ou reiniciado com o mesmo código de plugin. Em configurações de VPS/contêiner
com processos wrapper, envie reinicializações ou escritas que acionam recarregamento para o processo real
plugin participe. Isso não prova que um Gateway remoto já em execução tenha recarregado
ou reiniciado para o mesmo código de plugin. Em configurações VPS/contêiner
com processos wrapper, envie reinícios ou gravações que acionem recarregamento ao processo real
`openclaw gateway run`, ou use `openclaw gateway restart` contra o
Gateway em execução quando o recarregamento relatar uma falha.
Gateway em execução quando o recarregamento reportar uma falha.
<Accordion title="Estados do Plugin: desativado vs ausente vs inválido">
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **Desativado**: o plugin existe, mas as regras de ativação o desligaram. A configuração é preservada.
- **Ausente**: a configuração referencia um id de plugin que a descoberta não encontrou.
- **Inválido**: o plugin existe, mas sua configuração não corresponde ao esquema declarado. A inicialização do Gateway ignora somente esse plugin; `openclaw doctor --fix` pode colocar a entrada inválida em quarentena desativando-a e removendo sua carga útil de configuração.
- **Inválido**: o plugin existe, mas sua configuração não corresponde ao esquema declarado. A inicialização do Gateway ignora apenas esse plugin; `openclaw doctor --fix` pode colocar a entrada inválida em quarentena, desativando-a e removendo seu payload de configuração.
</Accordion>
@ -308,79 +316,79 @@ Gateway em execução quando o recarregamento relatar uma falha.
O OpenClaw procura plugins nesta ordem (a primeira correspondência vence):
<Steps>
<Step title="Caminhos de configuração">
<Step title="Config paths">
`plugins.load.paths` — caminhos explícitos de arquivo ou diretório. Caminhos que apontam
de volta para os próprios diretórios de plugins agrupados empacotados do OpenClaw são ignorados;
de volta para os próprios diretórios de plugins empacotados do OpenClaw são ignorados;
execute `openclaw doctor --fix` para remover esses aliases obsoletos.
</Step>
<Step title="Plugins do workspace">
<Step title="Workspace plugins">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` e `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugins globais">
<Step title="Global plugins">
`~/.openclaw/<plugin-root>/*.ts` e `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugins agrupados">
<Step title="Bundled plugins">
Distribuídos com o OpenClaw. Muitos são ativados por padrão (provedores de modelo, fala).
Outros exigem ativação explícita.
</Step>
</Steps>
Instalações empacotadas e imagens Docker normalmente resolvem plugins agrupados a partir da
árvore compilada `dist/extensions`. Se um diretório de origem de plugin agrupado for
montado por bind sobre o caminho de origem empacotado correspondente, por exemplo
`/app/extensions/synology-chat`, o OpenClaw trata esse diretório de origem montado
como uma sobreposição de origem agrupada e o descobre antes do pacote
`/app/dist/extensions/synology-chat` empacotado. Isso mantém os loops de contêiner de mantenedores
funcionando sem mudar todos os plugins agrupados de volta para a origem TypeScript.
Instalações empacotadas e imagens Docker normalmente resolvem plugins empacotados a partir da
árvore compilada `dist/extensions`. Se um diretório-fonte de plugin empacotado for
montado por bind sobre o caminho-fonte empacotado correspondente, por exemplo
`/app/extensions/synology-chat`, o OpenClaw trata esse diretório-fonte montado
como uma sobreposição de fonte empacotada e o descobre antes do pacote
`/app/dist/extensions/synology-chat`. Isso mantém loops de contêiner de mantenedores
funcionando sem alternar todos os plugins empacotados de volta para código-fonte TypeScript.
Defina `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` para forçar pacotes dist empacotados
mesmo quando montagens de sobreposição de origem estiverem presentes.
mesmo quando montagens de sobreposição de fonte estiverem presentes.
### Regras de ativação
- `plugins.enabled: false` desativa todos os plugins e ignora o trabalho de descoberta/carregamento de plugins
- `plugins.deny` sempre vence sobre allow
- `plugins.enabled: false` desativa todos os plugins e pula o trabalho de descoberta/carregamento de plugins
- `plugins.deny` sempre vence allow
- `plugins.entries.\<id\>.enabled: false` desativa esse plugin
- Plugins originados do workspace são **desativados por padrão** (devem ser ativados explicitamente)
- Plugins agrupados seguem o conjunto integrado ativado por padrão, salvo substituição
- Plugins originados no workspace são **desativados por padrão** (devem ser ativados explicitamente)
- Plugins empacotados seguem o conjunto embutido ativado por padrão, a menos que sejam sobrescritos
- Slots exclusivos podem forçar a ativação do plugin selecionado para esse slot
- Alguns plugins agrupados opt-in são ativados automaticamente quando a configuração nomeia uma
superfície pertencente ao plugin, como uma referência de modelo de provedor, configuração de canal ou runtime
- Alguns plugins empacotados opt-in são ativados automaticamente quando a configuração nomeia uma
superfície pertencente ao plugin, como uma ref de modelo de provedor, configuração de canal ou runtime
de harness
- Configuração obsoleta de plugin é preservada enquanto `plugins.enabled: false` está ativo;
reative os plugins antes de executar a limpeza do doctor se quiser que ids obsoletos sejam removidos
reative os plugins antes de executar a limpeza do doctor se quiser remover ids obsoletos
- Rotas Codex da família OpenAI mantêm limites de plugin separados:
`openai-codex/*` pertence ao plugin OpenAI, enquanto o plugin agrupado do servidor de app Codex
é selecionado por `agentRuntime.id: "codex"` ou referências legadas de modelo
`openai-codex/*` pertence ao plugin OpenAI, enquanto o plugin empacotado de
app-server do Codex é selecionado por `agentRuntime.id: "codex"` ou refs de modelo legadas
`codex/*`
## Solução de problemas de hooks de runtime
## Solução de problemas de hooks em runtime
Se um plugin aparece em `plugins list`, mas efeitos colaterais ou hooks de `register(api)`
não são executados em tráfego de chat ao vivo, verifique isto primeiro:
Se um plugin aparecer em `plugins list`, mas efeitos colaterais ou hooks de `register(api)`
não forem executados no tráfego de chat ao vivo, verifique estes pontos primeiro:
- Execute `openclaw gateway status --deep --require-rpc` e confirme se a URL ativa do
Gateway, o perfil, o caminho da configuração e o processo são os que você está editando.
- Reinicie o Gateway ao vivo após alterações de instalação/configuração/código do plugin. Em contêineres
- Execute `openclaw gateway status --deep --require-rpc` e confirme que a URL, o perfil,
o caminho de configuração e o processo do Gateway ativo são os que você está editando.
- Reinicie o Gateway ao vivo após alterações de instalação/configuração/código de plugins. Em contêineres
wrapper, o PID 1 pode ser apenas um supervisor; reinicie ou sinalize o processo filho
`openclaw gateway run`.
- Use `openclaw plugins inspect <id> --runtime --json` para confirmar registros de hooks e
diagnósticos. Hooks de conversa não agrupados, como `llm_input`,
diagnósticos. Hooks de conversa não empacotados, como `llm_input`,
`llm_output`, `before_agent_finalize` e `agent_end`, precisam de
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Para troca de modelo, prefira `before_model_resolve`. Ele é executado antes da resolução de modelo
para turnos de agente; `llm_output` só é executado depois que uma tentativa de modelo
- Para troca de modelo, prefira `before_model_resolve`. Ele é executado antes da resolução
de modelo para turnos de agente; `llm_output` só é executado depois que uma tentativa de modelo
produz saída do assistente.
- Para prova do modelo efetivo da sessão, use `openclaw sessions` ou as superfícies
de sessão/status do Gateway e, ao depurar payloads de provedor, inicie
- Para prova do modelo efetivo da sessão, use `openclaw sessions` ou as superfícies de
sessão/status do Gateway e, ao depurar payloads de provedores, inicie
o Gateway com `--raw-stream --raw-stream-path <path>`.
### Configuração lenta de ferramentas de plugin
Se turnos de agente parecem travar durante a preparação de ferramentas, ative logs de rastreamento e
verifique linhas de tempo de fábrica de ferramentas de plugin:
Se turnos de agente parecerem travar ao preparar ferramentas, ative logs de trace e
verifique linhas de temporização da factory de ferramentas de plugin:
```bash
openclaw config set logging.level trace
@ -393,26 +401,26 @@ Procure por:
[trace:plugin-tools] factory timings ...
```
O resumo lista o tempo total de fábrica e as fábricas de ferramentas de plugin mais lentas,
O resumo lista o tempo total de factory e as factories de ferramentas de plugin mais lentas,
incluindo id do plugin, nomes de ferramentas declarados, formato do resultado e se a ferramenta é
opcional. Linhas lentas são promovidas a avisos quando uma única fábrica leva
pelo menos 1s ou a preparação total de fábricas de ferramentas de plugin leva pelo menos 5s.
opcional. Linhas lentas são promovidas a avisos quando uma única factory leva pelo menos
1s ou a preparação total das factories de ferramentas de plugin leva pelo menos 5s.
O OpenClaw armazena em cache resultados bem-sucedidos de fábricas de ferramentas de plugin para resoluções repetidas
com o mesmo contexto efetivo da requisição. A chave de cache inclui a configuração
efetiva de runtime, workspace, ids de agente/sessão, política de sandbox, configurações do navegador,
contexto de entrega, identidade do solicitante e estado de propriedade, então fábricas que
O OpenClaw armazena em cache resultados bem-sucedidos de factories de ferramentas de plugin para resoluções repetidas
com o mesmo contexto efetivo de requisição. A chave de cache inclui a configuração efetiva
de runtime, workspace, ids de agente/sessão, política de sandbox, configurações do navegador,
contexto de entrega, identidade do solicitante e estado de propriedade, então factories que
dependem desses campos confiáveis são executadas novamente quando o contexto muda.
Se um plugin domina o tempo, inspecione seus registros de runtime:
Se um plugin dominar a temporização, inspecione seus registros de runtime:
```bash
openclaw plugins inspect <plugin-id> --runtime --json
```
Depois atualize, reinstale ou desative esse plugin. Autores de Plugin devem mover
Depois atualize, reinstale ou desative esse plugin. Autores de plugins devem mover
carregamento caro de dependências para trás do caminho de execução da ferramenta, em vez de fazê-lo
dentro da fábrica de ferramentas.
dentro da factory da ferramenta.
### Propriedade duplicada de canal ou ferramenta
@ -422,9 +430,9 @@ Sintomas:
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Isso significa que mais de um plugin ativado está tentando ser proprietário do mesmo canal,
fluxo de configuração ou nome de ferramenta. A causa mais comum é um plugin de canal externo
instalado ao lado de um plugin agrupado que agora fornece o mesmo id de canal.
Isso significa que mais de um plugin ativado está tentando possuir o mesmo canal,
fluxo de configuração ou nome de ferramenta. A causa mais comum é um plugin externo de canal
instalado ao lado de um plugin empacotado que agora fornece o mesmo id de canal.
Etapas de depuração:
@ -432,25 +440,25 @@ Etapas de depuração:
e sua origem.
- Execute `openclaw plugins inspect <id> --runtime --json` para cada plugin suspeito e
compare `channels`, `channelConfigs`, `tools` e diagnósticos.
- Execute `openclaw plugins registry --refresh` após instalar ou remover
pacotes de plugin para que metadados persistidos reflitam a instalação atual.
- Execute `openclaw plugins registry --refresh` depois de instalar ou remover
pacotes de plugin para que os metadados persistidos reflitam a instalação atual.
- Reinicie o Gateway após alterações de instalação, registro ou configuração.
Opções de correção:
- Se um plugin substitui intencionalmente outro para o mesmo id de canal, o
plugin preferido deve declarar `channelConfigs.<channel-id>.preferOver` com
o id do plugin de prioridade mais baixa. Consulte [/plugins/manifest#replacing-another-channel-plugin](/pt-BR/plugins/manifest#replacing-another-channel-plugin).
- Se a duplicação for acidental, desative um lado com
`plugins.entries.<plugin-id>.enabled: false` ou remova a instalação obsoleta do
plugin.
o id do plugin de prioridade mais baixa. Veja [/plugins/manifest#replacing-another-channel-plugin](/pt-BR/plugins/manifest#replacing-another-channel-plugin).
- Se a duplicação for acidental, desative um dos lados com
`plugins.entries.<plugin-id>.enabled: false` ou remova a instalação obsoleta
do plugin.
- Se você ativou explicitamente ambos os plugins, o OpenClaw mantém essa solicitação e
relata o conflito. Escolha um proprietário para o canal ou renomeie ferramentas pertencentes a plugin
reporta o conflito. Escolha um proprietário para o canal ou renomeie as ferramentas pertencentes ao plugin
para que a superfície de runtime seja inequívoca.
## Slots de Plugin (categorias exclusivas)
## Slots de plugin (categorias exclusivas)
Algumas categorias são exclusivas (somente uma ativa por vez):
Algumas categorias são exclusivas (apenas uma ativa por vez):
```json5
{
@ -465,8 +473,8 @@ Algumas categorias são exclusivas (somente uma ativa por vez):
| Slot | O que controla | Padrão |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin de memória ativa | `memory-core` |
| `contextEngine` | Motor de contexto ativo | `legacy` (integrado) |
| `memory` | Plugin de Active Memory | `memory-core` |
| `contextEngine` | Mecanismo de contexto ativo | `legacy` (embutido) |
## Referência da CLI
@ -516,84 +524,33 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Plugins incluídos são distribuídos com o OpenClaw. Muitos são habilitados por padrão (por exemplo
provedores de modelo incluídos, provedores de fala incluídos e o plugin de navegador
incluído). Outros plugins incluídos ainda precisam de `openclaw plugins enable <id>`.
Plugins incluídos são distribuídos com o OpenClaw. Muitos são ativados por padrão (por exemplo, provedores de modelos incluídos, provedores de fala incluídos e o plugin de navegador incluído). Outros plugins incluídos ainda precisam de `openclaw plugins enable <id>`.
`--force` sobrescreve no local um plugin instalado ou pacote de hooks existente. Use
`openclaw plugins update <id-or-npm-spec>` para atualizações rotineiras de plugins npm
rastreados. Ele não é compatível com `--link`, que reutiliza o caminho de origem em vez
de copiar sobre um destino de instalação gerenciada.
`--force` sobrescreve no lugar um plugin instalado existente ou pacote de hooks. Use `openclaw plugins update <id-or-npm-spec>` para atualizações rotineiras de plugins npm rastreados. Ele não é compatível com `--link`, que reutiliza o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.
Quando `plugins.allow` já está definido, `openclaw plugins install` adiciona o
id do plugin instalado a essa allowlist antes de habilitá-lo. Se o mesmo id de plugin
estiver presente em `plugins.deny`, a instalação remove essa entrada deny obsoleta para que a
instalação explícita possa ser carregada imediatamente após a reinicialização.
Quando `plugins.allow` já está definido, `openclaw plugins install` adiciona o id do plugin instalado a essa lista de permissões antes de ativá-lo. Se o mesmo id de plugin estiver presente em `plugins.deny`, a instalação remove essa entrada de negação obsoleta para que a instalação explícita possa ser carregada imediatamente após a reinicialização.
O OpenClaw mantém um registro local persistido de plugins como modelo de leitura frio para
inventário de plugins, propriedade de contribuições e planejamento de inicialização. Os fluxos de instalação, atualização,
desinstalação, habilitação e desabilitação atualizam esse registro depois de alterar o
estado do plugin. O mesmo arquivo `plugins/installs.json` mantém metadados duráveis de instalação em
`installRecords` de nível superior e metadados reconstruíveis de manifesto em `plugins`. Se
o registro estiver ausente, obsoleto ou inválido, `openclaw plugins registry
--refresh` reconstrói sua visão de manifesto a partir dos registros de instalação, política de configuração e
metadados de manifesto/pacote sem carregar módulos de runtime de plugin.
`openclaw plugins update <id-or-npm-spec>` se aplica a instalações rastreadas. Passar
uma especificação de pacote npm com uma dist-tag ou versão exata resolve o nome do pacote
de volta para o registro de plugin rastreado e registra a nova especificação para futuras atualizações.
Passar o nome do pacote sem uma versão move uma instalação com pin exato de volta para
a linha de lançamento padrão do registro. Se o plugin npm instalado já corresponder
à versão resolvida e à identidade de artefato registrada, o OpenClaw pula a atualização
sem baixar, reinstalar ou reescrever a configuração.
Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub
na linha padrão tentam `@beta` primeiro e voltam para default/latest quando não existe
lançamento beta do plugin. Versões exatas e tags explícitas permanecem fixadas.
O OpenClaw mantém um registro local persistente de plugins como modelo de leitura fria para inventário de plugins, propriedade de contribuições e planejamento de inicialização. Fluxos de instalação, atualização, desinstalação, ativação e desativação atualizam esse registro depois de alterar o estado do plugin. O mesmo arquivo `plugins/installs.json` mantém metadados de instalação duráveis em `installRecords` no nível superior e metadados de manifesto reconstruíveis em `plugins`. Se o registro estiver ausente, obsoleto ou inválido, `openclaw plugins registry --refresh` reconstrói sua visão de manifesto a partir dos registros de instalação, da política de configuração e dos metadados de manifesto/pacote sem carregar módulos de runtime de plugins. `openclaw plugins update <id-or-npm-spec>` se aplica a instalações rastreadas. Passar uma especificação de pacote npm com uma dist-tag ou versão exata resolve o nome do pacote de volta para o registro do plugin rastreado e registra a nova especificação para atualizações futuras. Passar o nome do pacote sem uma versão move uma instalação fixada exata de volta para a linha de lançamento padrão do registro. Se o plugin npm instalado já corresponder à versão resolvida e à identidade de artefato registrada, o OpenClaw ignora a atualização sem baixar, reinstalar ou reescrever a configuração. Quando `openclaw update` é executado no canal beta, registros de plugins npm e ClawHub da linha padrão tentam `@beta` primeiro e retornam para padrão/latest quando não existe lançamento beta do plugin. Versões exatas e tags explícitas permanecem fixadas.
`--pin` é somente para npm. Ele não é compatível com `--marketplace`, porque
instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm.
`--pin` é somente para npm. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm.
`--dangerously-force-unsafe-install` é uma substituição de emergência para falsos
positivos do scanner de código perigoso integrado. Ela permite que instalações de plugins
e atualizações de plugins continuem após achados `critical` integrados, mas ainda
não contorna bloqueios de política `before_install` de plugins nem bloqueio por falha de varredura.
Varreduras de instalação ignoram arquivos e diretórios comuns de teste, como `tests/`,
`__tests__/`, `*.test.*` e `*.spec.*`, para evitar bloquear mocks de teste empacotados;
entrypoints de runtime declarados pelo plugin ainda são verificados mesmo que usem um desses
nomes.
`--dangerously-force-unsafe-install` é uma substituição de emergência para falsos positivos do scanner de código perigoso integrado. Ele permite que instalações e atualizações de plugins continuem após descobertas `critical` integradas, mas ainda não contorna bloqueios de política `before_install` de plugins nem bloqueios por falha de varredura. Varreduras de instalação ignoram arquivos e diretórios de teste comuns, como `tests/`, `__tests__/`, `*.test.*` e `*.spec.*`, para evitar bloquear mocks de teste empacotados; pontos de entrada de runtime declarados do plugin ainda são verificados mesmo que usem um desses nomes.
Essa flag de CLI se aplica apenas aos fluxos de instalação/atualização de plugins. Instalações de dependências de Skills
com suporte do Gateway usam a substituição de solicitação `dangerouslyForceUnsafeInstall`
correspondente, enquanto `openclaw skills install` continua sendo o fluxo separado de
download/instalação de Skills do ClawHub.
Esta flag da CLI se aplica apenas aos fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` permanece o fluxo separado de download/instalação de Skills do ClawHub.
Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma varredura, abra o
painel do ClawHub ou execute `clawhub package rescan <name>` para pedir ao ClawHub que o verifique
novamente. `--dangerously-force-unsafe-install` afeta apenas instalações na sua própria
máquina; ele não pede ao ClawHub para verificar o plugin novamente nem torna público um lançamento
bloqueado.
Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma varredura, abra o painel do ClawHub ou execute `clawhub package rescan <name>` para pedir que o ClawHub o verifique novamente. `--dangerously-force-unsafe-install` afeta apenas instalações na sua própria máquina; ele não pede ao ClawHub para verificar novamente o plugin nem torna público um lançamento bloqueado.
Bundles compatíveis participam do mesmo fluxo de listar/inspecionar/habilitar/desabilitar
plugins. O suporte de runtime atual inclui Skills de bundle, command-skills do Claude,
padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude e de
`lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks
compatíveis do Codex.
Bundles compatíveis participam do mesmo fluxo de listar/inspecionar/ativar/desativar plugins. O suporte de runtime atual inclui Skills de bundle, command-skills do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude e `lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks compatíveis do Codex.
`openclaw plugins inspect <id>` também relata capacidades detectadas do bundle, além de
entradas de servidor MCP e LSP compatíveis ou incompatíveis para plugins baseados em bundle.
`openclaw plugins inspect <id>` também relata capacidades de bundle detectadas, além de entradas de servidor MCP e LSP compatíveis ou incompatíveis para plugins apoiados por bundle.
Origens de marketplace podem ser um nome de marketplace conhecido do Claude em
`~/.claude/plugins/known_marketplaces.json`, uma raiz de marketplace local ou
caminho de `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório do GitHub
ou uma URL git. Para marketplaces remotos, as entradas de plugins devem permanecer dentro do
repositório de marketplace clonado e usar apenas origens de caminho relativo.
Origens de marketplace podem ser um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json`, uma raiz de marketplace local ou caminho `marketplace.json`, um atalho do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. Para marketplaces remotos, as entradas de plugin devem permanecer dentro do repositório de marketplace clonado e usar somente origens de caminho relativas.
Veja a [referência de CLI de `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos.
Consulte a [referência da CLI `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos.
## Visão geral da API de Plugin
Plugins nativos exportam um objeto de entrada que expõe `register(api)`. Plugins mais antigos
ainda podem usar `activate(api)` como alias legado, mas novos plugins devem
usar `register`.
Plugins nativos exportam um objeto de entrada que expõe `register(api)`. Plugins mais antigos ainda podem usar `activate(api)` como alias legado, mas novos plugins devem usar `register`.
```typescript
export default definePluginEntry({
@ -613,75 +570,60 @@ export default definePluginEntry({
});
```
O OpenClaw carrega o objeto de entrada e chama `register(api)` durante a
ativação do plugin. O loader ainda recorre a `activate(api)` para plugins mais antigos,
mas plugins incluídos e novos plugins externos devem tratar `register` como o
contrato público.
O OpenClaw carrega o objeto de entrada e chama `register(api)` durante a ativação do plugin. O carregador ainda recorre a `activate(api)` para plugins mais antigos, mas plugins incluídos e novos plugins externos devem tratar `register` como o contrato público.
`api.registrationMode` informa a um plugin por que sua entrada está sendo carregada:
| Modo | Significado |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Ativação de runtime. Registre ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ao vivo. |
| `discovery` | Descoberta de capacidades somente leitura. Registre provedores e metadados; código de entrada de plugin confiável pode carregar, mas pule efeitos colaterais ao vivo. |
| `setup-only` | Carregamento de metadados de configuração de canal por meio de uma entrada de configuração leve. |
| `setup-runtime` | Carregamento de configuração de canal que também precisa da entrada de runtime. |
| `cli-metadata` | Apenas coleta de metadados de comando da CLI. |
| Modo | Significado |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `full` | Ativação de runtime. Registre ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ativos. |
| `discovery` | Descoberta de capacidades somente leitura. Registre provedores e metadados; código de entrada confiável do plugin pode carregar, mas pule efeitos colaterais ativos. |
| `setup-only` | Carregamento de metadados de configuração de canal por meio de uma entrada de configuração leve. |
| `setup-runtime` | Carregamento de configuração de canal que também precisa da entrada de runtime. |
| `cli-metadata` | Apenas coleta de metadados de comandos da CLI. |
Entradas de plugin que abrem sockets, bancos de dados, workers em segundo plano ou clientes
de longa duração devem proteger esses efeitos colaterais com `api.registrationMode === "full"`.
Cargas de descoberta são armazenadas em cache separadamente das cargas de ativação e não substituem
o registro do Gateway em execução. A descoberta é não ativadora, não livre de imports:
o OpenClaw pode avaliar a entrada confiável do plugin ou o módulo de plugin de canal para criar
o snapshot. Mantenha os níveis superiores dos módulos leves e sem efeitos colaterais, e mova
clientes de rede, subprocessos, listeners, leituras de credenciais e inicialização de serviços
para trás de caminhos de runtime completo.
Entradas de plugin que abrem sockets, bancos de dados, workers em segundo plano ou clientes de longa duração devem proteger esses efeitos colaterais com `api.registrationMode === "full"`. Cargas de descoberta são armazenadas em cache separadamente das cargas de ativação e não substituem o registro em execução do Gateway. A descoberta é não ativadora, não livre de imports: o OpenClaw pode avaliar a entrada confiável do plugin ou o módulo de plugin de canal para criar o snapshot. Mantenha os níveis superiores de módulo leves e sem efeitos colaterais, e mova clientes de rede, subprocessos, listeners, leituras de credenciais e inicialização de serviços para trás de caminhos de runtime completo.
Métodos comuns de registro:
Métodos de registro comuns:
| Método | O que registra |
| --------------------------------------- | --------------------------------------- |
| `registerProvider` | Provedor de modelo (LLM) |
| `registerChannel` | Canal de chat |
| `registerTool` | Ferramenta de agente |
| `registerHook` / `on(...)` | Hooks de ciclo de vida |
| `registerSpeechProvider` | Texto para fala / STT |
| `registerRealtimeTranscriptionProvider` | STT em streaming |
| `registerRealtimeVoiceProvider` | Voz em tempo real duplex |
| `registerMediaUnderstandingProvider` | Análise de imagem/áudio |
| `registerImageGenerationProvider` | Geração de imagem |
| `registerMusicGenerationProvider` | Geração de música |
| `registerVideoGenerationProvider` | Geração de vídeo |
| `registerWebFetchProvider` | Provedor de busca/coleta na web |
| `registerWebSearchProvider` | Busca na web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Comandos de CLI |
| `registerContextEngine` | Motor de contexto |
| `registerService` | Serviço em segundo plano |
| Método | O que registra |
| --------------------------------------- | -------------------------------- |
| `registerProvider` | Provedor de modelo (LLM) |
| `registerChannel` | Canal de chat |
| `registerTool` | Ferramenta de agente |
| `registerHook` / `on(...)` | Hooks de ciclo de vida |
| `registerSpeechProvider` | Texto para fala / STT |
| `registerRealtimeTranscriptionProvider` | STT em streaming |
| `registerRealtimeVoiceProvider` | Voz em tempo real duplex |
| `registerMediaUnderstandingProvider` | Análise de imagem/áudio |
| `registerImageGenerationProvider` | Geração de imagens |
| `registerMusicGenerationProvider` | Geração de música |
| `registerVideoGenerationProvider` | Geração de vídeo |
| `registerWebFetchProvider` | Provedor de busca/coleta Web |
| `registerWebSearchProvider` | Pesquisa Web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Comandos da CLI |
| `registerContextEngine` | Mecanismo de contexto |
| `registerService` | Serviço em segundo plano |
Comportamento de guard para hooks tipados de ciclo de vida:
Comportamento de guarda de hooks para hooks de ciclo de vida tipados:
- `before_tool_call`: `{ block: true }` é terminal; handlers de prioridade mais baixa são pulados.
- `before_tool_call`: `{ block: true }` é terminal; manipuladores de prioridade mais baixa são ignorados.
- `before_tool_call`: `{ block: false }` é um no-op e não limpa um bloqueio anterior.
- `before_install`: `{ block: true }` é terminal; handlers de prioridade mais baixa são pulados.
- `before_install`: `{ block: true }` é terminal; manipuladores de prioridade mais baixa são ignorados.
- `before_install`: `{ block: false }` é um no-op e não limpa um bloqueio anterior.
- `message_sending`: `{ cancel: true }` é terminal; handlers de prioridade mais baixa são pulados.
- `message_sending`: `{ cancel: true }` é terminal; manipuladores de prioridade mais baixa são ignorados.
- `message_sending`: `{ cancel: false }` é um no-op e não limpa um cancelamento anterior.
O app-server nativo do Codex faz a ponte de eventos de ferramentas nativas do Codex de volta para esta
superfície de hooks. Plugins podem bloquear ferramentas nativas do Codex por meio de `before_tool_call`,
observar resultados por meio de `after_tool_call` e participar de aprovações de
`PermissionRequest` do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do Codex.
O limite exato de suporte ao runtime do Codex está no
[contrato de suporte v1 do harness do Codex](/pt-BR/plugins/codex-harness#v1-support-contract).
O app-server nativo do Codex faz a ponte de eventos de ferramentas nativas do Codex de volta para esta superfície de hooks. Plugins podem bloquear ferramentas nativas do Codex por meio de `before_tool_call`, observar resultados por meio de `after_tool_call` e participar de aprovações `PermissionRequest` do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do Codex. O limite exato de suporte de runtime do Codex está no [contrato de suporte do harness Codex v1](/pt-BR/plugins/codex-harness#v1-support-contract).
Para o comportamento completo de hooks tipados, veja a [visão geral do SDK](/pt-BR/plugins/sdk-overview#hook-decision-semantics).
Para o comportamento completo de hooks tipados, consulte a [visão geral do SDK](/pt-BR/plugins/sdk-overview#hook-decision-semantics).
## Relacionados
## Relacionado
- [Criando plugins](/pt-BR/plugins/building-plugins) — crie seu próprio plugin
- [Bundles de Plugin](/pt-BR/plugins/bundles) — compatibilidade de bundles Codex/Claude/Cursor
- [Manifesto de Plugin](/pt-BR/plugins/manifest) — esquema de manifesto
- [Pacotes de plugins](/pt-BR/plugins/bundles) — compatibilidade de pacotes do Codex/Claude/Cursor
- [Manifesto do plugin](/pt-BR/plugins/manifest) — esquema do manifesto
- [Registrando ferramentas](/pt-BR/plugins/building-plugins#registering-agent-tools) — adicione ferramentas de agente em um plugin
- [Internos de Plugin](/pt-BR/plugins/architecture) — modelo de capacidade e pipeline de carregamento
- [Aspectos internos do plugin](/pt-BR/plugins/architecture) — modelo de capacidades e pipeline de carregamento
- [Plugins da comunidade](/pt-BR/plugins/community) — listagens de terceiros

135
docs/pt-BR/tools/thinking.md
View File

@ -1,97 +1,98 @@
---
read_when:
- Ajuste da análise de diretivas ou padrões de raciocínio, modo rápido ou verbosidade
- Ajustar a análise sintática ou os padrões das diretivas thinking, fast-mode ou verbose
summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio
title: Níveis de raciocínio
x-i18n:
generated_at: "2026-05-04T18:24:30Z"
generated_at: "2026-05-05T01:50:47Z"
model: gpt-5.5
provider: openai
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
## O que ele faz
## O que faz
- Diretiva inline em qualquer corpo recebido: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- minimal → “pensar”
- low → “pensar muito”
- medium → “pensar ainda mais”
- high → “ultrathink” (orçamento máximo)
- xhigh → “ultrathink+” (modelos GPT-5.2+ e Codex, além do esforço do Anthropic Claude Opus 4.7)
- adaptive → pensamento adaptativo gerenciado pelo provedor (com suporte para Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; o Ollama mapeia isso para seu maior esforço `think` nativo)
- adaptive → pensamento adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; Ollama mapeia isso para seu maior esforço nativo de `think`)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` mapeiam para `xhigh`.
- `highest` mapeia para `high`.
- Observações sobre provedores:
- Menus e seletores de pensamento são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como `on` binário.
- `adaptive`, `xhigh` e `max` só são anunciados para perfis de provedor/modelo que os suportam. Diretivas digitadas para níveis sem suporte são rejeitadas com as opções válidas desse modelo.
- Níveis sem suporte armazenados anteriormente são remapeados pela classificação do perfil do provedor. `adaptive` volta para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` voltam para o maior nível não `off` com suporte para o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento é definido.
- Menus e seletores de pensamento são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como o binário `on`.
- `adaptive`, `xhigh` e `max` só são anunciados para perfis de provedor/modelo compatíveis. Diretivas digitadas para níveis não compatíveis são rejeitadas com as opções válidas desse modelo.
- Níveis armazenados existentes que não são compatíveis são remapeados pela classificação do perfil do provedor. `adaptive` volta para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` voltam para o maior nível não `off` compatível com o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento está definido.
- Anthropic Claude Opus 4.7 não usa pensamento adaptativo por padrão. O padrão de esforço da API continua pertencendo ao provedor, a menos que você defina explicitamente um nível de pensamento.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para pensamento adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de pensamento e `xhigh` é a configuração de esforço do Opus 4.7.
- Anthropic Claude Opus 4.7 também expõe `/think max`; ele mapeia para o mesmo caminho de esforço máximo pertencente ao provedor.
- Modelos DeepSeek V4 expõem `/think xhigh|max`; ambos mapeiam para `reasoning_effort: "max"` do DeepSeek, enquanto níveis menores não `off` mapeiam para `high`.
- Modelos Ollama com capacidade de pensamento expõem `/think low|medium|high|max`; `max` mapeia para `think: "high"` nativo porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` pelo suporte de esforço da Responses API específico do modelo. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino oferece suporte; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI de agente e `llm-task` concordam com o comportamento de transporte.
- Refs configuradas obsoletas do OpenRouter Hunter Alpha pulam a injeção de raciocínio por proxy porque essa rota aposentada poderia retornar o texto da resposta final por campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o pensamento dinâmico pertencente ao provedor do Gemini. Requisições Gemini 3 omitem um `thinkingLevel` fixo, enquanto requisições Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou da requisição. Isso evita deltas `reasoning_content` vazados do formato de stream Anthropic não nativo da MiniMax.
- Z.AI (`zai/*`) oferece suporte apenas a pensamento binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`.
- Modelos diretos DeepSeek V4 expõem `/think xhigh|max`; ambos mapeiam para `reasoning_effort: "max"` do DeepSeek, enquanto níveis não `off` menores mapeiam para `high`.
- Modelos DeepSeek V4 roteados pelo OpenRouter expõem `/think xhigh` e enviam valores de `reasoning_effort` compatíveis com o OpenRouter. Sobrescritas `max` armazenadas voltam para `xhigh`.
- Modelos Ollama com capacidade de pensamento expõem `/think low|medium|high|max`; `max` mapeia para o `think: "high"` nativo, porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` pelo suporte a esforço da Responses API específico do modelo. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino é compatível; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem aderir a `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI de agente e `llm-task` concordam com o comportamento de transporte.
- Referências configuradas obsoletas do OpenRouter Hunter Alpha ignoram a injeção de raciocínio por proxy porque essa rota descontinuada podia retornar texto de resposta final por campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o pensamento dinâmico pertencente ao provedor do Gemini. Solicitações do Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações do Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou da solicitação. Isso evita deltas de `reasoning_content` vazados pelo formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) só oferece suporte a pensamento binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, Moonshot só aceita `tool_choice` `auto|none`; OpenClaw normaliza valores incompatíveis para `auto`.
## Ordem de resolução
1. Diretiva inline na mensagem (aplica-se somente a essa mensagem).
2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas a diretiva).
2. Sobrescrita de sessão (definida pelo envio de uma mensagem contendo apenas a diretiva).
3. Padrão por agente (`agents.list[].thinkingDefault` na configuração).
4. Padrão global (`agents.defaults.thinkingDefault` na configuração).
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou para o nível não `off` com suporte mais próximo para esse modelo, e modelos sem raciocínio permanecem `off`.
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou o nível não `off` compatível mais próximo para esse modelo, e modelos sem raciocínio permanecem `off`.
## Definir um padrão de sessão
## Definindo um padrão de sessão
- Envie uma mensagem que seja **somente** a diretiva (espaços em branco permitidos), por exemplo, `/think:medium` ou `/t high`.
- Isso permanece para a sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição de sessão ociosa.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão ficará inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível atual de pensamento.
- Isso fica fixo para a sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição de ociosidade da sessão.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão permanecerá inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de pensamento atual.
## Aplicação por agente
- **Pi embutido**: o nível resolvido é passado para o runtime do agente Pi em processo.
- **Backend Claude CLI**: níveis diferentes de off são passados para Claude Code como `--effort` ao usar `claude-cli`; consulte [backends CLI](/pt-BR/gateway/cli-backends).
- **Pi incorporado**: o nível resolvido é passado para o runtime do agente Pi em processo.
- **backend Claude CLI**: níveis diferentes de off são passados para Claude Code como `--effort` ao usar `claude-cli`; consulte [backends CLI](/pt-BR/gateway/cli-backends).
## Modo rápido (/fast)
- Níveis: `on|off`.
- Mensagem contendo apenas a diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Mensagem contendo apenas a diretiva alterna uma sobrescrita de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido.
- O OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/contendo apenas a diretiva
2. Substituição da sessão
- OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/contendo apenas diretiva
2. Sobrescrita de sessão
3. Padrão por agente (`agents.list[].fastModeDefault`)
4. Configuração por modelo: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Para `openai/*`, o modo rápido mapeia para processamento prioritário da OpenAI enviando `service_tier=priority` em requisições Responses com suporte.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Responses do Codex. O OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para requisições públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para camadas de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `openai/*`, o modo rápido mapeia para processamento prioritário da OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Codex Responses. OpenClaw mantém uma única alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
- Parâmetros de modelo Anthropic explícitos `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. O OpenClaw ainda pula a injeção de camada de serviço Anthropic para URLs base de proxy não Anthropic.
- Parâmetros explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão de modo rápido quando ambos estão definidos. OpenClaw ainda ignora a injeção de nível de serviço Anthropic para URLs base de proxy não Anthropic.
- `/status` mostra `Fast` somente quando o modo rápido está ativado.
## Diretivas detalhadas (/verbose ou /v)
## Diretivas verbosas (/verbose ou /v)
- Níveis: `on` (mínimo) | `full` | `off` (padrão).
- Mensagem contendo apenas a diretiva alterna o detalhamento da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessões escolhendo `inherit`.
- Mensagem contendo apenas a diretiva alterna o verbose da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma sobrescrita explícita de sessão; limpe-a pela UI de Sessões escolhendo `inherit`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam caso contrário.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual.
- Quando o modo detalhado está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem apenas de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível. Esses resumos de ferramentas são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming.
- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos com detalhes brutos de erro ficam ocultos, a menos que o detalhamento seja `on` ou `full`.
- Quando o detalhamento é `full`, saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução está em andamento, bolhas de ferramentas posteriores respeitarão a nova configuração.
- `agents.defaults.toolProgressDetail` controla o formato dos resumos de ferramentas de `/verbose` e das linhas de ferramenta de rascunho de progresso. Use `"explain"` (padrão) para rótulos humanos compactos como `🛠️ Exec: checking JS syntax`; use `"raw"` quando também quiser o comando/detalhe bruto anexado para depuração. `agents.list[].toolProgressDetail` por agente substitui o padrão.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível verbose atual.
- Quando verbose está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível. Esses resumos de ferramenta são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming.
- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos de detalhes brutos de erro ficam ocultos, a menos que verbose seja `on` ou `full`.
- Quando verbose é `full`, as saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um comprimento seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração.
- `agents.defaults.toolProgressDetail` controla o formato dos resumos de ferramenta de `/verbose` e das linhas de ferramenta de rascunho de progresso. Use `"explain"` (padrão) para rótulos humanos compactos, como `🛠️ Exec: checking JS syntax`; use `"raw"` quando também quiser o comando/detalhe bruto anexado para depuração. `agents.list[].toolProgressDetail` por agente substitui o padrão.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
@ -100,21 +101,21 @@ x-i18n:
- Níveis: `on` | `off` (padrão).
- Mensagem contendo apenas a diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam caso contrário.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível atual de rastreamento.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual.
- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de rastreamento/depuração pertencentes ao Plugin, como resumos de depuração da Active Memory.
- Linhas de rastreamento podem aparecer em `/status` e como mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
## Visibilidade do raciocínio (/reasoning)
## Visibilidade de raciocínio (/reasoning)
- Níveis: `on|off|stream`.
- Mensagem contendo apenas a diretiva alterna se blocos de pensamento são mostrados nas respostas.
- Mensagem contendo apenas a diretiva alterna se blocos de pensamento são exibidos nas respostas.
- Quando ativado, o raciocínio é enviado como uma **mensagem separada** prefixada com `Reasoning:`.
- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta está sendo gerada, depois envia a resposta final sem raciocínio.
- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta está sendo gerada e depois envia a resposta final sem raciocínio.
- Alias: `/reason`.
- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível atual de raciocínio.
- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`).
- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível de raciocínio atual.
- Ordem de resolução: diretiva inline, depois sobrescrita de sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`).
Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos `<think>...</think>` fechados permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, de outra forma, seria entregue como texto vazio, o OpenClaw remove a tag de abertura malformada e entrega o texto restante.
Tags de raciocínio malformadas de modelo local são tratadas de forma conservadora. Blocos fechados `<think>...</think>` permanecem ocultos em respostas normais, e raciocínio não fechado depois de texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e de outra forma seria entregue como texto vazio, OpenClaw remove a tag de abertura malformada e entrega o texto restante.
## Relacionado
@ -122,23 +123,23 @@ Tags de raciocínio de modelo local malformadas são tratadas de forma conservad
## Heartbeats
- O corpo da sondagem de Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats).
- A entrega de Heartbeat usa somente o payload final por padrão. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
- O corpo da sonda Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats).
- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
## UI de chat web
- O seletor de pensamento do chat web reflete o nível armazenado da sessão a partir do armazenamento/configuração da sessão recebida quando a página carrega.
- Escolher outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição `thinkingOnce` de uso único.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback que `/status` e `session_status` usam.
- O seletor usa `thinkingLevels` retornado pela linha/padrões de sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedores; Plugins possuem os conjuntos de níveis específicos de modelo.
- `/think:<level>` ainda funciona e atualiza o mesmo nível armazenado da sessão, então diretivas de chat e o seletor permanecem sincronizados.
- O seletor de pensamento do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão recebida quando a página carrega.
- Escolher outro nível grava a sobrescrita de sessão imediatamente via `sessions.patch`; ele não espera pelo próximo envio e não é uma sobrescrita `thinkingOnce` de uso único.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback usada por `/status` e `session_status`.
- O seletor usa `thinkingLevels` retornado pela linha/padrões de sessão do Gateway, com `thinkingOptions` mantido como uma lista de rótulos legada. A UI do navegador não mantém sua própria lista de regex de provedor; os Plugins são donos dos conjuntos de níveis específicos de modelo.
- `/think:<level>` ainda funciona e atualiza o mesmo nível de sessão armazenado, então as diretivas de chat e o seletor permanecem sincronizados.
## Perfis de provedor
- Plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão.
- Plugins de provedor que atuam como proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e de proxy permaneçam alinhados.
- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir um `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`.
- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` mais `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis de provedor/modelo.
- Plugins de ferramenta com acesso aos metadados configurados de modelo personalizado podem passar `catalog` para `resolveThinkingPolicy` para que adesões de `compat.supportedReasoningEfforts` sejam refletidas na validação no lado do Plugin.
- Os plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão.
- Os plugins de provedor que intermedeiam modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos Anthropic diretos e de proxy permaneçam alinhados.
- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir uma `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`.
- Plugins de ferramenta que precisam validar uma substituição explícita de pensamento devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto com `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis por provedor/modelo.
- Plugins de ferramenta com acesso aos metadados configurados de modelos personalizados podem passar `catalog` para `resolveThinkingPolicy` para que adesões por `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do plugin.
- Hooks legados publicados (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) permanecem como adaptadores de compatibilidade, mas novos conjuntos de níveis personalizados devem usar `resolveThinkingProfile`.
- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos ids e rótulos de perfil que a validação em tempo de execução usa.
- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos IDs e rótulos de perfil que a validação de runtime usa.

352
docs/pt-BR/tools/video-generation.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Gerando vídeos por meio do agente
- Geração de vídeos por meio do agente
- Configuração de provedores e modelos de geração de vídeo
- Entendendo os parâmetros da ferramenta video_generate
sidebarTitle: Video generation
summary: Gere vídeos via video_generate a partir de referências de texto, imagem ou vídeo em 16 backends de provedores
summary: Gere vídeos via video_generate a partir de referências de texto, imagem ou vídeo em 16 mecanismos de provedores
title: Geração de vídeo
x-i18n:
generated_at: "2026-04-30T10:13:16Z"
generated_at: "2026-05-05T01:51:02Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
Os agentes do OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou
Os agentes OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou
vídeos existentes. Dezesseis backends de provedores são compatíveis, cada um com
diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe o
provedor certo automaticamente com base na sua configuração e nas chaves de API
@ -24,10 +24,10 @@ disponíveis.
<Note>
A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo
está disponível. Se você não a vir nas ferramentas do seu agente, defina uma
chave de API de provedor ou configure `agents.defaults.videoGenerationModel`.
chave de API do provedor ou configure `agents.defaults.videoGenerationModel`.
</Note>
O OpenClaw trata a geração de vídeo como três modos de tempo de execução:
O OpenClaw trata a geração de vídeo como três modos de runtime:
- `generate` — solicitações de texto para vídeo sem mídia de referência.
- `imageToVideo` — a solicitação inclui uma ou mais imagens de referência.
@ -39,7 +39,7 @@ modo ativo antes do envio e relata os modos compatíveis em `action=list`.
## Início rápido
<Steps>
<Step title="Configure a autenticação">
<Step title="Configure auth">
Defina uma chave de API para qualquer provedor compatível:
```bash
@ -47,15 +47,15 @@ modo ativo antes do envio e relata os modos compatíveis em `action=list`.
```
</Step>
<Step title="Escolha um modelo padrão (opcional)">
<Step title="Pick a default model (optional)">
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
</Step>
<Step title="Peça ao agente">
<Step title="Ask the agent">
> Gere um vídeo cinematográfico de 5 segundos de uma lagosta simpática surfando ao pôr do sol.
O agente chama `video_generate` automaticamente. Nenhuma lista de permissões de ferramentas
O agente chama `video_generate` automaticamente. Nenhuma allowlist de ferramentas
é necessária.
</Step>
@ -68,33 +68,35 @@ sessão:
1. O OpenClaw envia a solicitação ao provedor e retorna imediatamente um id de tarefa.
2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução).
3. Quando o vídeo fica pronto, o OpenClaw desperta a mesma sessão com um evento interno de conclusão.
4. O agente publica o vídeo finalizado de volta na conversa original.
3. Quando o vídeo está pronto, o OpenClaw desperta a mesma sessão com um evento interno de conclusão.
4. O agente informa o usuário e anexa o vídeo finalizado. Em conversas de grupo/canal
que usam entrega visível somente por ferramenta de mensagem, o agente retransmite o
resultado pela ferramenta de mensagem em vez de o OpenClaw publicá-lo diretamente.
Enquanto um trabalho está em andamento, chamadas duplicadas de `video_generate` na mesma
sessão retornam o status da tarefa atual em vez de iniciar outra
sessão retornam o status atual da tarefa em vez de iniciar outra
geração. Use `openclaw tasks list` ou `openclaw tasks show <taskId>` para
verificar o progresso pela CLI.
Fora de execuções de agente com sessão de apoio (por exemplo, invocações diretas de ferramentas),
a ferramenta recorre à geração em linha e retorna o caminho da mídia final
Fora de execuções de agente com sessão (por exemplo, invocações diretas de ferramenta),
a ferramenta recorre à geração inline e retorna o caminho final da mídia
no mesmo turno.
Arquivos de vídeo gerados são salvos no armazenamento de mídia gerenciado pelo OpenClaw quando
o provedor retorna bytes. O limite padrão de salvamento de vídeos gerados segue
o limite de mídia de vídeo, e `agents.defaults.mediaMaxMb` o aumenta para
renderizações maiores. Quando um provedor também retorna uma URL de saída hospedada, o OpenClaw
pode entregar essa URL em vez de falhar a tarefa se a persistência local
rejeitar um arquivo grande demais.
pode entregar essa URL em vez de falhar a tarefa caso a persistência local
rejeite um arquivo grande demais.
### Ciclo de vida da tarefa
| Estado | Significado |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Tarefa criada, aguardando o provedor aceitá-la. |
| Estado | Significado |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `queued` | Tarefa criada, aguardando o provedor aceitá-la. |
| `running` | O provedor está processando (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução). |
| `succeeded` | Vídeo pronto; o agente desperta e o publica na conversa. |
| `failed` | Erro ou tempo limite do provedor; o agente desperta com detalhes do erro. |
| `succeeded` | Vídeo pronto; o agente desperta e o publica na conversa. |
| `failed` | Erro ou timeout do provedor; o agente desperta com detalhes do erro. |
Verifique o status pela CLI:
@ -105,55 +107,55 @@ openclaw tasks cancel <taskId>
```
Se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual,
`video_generate` retorna o status da tarefa existente em vez de iniciar uma nova
`video_generate` retornará o status da tarefa existente em vez de iniciar uma nova
tarefa. Use `action: "status"` para verificar explicitamente sem acionar uma nova
geração.
## Provedores compatíveis
| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação |
| --------------------- | ------------------------------ | :---: | -------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via função) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance de referência para vídeo | Até 3 vídeos com Seedance de referência para vídeo | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` |
| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação |
| --------------------- | ------------------------------ | :---: | --------------------------------------------------- | -------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via papel) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance de referência para vídeo | Até 3 vídeos com Seedance de referência para vídeo | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` |
Alguns provedores aceitam variáveis de ambiente de chave de API adicionais ou alternativas. Consulte
as [páginas de provedores](#related) individuais para obter detalhes.
as [páginas dos provedores](#related) individuais para obter detalhes.
Execute `video_generate action=list` para inspecionar provedores, modelos e
modos de tempo de execução disponíveis em tempo de execução.
modos de runtime disponíveis em tempo de execução.
### Matriz de capacidades
O contrato de modo explícito usado por `video_generate`, testes de contrato e
a varredura compartilhada ao vivo:
a varredura ao vivo compartilhada:
| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Trilhas compartilhadas ao vivo hoje |
| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Trilhas ao vivo compartilhadas hoje |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Não está na varredura compartilhada; a cobertura específica de workflow fica com os testes do Comfy |
| DeepInfra | ✓ | — | — | `generate`; os esquemas de vídeo nativos do DeepInfra são de texto para vídeo no contrato incluído |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` somente ao usar Seedance de referência para vídeo |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura atual Gemini/Veo baseada em buffer não aceita essa entrada |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura Gemini/Veo atual baseada em buffer não aceita essa entrada |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente precisa de acesso de inpaint/remix do lado do provedor |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente precisa de acesso a inpaint/remix no lado do provedor |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` roda somente quando o modelo selecionado é `runway/gen4_aleph` |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` executa somente quando o modelo selecionado é `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` incluído é somente texto e o `kling` incluído exige uma URL de imagem remota |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota |
@ -186,19 +188,19 @@ referência de voz quando o provedor oferece suporte a entradas de áudio.
</ParamField>
<ParamField path="audioRefs" type="string[]">Vários áudios de referência (até 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
Dicas opcionais de função por posição, paralelas à lista combinada de áudio.
Dicas opcionais de função por posição, paralelas à lista combinada de áudios.
Valor canônico: `reference_audio`.
</ParamField>
<Note>
As dicas de função são encaminhadas ao provedor como estão. Os valores
canônicos vêm da união `VideoGenerationAssetRole`, mas os provedores podem
aceitar strings de função adicionais. Arrays `*Roles` não devem ter mais
entradas do que a lista de referência correspondente; erros de deslocamento
de uma posição falham com uma mensagem clara. Use uma string vazia para
deixar uma posição sem definição. Para xAI, defina toda função de imagem como
aceitar strings de função adicionais. Os arrays `*Roles` não devem ter mais
entradas que a lista de referência correspondente; erros de deslocamento de
uma posição falham com uma mensagem clara. Use uma string vazia para deixar
um slot sem definição. Para xAI, defina todas as funções de imagem como
`reference_image` para usar seu modo de geração `reference_images`; omita a
função ou use `first_frame` para imagem-para-vídeo com uma única imagem.
função ou use `first_frame` para imagem para vídeo com uma única imagem.
</Note>
### Controles de estilo
@ -208,19 +210,19 @@ função ou use `first_frame` para imagem-para-vídeo com uma única imagem.
</ParamField>
<ParamField path="resolution" type="string">`480P`, `720P`, `768P` ou `1080P`.</ParamField>
<ParamField path="durationSeconds" type="number">
Duração alvo em segundos (arredondada para o valor compatível mais próximo do provedor).
Duração-alvo em segundos (arredondada para o valor mais próximo aceito pelo provedor).
</ParamField>
<ParamField path="size" type="string">Dica de tamanho quando o provedor oferece suporte.</ParamField>
<ParamField path="audio" type="boolean">
Habilita áudio gerado na saída quando houver suporte. Diferente de `audioRef*` (entradas).
</ParamField>
<ParamField path="watermark" type="boolean">Alterna a marca d'água do provedor quando houver suporte.</ParamField>
<ParamField path="watermark" type="boolean">Alterna a marca-d'água do provedor quando houver suporte.</ParamField>
`adaptive` é um sentinela específico do provedor: ele é encaminhado como
está para provedores que declaram `adaptive` em seus recursos (por exemplo,
o BytePlus Seedance o usa para detectar automaticamente a proporção a partir
`adaptive` é um sentinela específico do provedor: ele é encaminhado como está
para provedores que declaram `adaptive` em suas capacidades (por exemplo, o
BytePlus Seedance o usa para detectar automaticamente a proporção a partir
das dimensões da imagem de entrada). Provedores que não o declaram expõem o
valor via `details.ignoredOverrides` no resultado da ferramenta para que o
valor via `details.ignoredOverrides` no resultado da ferramenta, para que o
descarte fique visível.
### Avançado
@ -230,70 +232,68 @@ descarte fique visível.
</ParamField>
<ParamField path="model" type="string">Substituição de provedor/modelo (por exemplo, `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">Dica de nome de arquivo de saída.</ParamField>
<ParamField path="timeoutMs" type="number">Tempo limite opcional da solicitação ao provedor em milissegundos.</ParamField>
<ParamField path="timeoutMs" type="number">Tempo limite opcional da solicitação ao provedor, em milissegundos.</ParamField>
<ParamField path="providerOptions" type="object">
Opções específicas do provedor como objeto JSON (por exemplo, `{"seed": 42, "draft": true}`).
Opções específicas do provedor como um objeto JSON (por exemplo, `{"seed": 42, "draft": true}`).
Provedores que declaram um esquema tipado validam as chaves e os tipos; chaves
desconhecidas ou incompatibilidades ignoram o candidato durante o fallback.
Provedores sem um esquema declarado recebem as opções como estão. Execute
`video_generate action=list` para ver o que cada provedor aceita.
desconhecidas ou incompatibilidades pulam o candidato durante o fallback. Provedores sem um
esquema declarado recebem as opções como estão. Execute `video_generate action=list`
para ver o que cada provedor aceita.
</ParamField>
<Note>
Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw
normaliza a duração para o valor compatível mais próximo do provedor e
remapeia dicas de geometria traduzidas, como tamanho-para-proporção, quando
um provedor de fallback expõe uma superfície de controle diferente.
Substituições realmente sem suporte são ignoradas com base no melhor esforço
e relatadas como avisos no resultado da ferramenta. Limites rígidos de
recurso (como excesso de entradas de referência) falham antes do envio. Os
resultados da ferramenta relatam as configurações aplicadas;
`details.normalization` captura qualquer tradução de solicitado-para-aplicado.
Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw normaliza a duração para
o valor mais próximo aceito pelo provedor e remapeia dicas de geometria traduzidas,
como tamanho para proporção, quando um provedor de fallback expõe uma
superfície de controle diferente. Substituições realmente sem suporte são ignoradas em regime de melhor esforço
e relatadas como avisos no resultado da ferramenta. Limites rígidos de capacidade
(como excesso de entradas de referência) falham antes do envio. Os resultados da ferramenta
relatam as configurações aplicadas; `details.normalization` captura qualquer
tradução de solicitado para aplicado.
</Note>
Entradas de referência selecionam o modo de runtime:
As entradas de referência selecionam o modo de runtime:
- Nenhuma mídia de referência → `generate`
- Qualquer referência de imagem → `imageToVideo`
- Qualquer referência de vídeo → `videoToVideo`
- Entradas de áudio de referência **não** alteram o modo resolvido; elas são
aplicadas sobre qualquer modo selecionado pelas referências de imagem/vídeo
e funcionam apenas com provedores que declaram `maxInputAudios`.
- Entradas de áudio de referência **não** alteram o modo resolvido; elas se aplicam sobre
qualquer modo selecionado pelas referências de imagem/vídeo e só funcionam
com provedores que declaram `maxInputAudios`.
Referências mistas de imagem e vídeo não são uma superfície de recurso
compartilhada estável. Prefira um tipo de referência por solicitação.
Referências mistas de imagem e vídeo não são uma superfície de capacidade compartilhada estável.
Prefira um tipo de referência por solicitação.
#### Fallback e opções tipadas
Algumas verificações de recurso são aplicadas na camada de fallback em vez
de no limite da ferramenta, portanto uma solicitação que excede os limites
do provedor primário ainda pode ser executada em um fallback capaz:
Algumas verificações de capacidade são aplicadas na camada de fallback, em vez de na
fronteira da ferramenta, portanto uma solicitação que excede os limites do provedor primário ainda pode
ser executada em um fallback capaz:
- Candidato ativo que não declara `maxInputAudios` (ou declara `0`) é ignorado
quando a solicitação contém referências de áudio; o próximo candidato é tentado.
- `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds`
solicitado sem uma lista `supportedDurationSeconds` declarada → ignorado.
- A solicitação contém `providerOptions` e o candidato ativo declara
explicitamente um esquema tipado `providerOptions` → ignorado se as chaves
fornecidas não estiverem no esquema ou se os tipos de valor não corresponderem.
Provedores sem um esquema declarado recebem as opções como estão
(repasse compatível com versões anteriores). Um provedor pode recusar todas
as opções de provedor declarando um esquema vazio (`capabilities.providerOptions: {}`),
o que causa o mesmo salto de uma incompatibilidade de tipo.
- O candidato ativo que não declara `maxInputAudios` (ou declara `0`) é pulado quando
a solicitação contém referências de áudio; o próximo candidato é tentado.
- O `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds` solicitado
sem uma lista `supportedDurationSeconds` declarada → pulado.
- A solicitação contém `providerOptions` e o candidato ativo declara explicitamente
um esquema tipado de `providerOptions` → pulado se as chaves fornecidas
não estiverem no esquema ou se os tipos dos valores não corresponderem. Provedores sem um
esquema declarado recebem as opções como estão (passagem direta compatível
com versões anteriores). Um provedor pode optar por não aceitar nenhuma opção de provedor
declarando um esquema vazio (`capabilities.providerOptions: {}`), o que
causa o mesmo pulo que uma incompatibilidade de tipo.
O primeiro motivo de salto em uma solicitação é registrado em `warn` para
que operadores vejam quando o provedor primário foi preterido; saltos
subsequentes são registrados em `debug` para manter cadeias longas de
fallback silenciosas. Se todos os candidatos forem ignorados, o erro agregado
inclui o motivo do salto de cada um.
O primeiro motivo de pulo em uma solicitação é registrado em `warn` para que operadores vejam quando
seu provedor primário foi preterido; pulos subsequentes são registrados em `debug` para
manter cadeias longas de fallback silenciosas. Se todos os candidatos forem pulados, o
erro agregado incluirá o motivo de pulo de cada um.
## Ações
| Ação | O que faz |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. |
| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. |
| `list` | Mostra provedores, modelos e seus recursos disponíveis. |
| Ação | O que faz |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. |
| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. |
| `list` | Mostra provedores, modelos e suas capacidades disponíveis. |
## Seleção de modelo
@ -303,13 +303,14 @@ O OpenClaw resolve o modelo nesta ordem:
2. **`videoGenerationModel.primary`** da configuração.
3. **`videoGenerationModel.fallbacks`** em ordem.
4. **Detecção automática** — provedores que têm autenticação válida, começando pelo
provedor padrão atual e depois pelos provedores restantes em ordem alfabética.
provedor padrão atual e depois os provedores restantes em ordem
alfabética.
Se um provedor falhar, o próximo candidato é tentado automaticamente. Se
todos os candidatos falharem, o erro inclui detalhes de cada tentativa.
Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos
os candidatos falharem, o erro incluirá detalhes de cada tentativa.
Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` para usar
apenas as entradas explícitas `model`, `primary` e `fallbacks`.
apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
```json5
{
@ -324,12 +325,12 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`.
}
```
## Notas de provedores
## Observações dos provedores
<AccordionGroup>
<Accordion title="Alibaba">
Usa o endpoint assíncrono do DashScope / Model Studio. Imagens e
vídeos de referência devem ser URLs `http(s)` remotas.
Usa o endpoint assíncrono DashScope / Model Studio. Imagens e
vídeos de referência devem ser URLs remotas `http(s)`.
</Accordion>
<Accordion title="BytePlus (1.0)">
ID do provedor: `byteplus`.
@ -339,12 +340,12 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`.
`seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
Modelos T2V (`*-t2v-*`) não aceitam entradas de imagem; modelos I2V e
modelos gerais `*-pro-*` oferecem suporte a uma única imagem de
referência (primeiro quadro). Passe a imagem posicionalmente ou defina
`role: "first_frame"`. IDs de modelo T2V são alternados automaticamente
para a variante I2V correspondente quando uma imagem é fornecida.
modelos gerais `*-pro-*` oferecem suporte a uma única imagem de referência (primeiro
frame). Passe a imagem posicionalmente ou defina `role: "first_frame"`.
IDs de modelo T2V são trocados automaticamente para a variante I2V
correspondente quando uma imagem é fornecida.
Chaves `providerOptions` compatíveis: `seed` (número), `draft` (booleano —
Chaves de `providerOptions` compatíveis: `seed` (número), `draft` (booleano —
força 480p), `camera_fixed` (booleano).
</Accordion>
@ -353,14 +354,14 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`.
ID do provedor: `byteplus-seedance15`. Modelo:
`seedance-1-5-pro-251215`.
Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens
de entrada (`first_frame` + `last_frame`). Todas as entradas devem ser
URLs `https://` remotas. Defina `role: "first_frame"` / `"last_frame"`
em cada imagem, ou passe imagens posicionalmente.
Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens de entrada
(`first_frame` + `last_frame`). Todas as entradas devem ser URLs remotas `https://`.
Defina `role: "first_frame"` / `"last_frame"` em cada imagem, ou
passe as imagens posicionalmente.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir
da imagem de entrada. `audio: true` é mapeado para `generate_audio`.
`providerOptions.seed` (número) é encaminhado.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada.
`audio: true` mapeia para `generate_audio`. `providerOptions.seed`
(número) é encaminhado.
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
@ -369,32 +370,32 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`.
`dreamina-seedance-2-0-260128`,
`dreamina-seedance-2-0-fast-260128`.
Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de
referência, 3 vídeos de referência e 3 áudios de referência. Todas as
entradas devem ser URLs `https://` remotas. Defina `role` em cada ativo —
valores compatíveis: `"first_frame"`, `"last_frame"`, `"reference_image"`,
Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de referência,
3 vídeos de referência e 3 áudios de referência. Todas as entradas devem ser URLs remotas
`https://`. Defina `role` em cada ativo — valores compatíveis:
`"first_frame"`, `"last_frame"`, `"reference_image"`,
`"reference_video"`, `"reference_audio"`.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir
da imagem de entrada. `audio: true` é mapeado para `generate_audio`.
`providerOptions.seed` (número) é encaminhado.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada.
`audio: true` mapeia para `generate_audio`. `providerOptions.seed`
(número) é encaminhado.
</Accordion>
<Accordion title="ComfyUI">
Execução local ou em nuvem orientada por workflow. Oferece suporte a
texto-para-vídeo e imagem-para-vídeo pelo grafo configurado.
Execução local ou em nuvem orientada por workflow. Oferece suporte a texto para vídeo e
imagem para vídeo por meio do grafo configurado.
</Accordion>
<Accordion title="fal">
Usa um fluxo com fila para tarefas de longa duração. A maioria dos
modelos de vídeo da fal aceita uma única referência de imagem. Modelos
Seedance 2.0 de referência-para-vídeo aceitam até 9 imagens, 3 vídeos e
3 referências de áudio, com no máximo 12 arquivos de referência no total.
Usa um fluxo baseado em fila para jobs de longa duração. A maioria dos modelos de vídeo da fal
aceita uma única referência de imagem. Modelos de referência para vídeo do Seedance 2.0
aceitam até 9 imagens, 3 vídeos e 3 referências de áudio, com
no máximo 12 arquivos de referência no total.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Oferece suporte a uma referência de imagem ou uma referência de vídeo.
</Accordion>
<Accordion title="MiniMax">
Apenas referência de imagem única.
Apenas uma única referência de imagem.
</Accordion>
<Accordion title="OpenAI">
Apenas a substituição `size` é encaminhada. Outras substituições de estilo
@ -402,39 +403,41 @@ apenas as entradas explícitas `model`, `primary` e `fallbacks`.
um aviso.
</Accordion>
<Accordion title="OpenRouter">
Usa a API assíncrona `/videos` do OpenRouter. O OpenClaw envia a tarefa,
consulta `polling_url` e baixa `unsigned_urls` ou o endpoint documentado
de conteúdo da tarefa. O padrão incluído `google/veo-3.1-fast` anuncia
durações de 4/6/8 segundos, resoluções `720P`/`1080P` e proporções
`16:9`/`9:16`.
Usa a API assíncrona `/videos` do OpenRouter. O OpenClaw envia o
job, consulta `polling_url` e baixa `unsigned_urls` ou o
endpoint de conteúdo de job documentado. O padrão incluído `google/veo-3.1-fast`
anuncia durações de 4/6/8 segundos, resoluções `720P`/`1080P` e
proporções `16:9`/`9:16`.
</Accordion>
<Accordion title="Qwen">
Mesmo backend DashScope da Alibaba. Entradas de referência devem ser
URLs `http(s)` remotas; arquivos locais são rejeitados antecipadamente.
Mesmo backend DashScope que o Alibaba. Entradas de referência devem ser URLs remotas
`http(s)`; arquivos locais são rejeitados antecipadamente.
</Accordion>
<Accordion title="Runway">
Oferece suporte a arquivos locais via URIs de dados. Vídeo-para-vídeo
requer `runway/gen4_aleph`. Execuções somente texto expõem proporções
Oferece suporte a arquivos locais via URIs de dados. Vídeo para vídeo requer
`runway/gen4_aleph`. Execuções somente texto expõem proporções
`16:9` e `9:16`.
</Accordion>
<Accordion title="Together">
Apenas referência de imagem única.
Apenas uma única referência de imagem.
</Accordion>
<Accordion title="Vydra">
Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos
que descartam autenticação. `veo3` é incluído apenas como texto-para-vídeo;
`kling` requer uma URL de imagem remota.
que descartam autenticação. `veo3` é incluído apenas como texto para vídeo; `kling` requer
uma URL de imagem remota.
</Accordion>
<Accordion title="xAI">
Oferece suporte a texto-para-vídeo, imagem-para-vídeo com um único primeiro
quadro, até 7 entradas `reference_image` por meio de `reference_images`
da xAI, e fluxos remotos de edição/extensão de vídeo.
Oferece suporte a texto para vídeo, imagem para vídeo com uma única imagem de primeiro frame, até 7
entradas `reference_image` por meio de `reference_images` da xAI e fluxos remotos
de edição/extensão de vídeo.
</Accordion>
</AccordionGroup>
## Modos de recursos do provedor
## Modos de capacidade dos provedores
O contrato compartilhado de geração de vídeo oferece suporte a recursos específicos por modo em vez de apenas limites agregados planos. Novas implementações de provedor devem preferir blocos de modo explícitos:
O contrato compartilhado de geração de vídeo oferece suporte a recursos específicos por modo
em vez de apenas limites agregados planos. Novas implementações de provedores
devem preferir blocos de modo explícitos:
```typescript
capabilities: {
@ -459,42 +462,55 @@ capabilities: {
}
```
Campos agregados planos como `maxInputImages` e `maxInputVideos` **não** são suficientes para anunciar suporte ao modo de transformação. Os provedores devem declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes ao vivo, testes de contrato e a ferramenta compartilhada `video_generate` possam validar o suporte a modos de forma determinística.
Campos agregados planos como `maxInputImages` e `maxInputVideos`
**não** são suficientes para anunciar suporte a modos de transformação. Provedores devem
declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes
ao vivo, testes de contrato e a ferramenta compartilhada `video_generate` possam validar
o suporte a modos de forma determinística.
Quando um modelo em um provedor tiver suporte mais amplo a entradas de referência do que os demais, use `maxInputImagesByModel`, `maxInputVideosByModel` ou `maxInputAudiosByModel` em vez de aumentar o limite de todo o modo.
Quando um modelo em um provedor tiver suporte mais amplo a entradas de referência do que o
restante, use `maxInputImagesByModel`, `maxInputVideosByModel` ou
`maxInputAudiosByModel` em vez de aumentar o limite de todo o modo.
## Testes ao vivo
Cobertura ao vivo opcional para os provedores compartilhados incluídos:
Cobertura ao vivo opcional para os provedores agrupados compartilhados:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
Encapsulador do repositório:
Wrapper do repositório:
```bash
pnpm test:live:media video
```
Este arquivo ao vivo carrega variáveis de ambiente de provedor ausentes de `~/.profile`, por padrão prefere chaves de API ao vivo/de ambiente antes de perfis de autenticação armazenados e executa um smoke seguro para release por padrão:
Este arquivo ao vivo carrega variáveis de ambiente ausentes de provedores a partir de `~/.profile`, prefere
chaves de API ao vivo/do ambiente antes de perfis de autenticação armazenados por padrão e executa um
smoke test seguro para lançamento por padrão:
- `generate` para cada provedor não FAL na varredura.
- `generate` para todos os provedores não FAL na varredura.
- Prompt de lagosta de um segundo.
- Limite de operação por provedor de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão).
- Limite de operação por provedor a partir de
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão).
FAL é opcional porque a latência da fila do lado do provedor pode dominar o tempo de release:
FAL é opcional porque a latência da fila do lado do provedor pode dominar o tempo de lançamento:
```bash
pnpm test:live:media video --video-providers fal
```
Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados que a varredura compartilhada pode exercitar com segurança com mídia local:
Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de
transformação declarados que a varredura compartilhada pode exercitar com segurança com mídia local:
- `imageToVideo` quando `capabilities.imageToVideo.enabled`.
- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o provedor/modelo aceita entrada de vídeo local baseada em buffer na varredura compartilhada.
- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o
provedor/modelo aceita entrada de vídeo local baseada em buffer na varredura
compartilhada.
Hoje, a faixa ao vivo compartilhada de `videoToVideo` cobre `runway` somente quando você seleciona `runway/gen4_aleph`.
Hoje, a faixa ao vivo compartilhada de `videoToVideo` cobre apenas `runway` quando você
seleciona `runway/gen4_aleph`.
## Configuração
@ -513,7 +529,7 @@ Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw
}
```
Ou pela CLI:
Ou via CLI:
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
@ -522,7 +538,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## Relacionados
- [Alibaba Model Studio](/pt-BR/providers/alibaba)
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — acompanhamento de tarefas para geração assíncrona de vídeo
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para geração de vídeo assíncrona
- [BytePlus](/pt-BR/concepts/model-providers#byteplus-international)
- [ComfyUI](/pt-BR/providers/comfy)
- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults)

108
docs/pt-BR/web/dashboard.md
View File

@ -1,18 +1,18 @@
---
read_when:
- Alterando modos de autenticação ou exposição do painel
summary: Acesso e autenticação do painel do Gateway (Control UI)
- Alteração da autenticação ou dos modos de exposição do painel
summary: Acesso e autenticação do painel do Gateway (interface de controle)
title: Painel
x-i18n:
generated_at: "2026-04-25T13:58:52Z"
model: gpt-5.4
generated_at: "2026-05-05T01:50:50Z"
model: gpt-5.5
provider: openai
source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
source_path: web/dashboard.md
workflow: 15
workflow: 16
---
O painel do Gateway é o Control UI no navegador servido em `/` por padrão
O painel do Gateway é a Interface de Controle no navegador servida em `/` por padrão
(substitua com `gateway.controlUi.basePath`).
Abertura rápida (Gateway local):
@ -23,87 +23,91 @@ Abertura rápida (Gateway local):
Referências principais:
- [Control UI](/pt-BR/web/control-ui) para uso e recursos da UI.
- [Interface de Controle](/pt-BR/web/control-ui) para uso e recursos da UI.
- [Tailscale](/pt-BR/gateway/tailscale) para automação de Serve/Funnel.
- [Superfícies web](/pt-BR/web) para modos de bind e observações de segurança.
- [Superfícies Web](/pt-BR/web) para modos de bind e notas de segurança.
A autenticação é aplicada no handshake do WebSocket pelo caminho de autenticação
configurado do gateway:
A autenticação é aplicada no handshake WebSocket pelo caminho de autenticação do gateway
configurado:
- `connect.params.auth.token`
- `connect.params.auth.password`
- Cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true`
- Cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"`
- cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true`
- cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"`
Consulte `gateway.auth` em [Configuração do Gateway](/pt-BR/gateway/configuration).
Veja `gateway.auth` em [Configuração do Gateway](/pt-BR/gateway/configuration).
Observação de segurança: o Control UI é uma **superfície administrativa** (chat, configuração, aprovações de exec).
Não o exponha publicamente. A UI mantém tokens de URL do painel em `sessionStorage`
Nota de segurança: a Interface de Controle é uma **superfície de administração** (chat, configuração, aprovações de execução).
Não a exponha publicamente. A UI mantém tokens de URL do painel em sessionStorage
para a sessão atual da aba do navegador e a URL do gateway selecionada, e os remove da URL após o carregamento.
Prefira localhost, Tailscale Serve ou um túnel SSH.
## Caminho rápido (recomendado)
- Após o onboarding, a CLI abre automaticamente o painel e imprime um link limpo (sem token).
- Reabra a qualquer momento: `openclaw dashboard` (copia o link, abre o navegador se possível, mostra dica de SSH se estiver em modo headless).
- Após a integração inicial, a CLI abre automaticamente o painel e imprime um link limpo (sem token).
- Reabra a qualquer momento: `openclaw dashboard` (copia o link, abre o navegador se possível, mostra dica de SSH se estiver sem interface gráfica).
- Se a entrega por área de transferência e navegador falhar, `openclaw dashboard` ainda imprime a
URL limpa e informa para usar o token de `OPENCLAW_GATEWAY_TOKEN` ou
`gateway.auth.token` como a chave de fragmento de URL `token`; ele não imprime valores de token
nos logs.
- Se a UI solicitar autenticação por segredo compartilhado, cole o token ou
a senha configurados nas configurações do Control UI.
a senha configurados nas configurações da Interface de Controle.
## Noções básicas de autenticação (local vs remoto)
- **Localhost**: abra `http://127.0.0.1:18789/`.
- **TLS do Gateway**: quando `gateway.tls.enabled: true`, links de painel/status usam
`https://` e links WebSocket do Control UI usam `wss://`.
`https://` e links WebSocket da Interface de Controle usam `wss://`.
- **Origem do token de segredo compartilhado**: `gateway.auth.token` (ou
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` pode passá-lo por fragmento de URL
para bootstrap único, e o Control UI o mantém em `sessionStorage` para a
sessão atual da aba do navegador e a URL do gateway selecionada, em vez de `localStorage`.
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` pode passá-lo via fragmento de URL
para bootstrap único, e a Interface de Controle o mantém em sessionStorage para a
sessão atual da aba do navegador e a URL do gateway selecionada em vez de localStorage.
- Se `gateway.auth.token` for gerenciado por SecretRef, `openclaw dashboard`
imprime/copia/abre uma URL sem token por design. Isso evita expor
tokens gerenciados externamente em logs do shell, histórico da área de transferência ou argumentos
de inicialização do navegador.
- Se `gateway.auth.token` estiver configurado como um SecretRef e não for resolvido no seu
tokens gerenciados externamente em logs do shell, histórico da área de transferência ou argumentos de
inicialização do navegador.
- Se `gateway.auth.token` estiver configurado como SecretRef e não for resolvido no seu
shell atual, `openclaw dashboard` ainda imprime uma URL sem token mais
orientações práticas de configuração de autenticação.
- **Senha de segredo compartilhado**: use a `gateway.auth.password` configurada (ou
orientações acionáveis de configuração de autenticação.
- **Senha de segredo compartilhado**: use o `gateway.auth.password` configurado (ou
`OPENCLAW_GATEWAY_PASSWORD`). O painel não persiste senhas entre
recarregamentos.
- **Modos com identidade**: o Tailscale Serve pode satisfazer a autenticação do Control UI/WebSocket
por cabeçalhos de identidade quando `gateway.auth.allowTailscale: true`, e um
proxy reverso com reconhecimento de identidade fora de loopback pode satisfazer
- **Modos com identidade**: Tailscale Serve pode satisfazer a autenticação da Interface de Controle/WebSocket
via cabeçalhos de identidade quando `gateway.auth.allowTailscale: true`, e um
proxy reverso com reconhecimento de identidade que não seja loopback pode satisfazer
`gateway.auth.mode: "trusted-proxy"`. Nesses modos, o painel não
precisa de um segredo compartilhado colado para o WebSocket.
- **Não localhost**: use Tailscale Serve, um bind fora de loopback com segredo compartilhado, um
proxy reverso fora de loopback com reconhecimento de identidade e
`gateway.auth.mode: "trusted-proxy"`, ou um túnel SSH. As APIs HTTP ainda usam
autenticação por segredo compartilhado, a menos que você execute intencionalmente um ingresso privado com
`gateway.auth.mode: "none"` ou autenticação HTTP trusted-proxy. Consulte
[Superfícies web](/pt-BR/web).
- **Não localhost**: use Tailscale Serve, um bind de segredo compartilhado que não seja loopback, um
proxy reverso com reconhecimento de identidade que não seja loopback com
`gateway.auth.mode: "trusted-proxy"` ou um túnel SSH. APIs HTTP ainda usam
autenticação por segredo compartilhado, a menos que você execute intencionalmente
`gateway.auth.mode: "none"` com private-ingress ou autenticação HTTP por proxy confiável. Veja
[Superfícies Web](/pt-BR/web).
<a id="if-you-see-unauthorized-1008"></a>
## Se você vir "unauthorized" / 1008
- Verifique se o gateway está acessível (local: `openclaw status`; remoto: túnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` e depois abra `http://127.0.0.1:18789/`).
- Para `AUTH_TOKEN_MISMATCH`, os clientes podem fazer uma nova tentativa confiável com um token de dispositivo em cache quando o gateway retorna dicas de nova tentativa. Essa nova tentativa com token em cache reutiliza os escopos aprovados em cache do token; chamadores com `deviceToken` explícito / `scopes` explícitos mantêm seu conjunto de escopos solicitado. Se a autenticação ainda falhar após essa nova tentativa, resolva manualmente a divergência de token.
- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é token/senha compartilhados explícitos primeiro, depois `deviceToken` explícito, depois token de dispositivo armazenado e, por fim, token de bootstrap.
- No caminho assíncrono do Control UI via Tailscale Serve, tentativas com falha para o mesmo
`{scope, ip}` são serializadas antes de o limitador de autenticação com falha registrá-las, então
a segunda nova tentativa ruim concorrente já pode mostrar `retry later`.
- Para etapas de reparo de divergência de token, siga a [Checklist de recuperação de divergência de token](/pt-BR/cli/devices#token-drift-recovery-checklist).
- Garanta que o gateway esteja acessível (local: `openclaw status`; remoto: túnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` e então abra `http://127.0.0.1:18789/`).
- Para `AUTH_TOKEN_MISMATCH`, clientes podem fazer uma nova tentativa confiável com um token de dispositivo em cache quando o gateway retorna dicas de nova tentativa. Essa nova tentativa com token em cache reutiliza os escopos aprovados em cache do token; chamadores com `deviceToken` explícito / `scopes` explícitos mantêm o conjunto de escopos solicitado. Se a autenticação ainda falhar após essa nova tentativa, resolva a divergência de token manualmente.
- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é primeiro token/senha compartilhados explícitos, depois `deviceToken` explícito, depois token de dispositivo armazenado, depois token de bootstrap.
- No caminho assíncrono da Interface de Controle via Tailscale Serve, tentativas com falha para o mesmo
`{scope, ip}` são serializadas antes que o limitador de autenticação com falha as registre, então
a segunda nova tentativa incorreta simultânea já pode mostrar `retry later`.
- Para etapas de reparo de divergência de token, siga a [lista de verificação de recuperação de divergência de token](/pt-BR/cli/devices#token-drift-recovery-checklist).
- Recupere ou forneça o segredo compartilhado a partir do host do gateway:
- Token: `openclaw config get gateway.auth.token`
- Senha: resolva a `gateway.auth.password` configurada ou
- Senha: resolva o `gateway.auth.password` configurado ou
`OPENCLAW_GATEWAY_PASSWORD`
- Token gerenciado por SecretRef: resolva o provedor de segredo externo ou exporte
`OPENCLAW_GATEWAY_TOKEN` neste shell e depois execute `openclaw dashboard` novamente
`OPENCLAW_GATEWAY_TOKEN` neste shell, então execute novamente `openclaw dashboard`
- Nenhum segredo compartilhado configurado: `openclaw doctor --generate-gateway-token`
- Nas configurações do painel, cole o token ou a senha no campo de autenticação
e depois conecte.
- O seletor de idioma da UI está em **Overview -> Gateway Access -> Language**.
Ele faz parte do cartão de acesso, não da seção Appearance.
- Nas configurações do painel, cole o token ou a senha no campo de autenticação,
então conecte.
- O seletor de idioma da UI fica em **Visão geral -> Acesso ao Gateway -> Idioma**.
Ele faz parte do cartão de acesso, não da seção Aparência.
## Relacionado
## Relacionados
- [Control UI](/pt-BR/web/control-ui)
- [Interface de Controle](/pt-BR/web/control-ui)
- [WebChat](/pt-BR/web/webchat)