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-01 06:01:40 +00:00
parent c1609cc204
commit 92593b5ff5
27 changed files with 3982 additions and 3603 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/pt-BR/auth-credential-semantics.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Trabalhando na resolução de perfil de autenticação ou no roteamento de credenciais
- Depuração de falhas de autenticação de modelo ou da ordem dos perfis
summary: Semântica de elegibilidade e resolução de credenciais canônicas para perfis de autenticação
- Trabalhando na resolução de perfis de autenticação ou no roteamento de credenciais
- Depuração de falhas de autenticação de modelos ou da ordem de perfis
summary: Semântica canônica de elegibilidade e resolução de credenciais para perfis de autenticação
title: Semântica das credenciais de autenticação
x-i18n:
generated_at: "2026-04-30T09:34:47Z"
generated_at: "2026-05-01T05:55:08Z"
model: gpt-5.5
provider: openai
source_hash: 0525a71d3f08b7aa95e2f06acc6c23d87cd92d6b5fe4fc050ecf2b7caff84b3f
source_hash: 39b9f96159d5a7b793983d07c37a73139a0904abbbc8831267807d6acf5c0037
source_path: auth-credential-semantics.md
workflow: 16
---
@ -22,7 +22,7 @@ Este documento define a elegibilidade canônica de credenciais e a semântica de
O objetivo é manter alinhados o comportamento no momento da seleção e em tempo de execução.
## Códigos de motivo estáveis da sondagem
## Códigos de motivo estáveis de sondagem
- `ok`
- `excluded_by_auth_order`
@ -34,67 +34,68 @@ O objetivo é manter alinhados o comportamento no momento da seleção e em temp
## Credenciais de token
Credenciais de token (`type: "token"`) aceitam `token` inline e/ou `tokenRef`.
Credenciais de token (`type: "token"`) oferecem suporte a `token` inline e/ou `tokenRef`.
### Regras de elegibilidade
1. Um perfil de token é inelegível quando tanto `token` quanto `tokenRef` estão ausentes.
2. `expires` é opcional.
3. Se `expires` estiver presente, ele deve ser um número finito maior que `0`.
4. Se `expires` for inválido (`NaN`, `0`, negativo, não finito ou tipo incorreto), o perfil é inelegível com `invalid_expires`.
5. Se `expires` estiver no passado, o perfil é inelegível com `expired`.
6. `tokenRef` não contorna a validação de `expires`.
4. Se `expires` for inválido (`NaN`, `0`, negativo, não finito ou do tipo errado), o perfil será inelegível com `invalid_expires`.
5. Se `expires` estiver no passado, o perfil será inelegível com `expired`.
6. `tokenRef` não ignora a validação de `expires`.
### Regras de resolução
1. A semântica do resolvedor corresponde à semântica de elegibilidade para `expires`.
2. Para perfis elegíveis, o material do token pode ser resolvido a partir de valor inline ou de `tokenRef`.
3. Referências irresolvíveis produzem `unresolved_ref` na saída de `models status --probe`.
2. Para perfis elegíveis, o material do token pode ser resolvido a partir do valor inline ou de `tokenRef`.
3. Referências não resolvíveis produzem `unresolved_ref` na saída de `models status --probe`.
## Portabilidade de cópia de agente
A herança de autenticação do agente é de leitura passante. Quando um agente não tem perfil local, ele pode resolver perfis do armazenamento do agente padrão/principal em tempo de execução sem copiar material secreto para seu próprio `auth-profiles.json`.
A herança de autenticação de agente é feita por leitura indireta. Quando um agente não tem perfil local, ele pode resolver perfis a partir do armazenamento do agente padrão/principal em tempo de execução sem copiar material secreto para seu próprio `auth-profiles.json`.
Fluxos de cópia explícitos, como `openclaw agents add`, usam esta política de portabilidade:
- Perfis `api_key` são portáveis, a menos que `copyToAgents: false`.
- Perfis `token` são portáveis, a menos que `copyToAgents: false`.
- Perfis `oauth` não são portáveis por padrão porque tokens de atualização podem ser de uso único ou sensíveis à rotação.
- Fluxos de OAuth pertencentes a provedores podem optar por entrar com `copyToAgents: true` somente quando for comprovadamente seguro copiar material de atualização entre agentes.
- Perfis `api_key` são portáteis, a menos que `copyToAgents: false`.
- Perfis `token` são portáteis, a menos que `copyToAgents: false`.
- Perfis `oauth` não são portáteis por padrão porque tokens de atualização podem ser de uso único ou sensíveis à rotação.
- Fluxos OAuth pertencentes ao provedor podem optar por participar com `copyToAgents: true` somente quando a cópia de material de atualização entre agentes for sabidamente segura.
Perfis não portáveis continuam disponíveis por meio da herança de leitura passante, a menos que o agente de destino faça login separadamente e crie seu próprio perfil local.
Perfis não portáteis continuam disponíveis por herança de leitura indireta, a menos que o agente de destino faça login separadamente e crie seu próprio perfil local.
## Filtragem explícita de ordem de autenticação
## Filtragem explícita da ordem de autenticação
- Quando `auth.order.<provider>` ou a substituição de ordem do armazenamento de autenticação estiver definida para um provedor, `models status --probe` sonda apenas IDs de perfil que permanecem na ordem de autenticação resolvida para esse provedor.
- Quando `auth.order.<provider>` ou a substituição de ordem do armazenamento de autenticação está definida para um provedor, `models status --probe` sonda apenas IDs de perfil que permanecem na ordem de autenticação resolvida para esse provedor.
- Um perfil armazenado para esse provedor que é omitido da ordem explícita não é tentado silenciosamente depois. A saída da sondagem o relata com `reasonCode: excluded_by_auth_order` e o detalhe `Excluded by auth.order for this provider.`
## Resolução de alvo de sondagem
## Resolução do alvo da sondagem
- Alvos de sondagem podem vir de perfis de autenticação, credenciais de ambiente ou `models.json`.
- Se um provedor tem credenciais, mas o OpenClaw não consegue resolver um candidato de modelo sondável para ele, `models status --probe` relata `status: no_model` com `reasonCode: no_model`.
- Se um provedor tiver credenciais, mas o OpenClaw não conseguir resolver um candidato de modelo sondável para ele, `models status --probe` relata `status: no_model` com `reasonCode: no_model`.
## Descoberta de credenciais de CLI externa
## Descoberta de credenciais por CLI externa
- Credenciais somente de tempo de execução pertencentes a CLIs externas são descobertas apenas quando o provedor, o runtime ou o perfil de autenticação está no escopo da operação atual, ou quando um perfil local armazenado para essa fonte externa já existe.
- Caminhos somente leitura/de status passam `allowKeychainPrompt: false`; eles usam apenas credenciais de CLI externa respaldadas por arquivo e não leem nem reutilizam resultados do macOS Keychain.
- Credenciais apenas de tempo de execução pertencentes a CLIs externas são descobertas somente quando o provedor, o runtime ou o perfil de autenticação está no escopo da operação atual, ou quando um perfil local armazenado para essa origem externa já existe.
- Chamadores do armazenamento de autenticação devem escolher um modo explícito de descoberta de CLI externa: `none` para autenticação persistida/de Plugin apenas, `existing` para atualizar perfis de CLI externa já armazenados ou `scoped` para um conjunto concreto de provedor/perfil.
- Caminhos somente leitura/de status passam `allowKeychainPrompt: false`; eles usam apenas credenciais de CLI externa baseadas em arquivo e não leem nem reutilizam resultados do Keychain do macOS.
## Proteção da política de SecretRef OAuth
## Guarda de política de SecretRef para OAuth
- Entrada SecretRef é apenas para credenciais estáticas.
- Se uma credencial de perfil for `type: "oauth"`, objetos SecretRef não serão compatíveis com o material de credencial desse perfil.
- Se `auth.profiles.<id>.mode` for `"oauth"`, a entrada `keyRef`/`tokenRef` respaldada por SecretRef para esse perfil será rejeitada.
- Se a credencial de um perfil for `type: "oauth"`, objetos SecretRef não serão compatíveis com o material de credencial desse perfil.
- Se `auth.profiles.<id>.mode` for `"oauth"`, entradas `keyRef`/`tokenRef` baseadas em SecretRef para esse perfil serão rejeitadas.
- Violações são falhas rígidas nos caminhos de resolução de autenticação de inicialização/recarregamento.
## Mensagens compatíveis com legado
Para compatibilidade de scripts, erros de sondagem mantêm esta primeira linha inalterada:
Para compatibilidade com scripts, erros de sondagem mantêm esta primeira linha inalterada:
`Auth profile credentials are missing or expired.`
Detalhes amigáveis para humanos e códigos de motivo estáveis podem ser adicionados nas linhas subsequentes.
Detalhes mais amigáveis para humanos e códigos de motivo estáveis podem ser adicionados nas linhas subsequentes.
## Relacionados
## Relacionado
- [Gerenciamento de segredos](/pt-BR/gateway/secrets)
- [Armazenamento de autenticação](/pt-BR/concepts/oauth)

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

@ -1,53 +1,53 @@
---
read_when:
- Inspecionando trabalho em segundo plano em andamento ou concluído recentemente
- Depuração de falhas de entrega em execuções destacadas de agentes
- Entendendo como execuções em segundo plano se relacionam com sessões, Cron e Heartbeat
- 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
sidebarTitle: Background tasks
summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, trabalhos Cron isolados e operações da CLI
summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, tarefas Cron isoladas e operações da CLI
title: Tarefas em segundo plano
x-i18n:
generated_at: "2026-04-30T16:27:52Z"
generated_at: "2026-05-01T05:55:21Z"
model: gpt-5.5
provider: openai
source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_path: automation/tasks.md
workflow: 16
---
<Note>
Procurando agendamento? Consulte [Automação e tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página é o registro de atividades para trabalho em segundo plano, não o agendador.
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 trabalho que é executado **fora da sua sessão de conversa principal**: execuções ACP, criação de subagentes, execuções isoladas de trabalhos Cron e operações iniciadas pela CLI.
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 **não** substituem sessões, trabalhos Cron nem Heartbeats — elas são o **registro de atividades** que registra qual trabalho desconectado aconteceu, quando e se foi bem-sucedido.
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.
<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 da CLI criam.
Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat interativo normal não criam. Todas as execuções Cron, 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, todos os trabalhos 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 é 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.
- Cada tarefa passa por `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost).
- Tarefas Cron permanecem ativas enquanto o runtime Cron ainda é dono do trabalho; 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 antes de marcar uma tarefa como perdida.
- A conclusão é orientada por push: trabalho desconectado pode notificar diretamente ou acordar a
sessão/Heartbeat solicitante quando termina, então loops de polling de status
- 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
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
geralmente têm o formato errado.
- Execuções Cron isoladas e conclusões de subagentes fazem a melhor tentativa de limpar abas/processos do navegador rastreados para sua sessão filha antes da contabilidade final de limpeza.
- A entrega Cron isolada suprime respostas intermediárias obsoletas do pai enquanto o trabalho de subagente descendente ainda está esvaziando, e prefere a saída final do descendente quando ela chega antes da entrega.
- 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` revela problemas.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` expõe problemas.
- Registros terminais são mantidos por 7 dias e depois removidos automaticamente.
## Início rápido
<Tabs>
<Tab title="List and filter">
<Tab title="Listar e filtrar">
```bash
# List all tasks (newest first)
openclaw tasks list
@ -58,13 +58,13 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
```
</Tab>
<Tab title="Inspect">
<Tab title="Inspecionar">
```bash
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>
```
</Tab>
<Tab title="Cancel and notify">
<Tab title="Cancelar e notificar">
```bash
# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>
@ -74,7 +74,7 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
```
</Tab>
<Tab title="Audit and maintenance">
<Tab title="Auditoria e manutenção">
```bash
# Run a health audit
openclaw tasks audit
@ -85,7 +85,7 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
```
</Tab>
<Tab title="Task flow">
<Tab title="Fluxo de tarefas">
```bash
# Inspect TaskFlow state
openclaw tasks flow list
@ -97,25 +97,25 @@ 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 de notificação padrão |
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política padrão de notificação |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Execuções em segundo plano ACP | `acp` | Ao criar uma sessão ACP filha | `done_only` |
| Orquestração de subagentes | `subagent` | Ao criar um subagente via `sessions_spawn` | `done_only` |
| Trabalhos Cron (todos os tipos) | `cron` | Toda execução Cron (sessão principal e isolada) | `silent` |
| Operações da CLI | `cli` | Comandos `openclaw agent` que são executados pelo Gateway | `silent` |
| Trabalhos de mídia do agente | `cli` | Execuções `video_generate` respaldadas por sessão | `silent` |
| Execuções em segundo plano ACP | `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` |
| Jobs de mídia do agente | `cli` | Execuções `music_generate`/`video_generate` apoiadas por sessão | `silent` |
<AccordionGroup>
<Accordion title="Notify defaults for cron and media">
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 são executadas em sua própria sessão.
<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.
Execuções `video_generate` respaldadas 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 o vídeo finalizado por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta no canal antes de recorrer ao 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 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.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
Enquanto uma tarefa `video_generate` respaldada 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 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>
<Accordion title="What does not create tasks">
<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`
@ -137,56 +137,56 @@ 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á em execução ativa |
| `succeeded` | Concluída com sucesso |
| `failed` | Concluída com erro |
| `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 |
| `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 |
Transições acontecem automaticamente — quando a execução de agente associada termina, o status da tarefa é atualizado para corresponder.
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 desconectada bem-sucedida é finalizada como `succeeded`, erros comuns de execução são finalizados como `failed`, e resultados de timeout ou abort são finalizados 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 de sucesso posterior não rebaixa esse status terminal.
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.
`lost` considera o runtime:
`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 trabalho como ativo e o histórico durável de
execuções Cron não mostra um resultado terminal para essa execução. Auditoria da CLI offline
- 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 isoladas de sessão filha usam a sessão filha; tarefas da CLI respaldadas por chat
usam o contexto de execução ao vivo em vez disso, então linhas persistentes de
sessão de canal/grupo/direta não as mantêm vivas. Execuções `openclaw agent`
respaldadas pelo Gateway também são finalizadas a partir do resultado da execução, então execuções concluídas
- 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`.
## Entrega e notificações
Quando uma tarefa chega a um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
**Entrega direta** — se a tarefa tiver um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai direto 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 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 enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo Heartbeat.
**Entrega enfileirada na sessão** — se a entrega direta 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.
<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.
</Tip>
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho desconectado uma vez e então deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa por polling apenas 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 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.
### 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) | Apenas estado terminal (succeeded, failed etc.) — **este é o padrão** |
| `state_changes` | Toda transição de estado e atualização de progresso |
| `silent` | Nada |
| `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 |
| `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á identificador separado de runtime filho). O status muda 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á handle separado de runtime filho). O status transita 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]
```
Revela problemas operacionais. Achados também aparecem em `openclaw status` quando problemas são detectados.
Expõe problemas operacionais. Constatações também aparecem em `openclaw status` quando problemas são detectados.
| Constatação | Gravidade | Acionador |
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | warn | Na fila por mais de 10 minutos |
| `stale_running` | error | Em execução por mais de 30 minutos |
| `lost` | warn/error | A propriedade da tarefa apoiada pelo runtime desapareceu; tarefas perdidas retidas avisam até `cleanupAfter` e 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) |
| 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) |
</Accordion>
<Accordion title="manutenção de tarefas">
@ -249,32 +249,32 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e estado do Task Flow.
Use isto para visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e estado do TaskFlow.
A reconciliação reconhece o runtime:
A reconciliação é ciente de runtime:
- Tarefas ACP/subagent verificam a sessão filha que as sustenta.
- Tarefas subagent cuja sessão filha tem uma lápide de recuperação de reinício são marcadas como perdidas, em vez de serem tratadas como sessões de sustentação recuperáveis.
- Tarefas Cron verificam se o runtime cron ainda é proprietário do trabalho e então recuperam o status terminal de logs de execução cron persistidos/estado do trabalho antes de recorrer a `lost`. Somente o processo Gateway é autoritativo para o conjunto em memória de trabalhos cron ativos; 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.
- Tarefas 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.
A limpeza de conclusão também reconhece o runtime:
A limpeza de conclusão também é ciente de runtime:
- A conclusão de subagent 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 cron antes que a execução seja totalmente encerrada.
- A entrega de cron isolado aguarda o acompanhamento de subagent descendente quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
- A entrega de conclusão de subagent prefere o texto de assistente visível mais recente; se estiver vazio, recorre ao texto sanitizado mais recente de ferramenta/toolResult, e execuções de chamada de ferramenta apenas com 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.
- 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.
- Falhas de limpeza não mascaram o resultado real da tarefa.
</Accordion>
<Accordion title="listar | mostrar | cancelar fluxo de tarefas">
<Accordion title="tasks flow list | show | cancel">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Use estes comandos quando o Task Flow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano.
Use estes quando o TaskFlow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano.
</Accordion>
</AccordionGroup>
@ -283,7 +283,7 @@ openclaw tasks notify <lookup> state_changes
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.
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 às 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`.
@ -301,7 +301,7 @@ O resumo informa:
- **failures** — contagem de `failed` + `timed_out` + `lost`
- **byRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli`
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas são ocultadas, e falhas recentes só aparecem quando não há mais trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas 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.
## Armazenamento e manutenção
@ -314,7 +314,8 @@ $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 write-ahead do SQLite limitado usando o limite padrão de autocheckpoint do SQLite, além de checkpoints periódicos e de desligamento `TRUNCATE`.
O Gateway mantém o log de gravação antecipada do SQLite limitado usando o limite padrão de
autocheckpoint do SQLite mais checkpoints `TRUNCATE` periódicos e no desligamento.
### Manutenção automática
@ -322,13 +323,13 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
<Steps>
<Step title="Reconciliação">
Verifica se tarefas ativas ainda têm sustentação autoritativa do runtime. Tarefas ACP/subagent usam o estado da sessão filha, tarefas cron usam propriedade de trabalho ativo, e tarefas da CLI apoiadas por chat usam o contexto de execução proprietário. Se esse estado de sustentação desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
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`.
</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 nenhuma vinculação de conversa ativa.
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.
</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 os metadados de limpeza estão ausentes, elas são erros.
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`.
@ -336,26 +337,26 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
</Steps>
<Note>
**Retenção:** registros de tarefas terminais são mantidos por **7 dias** e depois automaticamente podados. Nenhuma configuração necessária.
**Retenção:** registros de tarefas terminais são mantidos por **7 dias** e depois podados automaticamente. Nenhuma configuração necessária.
</Note>
## Como tarefas se relacionam com outros sistemas
## Como as tarefas se relacionam com outros sistemas
<AccordionGroup>
<Accordion title="Tarefas e Task Flow">
[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo orquestrador.
<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.
Consulte [Task Flow](/pt-BR/automation/taskflow) para obter detalhes.
Consulte [TaskFlow](/pt-BR/automation/taskflow) para detalhes.
</Accordion>
<Accordion title="Tarefas e cron">
Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução do runtime fica ao lado, em `~/.openclaw/cron/jobs-state.json`. **Toda** execução cron cria um registro de tarefa, tanto de sessão principal quanto isolada. Tarefas cron de sessão principal usam por padrão a política de notificação `silent`, para que sejam rastreadas sem gerar notificações.
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.
Consulte [Cron Jobs](/pt-BR/automation/cron-jobs).
</Accordion>
<Accordion title="Tarefas e Heartbeat">
Execuções de Heartbeat são turnos da sessão principal; elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um despertar de Heartbeat para que você veja o resultado prontamente.
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.
Consulte [Heartbeat](/pt-BR/gateway/heartbeat).
@ -364,14 +365,14 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
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.
</Accordion>
<Accordion title="Tarefas e execuções de agente">
O `runId` de uma tarefa vincula à execução do 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.
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.
</Accordion>
</AccordionGroup>
## Relacionados
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em uma visão rápida
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo
- [CLI: Tarefas](/pt-BR/cli/tasks) — referência de comandos da CLI
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal
- [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
- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxos acima de tarefas
- [TaskFlow](/pt-BR/automation/taskflow) — orquestração de fluxo acima das tarefas

249
docs/pt-BR/channels/bluebubbles.md
View File

@ -2,47 +2,47 @@
read_when:
- Configurando o canal BlueBubbles
- Solução de problemas de pareamento de Webhook
- Configurando o iMessage no macOS
- Configurando iMessage no macOS
sidebarTitle: BlueBubbles
summary: iMessage via servidor macOS BlueBubbles (envio/recebimento REST, digitação, reações, pareamento, ações avançadas).
summary: iMessage via servidor macOS do BlueBubbles (envio/recebimento REST, digitação, reações, pareamento, ações avançadas).
title: BlueBubbles
x-i18n:
generated_at: "2026-04-30T09:35:10Z"
generated_at: "2026-05-01T05:55:15Z"
model: gpt-5.5
provider: openai
source_hash: 7a77b248ed86eb4114f8b7f1fc6bd4cea004d65095a0439a4a8c814bc180082c
source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145
source_path: channels/bluebubbles.md
workflow: 16
---
Status: Plugin incluído que se comunica com o servidor BlueBubbles macOS por HTTP. **Recomendado para integração com iMessage** devido à sua API mais rica e à configuração mais fácil em comparação com o canal imsg legado.
Status: Plugin empacotado que se comunica com o servidor macOS BlueBubbles por HTTP. **Recomendado para integração com iMessage** devido à sua API mais rica e configuração mais fácil em comparação com o canal imsg legado.
<Note>
As versões atuais do OpenClaw incluem o BlueBubbles, portanto builds empacotadas normais não precisam de uma etapa separada de `openclaw plugins install`.
As versões atuais do OpenClaw incluem o BlueBubbles, portanto builds empacotados normais não precisam de uma etapa separada de `openclaw plugins install`.
</Note>
## Visão geral
- Executa no macOS por meio do app auxiliar BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
- Recomendado/testado: macOS Sequoia (15). macOS Tahoe (26) funciona; a edição está quebrada no Tahoe no momento, e atualizações de ícone de grupo podem relatar sucesso, mas não sincronizar.
- O OpenClaw se comunica com ele por meio da sua API REST (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Mensagens recebidas chegam via webhooks; respostas enviadas, indicadores de digitação, confirmações de leitura e tapbacks são chamadas REST.
- Anexos e figurinhas são ingeridos como mídia de entrada (e expostos ao agente quando possível).
- Respostas Auto-TTS que sintetizam áudio MP3 ou CAF são entregues como bolhas de memo de voz do iMessage em vez de anexos de arquivo simples.
- Emparelhamento/lista de permissões funciona da mesma forma que outros canais (`/channels/pairing` etc.) com `channels.bluebubbles.allowFrom` + códigos de emparelhamento.
- Reações são expostas como eventos de sistema, assim como no Slack/Telegram, para que agentes possam "mencioná-las" antes de responder.
- Recomendado/testado: macOS Sequoia (15). macOS Tahoe (26) funciona; a edição está atualmente quebrada no Tahoe, e atualizações de ícone de grupo podem relatar sucesso, mas não sincronizar.
- O OpenClaw se comunica com ele por meio da API REST (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Mensagens recebidas chegam por webhooks; respostas enviadas, indicadores de digitação, confirmações de leitura e tapbacks são chamadas REST.
- Anexos e stickers são ingeridos como mídia de entrada (e expostos ao agente quando possível).
- Respostas Auto-TTS que sintetizam áudio MP3 ou CAF são entregues como bolhas de memorando de voz do iMessage em vez de anexos de arquivo simples.
- O pareamento/lista de permissões funciona da mesma forma que outros canais (`/channels/pairing` etc.) com `channels.bluebubbles.allowFrom` + códigos de pareamento.
- Reações são expostas como eventos do sistema, assim como Slack/Telegram, para que agentes possam "mencioná-las" antes de responder.
- Recursos avançados: editar, desfazer envio, encadeamento de respostas, efeitos de mensagem, gerenciamento de grupos.
## Início rápido
<Steps>
<Step title="Instale o BlueBubbles">
<Step title="Install BlueBubbles">
Instale o servidor BlueBubbles no seu Mac (siga as instruções em [bluebubbles.app/install](https://bluebubbles.app/install)).
</Step>
<Step title="Ative a API web">
Na configuração do BlueBubbles, ative a API web e defina uma senha.
<Step title="Enable the web API">
Na configuração do BlueBubbles, habilite a API web e defina uma senha.
</Step>
<Step title="Configure o OpenClaw">
<Step title="Configure OpenClaw">
Execute `openclaw onboard` e selecione BlueBubbles, ou configure manualmente:
```json5
@ -59,29 +59,29 @@ As versões atuais do OpenClaw incluem o BlueBubbles, portanto builds empacotada
```
</Step>
<Step title="Aponte os webhooks para o gateway">
<Step title="Point webhooks at the gateway">
Aponte os webhooks do BlueBubbles para o seu gateway (exemplo: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
</Step>
<Step title="Inicie o gateway">
Inicie o gateway; ele registrará o manipulador de webhook e começará o emparelhamento.
<Step title="Start the gateway">
Inicie o Gateway; ele registrará o manipulador de Webhook e começará o pareamento.
</Step>
</Steps>
<Warning>
**Segurança**
- Sempre defina uma senha de webhook.
- A autenticação de webhook é sempre obrigatória. O OpenClaw rejeita solicitações de webhook do BlueBubbles a menos que incluam uma senha/guid que corresponda a `channels.bluebubbles.password` (por exemplo, `?password=<password>` ou `x-password`), independentemente da topologia de loopback/proxy.
- A autenticação por senha é verificada antes da leitura/análise dos corpos completos de webhook.
- Sempre defina uma senha de Webhook.
- A autenticação de Webhook é sempre obrigatória. O OpenClaw rejeita solicitações de Webhook do BlueBubbles a menos que incluam uma senha/guid que corresponda a `channels.bluebubbles.password` (por exemplo, `?password=<password>` ou `x-password`), independentemente da topologia de loopback/proxy.
- A autenticação por senha é verificada antes da leitura/análise dos corpos completos de Webhook.
</Warning>
## Mantendo o Mensagens.app ativo (VM / configurações headless)
## Mantendo o Messages.app ativo (VM / configurações headless)
Algumas configurações de VM macOS / sempre ativas podem acabar com o Mensagens.app ficando "ocioso" (eventos recebidos param até que o app seja aberto/trazido para primeiro plano). Uma solução simples é **acionar o Mensagens a cada 5 minutos** usando um AppleScript + LaunchAgent.
Algumas configurações de VM macOS / sempre ativas podem acabar com o Messages.app ficando "ocioso" (eventos recebidos param até que o app seja aberto/trazido para primeiro plano). Uma solução simples é **cutucar o Messages a cada 5 minutos** usando um AppleScript + LaunchAgent.
<Steps>
<Step title="Salve o AppleScript">
<Step title="Save the AppleScript">
Salve isto como `~/Scripts/poke-messages.scpt`:
```applescript
@ -100,7 +100,7 @@ Algumas configurações de VM macOS / sempre ativas podem acabar com o Mensagens
```
</Step>
<Step title="Instale um LaunchAgent">
<Step title="Install a LaunchAgent">
Salve isto como `~/Library/LaunchAgents/com.user.poke-messages.plist`:
```xml
@ -132,10 +132,10 @@ Algumas configurações de VM macOS / sempre ativas podem acabar com o Mensagens
</plist>
```
Isso executa **a cada 300 segundos** e **ao fazer login**. A primeira execução pode acionar prompts de **Automação** do macOS (`osascript` → Messages). Aprove-os na mesma sessão de usuário que executa o LaunchAgent.
Isso executa **a cada 300 segundos** e **no login**. A primeira execução pode acionar prompts de **Automação** do macOS (`osascript` → Messages). Aprove-os na mesma sessão de usuário que executa o LaunchAgent.
</Step>
<Step title="Carregue-o">
<Step title="Load it">
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
@ -145,7 +145,7 @@ Algumas configurações de VM macOS / sempre ativas podem acabar com o Mensagens
## Onboarding
O BlueBubbles está disponível no onboarding interativo:
BlueBubbles está disponível no onboarding interativo:
```
openclaw onboard
@ -160,7 +160,7 @@ O assistente solicita:
Senha da API das configurações do BlueBubbles Server.
</ParamField>
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
Caminho do endpoint de webhook.
Caminho do endpoint de Webhook.
</ParamField>
<ParamField path="DM policy" type="string">
`pairing`, `allowlist`, `open` ou `disabled`.
@ -180,27 +180,27 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
<Tabs>
<Tab title="DMs">
- Padrão: `channels.bluebubbles.dmPolicy = "pairing"`.
- Remetentes desconhecidos recebem um código de emparelhamento; mensagens são ignoradas até serem aprovadas (códigos expiram após 1 hora).
- Remetentes desconhecidos recebem um código de pareamento; as mensagens são ignoradas até a aprovação (os códigos expiram após 1 hora).
- Aprove via:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- Emparelhamento é a troca de token padrão. Detalhes: [Emparelhamento](/pt-BR/channels/pairing)
- O pareamento é a troca de tokens padrão. Detalhes: [Pareamento](/pt-BR/channels/pairing)
</Tab>
<Tab title="Grupos">
<Tab title="Groups">
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (padrão: `allowlist`).
- `channels.bluebubbles.groupAllowFrom` controla quem pode acionar em grupos quando `allowlist` está definido.
</Tab>
</Tabs>
### Enriquecimento de nomes de contatos (macOS, opcional)
### Enriquecimento de nome de contato (macOS, opcional)
Webhooks de grupo do BlueBubbles frequentemente incluem apenas endereços brutos dos participantes. Se você quiser que o contexto `GroupMembers` mostre nomes de contatos locais em vez disso, pode optar pelo enriquecimento local de Contatos no macOS:
Webhooks de grupo do BlueBubbles muitas vezes incluem apenas endereços brutos dos participantes. Se você quiser que o contexto `GroupMembers` mostre nomes de contatos locais em vez disso, pode optar pelo enriquecimento local de Contatos no macOS:
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` ativa a busca. Padrão: `false`.
- As buscas são executadas somente depois que o acesso ao grupo, a autorização de comando e o gating de menção permitiram a passagem da mensagem.
- Somente participantes por telefone sem nome são enriquecidos.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` habilita a consulta. Padrão: `false`.
- As consultas são executadas somente depois que o acesso ao grupo, a autorização de comando e o gating de menção permitirem a passagem da mensagem.
- Somente participantes de telefone sem nome são enriquecidos.
- Números de telefone brutos permanecem como fallback quando nenhuma correspondência local é encontrada.
```json5
@ -215,10 +215,10 @@ Webhooks de grupo do BlueBubbles frequentemente incluem apenas endereços brutos
### Gating de menção (grupos)
O BlueBubbles oferece suporte a gating de menção para chats em grupo, correspondendo ao comportamento do iMessage/WhatsApp:
BlueBubbles oferece suporte a gating de menção para chats em grupo, correspondendo ao comportamento do iMessage/WhatsApp:
- Usa `agents.list[].groupChat.mentionPatterns` (ou `messages.groupChat.mentionPatterns`) para detectar menções.
- Quando `requireMention` está ativado para um grupo, o agente responde somente quando mencionado.
- Quando `requireMention` está habilitado para um grupo, o agente responde somente quando mencionado.
- Comandos de controle de remetentes autorizados ignoram o gating de menção.
Configuração por grupo:
@ -246,7 +246,7 @@ Configuração por grupo:
### Prompt de sistema por grupo
Cada entrada em `channels.bluebubbles.groups.*` aceita uma string `systemPrompt` opcional. O valor é injetado no prompt de sistema do agente em cada turno que trata uma mensagem nesse grupo, para que você possa definir persona ou regras comportamentais por grupo sem editar prompts de agentes:
Cada entrada em `channels.bluebubbles.groups.*` aceita uma string opcional `systemPrompt`. O valor é injetado no prompt de sistema do agente em cada turno que processa uma mensagem nesse grupo, para que você possa definir persona ou regras comportamentais por grupo sem editar prompts do agente:
```json5
{
@ -262,11 +262,11 @@ Cada entrada em `channels.bluebubbles.groups.*` aceita uma string `systemPrompt`
}
```
A chave corresponde ao que o BlueBubbles relata como `chatGuid` / `chatIdentifier` / `chatId` numérico para o grupo, e uma entrada curinga `"*"` fornece um padrão para todos os grupos sem correspondência exata (o mesmo padrão usado por `requireMention` e políticas de ferramentas por grupo). Correspondências exatas sempre prevalecem sobre o curinga. DMs ignoram este campo; use personalização de prompt no nível do agente ou da conta em vez disso.
A chave corresponde a qualquer valor que o BlueBubbles relate como `chatGuid` / `chatIdentifier` / `chatId` numérico para o grupo, e uma entrada curinga `"*"` fornece um padrão para todos os grupos sem uma correspondência exata (o mesmo padrão usado por `requireMention` e políticas de ferramentas por grupo). Correspondências exatas sempre vencem o curinga. DMs ignoram esse campo; use personalização de prompt no nível do agente ou da conta em vez disso.
#### Exemplo completo: respostas encadeadas e reações tapback (API privada)
#### Exemplo prático: respostas encadeadas e reações tapback (API privada)
Com a API privada do BlueBubbles ativada, mensagens recebidas chegam com IDs curtos de mensagem (por exemplo, `[[reply_to:5]]`) e o agente pode chamar `action=reply` para encadear em uma mensagem específica ou `action=react` para enviar um tapback. Um `systemPrompt` por grupo é uma forma confiável de manter o agente escolhendo a ferramenta certa:
Com a API privada do BlueBubbles habilitada, mensagens de entrada chegam com IDs curtos de mensagem (por exemplo, `[[reply_to:5]]`) e o agente pode chamar `action=reply` para encadear em uma mensagem específica ou `action=react` para enviar um tapback. Um `systemPrompt` por grupo é uma forma confiável de manter o agente escolhendo a ferramenta certa:
```json5
{
@ -292,18 +292,18 @@ Com a API privada do BlueBubbles ativada, mensagens recebidas chegam com IDs cur
Reações tapback e respostas encadeadas exigem a API privada do BlueBubbles; consulte [Ações avançadas](#advanced-actions) e [IDs de mensagem](#message-ids-short-vs-full) para a mecânica subjacente.
## Vinculações de conversa ACP
## Associações de conversas ACP
Chats do BlueBubbles podem ser transformados em workspaces ACP duráveis sem alterar a camada de transporte.
Fluxo rápido do operador:
- Execute `/acp spawn codex --bind here` dentro da DM ou do chat em grupo permitido.
- Mensagens futuras nessa mesma conversa BlueBubbles são roteadas para a sessão ACP criada.
- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no local.
- `/acp close` fecha a sessão ACP e remove a vinculação.
- Execute `/acp spawn codex --bind here` dentro da DM ou chat em grupo permitido.
- Mensagens futuras nessa mesma conversa do BlueBubbles são roteadas para a sessão ACP gerada.
- `/new` e `/reset` redefinem a mesma sessão ACP associada no lugar.
- `/acp close` fecha a sessão ACP e remove a associação.
Vinculações persistentes configuradas também são compatíveis por meio de entradas `bindings[]` de nível superior com `type: "acp"` e `match.channel: "bluebubbles"`.
Associações persistentes configuradas também são compatíveis por meio de entradas `bindings[]` de nível superior com `type: "acp"` e `match.channel: "bluebubbles"`.
`match.peer.id` pode usar qualquer forma de destino BlueBubbles compatível:
@ -312,7 +312,7 @@ Vinculações persistentes configuradas também são compatíveis por meio de en
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
Para vinculações de grupo estáveis, prefira `chat_id:*` ou `chat_identifier:*`.
Para associações estáveis de grupo, prefira `chat_id:*` ou `chat_identifier:*`.
Exemplo:
@ -344,13 +344,13 @@ Exemplo:
}
```
Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para o comportamento compartilhado de vinculação ACP.
Consulte [Agentes ACP](/pt-BR/tools/acp-agents) para o comportamento compartilhado de associação ACP.
## Digitação + confirmações de leitura
- **Indicadores de digitação**: Enviados automaticamente antes e durante a geração da resposta.
- **Confirmações de leitura**: Controladas por `channels.bluebubbles.sendReadReceipts` (padrão: `true`).
- **Indicadores de digitação**: O OpenClaw envia eventos de início de digitação; o BlueBubbles limpa a digitação automaticamente ao enviar ou por timeout (a parada manual via DELETE não é confiável).
- **Indicadores de digitação**: O OpenClaw envia eventos de início de digitação; o BlueBubbles limpa a digitação automaticamente ao enviar ou ao atingir o tempo limite (a parada manual via DELETE não é confiável).
```json5
{
@ -390,30 +390,30 @@ O BlueBubbles oferece suporte a ações avançadas de mensagem quando habilitada
<AccordionGroup>
<Accordion title="Available actions">
- **react**: Adiciona/remove reações tapback (`messageId`, `emoji`, `remove`). O conjunto nativo de tapbacks do iMessage é `love`, `like`, `dislike`, `laugh`, `emphasize` e `question`. Quando um agente escolhe um emoji fora desse conjunto (por exemplo, `👀`), a ferramenta de reação recorre a `love` para que o tapback ainda seja renderizado em vez de falhar a solicitação inteira. Reações de confirmação configuradas ainda são validadas estritamente e geram erro para valores desconhecidos.
- **edit**: Edita uma mensagem enviada (`messageId`, `text`).
- **unsend**: Cancela o envio de uma mensagem (`messageId`).
- **reply**: Responde a uma mensagem específica (`messageId`, `text`, `to`).
- **sendWithEffect**: Envia com efeito do iMessage (`text`, `to`, `effectId`).
- **renameGroup**: Renomeia uma conversa em grupo (`chatGuid`, `displayName`).
- **setGroupIcon**: Define o ícone/foto de uma conversa em grupo (`chatGuid`, `media`) — instável no macOS 26 Tahoe (a API pode retornar sucesso, mas o ícone não sincroniza).
- **addParticipant**: Adiciona alguém a um grupo (`chatGuid`, `address`).
- **removeParticipant**: Remove alguém de um grupo (`chatGuid`, `address`).
- **leaveGroup**: Sai de uma conversa em grupo (`chatGuid`).
- **upload-file**: Envia mídia/arquivos (`to`, `buffer`, `filename`, `asVoice`).
- Mensagens de voz: defina `asVoice: true` com áudio **MP3** ou **CAF** para enviar como mensagem de voz do iMessage. O BlueBubbles converte MP3 → CAF ao enviar mensagens de voz.
- **react**: Adicionar/remover reações tapback (`messageId`, `emoji`, `remove`). O conjunto nativo de tapbacks do iMessage é `love`, `like`, `dislike`, `laugh`, `emphasize` e `question`. Quando um agente escolhe um emoji fora desse conjunto (por exemplo, `👀`), a ferramenta de reação recorre a `love` para que o tapback ainda seja renderizado em vez de falhar a solicitação inteira. Reações de confirmação configuradas ainda são validadas estritamente e geram erro em valores desconhecidos.
- **edit**: Editar uma mensagem enviada (`messageId`, `text`).
- **unsend**: Desfazer o envio de uma mensagem (`messageId`).
- **reply**: Responder a uma mensagem específica (`messageId`, `text`, `to`).
- **sendWithEffect**: Enviar com efeito do iMessage (`text`, `to`, `effectId`).
- **renameGroup**: Renomear uma conversa em grupo (`chatGuid`, `displayName`).
- **setGroupIcon**: Definir o ícone/foto de uma conversa em grupo (`chatGuid`, `media`) — instável no macOS 26 Tahoe (a API pode retornar sucesso, mas o ícone não sincroniza).
- **addParticipant**: Adicionar alguém a um grupo (`chatGuid`, `address`).
- **removeParticipant**: Remover alguém de um grupo (`chatGuid`, `address`).
- **leaveGroup**: Sair de uma conversa em grupo (`chatGuid`).
- **upload-file**: Enviar mídia/arquivos (`to`, `buffer`, `filename`, `asVoice`).
- Memos de voz: defina `asVoice: true` com áudio **MP3** ou **CAF** para enviar como uma mensagem de voz do iMessage. O BlueBubbles converte MP3 → CAF ao enviar memos de voz.
- Alias legado: `sendAttachment` ainda funciona, mas `upload-file` é o nome canônico da ação.
</Accordion>
</AccordionGroup>
### IDs de mensagem (curto vs completo)
### IDs de mensagem (curtos vs. completos)
O OpenClaw pode expor IDs de mensagem _curtos_ (por exemplo, `1`, `2`) para economizar tokens.
- `MessageSid` / `ReplyToId` podem ser IDs curtos.
- `MessageSidFull` / `ReplyToIdFull` contêm os IDs completos do provedor.
- IDs curtos ficam em memória; eles podem expirar ao reiniciar ou por remoção do cache.
- IDs curtos ficam em memória; podem expirar ao reiniciar ou com a remoção do cache.
- Ações aceitam `messageId` curto ou completo, mas IDs curtos gerarão erro se não estiverem mais disponíveis.
Use IDs completos para automações e armazenamento duráveis:
@ -425,29 +425,29 @@ Consulte [Configuração](/pt-BR/gateway/configuration) para variáveis de model
<a id="coalescing-split-send-dms-command--url-in-one-composition"></a>
## Coalescência de DMs de envio dividido (comando + URL em uma composição)
## Mesclagem de DMs com envio dividido (comando + URL em uma composição)
Quando um usuário digita um comando e uma URL juntos no iMessage — por exemplo, `Dump https://example.com/article` — a Apple divide o envio em **duas entregas de Webhook separadas**:
Quando um usuário digita um comando e uma URL juntos no iMessage — por exemplo, `Dump https://example.com/article` — a Apple divide o envio em **duas entregas de webhook separadas**:
1. Uma mensagem de texto (`"Dump"`).
2. Um balão de pré-visualização de URL (`"https://..."`) com imagens de pré-visualização OG como anexos.
Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem coalescência, o agente recebe apenas o comando no turno 1, responde (frequentemente "envie a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido.
Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das configurações. Sem mesclagem, o agente recebe apenas o comando no turno 1, responde (geralmente "envie a URL") e só vê a URL no turno 2 — momento em que o contexto do comando já foi perdido.
`channels.bluebubbles.coalesceSameSenderDms` opta por mesclar webhooks consecutivos do mesmo remetente em uma DM em um único turno do agente. Conversas em grupo continuam usando chave por mensagem, preservando a estrutura de turnos com vários usuários.
`channels.bluebubbles.coalesceSameSenderDms` opta por mesclar webhooks consecutivos do mesmo remetente em uma DM em um único turno do agente. Conversas em grupo continuam a usar chave por mensagem para preservar a estrutura de turnos de vários usuários.
<Tabs>
<Tab title="When to enable">
Habilite quando:
- Você entrega Skills que esperam `command + payload` em uma mensagem (dump, paste, save, queue etc.).
- Você entrega skills que esperam `command + payload` em uma mensagem (dump, colar, salvar, enfileirar etc.).
- Seus usuários colam URLs, imagens ou conteúdo longo junto com comandos.
- Você pode aceitar a latência adicional no turno da DM (veja abaixo).
- Você pode aceitar a latência adicional no turno de DM (veja abaixo).
Deixe desabilitado quando:
- Você precisa de latência mínima de comando para acionadores de DM de uma única palavra.
- Todos os seus fluxos são comandos pontuais sem payloads subsequentes.
- Você precisa de latência mínima de comando para gatilhos de DM de uma única palavra.
- Todos os seus fluxos são comandos únicos sem payloads subsequentes.
</Tab>
<Tab title="Enabling">
@ -461,7 +461,7 @@ Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das
}
```
Com a flag ativada e sem `messages.inbound.byChannel.bluebubbles` explícito, a janela de debounce aumenta para **2500 ms** (o padrão sem coalescência é 500 ms). A janela mais ampla é necessária — a cadência de envio dividido da Apple, de 0,8-2,0 s, não cabe no padrão mais estreito.
Com a flag ativada e sem `messages.inbound.byChannel.bluebubbles` explícito, a janela de debounce aumenta para **2500 ms** (o padrão sem mesclagem é 500 ms). A janela maior é necessária — a cadência de envio dividido da Apple, de 0,8-2,0 s, não cabe no padrão mais estreito.
Para ajustar a janela por conta própria:
@ -481,25 +481,25 @@ Os dois webhooks chegam ao OpenClaw com ~0,8-2,0 s de diferença na maioria das
</Tab>
<Tab title="Trade-offs">
- **Latência adicional para comandos de controle em DM.** Com a flag ativada, mensagens de comando de controle em DM (como `Dump`, `Save` etc.) agora aguardam até a janela de debounce antes do despacho, caso um Webhook de payload esteja chegando. Comandos em conversas em grupo mantêm despacho instantâneo.
- **A saída mesclada tem limites** — o texto mesclado é limitado a 4000 caracteres com um marcador explícito `…[truncated]`; anexos são limitados a 20; entradas de origem são limitadas a 10 (a primeira e as mais recentes são mantidas além disso). Cada `messageId` de origem ainda chega à desduplicação de entrada, portanto uma repetição posterior do MessagePoller de qualquer evento individual é reconhecida como duplicata.
- **Opt-in, por canal.** Outros canais (Telegram, WhatsApp, Slack, …) não são afetados.
- **Latência adicional para comandos de controle de DM.** Com a flag ativada, mensagens de comando de controle em DM (como `Dump`, `Save` etc.) agora aguardam até a janela de debounce antes do despacho, caso um webhook de payload esteja chegando. Comandos em conversas de grupo mantêm despacho instantâneo.
- **A saída mesclada é limitada** — o texto mesclado tem limite de 4000 caracteres com um marcador explícito `…[truncated]`; anexos têm limite de 20; entradas de origem têm limite de 10 (a primeira e a mais recente são mantidas além disso). Cada `messageId` de origem ainda chega à desduplicação de entrada, então uma reprodução posterior do MessagePoller de qualquer evento individual é reconhecida como duplicada.
- **Opcional, por canal.** Outros canais (Telegram, WhatsApp, Slack, …) não são afetados.
</Tab>
</Tabs>
### Cenários e o que o agente vê
| O usuário compõe | A Apple entrega | Flag desativada (padrão) | Flag ativada + janela de 2500 ms |
| ------------------------------------------------------------------- | -------------------------- | --------------------------------------------- | --------------------------------------------------------------------- |
| `Dump https://example.com` (um envio) | 2 webhooks com ~1 s entre eles | Dois turnos do agente: "Dump" sozinho, depois URL | Um turno: texto mesclado `Dump https://example.com` |
| `Save this 📎image.jpg caption` (anexo + texto) | 2 webhooks | Dois turnos | Um turno: texto + imagem |
| `/status` (comando autônomo) | 1 Webhook | Despacho instantâneo | **Aguarda até a janela e então despacha** |
| URL colada sozinha | 1 Webhook | Despacho instantâneo | Despacho instantâneo (apenas uma entrada no bucket) |
| Texto + URL enviados como duas mensagens separadas intencionais, com minutos entre elas | 2 webhooks fora da janela | Dois turnos | Dois turnos (a janela expira entre eles) |
| Enxurrada rápida (>10 DMs pequenas dentro da janela) | N webhooks | N turnos | Um turno, saída limitada (primeira + mais recentes, limites de texto/anexo aplicados) |
| Usuário compõe | Apple entrega | Flag desativada (padrão) | Flag ativada + janela de 2500 ms |
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
| `Dump https://example.com` (um envio) | 2 webhooks com ~1 s entre eles | Dois turnos do agente: "Dump" sozinho, depois URL | Um turno: texto mesclado `Dump https://example.com` |
| `Save this 📎image.jpg caption` (anexo + texto) | 2 webhooks | Dois turnos | Um turno: texto + imagem |
| `/status` (comando independente) | 1 webhook | Despacho instantâneo | **Aguarda até a janela e então despacha** |
| URL colada sozinha | 1 webhook | Despacho instantâneo | Despacho instantâneo (apenas uma entrada no bucket) |
| Texto + URL enviados como duas mensagens separadas deliberadas, com minutos de diferença | 2 webhooks fora da janela | Dois turnos | Dois turnos (a janela expira entre eles) |
| Enxurrada rápida (>10 DMs pequenas dentro da janela) | N webhooks | N turnos | Um turno, saída limitada (primeira + mais recente, limites de texto/anexo aplicados) |
### Solução de problemas de coalescência de envio dividido
### Solução de problemas da mesclagem de envio dividido
Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, verifique cada camada:
@ -509,11 +509,11 @@ Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, ve
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
```
Depois `openclaw gateway restart` — a flag é lida na criação do registro de debouncers.
Em seguida, `openclaw gateway restart` — a flag é lida na criação do registro do debouncer.
</Accordion>
<Accordion title="Debounce window wide enough for your setup">
Veja o log do servidor BlueBubbles em `~/Library/Logs/bluebubbles-server/main.log`:
Consulte o log do servidor BlueBubbles em `~/Library/Logs/bluebubbles-server/main.log`:
```
grep -E "Dispatching event to webhook" main.log | tail -20
@ -523,13 +523,13 @@ Se a flag estiver ativada e envios divididos ainda chegarem como dois turnos, ve
</Accordion>
<Accordion title="Session JSONL timestamps ≠ webhook arrival">
Os timestamps de eventos de sessão (`~/.openclaw/agents/<id>/sessions/*.jsonl`) refletem quando o Gateway entrega uma mensagem ao agente, **não** quando o Webhook chegou. Uma segunda mensagem enfileirada marcada como `[Queued messages while agent was busy]` significa que o primeiro turno ainda estava em execução quando o segundo Webhook chegou — o bucket de coalescência já tinha sido liberado. Ajuste a janela com base no log do servidor BB, não no log da sessão.
Os carimbos de data/hora de eventos de sessão (`~/.openclaw/agents/<id>/sessions/*.jsonl`) refletem quando o gateway entrega uma mensagem ao agente, **não** quando o webhook chegou. Uma segunda mensagem enfileirada marcada como `[Queued messages while agent was busy]` significa que o primeiro turno ainda estava em execução quando o segundo webhook chegou — o bucket de mesclagem já tinha sido esvaziado. Ajuste a janela com base no log do servidor BB, não no log de sessão.
</Accordion>
<Accordion title="Memory pressure slowing reply dispatch">
Em máquinas menores (8 GB), os turnos do agente podem demorar o bastante para que o bucket de coalescência seja liberado antes de a resposta terminar, e a URL chegue como um segundo turno enfileirado. Verifique `memory_pressure` e `ps -o rss -p $(pgrep openclaw-gateway)`; se o Gateway estiver acima de ~500 MB de RSS e o compressor estiver ativo, feche outros processos pesados ou migre para um host maior.
Em máquinas menores (8 GB), turnos do agente podem demorar o suficiente para que o bucket de mesclagem seja esvaziado antes de a resposta ser concluída, e a URL chegue como um segundo turno enfileirado. Verifique `memory_pressure` e `ps -o rss -p $(pgrep openclaw-gateway)`; se o gateway estiver acima de ~500 MB RSS e o compressor estiver ativo, feche outros processos pesados ou migre para um host maior.
</Accordion>
<Accordion title="Reply-quote sends are a different path">
Se o usuário tocou em `Dump` como uma **resposta** a um balão de URL existente (o iMessage mostra um selo "1 Reply" no balão de Dump), a URL fica em `replyToBody`, não em um segundo Webhook. A coalescência não se aplica — isso é uma questão de skill/prompt, não do debouncer.
Se o usuário tocou em `Dump` como uma **resposta** a um balão de URL existente (o iMessage mostra um selo "1 Reply" no balão Dump), a URL fica em `replyToBody`, não em um segundo webhook. A mesclagem não se aplica — isso é uma questão de skill/prompt, não do debouncer.
</Accordion>
</AccordionGroup>
@ -551,7 +551,7 @@ Controle se as respostas são enviadas como uma única mensagem ou transmitidas
- Anexos de entrada são baixados e armazenados no cache de mídia.
- Limite de mídia via `channels.bluebubbles.mediaMaxMb` para mídia de entrada e saída (padrão: 8 MB).
- O texto de saída é dividido em partes em `channels.bluebubbles.textChunkLimit` (padrão: 4000 caracteres).
- Texto de saída é dividido em blocos até `channels.bluebubbles.textChunkLimit` (padrão: 4000 caracteres).
## Referência de configuração
@ -559,7 +559,7 @@ Configuração completa: [Configuração](/pt-BR/gateway/configuration)
<AccordionGroup>
<Accordion title="Connection and webhook">
- `channels.bluebubbles.enabled`: Habilita/desabilita o canal.
- `channels.bluebubbles.enabled`: Habilitar/desabilitar o canal.
- `channels.bluebubbles.serverUrl`: URL base da API REST do BlueBubbles.
- `channels.bluebubbles.password`: Senha da API.
- `channels.bluebubbles.webhookPath`: Caminho do endpoint de Webhook (padrão: `/bluebubbles-webhook`).
@ -567,30 +567,31 @@ Configuração completa: [Configuração](/pt-BR/gateway/configuration)
</Accordion>
<Accordion title="Access policy">
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: `pairing`).
- `channels.bluebubbles.allowFrom`: Lista de permissões de DM (identificadores, emails, números E.164, `chat_id:*`, `chat_guid:*`).
- `channels.bluebubbles.allowFrom`: Lista de permissões de DM (identificadores, e-mails, números E.164, `chat_id:*`, `chat_guid:*`).
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (padrão: `allowlist`).
- `channels.bluebubbles.groupAllowFrom`: Lista de permissões de remetentes de grupo.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: No macOS, opcionalmente enriquece participantes de grupo sem nome a partir dos Contatos locais depois que as verificações de acesso passam. Padrão: `false`.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: No macOS, opcionalmente enriquecer participantes de grupo sem nome a partir dos Contatos locais depois que as verificações de acesso passarem. Padrão: `false`.
- `channels.bluebubbles.groups`: Configuração por grupo (`requireMention` etc.).
</Accordion>
<Accordion title="Delivery and chunking">
<Accordion title="Entrega e fragmentação">
- `channels.bluebubbles.sendReadReceipts`: Enviar confirmações de leitura (padrão: `true`).
- `channels.bluebubbles.blockStreaming`: Habilitar streaming de blocos (padrão: `false`; obrigatório para respostas em streaming).
- `channels.bluebubbles.textChunkLimit`: Tamanho do fragmento de saída em caracteres (padrão: 4000).
- `channels.bluebubbles.sendTimeoutMs`: Tempo limite por solicitação em ms para envios de texto de saída via `/api/v1/message/text` (padrão: 30000). Aumente em configurações do macOS 26 em que envios do iMessage pela Private API podem travar por mais de 60 segundos dentro do framework do iMessage; por exemplo `45000` ou `60000`. Probes, consultas de chat, reações, edições e verificações de integridade atualmente mantêm o padrão mais curto de 10s; ampliar a cobertura para reações e edições está planejado como acompanhamento. Substituição por conta: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (padrão) divide apenas ao exceder `textChunkLimit`; `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
- `channels.bluebubbles.blockStreaming`: Habilitar streaming em blocos (padrão: `false`; obrigatório para respostas em streaming).
- `channels.bluebubbles.textChunkLimit`: Tamanho dos fragmentos de saída em caracteres (padrão: 4000).
- `channels.bluebubbles.sendTimeoutMs`: Tempo limite por solicitação, em ms, para envios de texto de saída via `/api/v1/message/text` (padrão: 30000). Aumente em configurações do macOS 26 nas quais envios do iMessage pela Private API podem travar por mais de 60 segundos dentro do framework do iMessage; por exemplo, `45000` ou `60000`. Probes, buscas de chat, reações, edições e verificações de integridade atualmente mantêm o padrão mais curto de 10 s; ampliar a cobertura para reações e edições está planejado como continuidade. Substituição por conta: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
- `channels.bluebubbles.chunkMode`: `length` (padrão) divide somente ao exceder `textChunkLimit`; `newline` divide em linhas em branco (limites de parágrafo) antes da fragmentação por tamanho.
</Accordion>
<Accordion title="Media and history">
<Accordion title="Mídia e histórico">
- `channels.bluebubbles.mediaMaxMb`: Limite de mídia de entrada/saída em MB (padrão: 8).
- `channels.bluebubbles.mediaLocalRoots`: Lista de permissões explícita de diretórios locais absolutos permitidos para caminhos de mídia local de saída. Envios por caminho local são negados por padrão, a menos que isso esteja configurado. Substituição por conta: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.coalesceSameSenderDms`: Mescla webhooks de DM consecutivos do mesmo remetente em um único turno do agente, para que o envio dividido de texto+URL da Apple chegue como uma única mensagem (padrão: `false`). Veja [Coalescência de DMs de envio dividido](#coalescing-split-send-dms-command--url-in-one-composition) para cenários, ajuste de janela e compensações. Amplia a janela padrão de debounce de entrada de 500 ms para 2500 ms quando habilitado sem um `messages.inbound.byChannel.bluebubbles` explícito.
- `channels.bluebubbles.mediaLocalRoots`: Lista de permissões explícita de diretórios locais absolutos permitidos para caminhos de mídia local de saída. Envios por caminho local são negados por padrão, a menos que isto esteja configurado. Substituição por conta: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.coalesceSameSenderDms`: Mesclar webhooks de DM consecutivos do mesmo remetente em um único turno do agente para que o envio dividido de texto+URL da Apple chegue como uma única mensagem (padrão: `false`). Consulte [Agrupando DMs enviadas em partes](#coalescing-split-send-dms-command--url-in-one-composition) para cenários, ajuste de janela e compensações. Amplia a janela padrão de debounce de entrada de 500 ms para 2500 ms quando habilitado sem um `messages.inbound.byChannel.bluebubbles` explícito.
- `channels.bluebubbles.historyLimit`: Máximo de mensagens de grupo para contexto (0 desabilita).
- `channels.bluebubbles.dmHistoryLimit`: Limite de histórico de DM.
- `channels.bluebubbles.replyContextApiFallback`: Quando uma resposta de entrada chega sem `replyToBody`/`replyToSender` e o cache em memória de contexto de resposta falha, buscar a mensagem original na API HTTP do BlueBubbles como fallback de melhor esforço (padrão: `false`). Útil para implantações com várias instâncias compartilhando uma conta do BlueBubbles, após reinicializações do processo ou após remoção por cache TTL/LRU de longa duração. A busca é protegida contra SSRF pela mesma política de todas as outras solicitações do cliente BlueBubbles, nunca lança erro e popula o cache para que respostas subsequentes sejam amortizadas. Substituição por conta: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`. Uma configuração no nível do canal se propaga para contas que omitem a flag.
</Accordion>
<Accordion title="Actions and accounts">
<Accordion title="Ações e contas">
- `channels.bluebubbles.actions`: Habilitar/desabilitar ações específicas.
- `channels.bluebubbles.accounts`: Configuração de várias contas.
@ -609,37 +610,37 @@ Prefira `chat_guid` para roteamento estável:
- `chat_guid:iMessage;-;+15555550123` (preferido para grupos)
- `chat_id:123`
- `chat_identifier:...`
- Handles diretos: `+15555550123`, `user@example.com`
- Se um handle direto não tiver um chat de DM existente, o OpenClaw criará um via `POST /api/v1/chat/new`. Isso exige que a Private API do BlueBubbles esteja habilitada.
- Identificadores diretos: `+15555550123`, `user@example.com`
- Se um identificador direto não tiver um chat de DM existente, o OpenClaw criará um via `POST /api/v1/chat/new`. Isso exige que a Private API do BlueBubbles esteja habilitada.
### Roteamento iMessage vs SMS
Quando o mesmo handle tem tanto um chat do iMessage quanto um chat de SMS no Mac (por exemplo, um número de telefone registrado no iMessage, mas que também recebeu fallbacks de bolha verde), o OpenClaw prefere o chat do iMessage e nunca faz downgrade silencioso para SMS. Para forçar o chat de SMS, use um prefixo de destino explícito `sms:` (por exemplo `sms:+15555550123`). Handles sem um chat do iMessage correspondente ainda enviam por qualquer chat que o BlueBubbles reportar.
Quando o mesmo identificador tem tanto um chat iMessage quanto um chat SMS no Mac (por exemplo, um número de telefone registrado no iMessage que também recebeu fallbacks de bolha verde), o OpenClaw prefere o chat iMessage e nunca rebaixa silenciosamente para SMS. Para forçar o chat SMS, use um prefixo de destino `sms:` explícito (por exemplo, `sms:+15555550123`). Identificadores sem um chat iMessage correspondente ainda enviam por qualquer chat que o BlueBubbles reportar.
## Segurança
- Solicitações de Webhook são autenticadas comparando parâmetros de consulta ou cabeçalhos `guid`/`password` com `channels.bluebubbles.password`.
- Mantenha a senha da API e o endpoint de Webhook em segredo (trate-os como credenciais).
- Não há bypass de localhost para autenticação de Webhook do BlueBubbles. Se você fizer proxy do tráfego de Webhook, mantenha a senha do BlueBubbles na solicitação de ponta a ponta. `gateway.trustedProxies` não substitui `channels.bluebubbles.password` aqui. Veja [Segurança do Gateway](/pt-BR/gateway/security#reverse-proxy-configuration).
- Habilite HTTPS + regras de firewall no servidor BlueBubbles se expô-lo fora da sua LAN.
- Mantenha a senha da API e o endpoint de Webhook secretos (trate-os como credenciais).
- Não há bypass de localhost para autenticação de Webhook do BlueBubbles. Se você encaminhar tráfego de Webhook por proxy, mantenha a senha do BlueBubbles na solicitação de ponta a ponta. `gateway.trustedProxies` não substitui `channels.bluebubbles.password` aqui. Consulte [segurança do Gateway](/pt-BR/gateway/security#reverse-proxy-configuration).
- Habilite HTTPS + regras de firewall no servidor BlueBubbles se o expuser fora da sua LAN.
## Solução de problemas
- Se eventos de digitação/leitura pararem de funcionar, verifique os logs de Webhook do BlueBubbles e confirme que o caminho do Gateway corresponde a `channels.bluebubbles.webhookPath`.
- Se eventos de digitação/leitura pararem de funcionar, verifique os logs de Webhook do BlueBubbles e confirme se o caminho do Gateway corresponde a `channels.bluebubbles.webhookPath`.
- Códigos de pareamento expiram após uma hora; use `openclaw pairing list bluebubbles` e `openclaw pairing approve bluebubbles <code>`.
- Reações exigem a API privada do BlueBubbles (`POST /api/v1/message/react`); certifique-se de que a versão do servidor a exponha.
- Editar/cancelar envio exige macOS 13+ e uma versão compatível do servidor BlueBubbles. No macOS 26 (Tahoe), a edição está atualmente quebrada devido a mudanças na API privada.
- Reações exigem a API privada do BlueBubbles (`POST /api/v1/message/react`); certifique-se de que a versão do servidor a expõe.
- Editar/desfazer envio exige macOS 13+ e uma versão compatível do servidor BlueBubbles. No macOS 26 (Tahoe), a edição está atualmente quebrada devido a alterações na API privada.
- Atualizações de ícone de grupo podem ser instáveis no macOS 26 (Tahoe): a API pode retornar sucesso, mas o novo ícone não sincroniza.
- O OpenClaw oculta automaticamente ações sabidamente quebradas com base na versão do macOS do servidor BlueBubbles. Se editar ainda aparecer no macOS 26 (Tahoe), desabilite manualmente com `channels.bluebubbles.actions.edit=false`.
- `coalesceSameSenderDms` habilitado, mas envios divididos (por exemplo, `Dump` + URL) ainda chegam como dois turnos: veja a lista de verificação de [solução de problemas de coalescência de envio dividido](#split-send-coalescing-troubleshooting) — causas comuns são janela de debounce muito curta, timestamps do log de sessão interpretados incorretamente como chegada de Webhook ou um envio de citação de resposta (que usa `replyToBody`, não um segundo Webhook).
- O OpenClaw oculta automaticamente ações sabidamente quebradas com base na versão do macOS do servidor BlueBubbles. Se a edição ainda aparecer no macOS 26 (Tahoe), desabilite-a manualmente com `channels.bluebubbles.actions.edit=false`.
- `coalesceSameSenderDms` habilitado, mas envios divididos (por exemplo, `Dump` + URL) ainda chegam como dois turnos: consulte a lista de verificação de [solução de problemas de agrupamento de envios divididos](#split-send-coalescing-troubleshooting) — causas comuns são janela de debounce apertada demais, timestamps do log de sessão interpretados incorretamente como chegada do Webhook ou um envio com citação de resposta (que usa `replyToBody`, não um segundo Webhook).
- Para informações de status/integridade: `openclaw status --all` ou `openclaw status --deep`.
Para referência geral do fluxo de trabalho de canais, veja [Canais](/pt-BR/channels) e o guia de [Plugins](/pt-BR/tools/plugin).
Para referência geral do fluxo de trabalho de canais, consulte [Canais](/pt-BR/channels) e o guia de [Plugins](/pt-BR/tools/plugin).
## Relacionado
## Relacionados
- [Roteamento de canal](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens
- [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis
- [Grupos](/pt-BR/channels/groups) — comportamento de chats em grupo e controle por menções
- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens
- [Visão geral de canais](/pt-BR/channels) — todos os canais compatíveis
- [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e controle por menções
- [Pareamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de pareamento
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e reforço de segurança
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e endurecimento

184
docs/pt-BR/channels/groups.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Alterar o comportamento de chats em grupo ou o controle por menções
- Alterando o comportamento de chats em grupo ou o controle por menções
sidebarTitle: Groups
summary: Comportamento de chats em grupo em diferentes superfícies (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: Grupos
x-i18n:
generated_at: "2026-04-30T16:27:38Z"
generated_at: "2026-05-01T05:55:08Z"
model: gpt-5.5
provider: openai
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_hash: a8580f98ab03c89770688102da776627d8ce18b7bd34c4a687009fd4aabb6213
source_path: channels/groups.md
workflow: 16
---
OpenClaw trata conversas em grupo de forma consistente entre as superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
OpenClaw trata chats em grupo de forma consistente entre as superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
## Introdução para iniciantes (2 minutos)
OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário de bot separado no WhatsApp. Se **você** está em um grupo, o OpenClaw consegue ver esse grupo e responder ali.
OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário de bot separado no WhatsApp. Se **você** está em um grupo, o OpenClaw pode ver esse grupo e responder nele.
Comportamento padrão:
- Grupos são restritos (`groupPolicy: "allowlist"`).
- Respostas exigem uma menção, a menos que você desative explicitamente o bloqueio por menção.
- Respostas exigem uma menção, a menos que você desative explicitamente o controle por menção.
- Respostas finais normais em grupos/canais são privadas por padrão. A saída visível na sala usa a ferramenta `message`.
Tradução: remetentes na allowlist podem acionar o OpenClaw mencionando-o.
Tradução: remetentes na lista de permissões podem acionar o OpenClaw mencionando-o.
<Note>
**TL;DR**
- **Acesso por DM** é controlado por `*.allowFrom`.
- **Acesso a grupos** é controlado por `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
- **Acionamento de resposta** é controlado pelo bloqueio por menção (`requireMention`, `/activation`).
- **Acesso a DMs** é controlado por `*.allowFrom`.
- **Acesso a grupos** é controlado por `*.groupPolicy` + listas de permissões (`*.groups`, `*.groupAllowFrom`).
- **Acionamento de respostas** é controlado pelo controle por menção (`requireMention`, `/activation`).
</Note>
@ -48,15 +48,18 @@ otherwise -> reply
## Respostas visíveis
Para salas de grupo/canal, o OpenClaw usa por padrão `messages.groupChat.visibleReplies: "message_tool"`.
Isso significa que o agente ainda processa o turno e pode atualizar o estado de memória/sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar de forma visível, o agente usa `message(action=send)`.
Isso significa que o agente ainda processa a rodada e pode atualizar o estado de memória/sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar visivelmente, o agente usa `message(action=send)`.
Para chats diretos e qualquer outro turno de origem, use `messages.visibleReplies: "message_tool"` para aplicar globalmente o mesmo comportamento de resposta visível apenas por ferramenta. `messages.groupChat.visibleReplies` continua sendo a substituição mais específica para salas de grupo/canal.
Se a ferramenta de mensagem estiver indisponível sob a política de ferramentas ativa, o OpenClaw recorre a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta.
`openclaw doctor` avisa sobre essa incompatibilidade.
Isso substitui o padrão antigo de forçar o modelo a responder `NO_REPLY` na maioria dos turnos em modo de observação. No modo apenas por ferramenta, não fazer nada visível simplesmente significa não chamar a ferramenta de mensagem.
Para chats diretos e qualquer outra rodada de origem, use `messages.visibleReplies: "message_tool"` para aplicar globalmente o mesmo comportamento de resposta visível somente por ferramenta. `messages.groupChat.visibleReplies` permanece como a substituição mais específica para salas de grupo/canal.
Indicadores de digitação ainda são enviados enquanto o agente trabalha no modo apenas por ferramenta. O modo padrão de digitação em grupo é atualizado de "message" para "instant" nesses turnos, porque talvez nunca haja texto normal de mensagem do assistente antes de o agente decidir se deve chamar a ferramenta de mensagem. A configuração explícita do modo de digitação ainda prevalece.
Isso substitui o padrão antigo de forçar o modelo a responder `NO_REPLY` para a maioria das rodadas em modo de observação. No modo somente por ferramenta, não fazer nada visível simplesmente significa não chamar a ferramenta de mensagem.
Para restaurar as respostas finais automáticas legadas para salas de grupo/canal:
Indicadores de digitação ainda são enviados enquanto o agente trabalha no modo somente por ferramenta. O modo padrão de digitação em grupo é atualizado de "message" para "instant" para essas rodadas porque pode nunca haver texto normal de mensagem do assistente antes que o agente decida se deve chamar a ferramenta de mensagem. A configuração explícita de modo de digitação ainda prevalece.
Para restaurar respostas finais automáticas legadas para salas de grupo/canal:
```json5
{
@ -68,10 +71,9 @@ Para restaurar as respostas finais automáticas legadas para salas de grupo/cana
}
```
O gateway recarrega a configuração de `messages` automaticamente após o arquivo ser salvo. Reinicie apenas
quando o monitoramento de arquivos ou o recarregamento de configuração estiver desativado na implantação.
O gateway recarrega a configuração `messages` automaticamente depois que o arquivo é salvo. Reinicie somente quando a observação de arquivos ou a recarga de configuração estiver desativada na implantação.
Para exigir que a saída visível passe pela ferramenta de mensagem em todos os chats de origem:
Para exigir que a saída visível passe pela ferramenta de mensagem para todo chat de origem:
```json5
{
@ -81,43 +83,43 @@ Para exigir que a saída visível passe pela ferramenta de mensagem em todos os
}
```
Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte nativo a comandos) ignoram `visibleReplies: "message_tool"` e sempre respondem de forma visível para que a interface de comando nativa do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos `/...` digitados como texto e turnos comuns de chat ainda seguem o padrão de grupo configurado.
Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte nativo a comandos) ignoram `visibleReplies: "message_tool"` e sempre respondem visivelmente para que a interface de comando nativa do canal receba a resposta esperada. Isso se aplica somente a rodadas validadas de comando nativo; comandos `/...` digitados como texto e rodadas comuns de chat ainda seguem o padrão de grupo configurado.
## Visibilidade de contexto e allowlists
## Visibilidade de contexto e listas de permissões
Dois controles diferentes estão envolvidos na segurança de grupos:
- **Autorização de acionamento**: quem pode acionar o agente (`groupPolicy`, `groups`, `groupAllowFrom`, allowlists específicas do canal).
- **Autorização de acionamento**: quem pode acionar o agente (`groupPolicy`, `groups`, `groupAllowFrom`, listas de permissões específicas do canal).
- **Visibilidade de contexto**: qual contexto suplementar é injetado no modelo (texto de resposta, citações, histórico de thread, metadados encaminhados).
Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o contexto quase como foi recebido. Isso significa que allowlists decidem principalmente quem pode acionar ações, não um limite universal de redação para cada trecho citado ou histórico.
Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o contexto principalmente como recebido. Isso significa que listas de permissões decidem principalmente quem pode acionar ações, não uma fronteira universal de redação para cada trecho citado ou histórico.
<AccordionGroup>
<Accordion title="O comportamento atual é específico por canal">
- Alguns canais já aplicam filtragem baseada em remetente para contexto suplementar em caminhos específicos (por exemplo, semeadura de threads do Slack, buscas de resposta/thread do Matrix).
- Outros canais ainda repassam contexto de citação/resposta/encaminhamento como recebido.
<Accordion title="Current behavior is channel-specific">
- Alguns canais já aplicam filtragem baseada no remetente para contexto suplementar em caminhos específicos (por exemplo, semeadura de threads do Slack, buscas de respostas/threads no Matrix).
- Outros canais ainda passam contexto de citação/resposta/encaminhamento como recebido.
</Accordion>
<Accordion title="Direção de reforço (planejada)">
<Accordion title="Hardening direction (planned)">
- `contextVisibility: "all"` (padrão) mantém o comportamento atual como recebido.
- `contextVisibility: "allowlist"` filtra contexto suplementar para remetentes na allowlist.
- `contextVisibility: "allowlist"` filtra contexto suplementar para remetentes na lista de permissões.
- `contextVisibility: "allowlist_quote"` é `allowlist` mais uma exceção explícita de citação/resposta.
Até que esse modelo de reforço seja implementado de forma consistente entre os canais, espere diferenças por superfície.
Até que esse modelo de fortalecimento seja implementado de forma consistente entre canais, espere diferenças por superfície.
</Accordion>
</AccordionGroup>
![Fluxo de mensagem de grupo](/images/groups-flow.svg)
![Fluxo de mensagem em grupo](/images/groups-flow.svg)
Se você quer...
| Objetivo | O que configurar |
| Objetivo | O que configurar |
| -------------------------------------------- | ---------------------------------------------------------- |
| Permitir todos os grupos, mas responder apenas em @menções | `groups: { "*": { requireMention: true } }` |
| Permitir todos os grupos, mas responder só em @menções | `groups: { "*": { requireMention: true } }` |
| Desativar todas as respostas em grupo | `groupPolicy: "disabled"` |
| Apenas grupos específicos | `groups: { "<group-id>": { ... } }` (sem chave `"*"` ) |
| Apenas você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
| Somente grupos específicos | `groups: { "<group-id>": { ... } }` (sem chave `"*"` ) |
| Somente você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## Chaves de sessão
@ -130,21 +132,21 @@ Se você quer...
## Padrão: DMs pessoais + grupos públicos (agente único)
Sim — isso funciona bem se o seu tráfego "pessoal" são **DMs** e o seu tráfego "público" são **grupos**.
Sim — isso funciona bem se seu tráfego "pessoal" são **DMs** e seu tráfego "público" são **grupos**.
Por quê: no modo de agente único, DMs normalmente chegam à chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main:<channel>:group:<id>`). Se você ativar sandboxing com `mode: "non-main"`, essas sessões de grupo rodam no backend de sandbox configurado enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um.
Motivo: no modo de agente único, DMs geralmente caem na chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main:<channel>:group:<id>`). Se você habilitar sandboxing com `mode: "non-main"`, essas sessões de grupo rodam no backend de sandbox configurado enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um.
Isso dá a você um "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução:
Isso dá a você um único "cérebro" de agente (espaço de trabalho + memória compartilhados), mas duas posturas de execução:
- **DMs**: ferramentas completas (host)
- **Grupos**: sandbox + ferramentas restritas
<Note>
Se você precisa de workspaces/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + bindings. Consulte [Roteamento multiagente](/pt-BR/concepts/multi-agent).
Se você precisa de espaços de trabalho/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + vinculações. Veja [Roteamento Multiagente](/pt-BR/concepts/multi-agent).
</Note>
<Tabs>
<Tab title="DMs no host, grupos em sandbox">
<Tab title="DMs on host, groups sandboxed">
```json5
{
agents: {
@ -168,8 +170,8 @@ Se você precisa de workspaces/personas realmente separados ("pessoal" e "públi
}
```
</Tab>
<Tab title="Grupos veem apenas uma pasta na allowlist">
Quer que "grupos só possam ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte apenas caminhos na allowlist dentro do sandbox:
<Tab title="Groups see only an allowlisted folder">
Quer "grupos só podem ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte somente caminhos na lista de permissões no sandbox:
```json5
{
@ -197,13 +199,13 @@ Se você precisa de workspaces/personas realmente separados ("pessoal" e "públi
Relacionado:
- Chaves de configuração e padrões: [Configuração do Gateway](/pt-BR/gateway/config-agents#agentsdefaultssandbox)
- Depurar por que uma ferramenta está bloqueada: [Sandbox vs Política de ferramentas vs Elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated)
- Detalhes de montagens bind: [Sandboxing](/pt-BR/gateway/sandboxing#custom-bind-mounts)
- Depuração de por que uma ferramenta está bloqueada: [Sandbox vs Política de Ferramentas vs Elevado](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated)
- Detalhes de montagens vinculadas: [Sandboxing](/pt-BR/gateway/sandboxing#custom-bind-mounts)
## Rótulos de exibição
- Rótulos da UI usam `displayName` quando disponível, formatado como `<channel>:<token>`.
- `#room` é reservado para salas/canais; chats em grupo usam `g-<slug>` (minúsculas, espaços -> `-`, mantém `#@+._-`).
- `#room` é reservado para salas/canais; chats em grupo usam `g-<slug>` (minúsculas, espaços -> `-`, manter `#@+._-`).
## Política de grupo
@ -254,25 +256,25 @@ Controle como mensagens de grupo/sala são tratadas por canal:
}
```
| Política | Comportamento |
| Política | Comportamento |
| ------------- | ------------------------------------------------------------ |
| `"open"` | Grupos ignoram allowlists; o bloqueio por menção ainda se aplica. |
| `"disabled"` | Bloqueia totalmente todas as mensagens de grupo. |
| `"allowlist"` | Permite apenas grupos/salas que correspondem à allowlist configurada. |
| `"open"` | Grupos ignoram listas de permissões; o controle por menção ainda se aplica. |
| `"disabled"` | Bloqueia completamente todas as mensagens de grupo. |
| `"allowlist"` | Permite somente grupos/salas que correspondem à lista de permissões configurada. |
<AccordionGroup>
<Accordion title="Observações por canal">
- `groupPolicy` é separado do bloqueio por menção (que exige @menções).
<Accordion title="Per-channel notes">
- `groupPolicy` é separado do controle por menção (que exige @menções).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use `groupAllowFrom` (fallback: `allowFrom` explícito).
- Signal: `groupAllowFrom` pode corresponder ao id de grupo Signal de entrada ou ao telefone/UUID do remetente.
- Aprovações de pareamento por DM (entradas de armazenamento `*-allowFrom`) aplicam-se apenas ao acesso por DM; a autorização de remetente em grupo permanece explícita para allowlists de grupo.
- Discord: a allowlist usa `channels.discord.guilds.<id>.channels`.
- Slack: a allowlist usa `channels.slack.channels`.
- Matrix: a allowlist usa `channels.matrix.groups`. Prefira IDs de sala ou aliases; a busca de nome de salas ingressadas é de melhor esforço, e nomes não resolvidos são ignorados em tempo de execução. Use `channels.matrix.groupAllowFrom` para restringir remetentes; allowlists `users` por sala também são compatíveis.
- Signal: `groupAllowFrom` pode corresponder ao id do grupo Signal de entrada ou ao telefone/UUID do remetente.
- Aprovações de pareamento de DM (entradas de armazenamento `*-allowFrom`) se aplicam somente ao acesso a DMs; autorização de remetente de grupo permanece explícita nas listas de permissões de grupo.
- Discord: a lista de permissões usa `channels.discord.guilds.<id>.channels`.
- Slack: a lista de permissões usa `channels.slack.channels`.
- Matrix: a lista de permissões usa `channels.matrix.groups`. Prefira IDs ou aliases de sala; a busca por nome de sala ingressada é de melhor esforço, e nomes não resolvidos são ignorados em tempo de execução. Use `channels.matrix.groupAllowFrom` para restringir remetentes; listas de permissões `users` por sala também são suportadas.
- DMs de grupo são controladas separadamente (`channels.discord.dm.*`, `channels.slack.dm.*`).
- A allowlist do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas.
- O padrão é `groupPolicy: "allowlist"`; se a allowlist de grupo estiver vazia, mensagens de grupo serão bloqueadas.
- Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (`channels.<provider>` ausente), a política de grupo recua para um modo fail-closed (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`.
- A lista de permissões do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas.
- O padrão é `groupPolicy: "allowlist"`; se sua lista de permissões de grupo estiver vazia, mensagens de grupo serão bloqueadas.
- Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (`channels.<provider>` ausente), a política de grupo recorre a um modo de falha fechada (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`.
</Accordion>
</AccordionGroup>
@ -283,17 +285,17 @@ Modelo mental rápido (ordem de avaliação para mensagens de grupo):
<Step title="groupPolicy">
`groupPolicy` (open/disabled/allowlist).
</Step>
<Step title="Allowlists de grupo">
Allowlists de grupo (`*.groups`, `*.groupAllowFrom`, allowlist específica do canal).
<Step title="Listas de permissão de grupos">
Listas de permissão de grupos (`*.groups`, `*.groupAllowFrom`, lista de permissão específica do canal).
</Step>
<Step title="Bloqueio por menção">
Bloqueio por menção (`requireMention`, `/activation`).
<Step title="Controle por menção">
Controle por menção (`requireMention`, `/activation`).
</Step>
</Steps>
## Bloqueio por menção (padrão)
## Controle por menção (padrão)
Mensagens de grupo exigem uma menção, a menos que sejam substituídas por grupo. Os padrões ficam por subsistema em `*.groups."*"`.
Mensagens de grupo exigem uma menção, a menos que isso seja substituído por grupo. Os padrões ficam por subsistema em `*.groups."*"`.
Responder a uma mensagem do bot conta como uma menção implícita quando o canal oferece suporte a metadados de resposta. Citar uma mensagem do bot também pode contar como uma menção implícita em canais que expõem metadados de citação. Os casos integrados atuais incluem Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser.
@ -334,35 +336,35 @@ Responder a uma mensagem do bot conta como uma menção implícita quando o cana
```
<AccordionGroup>
<Accordion title="Notas sobre controle por menção">
<Accordion title="Observações sobre controle por menção">
- `mentionPatterns` são padrões regex seguros e sem diferenciação entre maiúsculas e minúsculas; padrões inválidos e formas inseguras de repetição aninhada são ignorados.
- Superfícies que fornecem menções explícitas ainda passam; os padrões são um fallback.
- Superfícies que fornecem menções explícitas ainda passam; padrões são uma alternativa.
- Substituição por agente: `agents.list[].groupChat.mentionPatterns` (útil quando vários agentes compartilham um grupo).
- O controle por menção só é aplicado quando a detecção de menção é possível (menções nativas ou `mentionPatterns` estão configurados).
- Colocar um grupo ou remetente na lista de permissões não desativa o controle por menção; defina `requireMention` desse grupo como `false` quando todas as mensagens devem acionar.
- O contexto do prompt de chat em grupo carrega a instrução resolvida de resposta silenciosa a cada turno; arquivos do workspace não devem duplicar a mecânica de `NO_REPLY`.
- Grupos em que respostas silenciosas são permitidas tratam turnos do modelo limpos, vazios ou apenas de raciocínio como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo somente quando respostas silenciosas diretas são explicitamente permitidas; caso contrário, respostas vazias continuam sendo turnos de agente com falha.
- Os padrões do Discord ficam em `channels.discord.guilds."*"` (substituíveis por servidor/canal).
- O contexto de histórico de grupo é encapsulado uniformemente entre canais e é **somente pendente** (mensagens ignoradas devido ao controle por menção); use `messages.groupChat.historyLimit` para o padrão global e `channels.<channel>.historyLimit` (ou `channels.<channel>.accounts.*.historyLimit`) para substituições. Defina `0` para desativar.
- Colocar um grupo ou remetente na lista de permissão não desativa o controle por menção; defina `requireMention` desse grupo como `false` quando todas as mensagens devem acionar.
- O contexto de prompt de chat em grupo carrega a instrução de resposta silenciosa resolvida a cada turno; arquivos do workspace não devem duplicar a mecânica de `NO_REPLY`.
- Grupos onde respostas silenciosas são permitidas tratam turnos de modelo limpos, vazios ou apenas com raciocínio como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo apenas quando respostas silenciosas diretas são explicitamente permitidas; caso contrário, respostas vazias continuam sendo turnos de agente com falha.
- Os padrões do Discord ficam em `channels.discord.guilds."*"` (substituíveis por guild/canal).
- O contexto do histórico de grupo é encapsulado uniformemente entre canais e é **somente pendente** (mensagens ignoradas devido ao controle por menção); use `messages.groupChat.historyLimit` para o padrão global e `channels.<channel>.historyLimit` (ou `channels.<channel>.accounts.*.historyLimit`) para substituições. Defina `0` para desativar.
</Accordion>
</AccordionGroup>
## Restrições de ferramentas por grupo/canal (opcional)
## Restrições de ferramentas de grupo/canal (opcional)
Algumas configurações de canal permitem restringir quais ferramentas estão disponíveis **dentro de um grupo/sala/canal específico**.
- `tools`: permite/nega ferramentas para o grupo inteiro.
- `toolsBySender`: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` e o curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondem apenas como `id:`.
- `toolsBySender`: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` e curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondidas apenas como `id:`.
Ordem de resolução (a mais específica vence):
Ordem de resolução (o mais específico vence):
<Steps>
<Step title="toolsBySender do grupo">
Correspondência de `toolsBySender` do grupo/canal.
Correspondência de `toolsBySender` de grupo/canal.
</Step>
<Step title="tools do grupo">
`tools` do grupo/canal.
`tools` de grupo/canal.
</Step>
<Step title="toolsBySender padrão">
Correspondência de `toolsBySender` padrão (`"*"`).
@ -393,21 +395,21 @@ Exemplo (Telegram):
```
<Note>
Restrições de ferramentas por grupo/canal são aplicadas além da política global/de ferramentas do agente (negação ainda vence). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
Restrições de ferramentas de grupo/canal são aplicadas além da política global/de agente de ferramentas (a negação ainda prevalece). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
</Note>
## Listas de permissões de grupos
## Listas de permissão de grupos
Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` está configurado, as chaves atuam como uma lista de permissões de grupos. Use `"*"` para permitir todos os grupos enquanto ainda define o comportamento padrão de menção.
Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` está configurado, as chaves atuam como uma lista de permissão de grupos. Use `"*"` para permitir todos os grupos enquanto ainda define o comportamento padrão de menção.
<Warning>
Confusão comum: a aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento desbloqueia apenas DMs. Comandos de grupo ainda exigem autorização explícita do remetente do grupo por listas de permissões de configuração, como `groupAllowFrom`, ou pelo fallback de configuração documentado para esse canal.
Confusão comum: aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento desbloqueia apenas DMs. Comandos de grupo ainda exigem autorização explícita de remetente de grupo por listas de permissão de configuração, como `groupAllowFrom`, ou pela alternativa de configuração documentada para esse canal.
</Warning>
Intenções comuns (copiar/colar):
<Tabs>
<Tab title="Desativar todas as respostas em grupo">
<Tab title="Desativar todas as respostas de grupo">
```json5
{
channels: { whatsapp: { groupPolicy: "disabled" } },
@ -456,12 +458,12 @@ Intenções comuns (copiar/colar):
## Ativação (somente proprietário)
Proprietários de grupos podem alternar a ativação por grupo:
Proprietários de grupo podem alternar a ativação por grupo:
- `/activation mention`
- `/activation always`
O proprietário é determinado por `channels.whatsapp.allowFrom` (ou pelo E.164 próprio do bot quando não definido). Envie o comando como uma mensagem independente. Outras superfícies atualmente ignoram `/activation`.
O proprietário é determinado por `channels.whatsapp.allowFrom` (ou pelo E.164 do próprio bot quando não definido). Envie o comando como uma mensagem independente. Outras superfícies atualmente ignoram `/activation`.
## Campos de contexto
@ -469,21 +471,21 @@ Payloads de entrada de grupo definem:
- `ChatType=group`
- `GroupSubject` (se conhecido)
- `GroupMembers` (se conhecido)
- `GroupMembers` (se conhecidos)
- `WasMentioned` (resultado do controle por menção)
- Tópicos de fórum do Telegram também incluem `MessageThreadId` e `IsForum`.
Notas específicas por canal:
Observações específicas do canal:
- O BlueBubbles pode opcionalmente enriquecer participantes de grupos macOS sem nome a partir do banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa.
- BlueBubbles pode, opcionalmente, enriquecer participantes sem nome de grupos do macOS a partir do banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa.
O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como uma pessoa, evitar tabelas em Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupos e rótulos de participantes provenientes do canal são renderizados como metadados não confiáveis em bloco de código, não como instruções de sistema inline.
O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como uma pessoa, evitar tabelas Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupos e rótulos de participantes provenientes do canal são renderizados como metadados não confiáveis cercados por fences, não como instruções de sistema inline.
## Especificidades do iMessage
- Prefira `chat_id:<id>` ao rotear ou colocar na lista de permissões.
- Prefira `chat_id:<id>` ao rotear ou colocar na lista de permissão.
- Listar chats: `imsg chats --limit 20`.
- Respostas em grupo sempre voltam para o mesmo `chat_id`.
- Respostas de grupo sempre voltam para o mesmo `chat_id`.
## Prompts de sistema do WhatsApp
@ -491,11 +493,11 @@ Consulte [WhatsApp](/pt-BR/channels/whatsapp#system-prompts) para as regras can
## Especificidades do WhatsApp
Consulte [Mensagens de grupo](/pt-BR/channels/group-messages) para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menções).
Consulte [Mensagens de grupo](/pt-BR/channels/group-messages) para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menção).
## Relacionados
## Relacionado
- [Grupos de transmissão](/pt-BR/channels/broadcast-groups)
- [Roteamento de canais](/pt-BR/channels/channel-routing)
- [Roteamento de canal](/pt-BR/channels/channel-routing)
- [Mensagens de grupo](/pt-BR/channels/group-messages)
- [Pareamento](/pt-BR/channels/pairing)

32
docs/pt-BR/channels/qa-channel.md
View File

@ -2,14 +2,14 @@
read_when:
- Você está integrando o transporte sintético de QA a uma execução de teste local ou de CI
- Você precisa da superfície de configuração do qa-channel incluída
- Você está iterando na automação de QA de ponta a ponta
summary: Plugin sintético de canal do tipo Slack para cenários determinísticos de QA do OpenClaw
- Você está iterando na automação de garantia de qualidade de ponta a ponta
summary: Plugin de canal sintético da classe Slack para cenários determinísticos de QA do OpenClaw
title: Canal de QA
x-i18n:
generated_at: "2026-04-30T09:37:56Z"
generated_at: "2026-05-01T05:55:20Z"
model: gpt-5.5
provider: openai
source_hash: e1de1f52da1a14c845cf2a536ddc6f36ab52ed6364f68d9ece32ce272e2a2f96
source_hash: efe057812de1fbc6d89d2b6d5860cd6af4648c3e86913efa3a69267c4e8c57b4
source_path: channels/qa-channel.md
workflow: 16
---
@ -21,9 +21,11 @@ x-i18n:
- Gramática de destino de classe Slack:
- `dm:<user>`
- `channel:<room>`
- `group:<room>`
- `thread:<room>/<thread>`
- Conversas compartilhadas de `channel:` e `group:` são apresentadas aos agentes como turnos de sala de grupo/canal, para que exercitem a mesma política de resposta visível e roteamento de ferramentas de mensagem usada por Discord, Slack, Telegram e transportes semelhantes.
- Barramento sintético baseado em HTTP para injeção de mensagens de entrada, captura de transcrições de saída, criação de threads, reações, edições, exclusões e ações de busca/leitura.
- Executor de autoverificação no lado do host que grava um relatório Markdown em `.artifacts/qa-e2e/`.
- Executor de autoverificação no host que grava um relatório em Markdown em `.artifacts/qa-e2e/`.
## Configuração
@ -46,27 +48,27 @@ Chaves da conta:
- `enabled` — alternância principal para esta conta.
- `name` — rótulo de exibição opcional.
- `baseUrl` — URL do barramento sintético.
- `botUserId` — ID de usuário do bot no estilo Matrix usado na gramática de destino.
- `botUserId` — id de usuário do bot em estilo Matrix usado na gramática de destino.
- `botDisplayName` — nome de exibição para mensagens de saída.
- `pollTimeoutMs` — janela de espera de long-poll. Inteiro entre 100 e 30000.
- `allowFrom` — lista de permissões de remetentes (IDs de usuário ou `"*"`).
- `allowFrom` — lista de remetentes permitidos (ids de usuário ou `"*"`).
- `defaultTo` — destino de fallback quando nenhum é fornecido.
- `actions.messages` / `actions.reactions` / `actions.search` / `actions.threads` — controle de ferramentas por ação.
Chaves de múltiplas contas no nível superior:
- `accounts` — registro de substituições nomeadas por conta, indexadas por ID da conta.
- `defaultAccount` — ID da conta preferida quando várias estão configuradas.
- `accounts` — registro de substituições nomeadas por conta, indexadas por id da conta.
- `defaultAccount` — id de conta preferido quando múltiplas estão configuradas.
## Executores
Autoverificação no lado do host (grava um relatório Markdown em `.artifacts/qa-e2e/`):
Autoverificação no host (grava um relatório em Markdown em `.artifacts/qa-e2e/`):
```bash
pnpm qa:e2e
```
Isso passa pelo `qa-lab`, inicia o barramento de QA dentro do repositório, inicializa a fatia de runtime do `qa-channel` incluído e executa uma autoverificação determinística.
Isso roteia por `qa-lab`, inicia o barramento de QA dentro do repositório, inicializa a fatia de runtime incluída do `qa-channel` e executa uma autoverificação determinística.
Suíte completa de cenários baseada no repositório:
@ -74,20 +76,20 @@ Suíte completa de cenários baseada no repositório:
pnpm openclaw qa suite
```
Executa cenários em paralelo contra a faixa de Gateway de QA. Consulte [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) para cenários, perfis e modos de provedor.
Executa cenários em paralelo contra a faixa de Gateway de QA. Veja [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) para cenários, perfis e modos de provedor.
Site de QA baseado em Docker (Gateway + interface de depuração do QA Lab em uma única pilha):
Site de QA baseado em Docker (Gateway + interface de depuração do QA Lab em uma pilha):
```bash
pnpm qa:lab:up
```
Compila o site de QA, inicia a pilha de Gateway + QA Lab baseada em Docker e imprime a URL do QA Lab. A partir daí, você pode escolher cenários, selecionar a faixa do modelo, iniciar execuções individuais e acompanhar os resultados ao vivo. O depurador do QA Lab é separado do pacote de Control UI enviado.
Compila o site de QA, inicia a pilha de Gateway + QA Lab baseada em Docker e imprime a URL do QA Lab. A partir daí, você pode escolher cenários, escolher a faixa do modelo, iniciar execuções individuais e acompanhar os resultados ao vivo. O depurador do QA Lab é separado do pacote da Control UI distribuído.
## Relacionado
- [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) — pilha geral, adaptadores de transporte, autoria de cenários
- [QA do Matrix](/pt-BR/concepts/qa-matrix) — exemplo de executor de transporte ao vivo que controla um canal real
- [QA Matrix](/pt-BR/concepts/qa-matrix) — exemplo de executor de transporte ao vivo que aciona um canal real
- [Pareamento](/pt-BR/channels/pairing)
- [Grupos](/pt-BR/channels/groups)
- [Visão geral dos canais](/pt-BR/channels)

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

@ -1,75 +1,75 @@
---
read_when:
- Você precisa entender por que um job de CI foi ou não executado
- 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
summary: Grafo de jobs de CI, controles de escopo, agrupadores de lançamento e equivalentes de comandos locais
title: Pipeline de CI
- Você precisa entender por que uma tarefa de CI foi ou não executada
- Você está depurando uma verificação do GitHub Actions com falha
- Você está coordenando uma execução ou reexecução de validação de lançamento
summary: Grafo de tarefas de CI, critérios de escopo, guarda-chuvas de lançamento e equivalentes de comandos locais
title: pipeline de CI
x-i18n:
generated_at: "2026-04-30T18:38:47Z"
generated_at: "2026-05-01T05:55:24Z"
model: gpt-5.5
provider: openai
source_hash: a24afc27606ac7f4e9ead89acdd319bffa23336610f8a6cd8b576ea1a5b233dd
source_hash: aea06f9f336f9a478a284473b5c5f38730b87837b1acb0390161bf2c455f6c41
source_path: ci.md
workflow: 16
---
OpenClaw CI é executado a cada push para `main` e em toda pull request. O job `preflight` classifica o diff e desativa lanes caras quando apenas áreas não relacionadas mudaram. Execuções manuais via `workflow_dispatch` intencionalmente ignoram o escopo inteligente e expandem o grafo completo para candidatos a release e validação ampla. As lanes de Android permanecem opt-in por meio de `include_android`. A cobertura de plugins exclusiva 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 foram alteradas. 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 do Android continuam opt-in por meio de `include_android`. A cobertura de Plugin 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 dispatch manual explícito.
## Visão geral do pipeline
| Job | Propósito | Quando é executado |
| -------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `preflight` | Detecta alterações apenas de docs, escopos alterados, extensões alteradas e cria o manifesto de CI | Sempre em pushes e PRs que não sejam rascunho |
| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não sejam rascunho |
| `security-dependency-audit` | Auditoria de lockfile de produção sem dependências contra advisories do npm | Sempre em pushes e PRs que não sejam rascunho |
| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não sejam rascunho |
| `check-dependencies` | Passagem do Knip somente para dependências de produção mais o guarda da allowlist de arquivos não usados | Alterações relevantes para Node |
| `build-artifacts` | Compila `dist/`, Control UI, checks 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 checks bundled/plugin-contract/protocol | Alterações relevantes para Node |
| `checks-fast-contracts-channels` | Checks fragmentados de contrato de canais com um resultado agregado estável | Alterações relevantes para Node |
| `checks-node-core-test` | Shards de testes do core Node, excluindo lanes de canal, bundled, contrato e extensão | 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` | Shards de arquitetura, boundary, guardas de superfície de extensão, package-boundary 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 com 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 checks de links quebrados da documentação | Docs alterados |
| `skills-python` | Ruff + pytest para skills baseadas em Python | Alterações relevantes para skills Python |
| `checks-windows` | Testes específicos de processo/caminho no Windows mais regressões de especificadores de importação do runtime compartilhado | 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 Android para ambos os flavors mais um build de APK debug | Alterações relevantes para Android |
| `test-performance-agent` | Otimização diária de testes lentos do Codex após atividade confiável | Sucesso da CI principal ou disparo manual |
| Job | Finalidade | Quando é executado |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Detectar mudanças só em docs, escopos alterados, extensões alteradas e criar o manifesto da CI | Sempre em pushes e PRs que não sejam rascunho |
| `security-scm-fast` | Detecção de chave privada e auditoria de workflow via `zizmor` | Sempre em pushes e PRs que não sejam rascunho |
| `security-dependency-audit` | Auditoria do lockfile de produção sem dependências contra avisos do npm | Sempre em pushes e PRs que não sejam rascunho |
| `security-fast` | Agregado obrigatório para os jobs rápidos de segurança | Sempre em pushes e PRs que não sejam rascunho |
| `check-dependencies` | Passagem do Knip somente para dependências de produção mais o guard da allowlist de arquivos não usados | Mudanças relevantes para Node |
| `build-artifacts` | Compilar `dist/`, Control UI, checks de artefatos compilados e artefatos downstream reutilizáveis | Mudanças relevantes para Node |
| `checks-fast-core` | Lanes rápidas de correção no Linux, como checks de bundled/plugin-contract/protocol | Mudanças relevantes para Node |
| `checks-fast-contracts-channels` | Checks de contrato de canal fragmentados com um resultado de check agregado estável | Mudanças relevantes para Node |
| `checks-node-core-test` | Shards de testes do core Node, excluindo lanes de canais, bundled, contrato e extensões | Mudanças relevantes para Node |
| `check` | Equivalente fragmentado do gate local principal: tipos de produção, lint, guards, tipos de teste e smoke estrito | Mudanças relevantes para Node |
| `check-additional` | Shards de arquitetura, boundary, guards de superfície de extensão, package-boundary e gateway-watch | Mudanças relevantes para Node |
| `build-smoke` | Testes smoke da CLI compilada e smoke de memória de inicialização | Mudanças relevantes para Node |
| `checks` | Verificador para testes de canal de artefato compilado | Mudanças relevantes para Node |
| `checks-node-compat-node22` | Lane de build e smoke de compatibilidade com Node 22 | Dispatch manual da CI para releases |
| `check-docs` | Formatação, lint e checks de links quebrados da documentação | Docs alterados |
| `skills-python` | Ruff + pytest para skills baseadas em Python | Mudanças 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 | Mudanças relevantes para Windows |
| `macos-node` | Lane de testes TypeScript no macOS usando os artefatos compilados compartilhados | Mudanças relevantes para macOS |
| `macos-swift` | Swift lint, build e testes para o app macOS | Mudanças relevantes para macOS |
| `android` | Testes unitários do Android para ambos os flavors mais uma build de APK de debug | Mudanças 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 dispatch manual |
## Ordem de falha rápida
1. `preflight` decide quais lanes existem. A lógica de `docs-scope` e `changed-scope` é composta por etapas dentro desse job, não jobs independentes.
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` sobrepõe as lanes rápidas do Linux para que consumidores downstream possam começar assim que o build compartilhado estiver pronto.
3. `build-artifacts` se sobrepõe às lanes rápidas de Linux para que consumidores downstream possam começar assim que a build compartilhada estiver pronta.
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`.
O GitHub pode marcar jobs substituídos como `cancelled` quando um push mais novo chega na mesma 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. Checks agregados de shards usam `!cancelled() && always()` para que ainda relatem falhas normais de shards, mas não entrem na fila depois que todo o workflow já foi substituído. A chave automática de concorrência da CI é versionada (`CI-v7-*`), então um zumbi do lado do GitHub em um grupo de fila antigo não consegue 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 novo chega ao mesmo PR ou ref de `main`. Trate isso como ruído da CI, a menos que a execução mais nova para a mesma ref também esteja falhando. Checks agregados de shard usam `!cancelled() && always()` para que ainda relatem falhas normais de shard, mas não entrem na fila depois que todo o workflow já foi substituído. A chave automática de concorrência 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.
## 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 ignora a detecção de changed-scope e faz o manifesto de preflight agir como se todas as áreas com escopo tivessem mudado.
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 dispatch manual pula a detecção de changed-scope e faz o manifesto de preflight agir como se todas as áreas escopadas tivessem mudado.
- **Edições no workflow de CI** validam o grafo de CI Node mais o lint de workflows, 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 da plataforma.
- **Edições apenas de roteamento de CI, edições selecionadas de fixtures baratas de testes do core 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 ignora artefatos de build, compatibilidade com Node 22, contratos de canais, shards completos do core, shards de plugins bundled e matrizes de guardas adicionais quando a alteração se limita às superfícies de roteamento ou helpers que a tarefa rápida exercita diretamente.
- **Checks Node no Windows** são escopados a wrappers de processo/caminho específicos do Windows, helpers de runners npm/pnpm/UI, configuração de gerenciador de pacotes e superfícies de workflow de CI que executam essa lane; alterações não relacionadas de código-fonte, Plugin, install-smoke e somente testes permanecem nas lanes Node do Linux.
- **Edições no workflow de CI** validam o grafo da CI de Node mais o lint de workflow, mas não forçam builds nativas de Windows, Android ou macOS por si só; essas lanes de plataforma continuam escopadas a mudanças no código-fonte da plataforma.
- **Edições apenas de roteamento da CI, edições selecionadas de fixtures baratas de testes do core e edições estreitas de helpers/test-routing de contrato de Plugin** usam um caminho de manifesto rápido somente de Node: `preflight`, segurança e uma única tarefa `checks-fast-core`. Esse caminho pula artefatos de build, compatibilidade com Node 22, contratos de canal, shards completos do core, shards de Plugin bundled e matrizes adicionais de guard quando a mudança se limita às superfícies de roteamento ou helper que a tarefa rápida exercita diretamente.
- **Checks de Node no Windows** são escopados para wrappers específicos de processo/caminho no Windows, helpers de runner npm/pnpm/UI, configuração de gerenciador de pacotes e as superfícies do workflow de CI que executam essa lane; mudanças não relacionadas de código-fonte, Plugin, install-smoke e somente testes permanecem nas lanes Linux Node.
As famílias mais lentas de testes Node 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, pequenas lanes unitárias do core são pareadas, auto-reply roda como quatro workers balanceados (com a subárvore de reply dividida em shards de agent-runner, dispatch e commands/state-routing), e configurações agentic de Gateway/Plugin são distribuídas entre os jobs Node agentic somente de código-fonte existentes, em vez de esperar por artefatos compilados. Testes amplos de browser, QA, mídia e plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de plugins. Shards com padrões de inclusão registram entradas de timing usando o nome do shard de CI, então `.artifacts/vitest-shard-timings.json` consegue distinguir uma config inteira de um shard filtrado. `check-additional` mantém o trabalho de compile/canary de package-boundary junto e separa a arquitetura de topologia de runtime da cobertura de gateway watch; o shard de guarda de boundary executa seus pequenos guardas independentes concorrentemente dentro de um job. Gateway watch, testes de canal e o shard de support-boundary do core rodam concorrentemente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados.
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 canal rodam como três shards ponderados, lanes pequenas de unidade do core são pareadas, auto-reply roda como quatro workers balanceados (com a subárvore de reply dividida em shards de agent-runner, dispatch e commands/state-routing), e configs agentic de Gateway/Plugin são distribuídas pelos jobs Node agentic somente de código-fonte existentes em vez de esperar por artefatos compilados. Testes amplos de navegador, QA, mídia e Plugins diversos usam suas configs Vitest dedicadas em vez do catch-all compartilhado de Plugin. Shards de include-pattern registram entradas de tempo usando o nome do shard da CI, para que `.artifacts/vitest-shard-timings.json` consiga distinguir uma config inteira de um shard filtrado. `check-additional` mantém o trabalho de compilação/canário de package-boundary junto e separa arquitetura de topologia de runtime da cobertura de gateway watch; o shard de guard de boundary executa seus pequenos guards independentes concorrentemente dentro de um job. Gateway watch, testes de canal e o shard de support-boundary do core rodam concorrentemente dentro de `build-artifacts` depois que `dist/` e `dist-runtime/` já foram compilados.
A CI do Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest` e depois compila 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.
A CI do Android executa tanto `testPlayDebugUnitTest` quanto `testThirdPartyDebugUnitTest` e depois compila o APK de debug Play. O flavor third-party não tem source set nem manifesto separado; sua lane de teste unitário 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 shard `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`. O guarda de arquivos não usados falha quando uma PR adiciona um novo arquivo não usado sem revisão ou deixa uma entrada obsoleta na allowlist, preservando superfícies intencionais de Plugin dinâmico, geradas, de build, de testes live e de ponte de pacote que o Knip não consegue resolver estaticamente.
O shard `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 via `dlx`) e `pnpm deadcode:unused-files`, que compara os achados de arquivos de produção não usados do Knip com `scripts/deadcode-unused-files.allowlist.mjs`. O guard 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, teste live e bridge de pacote que o Knip não consegue resolver estaticamente.
## Disparos manuais
## Dispatches manuais
Disparos manuais de CI executam o mesmo grafo de jobs da CI normal, mas forçam todas as lanes escopadas não Android: shards Node do Linux, shards de plugins bundled, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, checks de docs, Skills Python, Windows, macOS e i18n do Control UI. Disparos manuais independentes de CI executam Android somente com `include_android=true`; o guarda-chuva de release completo habilita Android passando `include_android=true`. Checks estáticos de prerelease de Plugin, o shard `agentic-plugins` exclusivo de release, a varredura completa em lote de extensões e as lanes Docker de prerelease de plugins são excluídos da CI. A suíte Docker de prerelease só roda quando `Full Release Validation` dispara o workflow separado `Plugin Prerelease` com o gate de release-validation habilitado.
Dispatches manuais da CI executam o mesmo grafo de jobs que a CI normal, mas forçam todas as lanes escopadas que não são Android: shards Linux Node, shards de Plugin bundled, contratos de canal, compatibilidade com Node 22, `check`, `check-additional`, build smoke, checks de docs, Skills Python, Windows, macOS e i18n da Control UI. Dispatches manuais autônomos da CI executam Android apenas com `include_android=true`; o guarda-chuva de release completo habilita Android passando `include_android=true`. Checks estáticos de pré-lançamento de Plugin, o shard `agentic-plugins` exclusivo de release, a varredura completa em lote de extensões e as lanes Docker de pré-lançamento de Plugin são excluídos da CI. A suíte Docker de pré-lançamento só roda quando `Full Release Validation` dispara 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 outro push ou execução de 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 enquanto usa o arquivo de workflow da ref de disparo 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 outro push ou execução de 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 enquanto usa o arquivo de workflow da ref de dispatch selecionada.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -77,17 +77,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 | Trabalhos |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, trabalhos rápidos de segurança e agregados (`security-scm-fast`, `security-dependency-audit`, `security-fast`), verificações rápidas de protocolo/contrato/empacotadas, verificações fragmentadas de contrato de canal, fragmentos de `check`, exceto lint, fragmentos e agregados de `check-additional`, verificadores agregados de testes Node, verificações de docs, Skills de 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`, fragmentos de menor peso de extensões, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragmentos de testes Node no Linux, fragmentos de testes de Plugin empacotados, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU o suficiente para que 8 vCPU custasse mais do que economizava); builds Docker de install-smoke (o tempo de fila de 32 vCPU custava mais do que economizava) |
| `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 |
| 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/empacotadas, verificações fragmentadas de contrato de canais, fragmentos de `check` exceto lint, fragmentos 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 no GitHub para que a matriz Blacksmith possa entrar na fila mais cedo |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, fragmentos de extensões de menor peso, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` e `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, fragmentos de teste Node no Linux, fragmentos de teste de Plugins empacotados, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (sensível a CPU o suficiente para que 8 vCPU custassem mais do que economizaram); 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
@ -115,29 +115,41 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
```
## Validação completa de lançamento
## Validação Completa de Lançamento
`Full Release Validation` é o workflow guarda-chuva manual para "executar tudo antes do lançamento". Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para comprovação somente de lançamento de Plugin/pacote/estático/Docker e dispara `OpenClaw Release Checks` para install smoke, aceitação de pacote, suítes de caminho de lançamento Docker, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e canais do Telegram. Ele também pode executar o workflow pós-publicação `NPM Telegram Beta E2E` quando uma especificação de pacote publicado é fornecida.
`Full Release Validation` é o workflow guarda-chuva manual para "executar tudo antes do lançamento". Ele aceita uma branch, tag ou SHA completo de commit, dispara o workflow manual `CI` com esse alvo, dispara `Plugin Prerelease` para prova exclusiva de lançamento de Plugin/pacote/estático/Docker e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de lançamento Docker, live/E2E, OpenWebUI, paridade QA Lab, Matrix e lanes do Telegram. Ele também pode executar o workflow pós-publicação `NPM Telegram Beta E2E` quando uma especificação de pacote publicado é fornecida.
`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento:
Veja [validação completa de lançamento](/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.
- `minimum` mantém os canais críticos de lançamento OpenAI/núcleo mais rápidos.
`release_profile` controla a amplitude live/provedor passada para as verificações de lançamento. Os
workflows manuais de lançamento usam `stable` por padrão; use `full` somente quando você
intencionalmente quiser a matriz consultiva ampla de provedores/mídia.
- `minimum` mantém as lanes mais rápidas críticas para lançamento 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 matriz consultiva ampla 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 anexa tabelas dos trabalhos mais lentos para cada execução filha. Se um workflow filho for reexecutado e ficar verde, reexecute apenas o trabalho verificador pai para atualizar o resultado do guarda-chuva e o resumo de tempos.
O guarda-chuva registra os IDs das execuções filhas disparadas, e o job final `Verify full validation` revalida as conclusões atuais das execuções filhas e anexa tabelas dos jobs mais lentos de cada execução filha. Se um workflow 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 de lançamento, `ci` para apenas o filho de CI completo normal, `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 a reexecução de uma caixa de lançamento com falha delimitada 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` para somente o filho de CI completo normal, `plugin-prerelease` para somente o filho de pré-lançamento de Plugin, `release-checks` para todos os filhos de lançamento, ou um grupo mais restrito: `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.
`OpenClaw Release Checks` usa a referência confiável do workflow para resolver a referência selecionada uma vez em um tarball `release-package-under-test` e então passa esse artefato tanto para o workflow Docker de caminho de lançamento live/E2E quanto para o fragmento 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 workflow para resolver a referência selecionada uma vez em um tarball `release-package-under-test` e então passa esse artefato tanto para o workflow Docker live/E2E de caminho de lançamento quanto para o fragmento 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 jobs filhos.
## Fragmentos live e E2E
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 workflow filho que
já tenha disparado quando o pai é cancelado, para que uma validação mais nova de main
não fique atrás de uma execução obsoleta de release-check de duas horas. A validação de branch/tag
de lançamento e grupos de reexecução focada mantêm `cancel-in-progress: false`.
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 trabalho serial:
## Fragmentos Live e E2E
O filho live/E2E de lançamento mantém cobertura nativa ampla 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`
@ -147,27 +159,27 @@ O filho live/E2E de lançamento mantém ampla cobertura nativa de `pnpm test:liv
- `native-live-extensions-xai`
- 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 fragmentos agregados `native-live-extensions-o-z`, `native-live-extensions-media` e `native-live-extensions-media-music` permanecem válidos para reexecuções manuais de disparo único.
Isso mantém a mesma cobertura de arquivos enquanto torna falhas lentas de provedores live mais fáceis de reexecutar e diagnosticar. Os nomes agregados dos 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 fragmentos nativos de mídia live são executados em `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, criado pelo workflow `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 as suítes live com Docker em executores 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 workflow `Live Media Runner Image`. Essa imagem pré-instala `ffmpeg` e `ffprobe`; os jobs de mídia apenas verificam os binários antes da configuração. Mantenha suítes live baseadas em Docker em runners Blacksmith normais — jobs em contêiner são o lugar errado para iniciar testes Docker aninhados.
Fragmentos live de modelo/backend com Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:<sha>` por commit selecionado. O workflow de lançamento live cria e envia essa imagem uma vez, então os fragmentos Docker live de modelo, Gateway, backend CLI, associação ACP e harness Codex são executados com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Se esses fragmentos recriarem o alvo Docker completo do código-fonte de forma independente, a execução de lançamento está configurada incorretamente e desperdiçará tempo de relógio em builds de imagem duplicados.
Fragmentos live de modelo/backend baseados em Docker usam uma imagem compartilhada separada `ghcr.io/openclaw/openclaw-live-test:<sha>` por commit selecionado. O workflow de lançamento live cria e envia essa imagem uma vez; depois, os fragmentos de modelo live Docker, Gateway fragmentado por provedor, backend CLI, bind ACP e harness Codex são executados com `OPENCLAW_SKIP_DOCKER_BUILD=1`. Fragmentos Docker do Gateway carregam limites explícitos de `timeout` em nível de script abaixo do timeout do job do workflow para que um contêiner travado ou caminho de limpeza falhe rapidamente em vez de consumir todo o orçamento de release-check. Se esses fragmentos reconstruírem o alvo Docker completo de origem de forma independente, a execução de lançamento está mal configurada e desperdiçará tempo de relógio em builds duplicados de imagem.
## Aceitação de pacote
## Aceitação de Pacote
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 por meio do mesmo harness Docker E2E que usuários exercitam após instalar ou atualizar.
Use `Package Acceptance` quando a pergunta for "este pacote instalável do OpenClaw funciona como produto?" Ela é diferente do CI normal: o CI normal valida a árvore de origem, enquanto a aceitação de pacote valida um único tarball por meio do mesmo harness Docker E2E que os usuários exercitam após instalar ou atualizar.
### Trabalhos
### Jobs
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`, faz upload de ambos como o artefato `package-under-test` e imprime a origem, a referência do workflow, a referência do pacote, a versão, o SHA-256 e o 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 workflow reutilizável baixa esse artefato, valida o inventário do tarball, prepara imagens Docker de resumo de pacote quando necessário e executa os canais Docker selecionados contra esse pacote em vez de empacotar o checkout do workflow. Quando um perfil seleciona múltiplos `docker_lanes` direcionados, o workflow reutilizável prepara o pacote e as imagens compartilhadas uma vez e então distribui esses canais como trabalhos Docker direcionados paralelos com artefatos exclusivos.
3. `package_telegram` chama opcionalmente `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; o disparo autônomo do Telegram ainda pode instalar uma especificação npm publicada.
4. `summary` falha o workflow se a resolução do pacote, a aceitação Docker ou o canal opcional do Telegram falharem.
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`, carrega ambos como o artefato `package-under-test` e imprime a origem, a ref do workflow, a ref do pacote, a versão, o SHA-256 e o 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 workflow 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 workflow. Quando um perfil seleciona várias `docker_lanes` direcionadas, o workflow reutilizável prepara o pacote e as imagens compartilhadas uma vez, depois distribui essas lanes como jobs Docker direcionados paralelos com artefatos exclusivos.
3. `package_telegram` chama opcionalmente `NPM Telegram Beta E2E`. Ele executa quando `telegram_mode` não é `none` e instala o mesmo artefato `package-under-test` quando o Package Acceptance resolveu um; o dispatch independente do Telegram ainda pode instalar uma especificação npm publicada.
4. `summary` falha o workflow se a resolução do pacote, a aceitação Docker ou a lane opcional do Telegram falhou.
### Origens de candidatos
### Origens candidatas
- `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 beta/estável publicada.
- `source=ref` empacota uma branch, tag ou SHA completo de commit `package_ref` confiável. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável a partir do histórico de branches do repositório ou de uma tag de lançamento, instala dependências em uma worktree desanexada e o empacota com `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` aceita apenas `openclaw@beta`, `openclaw@latest` ou uma versão exata de release do OpenClaw, como `openclaw@2026.4.27-beta.2`. Use isto para aceitação de beta/estável publicado.
- `source=ref` empacota uma branch, tag ou SHA de commit completo confiável de `package_ref`. O resolvedor busca branches/tags do OpenClaw, verifica se o commit selecionado é alcançável a partir do histórico de branches do repositório ou de uma tag de release, 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.
@ -176,26 +188,26 @@ Mantenha `workflow_ref` e `package_ref` separados. `workflow_ref` é o código c
### 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`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
- `product` — `package` mais `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — blocos completos do caminho de lançamento do Docker com OpenWebUI
- `custom` — `docker_lanes` exatos; obrigatório quando `suite_profile=custom`
- `full` — blocos completos do caminho de release Docker com OpenWebUI
- `custom` — `docker_lanes` exatas; 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 lane opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, com o caminho da especificação npm publicada mantido para despachos independentes.
O perfil `package` usa cobertura de Plugin offline para que a validação do pacote publicado não dependa da disponibilidade ao vivo do ClawHub. A lane opcional do Telegram reutiliza o artefato `package-under-test` em `NPM Telegram Beta E2E`, mantendo o caminho da especificação npm publicada para dispatches independentes.
As verificações de lançamento chamam Package Acceptance com `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` e `telegram_mode=mock-openai`. Os blocos Docker do caminho de lançamento cobrem as lanes sobrepostas de pacote/atualização/plugin; Package Acceptance mantém a prova nativa do artefato para compatibilidade de canais incluídos, plugin offline e Telegram contra o mesmo tarball de pacote resolvido. As verificações de lançamento entre sistemas operacionais 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. As lanes novas de pacote e instalador do Windows também verificam que um pacote instalado pode importar uma substituição de controle de navegador a partir de um caminho absoluto bruto do Windows. O smoke de turno de agente OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` por padrão quando definido; caso contrário, usa `openai/gpt-5.4-mini`, para que a prova de instalação e Gateway permaneça rápida e determinística.
As verificações de release chamam Package Acceptance com `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` e `telegram_mode=mock-openai`. Os blocos Docker de caminho de release cobrem as lanes sobrepostas de pacote/atualização/Plugin; Package Acceptance mantém a prova nativa de artefato de compatibilidade de canais empacotados, Plugin offline e Telegram contra o mesmo tarball de pacote resolvido. As verificações de release entre sistemas operacionais 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. Em Package Acceptance, o tarball resolvido `package-under-test` é sempre o candidato e `published_upgrade_survivor_baseline` seleciona a linha de base publicada, usando `openclaw@latest` como padrão; comandos de reexecução de lanes com falha preservam essa linha de base. Execuções locais podem definir `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` para um pacote exato, como `openclaw@2026.4.15`. A lane publicada configura a linha de base com uma receita incorporada de comando `openclaw config set`, depois registra as etapas da receita em `summary.json`. Cobertura mais ampla de versões anteriores deve fragmentar Package Acceptance entre valores exatos de `published_upgrade_survivor_baseline`. As lanes Windows novas de pacote e instalador 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` como padrão quando definido; caso contrário, usa `openai/gpt-5.4-mini`, para que a prova de instalação e Gateway permaneça rápida e determinística.
### 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 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 de `gateway install --wrapper` quando o pacote não expõe essa flag;
- `update-channel-switch` pode remover `pnpm.patchedDependencies` ausentes do fixture fake de git derivado do tarball e pode registrar em log `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 sem reinstalação permaneçam inalterados.
- `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 da fixture fake de git derivada 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 config enquanto ainda exige que o registro de instalação e o comportamento de não reinstalação 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.
O pacote publicado `2026.4.26` também pode avisar sobre arquivos de carimbo de metadados de build local que já foram entregues. Pacotes posteriores devem satisfazer os contratos modernos; as mesmas condições falham em vez de avisar ou pular.
### Exemplos
@ -238,113 +250,113 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Ao depurar uma execução com falha de aceitação de pacote, 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 lane, tempos de fase e comandos de nova execução. Prefira executar novamente o perfil de pacote com falha ou as lanes Docker exatas em vez de executar novamente a validação completa de lançamento.
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. Depois inspecione a execução filha de `docker_acceptance` e seus artefatos Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, logs de lane, tempos de fases 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 seu próprio job `preflight`. Ele divide a cobertura de smoke em `run_fast_install_smoke` e `run_full_install_smoke`.
- **Caminho rápido** executa para pull requests que tocam superfícies Docker/pacote, alterações de pacote/manifesto de plugin incluído ou superfícies centrais de plugin/canal/Gateway/Plugin SDK que os jobs de smoke Docker exercitam. Alterações somente de código-fonte em plugin incluído, edições somente de teste e edições somente de documentação não reservam workers Docker. O caminho rápido constrói 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 gateway-network no contêiner, verifica um argumento de build de plugin incluído e executa o perfil Docker limitado de plugins incluídos sob um tempo limite agregado de comando de 240 segundos (cada execução Docker de cenário limitada separadamente).
- **Caminho completo** mantém a instalação de pacote por QR e a cobertura Docker/update do instalador para execuções noturnas agendadas, despachos manuais, verificações de lançamento via 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 do Dockerfile raiz GHCR de SHA alvo, depois executa instalação de pacote por QR, smokes do Dockerfile raiz/Gateway, smokes de instalador/update e o E2E Docker 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.
- **Caminho rápido** executa para pull requests que tocam superfícies Docker/pacote, alterações de pacote/manifesto de Plugin empacotado ou superfícies centrais de Plugin/canal/Gateway/SDK de Plugin que os jobs de smoke Docker exercitam. Alterações somente de origem em Plugin empacotado, edições somente de teste e edições somente de docs não reservam workers Docker. O caminho rápido cria a imagem Dockerfile raiz uma vez, verifica a CLI, executa o smoke de CLI de agentes delete com workspace compartilhado, executa o e2e gateway-network em container, verifica um argumento de build de Plugin empacotado e executa o perfil Docker de Plugin empacotado limitado 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/atualização de instalador para execuções agendadas noturnas, 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 GHCR de smoke do Dockerfile raiz no SHA-alvo, depois executa instalação de pacote QR, smokes de 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 pelos smokes da imagem raiz.
Pushes para `main` (incluindo commits de merge) não forçam o caminho completo; quando a lógica de escopo alterado 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 alterado 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 release.
O smoke lento de provedor de imagem com instalação global Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele executa na agenda noturna e a partir do workflow de verificações de lançamento, e despachos 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 de provedor de imagem com instalação global Bun é controlado separadamente por `run_bun_global_install_smoke`. Ele executa no agendamento noturno 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
`pnpm test:docker:all` pré-constrói uma imagem compartilhada de teste live, empacota o OpenClaw uma vez como um tarball npm e constrói duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
`pnpm test:docker:all` pré-compila uma imagem compartilhada de teste ao vivo, empacota o OpenClaw uma vez como um tarball npm e cria duas imagens compartilhadas de `scripts/e2e/Dockerfile`:
- um executor Node/Git básico para lanes de instalador/atualização/dependência de plugin;
- 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 normal.
As definições de lane Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica de planejamento fica em `scripts/lib/docker-e2e-plan.mjs`, e o executor apenas executa 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`.
As definições de lane Docker ficam em `scripts/lib/docker-e2e-scenarios.mjs`, a lógica de planner fica em `scripts/lib/docker-e2e-plan.mjs`, e o runner executa apenas o plano selecionado. O escalonador 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`.
### 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 simultâneas para que os provedores não apliquem throttling. |
| `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 | Escalonamento entre inícios de lanes para evitar rajadas de criação do daemon Docker; defina `0` para sem escalonamento. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Tempo limite 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 separada por vírgulas de lanes exatas; pula o smoke de limpeza para que agents 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 provedor. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Limite de lanes ao vivo 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 vários 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 nenhum intervalo. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout fallback por lane (120 minutos); lanes ao vivo/finais selecionadas usam limites menores. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` imprime o plano do escalonador sem executar lanes. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Lista exata de lanes separada por vírgulas; pula o smoke de limpeza para que agentes possam reproduzir uma lane com falha. |
Uma lane mais pesada que seu limite efetivo ainda pode iniciar a partir de um pool vazio, depois executa sozinha até liberar capacidade. O agregado local pré-verifica Docker, remove contêineres E2E obsoletos do OpenClaw, emite status de lanes ativas, persiste tempos de lane para ordenação do mais longo primeiro e, por padrão, para de agendar novas lanes em pool após a primeira falha.
Uma lane mais pesada que seu limite efetivo ainda pode iniciar a partir de um pool vazio e então executar sozinha até liberar capacidade. O agregado local faz preflight do Docker, remove containers E2E obsoletos do OpenClaw, emite status das lanes ativas, persiste tempos de lanes para ordenação da mais longa primeiro e, por padrão, para de agendar novas lanes agrupadas após a primeira falha.
### Workflow live/E2E reutilizável
### Fluxo de trabalho live/E2E reutilizável
O workflow live/E2E reutilizável pergunta a `scripts/test-docker-all.mjs --plan-json` quais coberturas de pacote, tipo de imagem, imagem live, lane e credenciais são necessárias. `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; constrói e envia imagens GHCR Docker E2E básicas/funcionais tagueadas por digest de pacote por meio do cache de camadas Docker da Blacksmith quando o plano precisa de lanes com pacote instalado; e reutiliza entradas fornecidas `docker_e2e_bare_image`/`docker_e2e_functional_image` ou imagens existentes por digest de pacote em vez de reconstruir. Pulls de imagens Docker são tentados novamente com um tempo limite limitado de 180 segundos por tentativa, para que um fluxo travado de registry/cache tente novamente rapidamente em vez de consumir a maior parte do caminho crítico de CI.
O fluxo de trabalho 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; constrói e envia imagens Docker E2E GHCR bare/functional 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 de digest de pacote em vez de reconstruir. Pulls de imagem Docker são repetidos com um tempo limite limitado de 180 segundos por tentativa, para que um fluxo travado de registro/cache seja repetido rapidamente em vez de consumir a maior parte do caminho crítico da CI.
### Blocos do caminho de lançamento
### Partes do caminho de lançamento
A cobertura Docker de lançamento executa jobs menores em blocos com `OPENCLAW_SKIP_DOCKER_BUILD=1`, para que cada bloco puxe apenas o tipo de imagem de que precisa e execute múltiplas lanes pelo mesmo agendador ponderado:
A cobertura Docker de lançamento executa jobs menores em partes com `OPENCLAW_SKIP_DOCKER_BUILD=1`, para que cada parte baixe apenas o tipo de imagem de que precisa e execute várias lanes por meio do mesmo scheduler 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 | bundled-channels`
Os chunks atuais do Docker de release são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a` até `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` e `bundled-channels-contracts`. O chunk agregado `bundled-channels` continua disponível para reexecuções manuais de uma só vez, e `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` continuam sendo aliases agregados de Plugin/runtime. O alias de faixa `install-e2e` continua sendo o alias agregado de reexecução manual para ambas as faixas de instalador de provedor. O chunk `bundled-channels` executa faixas divididas `bundled-channel-*` e `bundled-channel-update-*` em vez da faixa serial tudo-em-um `bundled-channel-deps`.
As partes Docker de lançamento atuais são `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, de `plugins-runtime-install-a` até `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` e `bundled-channels-contracts`. A parte agregada `bundled-channels` continua disponível para reexecuções manuais únicas, e `plugins-runtime-core`, `plugins-runtime` e `plugins-integrations` continuam sendo aliases agregados de plugin/runtime. O alias de lane `install-e2e` continua sendo o alias agregado de reexecução manual para ambas as lanes de instalador de provedor. A parte `bundled-channels` executa lanes divididas `bundled-channel-*` e `bundled-channel-update-*` em vez da lane serial tudo-em-um `bundled-channel-deps`.
OpenWebUI é incorporado a `plugins-runtime-services` quando a cobertura completa do caminho de release o solicita, e mantém um chunk independente `openwebui` apenas para dispatches exclusivos do OpenWebUI. As faixas de atualização de canais incluídos tentam novamente uma vez em caso de falhas transitórias de rede do npm.
OpenWebUI é incorporado a `plugins-runtime-services` quando a cobertura completa de release-path o solicita, e mantém uma parte independente `openwebui` apenas para despachos exclusivos de OpenWebUI. Lanes de atualização de canais empacotados repetem uma vez em caso de falhas transitórias de rede do npm.
Cada chunk envia `.artifacts/docker-tests/` com logs de faixas, tempos, `summary.json`, `failures.json`, tempos de fases, JSON do plano do scheduler, tabelas de faixas lentas e comandos de reexecução por faixa. A entrada `docker_lanes` do workflow executa as faixas selecionadas contra as imagens preparadas em vez dos jobs de chunk, o que mantém a depuração de faixas com falha limitada a um job Docker direcionado e prepara, baixa ou reutiliza o artefato de pacote para essa execução; se uma faixa selecionada for uma faixa Docker live, o job direcionado cria a imagem de teste live localmente para essa reexecução. Os comandos gerados de reexecução por faixa do GitHub incluem `package_artifact_run_id`, `package_artifact_name` e entradas de imagem preparada quando esses valores existem, para que uma faixa com falha possa reutilizar o pacote e as imagens exatos da execução com falha.
Cada parte envia `.artifacts/docker-tests/` com logs de lanes, tempos, `summary.json`, `failures.json`, tempos de fase, JSON do plano do scheduler, tabelas de lanes lentas e comandos de reexecução por lane. A entrada `docker_lanes` do fluxo de trabalho executa lanes selecionadas contra as imagens preparadas em vez dos jobs em partes, 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 constrói localmente a imagem de teste live 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.
```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 do caminho de release.
O fluxo de trabalho live/E2E agendado executa diariamente a suíte Docker completa de release-path.
## Pré-lançamento 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 dispatches manuais de CI independentes mantêm essa suíte desligada. Ele balanceia os testes de plugins incluídos em oito workers de extensões; 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ções não criem jobs extras de CI.
`Plugin Prerelease` é uma cobertura de produto/pacote mais cara, então é um fluxo de trabalho separado disparado por `Full Release Validation` ou por um operador explícito. Pull requests normais, pushes em `main` e despachos 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.
## QA Lab
QA Lab tem faixas de CI dedicadas fora do workflow principal com escopo inteligente.
O QA Lab tem lanes de CI dedicadas fora do principal fluxo de trabalho com escopo inteligente.
- O workflow `Parity gate` roda em alterações correspondentes de PR e em dispatch manual; ele cria o runtime privado de QA e compara os pacotes agentic simulados de GPT-5.5 e Opus 4.6.
- O workflow `QA-Lab - All Lanes` roda todas as noites em `main` e em dispatch manual; ele distribui o gate de paridade simulado, a faixa Matrix live e as faixas live de Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases do Convex.
- O fluxo de trabalho `Parity gate` executa em mudanças de PR correspondentes e despacho manual; ele constrói o runtime privado de QA e compara os pacotes agênticos mock GPT-5.5 e Opus 4.6.
- O fluxo de trabalho `QA-Lab - All Lanes` executa todas as noites em `main` e por despacho manual; ele distribui o gate de paridade mock, a lane Matrix live e as lanes live de Telegram e Discord como jobs paralelos. Jobs live usam o ambiente `qa-live-shared`, e Telegram/Discord usam leases do Convex.
As verificações de release executam faixas de transporte live de Matrix e Telegram com o provedor simulado 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 desabilita a busca de memória porque a paridade de QA cobre o comportamento de memória separadamente; a conectividade de provedor é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
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 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 provedor é coberta pelas suítes separadas de modelo live, provedor nativo e provedor Docker.
Matrix usa `--profile fast` para gates agendados e de release, adicionando `--fail-fast` apenas quando a CLI no checkout oferece suporte. O padrão da CLI e a entrada manual do workflow continuam sendo `all`; dispatch manual com `matrix_profile=all` sempre fragmenta a cobertura completa de Matrix nos jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
Matrix usa `--profile fast` para gates agendados e de lançamento, adicionando `--fail-fast` somente quando a CLI em checkout oferece suporte a isso. O padrão da CLI e a entrada manual do fluxo de trabalho continuam sendo `all`; o despacho manual `matrix_profile=all` sempre divide a cobertura completa do Matrix em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`.
`OpenClaw Release Checks` também executa as faixas 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 faixa paralelos, depois baixa ambos os artefatos para um job pequeno de relatório para a comparação final de paridade.
`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 lane paralelos, depois baixa ambos os artefatos em um pequeno job de relatório para a comparação final de paridade.
Não coloque o caminho de landing do PR atrás de `Parity gate` a menos que a alteração realmente toque no runtime de QA, na paridade de pacote de modelo ou em uma superfície que o workflow de paridade possui. Para correções normais de canal, configuração, docs ou testes de unidade, trate-o como um sinal opcional e siga as evidências de CI/verificação com escopo.
Não coloque o caminho de landing de PR atrás do `Parity gate` a menos que a mudança realmente toque no runtime de QA, na paridade de pacotes de modelo ou em uma superfície pertencente ao fluxo de trabalho de paridade. Para correções normais de canal, configuração, docs ou teste unitário, trate isso como um sinal opcional e siga as evidências de CI/verificação com escopo.
## CodeQL
O workflow `CodeQL` é intencionalmente um scanner de segurança estreito de primeira passagem, não a varredura completa do repositório. Execuções diárias, manuais e de guarda de pull request não rascunho escaneiam código de workflows do Actions mais as superfícies JavaScript/TypeScript de maior risco com consultas de segurança de alta confiança filtradas para `security-severity` alta/crítica.
O fluxo de trabalho `CodeQL` é intencionalmente um scanner de segurança estreito de primeira passagem, não uma varredura completa do repositório. Execuções diárias, manuais e de guarda de pull requests que não são rascunho escaneiam código de fluxos de trabalho do Actions mais 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 guarda de pull request permanece leve: ela só começa 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. CodeQL de Android e macOS ficam fora dos padrões de PR.
A guarda de pull request permanece leve: ela só inicia para mudanças em `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` ou `src`, e executa a mesma matriz de segurança de alta confiança que o fluxo de trabalho agendado. CodeQL de Android e macOS ficam fora dos padrões de PR.
### Categorias de segurança
| Categoria | Superfície |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, segredos, sandbox, cron e baseline de Gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canais core mais runtime de Plugin de canal, Gateway, Plugin SDK, segredos, pontos de contato de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies core de SSRF, parsing de IP, guarda de rede, web-fetch e política SSRF do Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Servidores MCP, helpers de execução de processo, entrega de saída e gates de execução de ferramentas de agentes |
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron e baseline de gateway |
| `/codeql-security-high/channel-runtime-boundary` | Contratos de implementação de canais core mais runtime de plugin de canal, gateway, Plugin SDK, secrets e pontos de contato de auditoria |
| `/codeql-security-high/network-ssrf-boundary` | Superfícies core de SSRF, parsing de IP, guarda 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 processo, entrega de saída e gates de execução de ferramentas por agentes |
| `/codeql-security-high/plugin-trust-boundary` | Superfícies de confiança de instalação de Plugin, loader, manifesto, registro, staging de dependências de runtime, carregamento de 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 Android. Cria o app Android manualmente para o CodeQL no menor runner Blacksmith Linux aceito pela sanidade do workflow. Envia em `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard semanal/manual de segurança macOS. Cria o app macOS manualmente para o CodeQL no Blacksmith macOS, filtra os resultados de build de dependências para fora do SARIF enviado e envia em `/codeql-critical-security/macos`. Mantido fora dos padrões diários porque o build macOS domina o tempo de execução mesmo quando limpo.
- `CodeQL Android Critical Security` — shard agendado de segurança do Android. Constrói o app Android manualmente para CodeQL no menor runner Linux 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. Constrói o app macOS manualmente para CodeQL no Blacksmith macOS, filtra resultados de build de dependências do SARIF enviado e envia 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 limpo.
### Categorias de Qualidade Crítica
### 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, com severidade de erro, sobre superfícies estreitas de alto valor no runner Blacksmith Linux menor. Sua guarda de pull request é 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 dispatch de resposta, código de schema/migração/IO de configuração, código de auth/segredos/sandbox/segurança, runtime de canais core e Plugin de canais incluídos, protocolo de Gateway/método de servidor, runtime de memória/glue de SDK, MCP/processo/entrega de saída, runtime de provedor/catálogo de modelos, 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 na configuração do CodeQL e no workflow 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 sem segurança e com severidade de erro em superfícies estreitas de alto valor no runner Linux Blacksmith menor. Sua guarda 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 mudanças em código de execução de comando/modelo/ferramenta de agente e despacho de resposta, schema/migração/IO de configuração, código de auth/secrets/sandbox/segurança, runtime de canal core e plugin de canal empacotado, protocolo de gateway/método de servidor, cola de runtime de memória/SDK, MCP/processo/entrega de saída, runtime de provedor/catálogo de modelos, diagnósticos de sessão/filas de entrega, loader de plugin, contrato de pacote/Plugin SDK ou runtime de resposta do Plugin SDK. Mudanças de configuração do CodeQL e de fluxo de trabalho de qualidade executam todos os doze shards de qualidade de PR.
Dispatch manual aceita:
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
@ -352,38 +364,38 @@ profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-run
Os perfis estreitos são hooks de ensino/iteração para executar um shard de qualidade isoladamente.
| Categoria | Superfície |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Autenticação, segredos, sandbox, cron e código de limite de segurança do gateway |
| `/codeql-critical-quality/config-boundary` | Contratos de esquema de configuração, migração, normalização e IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas de protocolo do Gateway e contratos de métodos do servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação de canais centrais e plugins de canal empacotados |
| `/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 processos 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 do SDK de Plugin de memória, cola de ativação do runtime de memória e comandos de doctor de memória |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internos da fila de respostas, 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 da CLI de doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do SDK de Plugin, 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 provedor, registro de runtime de provedor, padrões/catálogos de provedor 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` | Contratos de runtime de busca/pesquisa web central, IO de mídia, entendimento de mídia, geração de imagens e geração de mídia |
| `/codeql-critical-quality/plugin-boundary` | Contratos de carregador, registro, superfície pública e pontos de entrada do SDK de Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Código-fonte do SDK de Plugin no lado do pacote publicado e auxiliares de contrato de pacote de plugin |
| Categoria | Superfície |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Código de limite de segurança de autenticação, segredos, sandbox, Cron e Gateway |
| `/codeql-critical-quality/config-boundary` | Esquema de configuração, migração, normalização e contratos de IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Esquemas de protocolo do Gateway e contratos de métodos do servidor |
| `/codeql-critical-quality/channel-runtime-boundary` | Contratos de implementação do canal central e do 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 pontes 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, fachadas de runtime de memória, aliases do SDK de Plugin de memória, cola de ativação do runtime de memória e comandos de 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/pacotes de logs e contratos da CLI de doctor de sessão |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Despacho de respostas de entrada do SDK de Plugin, 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 provedores, padrões/catálogos de provedores e registros de web/search/fetch/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 central, 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 loader, registro, superfície pública e pontos de entrada do SDK de Plugin |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Fonte do SDK de Plugin no lado do pacote publicado e helpers de contrato de pacote de Plugin |
Qualidade permanece separada de segurança para que descobertas de qualidade possam ser agendadas, medidas, desabilitadas ou expandidas 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 definido ou fragmentado somente depois que os perfis estreitos tiverem runtime e sinal estáveis.
Qualidade permanece separada de segurança para que achados de qualidade possam ser agendados, medidos, desabilitados ou expandidos sem obscurecer o sinal de segurança. A expansão de CodeQL para Swift, Python e Plugins incluídos deve ser adicionada novamente como trabalho de acompanhamento com escopo ou fragmentado somente depois que os perfis estreitos tiverem runtime e sinal estáveis.
## Fluxos de manutenção
### Docs Agent
O fluxo de trabalho `Docs Agent` é uma trilha de manutenção do Codex orientada por eventos para manter a documentação existente alinhada com mudanças recém-integradas. Ele não tem agenda pura: 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 execução de fluxo de trabalho são ignoradas quando `main` avançou ou quando outra execução não ignorada do Docs Agent foi criada na última hora. Quando ele é executado, revisa o intervalo de commits do SHA de origem anterior não ignorado do Docs Agent até o `main` atual, de modo que uma execução por hora possa cobrir todas as mudanças no main acumuladas desde a última passagem de documentação.
O workflow `Docs Agent` é uma lane 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 agenda pura: uma execução bem-sucedida de CI de push não bot em `main` pode acioná-lo, e o disparo 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 executa, ele revisa o intervalo de commits do SHA de origem anterior não ignorado do Docs Agent até o `main` atual, de modo que uma execução por hora possa cobrir todas as alterações da main acumuladas desde a última passada de docs.
### Test Performance Agent
O fluxo de trabalho `Test Performance Agent` é uma trilha de manutenção do Codex orientada por eventos para testes lentos. Ele não tem agenda pura: 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 execução de fluxo de trabalho já tiver rodado ou estiver em execução naquele dia UTC. O despacho manual ignora esse bloqueio de atividade diária. A trilha cria um relatório completo de desempenho agrupado do Vitest, 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 executa novamente o relatório completo e rejeita mudanças que reduzam a contagem de testes aprovados na linha de base. Se a linha de base tiver testes com falha, o Codex pode corrigir apenas falhas óbvias, e o relatório completo pós-agente deve passar antes que qualquer coisa seja commitada. Quando `main` avança antes que o push do bot seja integrado, a trilha rebaseia o patch validado, executa novamente `pnpm check:changed` e tenta o push novamente; patches obsoletos conflitantes são ignorados. Ela usa Ubuntu hospedado pelo GitHub para que a ação do Codex possa manter a mesma postura de segurança sem sudo do agente de documentação.
O workflow `Test Performance Agent` é uma lane de manutenção do Codex orientada por eventos para testes lentos. Ele não tem agenda pura: uma execução bem-sucedida de CI de push não bot em `main` pode acioná-lo, mas ele é ignorado se outra invocação por workflow-run já executou ou está executando naquele dia UTC. O disparo manual contorna esse bloqueio de atividade diária. A lane cria um relatório de desempenho Vitest agrupado 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 executa novamente 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 com falha, o Codex pode corrigir apenas falhas óbvias, e o relatório da suíte completa pós-agente deve passar antes que qualquer coisa seja commitada. Quando `main` avança antes de o push do bot entrar, a lane faz rebase do patch validado, executa novamente `pnpm check:changed` e tenta o push de novo; patches obsoletos com conflito são ignorados. Ela usa Ubuntu hospedado pelo GitHub para que a ação do Codex possa manter a mesma postura de segurança drop-sudo que o agente de docs.
### PRs duplicados após merge
O fluxo de trabalho `Duplicate PRs After Merge` é um fluxo manual de mantenedor para limpeza de duplicatas após integração. Ele usa dry-run por padrão e só fecha PRs listados explicitamente quando `apply=true`. Antes de modificar o GitHub, ele verifica que o PR integrado foi mesclado e que cada duplicata tem uma issue referenciada compartilhada ou hunks alterados sobrepostos.
O workflow `Duplicate PRs After Merge` é um workflow manual de mantenedor para limpeza de duplicatas pós-integração. Por padrão, ele roda em modo dry-run e só fecha PRs listados explicitamente quando `apply=true`. Antes de modificar o GitHub, ele verifica se o PR integrado foi mesclado e se cada duplicata tem uma issue referenciada compartilhada ou hunks alterados sobrepostos.
```bash
gh workflow run duplicate-after-merge.yml \
@ -392,29 +404,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Portõ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 trilhas alteradas fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse portão de verificação local é mais rigoroso sobre limites de arquitetura do que o escopo amplo da plataforma de CI:
A lógica local de lanes alteradas fica em `scripts/changed-lanes.mjs` e é executada por `scripts/check-changed.mjs`. Esse gate de verificação local é mais estrito sobre limites de arquitetura do que o escopo amplo da plataforma de CI:
- mudanças de produção no núcleo executam typecheck de produção e de testes do núcleo, além de lint/guardas do núcleo;
- mudanças somente de testes do núcleo executam apenas typecheck de testes do núcleo, além de lint do núcleo;
- mudanças de produção em extensão executam typecheck de produção e de testes da extensão, além de lint da extensão;
- mudanças somente de testes de extensão executam typecheck de testes da extensão, além de lint da extensão;
- mudanças públicas no SDK de Plugin ou no contrato de plugin expandem para typecheck de extensão porque extensões dependem desses contratos centrais (varreduras Vitest de extensão permanecem trabalho de teste explícito);
- aumentos de versão somente de metadados de release executam verificações direcionadas de versão/configuração/dependências raiz;
- mudanças desconhecidas na raiz/configuração falham com segurança para todas as trilhas de verificação.
- alterações de produção no core executam typecheck de produção e de teste do core, além de lint/guards do core;
- alterações apenas de teste no core executam somente typecheck de teste do core, além de lint do core;
- alterações de produção em extensão executam typecheck de produção e de teste da extensão, além de lint da extensão;
- alterações apenas de teste em extensão executam typecheck de teste da extensão, além de lint da extensão;
- alterações públicas do SDK de Plugin ou de contrato de Plugin expandem para typecheck de extensões porque as extensões dependem desses contratos centrais (varreduras Vitest de extensões continuam sendo trabalho de teste explícito);
- aumentos de versão apenas 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 forma segura para todas as lanes de verificação.
O roteamento local de testes alterados fica em `scripts/test-projects.test-support.mjs` e é intencionalmente mais barato que `check:changed`: edições diretas de teste 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 de sala de grupo é um dos mapeamentos explícitos: mudanças na configuração de resposta visível ao grupo, no modo de entrega de resposta de origem ou no prompt do sistema da ferramenta de mensagens passam pelos testes centrais de resposta, além de regressões de entrega do Discord e Slack, para que uma mudança de padrão compartilhado falhe antes do primeiro push do PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando a mudança for ampla o suficiente no harness para que o conjunto mapeado barato não seja um proxy confiável.
O roteamento local de testes alterados fica 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 compartilhada de entrega em sala de grupo é um dos mapeamentos explícitos: alterações na configuração de resposta visível em grupo, no modo de entrega de resposta de origem ou na rota do prompt de sistema da ferramenta de mensagens passam pelos testes centrais de resposta, 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 do PR. Use `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando a alteração for ampla o suficiente no harness para que o conjunto mapeado barato não seja uma proxy confiável.
## Validação do Testbox
## Validação no Testbox
Execute o Testbox a partir da raiz do repositório e prefira uma caixa nova aquecida para prova ampla. Antes de gastar um portão lento em uma caixa que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute primeiro `pnpm testbox:sanity` dentro da caixa.
Execute o Testbox a partir da raiz do repo e prefira uma caixa nova aquecida para prova ampla. Antes de gastar um gate lento em uma caixa que foi reutilizada, expirou ou acabou de relatar uma sincronização inesperadamente grande, execute primeiro `pnpm testbox:sanity` dentro da caixa.
A verificação de sanidade falha rapidamente quando arquivos raiz obrigatórios, 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 caixa e aqueça uma nova em vez de depurar a falha de teste do produto. Para PRs intencionais com grande volume de exclusões, defina `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` para essa execução de sanidade.
A verificação de sanidade falha rápido quando arquivos raiz obrigatórios, 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 remota não é uma cópia confiável do PR; pare essa caixa e aqueça uma nova em vez de depurar a falha de 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 desabilitar essa guarda, 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 esse guard, ou use um valor maior em milissegundos para diffs locais excepcionalmente grandes.
## Relacionado
## Relacionados
- [Visão geral da instalação](/pt-BR/install)
- [Canais de desenvolvimento](/pt-BR/install/development-channels)

113
docs/pt-BR/cli/models.md
View File

@ -1,23 +1,23 @@
---
read_when:
- Você quer alterar os modelos padrão ou visualizar o status de autenticação do provedor
- Você quer verificar os modelos/provedores disponíveis e depurar perfis de autenticação
summary: Referência da CLI para `openclaw models` (status/list/set/scan, aliases, alternativas, autenticação)
- Você quer alterar os modelos padrão ou ver o status de autenticação do provedor
- Você quer examinar os modelos/provedores disponíveis e depurar perfis de autenticação
summary: Referência da CLI para `openclaw models` (status/list/set/scan, apelidos, alternativas, autenticação)
title: Modelos
x-i18n:
generated_at: "2026-04-30T09:42:14Z"
generated_at: "2026-05-01T05:55:10Z"
model: gpt-5.5
provider: openai
source_hash: 95e2361989b583f7f52947dad1faaaba44dc6a5f58719cc2e83c13fce7c33adc
source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
source_path: cli/models.md
workflow: 16
---
# `openclaw models`
Descoberta, varredura e configuração de modelos (modelo padrão, alternativas, perfis de autenticação).
Descoberta, varredura e configuração de modelos (modelo padrão, fallbacks, perfis de autenticação).
Relacionado:
Relacionados:
- Provedores + modelos: [Modelos](/pt-BR/providers/models)
- Conceitos de seleção de modelo + comando de barra `/models`: [Conceito de modelos](/pt-BR/concepts/models)
@ -32,77 +32,82 @@ openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` mostra o padrão/as alternativas resolvidos, além de uma visão geral de autenticação.
Quando snapshots de uso do provedor estão disponíveis, a seção de status OAuth/chave de API inclui
`openclaw models status` mostra o padrão/fallbacks resolvidos, além de uma visão geral de autenticação.
Quando snapshots de uso do provedor estão disponíveis, a seção de status de OAuth/chave de API inclui
janelas de uso do provedor e snapshots de cota.
Provedores atuais de janela de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Provedores atuais com janela de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi e z.ai. A autenticação de uso vem de hooks específicos do provedor
quando disponíveis; caso contrário, o OpenClaw recorre a credenciais OAuth/chave de API
correspondentes de perfis de autenticação, env ou config.
correspondentes de perfis de autenticação, env ou configuração.
Na saída `--json`, `auth.providers` é a visão geral de provedores ciente de env/config/store,
enquanto `auth.oauth` é apenas a integridade dos perfis do armazenamento de autenticação.
Adicione `--probe` para executar sondagens de autenticação ao vivo em cada perfil de provedor configurado.
Sondagens são solicitações reais (podem consumir tokens e acionar limites de taxa).
enquanto `auth.oauth` é apenas a integridade de perfis do armazenamento de autenticação.
Adicione `--probe` para executar probes de autenticação ao vivo em cada perfil de provedor configurado.
Probes são solicitações reais (podem consumir tokens e acionar limites de taxa).
Use `--agent <id>` para inspecionar o estado de modelo/autenticação de um agente configurado. Quando omitido,
o comando usa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` se definido; caso contrário, usa o
agente padrão configurado.
Linhas de sondagem podem vir de perfis de autenticação, credenciais de env ou `models.json`.
Linhas de probe podem vir de perfis de autenticação, credenciais env ou `models.json`.
Observações:
- `models set <model-or-alias>` aceita `provider/model` ou um alias.
- `models list` é somente leitura: ele lê a config, os perfis de autenticação, o estado de catálogo
existente e as linhas de catálogo pertencentes ao provedor, mas não reescreve
- `models list` é somente leitura: ele lê a configuração, perfis de autenticação, estado de catálogo
existente e linhas de catálogo pertencentes ao provedor, mas não reescreve
`models.json`.
- A coluna `Auth` é em nível de provedor e somente leitura. Ela é calculada a partir de metadados
locais de perfil de autenticação, marcadores de env, chaves de provedor configuradas, marcadores de
provedor local, marcadores de env/perfil do AWS Bedrock e metadados de autenticação sintética de plugins;
locais de perfil de autenticação, marcadores env, chaves de provedor configuradas, marcadores de
provedor local, marcadores env/perfil do AWS Bedrock e metadados de autenticação sintética de Plugin;
ela não carrega o runtime do provedor, não lê segredos do keychain, não chama APIs do provedor
nem comprova a prontidão exata de execução por modelo.
- `models list --all --provider <id>` pode incluir linhas estáticas de catálogo pertencentes ao provedor
vindas de manifests de plugin ou metadados de catálogo de provedor incluídos, mesmo quando você
ainda não se autenticou nesse provedor. Essas linhas ainda aparecem como
nem comprova prontidão exata de execução por modelo.
- `models list --all --provider <id>` pode incluir linhas de catálogo estático pertencentes ao provedor
vindas de manifestos de Plugin ou metadados de catálogo de provedor incluído, mesmo quando você
ainda não se autenticou com esse provedor. Essas linhas ainda aparecem como
indisponíveis até que a autenticação correspondente seja configurada.
- `models list --all` amplo mescla linhas de catálogo de manifest sobre linhas de registro
sem carregar hooks suplementares de runtime do provedor. Caminhos rápidos de manifest filtrados por provedor
- `models list` mantém o plano de controle responsivo enquanto a descoberta de catálogo do provedor
está lenta. As visualizações padrão e configurada recorrem a linhas de modelo configuradas ou
sintéticas após uma espera curta e deixam a descoberta terminar em
segundo plano. Use `--all` quando precisar do catálogo descoberto completo exato e
estiver disposto a esperar pela descoberta do provedor.
- `models list --all` amplo mescla linhas de catálogo de manifesto sobre linhas de registro
sem carregar hooks suplementares do runtime do provedor. Caminhos rápidos de manifesto filtrados por provedor
usam apenas provedores marcados como `static`; provedores marcados como `refreshable`
permanecem baseados em registro/cache e acrescentam linhas de manifest como suplementos, enquanto
provedores marcados como `runtime` permanecem na descoberta por registro/runtime.
permanecem apoiados por registro/cache e acrescentam linhas de manifesto como suplementos, enquanto
provedores marcados como `runtime` permanecem em descoberta de registro/runtime.
- `models list` mantém metadados nativos de modelo e limites de runtime distintos. Na saída em tabela,
`Ctx` mostra `contextTokens/contextWindow` quando um limite efetivo de runtime
difere da janela de contexto nativa; linhas JSON incluem `contextTokens`
quando um provedor expõe esse limite.
- `models list --provider <id>` filtra por id de provedor, como `moonshot` ou
- `models list --provider <id>` filtra por id do provedor, como `moonshot` ou
`openai-codex`. Ele não aceita rótulos de exibição de seletores interativos de provedor,
como `Moonshot AI`.
- Referências de modelo são analisadas dividindo no **primeiro** `/`. Se o ID do modelo incluir `/` (estilo OpenRouter), inclua o prefixo do provedor (exemplo: `openrouter/moonshotai/kimi-k2`).
- Referências de modelo são analisadas dividindo na **primeira** `/`. Se o ID do modelo incluir `/` (estilo OpenRouter), inclua o prefixo do provedor (exemplo: `openrouter/moonshotai/kimi-k2`).
- Se você omitir o provedor, o OpenClaw resolve a entrada primeiro como um alias, depois
como uma correspondência única de provedor configurado para esse id de modelo exato, e só então
recorre ao provedor padrão configurado com um aviso de depreciação.
Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw
recorre ao primeiro provedor/modelo configurado em vez de expor um
recorre ao primeiro provedor/modelo configurado em vez de mostrar um
padrão obsoleto de provedor removido.
- `models status` pode mostrar `marker(<value>)` na saída de autenticação para placeholders não secretos (por exemplo `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) em vez de mascará-los como segredos.
### Varredura de modelos
`models scan` lê o catálogo público `:free` do OpenRouter e classifica candidatos para
uso como alternativa. O catálogo em si é público, então varreduras somente de metadados não precisam de
uma chave do OpenRouter.
uso como fallback. O catálogo em si é público, então varreduras apenas de metadados não precisam
de uma chave do OpenRouter.
Por padrão, o OpenClaw tenta sondar suporte a ferramentas e imagens com chamadas de modelo ao vivo.
Se nenhuma chave do OpenRouter estiver configurada, o comando recorre à saída somente de metadados
Por padrão, o OpenClaw tenta testar suporte a ferramentas e imagens com chamadas de modelo ao vivo.
Se nenhuma chave do OpenRouter estiver configurada, o comando recorre à saída apenas de metadados
e explica que modelos `:free` ainda exigem `OPENROUTER_API_KEY` para
sondagens e inferência.
probes e inferência.
Opções:
- `--no-probe` (somente metadados; sem consulta a config/segredos)
- `--no-probe` (somente metadados; sem consulta de config/segredos)
- `--min-params <b>`
- `--max-age-days <days>`
- `--provider <name>`
- `--max-candidates <n>`
- `--timeout <ms>` (solicitação de catálogo e tempo limite por sondagem)
- `--timeout <ms>` (solicitação de catálogo e timeout por probe)
- `--concurrency <n>`
- `--yes`
- `--no-input`
@ -110,8 +115,8 @@ Opções:
- `--set-image`
- `--json`
`--set-default` e `--set-image` exigem sondagens ao vivo; resultados de varredura somente de metadados
são informativos e não são aplicados à config.
`--set-default` e `--set-image` exigem probes ao vivo; resultados de varredura
apenas de metadados são informativos e não são aplicados à configuração.
### Status de modelos
@ -120,8 +125,8 @@ Opções:
- `--json`
- `--plain`
- `--check` (exit 1=expirado/ausente, 2=expirando)
- `--probe` (sondagem ao vivo de perfis de autenticação configurados)
- `--probe-provider <name>` (sondar um provedor)
- `--probe` (probe ao vivo dos perfis de autenticação configurados)
- `--probe-provider <name>` (testar um provedor)
- `--probe-profile <id>` (repetir ou ids de perfil separados por vírgula)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
@ -129,10 +134,10 @@ Opções:
- `--agent <id>` (id de agente configurado; substitui `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
`--json` mantém stdout reservado para o payload JSON. Diagnósticos de perfil de autenticação, provedor
e inicialização são roteados para stderr para que scripts possam enviar stdout diretamente
e inicialização são roteados para stderr para que scripts possam encaminhar stdout diretamente
para ferramentas como `jq`.
Buckets de status de sondagem:
Buckets de status de probe:
- `ok`
- `auth`
@ -143,17 +148,17 @@ Buckets de status de sondagem:
- `unknown`
- `no_model`
Casos esperados de detalhe/código de motivo da sondagem:
Casos de código de detalhe/motivo de probe esperados:
- `excluded_by_auth_order`: existe um perfil armazenado, mas
`auth.order.<provider>` explícito o omitiu, então a sondagem informa a exclusão em vez de
- `excluded_by_auth_order`: existe um perfil armazenado, mas `auth.order.<provider>` explícito
o omitiu, então o probe relata a exclusão em vez de
tentar usá-lo.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
o perfil está presente, mas não é elegível/resolvível.
- `no_model`: existe autenticação do provedor, mas o OpenClaw não conseguiu resolver um candidato
de modelo sondável para esse provedor.
de modelo testável para esse provedor.
## Aliases + alternativas
## Aliases + fallbacks
```bash
openclaw models aliases list
@ -170,10 +175,10 @@ openclaw models auth paste-token
```
`models auth add` é o auxiliar interativo de autenticação. Ele pode iniciar um fluxo de autenticação
do provedor (OAuth/chave de API) ou orientar você na colagem manual de token, dependendo do
de provedor (OAuth/chave de API) ou guiar você para colar um token manualmente, dependendo do
provedor escolhido.
`models auth login` executa o fluxo de autenticação de um plugin de provedor (OAuth/chave de API). Use
`models auth login` executa o fluxo de autenticação de um Plugin de provedor (OAuth/chave de API). Use
`openclaw plugins list` para ver quais provedores estão instalados.
Use `openclaw models auth --agent <id> <subcommand>` para gravar resultados de autenticação em um
armazenamento específico de agente configurado. A flag pai `--agent` é respeitada por
@ -187,7 +192,7 @@ openclaw models auth login --provider openai-codex --set-default
Observações:
- `setup-token` e `paste-token` permanecem comandos genéricos de token para provedores
- `setup-token` e `paste-token` continuam sendo comandos genéricos de token para provedores
que expõem métodos de autenticação por token.
- `setup-token` exige um TTY interativo e executa o método de autenticação por token do provedor
(usando por padrão o método `setup-token` desse provedor quando ele expõe
@ -198,10 +203,10 @@ Observações:
`--profile-id`.
- `paste-token --expires-in <duration>` armazena uma expiração absoluta de token a partir de uma
duração relativa, como `365d` ou `12h`.
- Observação sobre a Anthropic: a equipe da Anthropic nos informou que o uso da Claude CLI no estilo OpenClaw é permitido novamente, então o OpenClaw trata a reutilização da Claude CLI e o uso de `claude -p` como sancionados para esta integração, a menos que a Anthropic publique uma nova política.
- Anthropic `setup-token` / `paste-token` permanecem disponíveis como um caminho de token OpenClaw compatível, mas o OpenClaw agora prefere reutilização da Claude CLI e `claude -p` quando disponíveis.
- Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw voltou a ser permitido, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como sancionados para esta integração, a menos que a Anthropic publique uma nova política.
- Anthropic `setup-token` / `paste-token` continuam disponíveis como um caminho de token do OpenClaw com suporte, mas o OpenClaw agora prefere reutilizar o Claude CLI e `claude -p` quando disponíveis.
## Relacionado
## Relacionados
- [Referência da CLI](/pt-BR/cli)
- [Seleção de modelo](/pt-BR/concepts/model-providers)

56
docs/pt-BR/cli/proxy.md
View File

@ -1,32 +1,36 @@
---
read_when:
- Você precisa capturar localmente o tráfego de transporte do OpenClaw para depuração
- Você quer inspecionar sessões do proxy de depuração, blobs ou predefinições de consulta integradas
summary: Referência da CLI para `openclaw proxy`, o proxy local de depuração e inspetor de capturas
- Você precisa validar o roteamento de proxy gerenciado pelo operador antes da implantação
- É necessário capturar o tráfego de transporte do OpenClaw localmente para depuração
- Você quer inspecionar sessões de proxy de depuração, blobs ou predefinições de consulta integradas
summary: Referência da CLI para `openclaw proxy`, incluindo a validação de proxy gerenciado pelo operador e o inspetor de capturas do proxy de depuração local
title: Proxy
x-i18n:
generated_at: "2026-04-24T05:46:19Z"
model: gpt-5.4
generated_at: "2026-05-01T05:55:18Z"
model: gpt-5.5
provider: openai
source_hash: 7af5c596fb36f67e3fcffaff14dcbb4eabbcff0b95174ac6058a097ec9fd715f
source_hash: e0820de861bfe1ec14e0c1624d636d6474b5fedd317e3ba1baaa61f6530e06e9
source_path: cli/proxy.md
workflow: 15
workflow: 16
---
# `openclaw proxy`
Execute o proxy local explícito de depuração e inspecione o tráfego capturado.
Valide o roteamento de proxy gerenciado pelo operador ou execute o proxy de depuração explícito local
e inspecione o tráfego capturado.
Este é um comando de depuração para investigação em nível de transporte. Ele pode iniciar um
proxy local, executar um comando filho com captura ativada, listar sessões de captura,
consultar padrões comuns de tráfego, ler blobs capturados e limpar dados locais
de captura.
Use `validate` para fazer uma verificação prévia de um proxy de encaminhamento gerenciado pelo operador antes de habilitar
o roteamento de proxy do OpenClaw. Os outros comandos são ferramentas de depuração para
investigação em nível de transporte: eles podem iniciar um proxy local, executar um comando filho
com captura habilitada, listar sessões de captura, consultar padrões comuns de tráfego, ler
blobs capturados e limpar dados de captura locais.
## Comandos
```bash
openclaw proxy start [--host <host>] [--port <port>]
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
openclaw proxy coverage
openclaw proxy sessions [--limit <count>]
openclaw proxy query --preset <name> [--session <id>]
@ -34,6 +38,28 @@ openclaw proxy blob --id <blobId>
openclaw proxy purge
```
## Validar
`openclaw proxy validate` verifica a URL efetiva do proxy gerenciado pelo operador a partir de
`--proxy-url`, da configuração ou de `OPENCLAW_PROXY_URL`. Ele relata um problema de configuração quando
nenhum proxy está habilitado e configurado; use `--proxy-url` para uma verificação prévia pontual
antes de alterar a configuração. Por padrão, ele verifica se um destino público tem sucesso
por meio do proxy e se o proxy não consegue acessar um canário temporário de loopback.
Destinos negados personalizados falham fechados: respostas HTTP e falhas de transporte
ambíguas falham, a menos que você consiga verificar separadamente um sinal de negação específico
da implantação.
Opções:
- `--json`: imprime JSON legível por máquina.
- `--proxy-url <url>`: valida esta URL de proxy em vez da configuração ou do env.
- `--allowed-url <url>`: adiciona um destino que deve ter sucesso por meio do proxy. Repita para verificar vários destinos.
- `--denied-url <url>`: adiciona um destino que deve ser bloqueado pelo proxy. Repita para verificar vários destinos.
- `--timeout-ms <ms>`: tempo limite por solicitação em milissegundos.
Consulte [Proxy de rede](/pt-BR/security/network-proxy) para orientação de implantação e semântica de
negação.
## Predefinições de consulta
`openclaw proxy query --preset <name>` aceita:
@ -48,10 +74,12 @@ openclaw proxy purge
## Observações
- `start` usa `127.0.0.1` por padrão, a menos que `--host` seja definido.
- `run` inicia um proxy local de depuração e depois executa o comando após `--`.
- Capturas são dados locais de depuração; use `openclaw proxy purge` quando terminar.
- `run` inicia um proxy de depuração local e depois executa o comando após `--`.
- `validate` sai com o código 1 quando a configuração do proxy ou as verificações de destino falham.
- As capturas são dados de depuração locais; use `openclaw proxy purge` quando terminar.
## Relacionado
- [Referência da CLI](/pt-BR/cli)
- [Proxy de rede](/pt-BR/security/network-proxy)
- [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth)

37
docs/pt-BR/cli/voicecall.md
View File

@ -2,30 +2,36 @@
read_when:
- Você usa o Plugin de chamada de voz e quer os pontos de entrada da CLI
- Você quer exemplos rápidos para `voicecall setup|smoke|call|continue|dtmf|status|tail|expose`
summary: Referência da CLI para `openclaw voicecall` (superfície de comando do Plugin de chamada de voz)
summary: Referência da CLI para `openclaw voicecall` (superfície de comandos do Plugin de chamada de voz)
title: Chamada de voz
x-i18n:
generated_at: "2026-04-25T13:44:15Z"
model: gpt-5.4
generated_at: "2026-05-01T05:55:55Z"
model: gpt-5.5
provider: openai
source_hash: 7c8b83ef75f792920024a67b0dee1b07aff9f55486de1149266c6d94854ca0fe
source_hash: c040cf4cd984ad6d6dd302923494a7c8ee131390b803fe20a9894b077f08d5bb
source_path: cli/voicecall.md
workflow: 15
workflow: 16
---
# `openclaw voicecall`
`voicecall` é um comando fornecido por Plugin. Ele só aparece se o Plugin de chamada de voz estiver instalado e ativado.
`voicecall` é um comando fornecido por Plugin. Ele aparece somente se o Plugin de chamada de voz estiver instalado e habilitado.
Quando o Gateway está em execução, comandos operacionais (`call`, `start`,
`continue`, `speak`, `dtmf`, `end` e `status`) são enviados para o runtime de
chamada de voz desse Gateway. Se nenhum Gateway estiver acessível, eles recorrem
a um runtime de CLI independente.
Documentação principal:
- Plugin de chamada de voz: [Voice Call](/pt-BR/plugins/voice-call)
- Plugin de chamada de voz: [Chamada de voz](/pt-BR/plugins/voice-call)
## Comandos comuns
```bash
openclaw voicecall setup
openclaw voicecall smoke
openclaw voicecall status --json
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
@ -40,16 +46,19 @@ scripts:
openclaw voicecall setup --json
```
Para provedores externos (`twilio`, `telnyx`, `plivo`), `setup` precisa resolver uma
URL pública de Webhook a partir de `publicUrl`, um túnel ou exposição via Tailscale. Um fallback de serviço em loopback/privado
é rejeitado porque as operadoras não conseguem alcançá-lo.
`status` imprime chamadas ativas como JSON por padrão. Passe `--call-id <id>` para inspecionar
uma chamada.
Para provedores externos (`twilio`, `telnyx`, `plivo`), a configuração precisa resolver uma URL de
Webhook pública a partir de `publicUrl`, de um túnel ou da exposição via Tailscale. Um fallback de
serviço em loopback/privado é rejeitado porque as operadoras não conseguem acessá-lo.
`smoke` executa as mesmas verificações de prontidão. Ele não fará uma chamada telefônica real
a menos que `--to` e `--yes` estejam presentes:
```bash
openclaw voicecall smoke --to "+15555550123" # execução de teste
openclaw voicecall smoke --to "+15555550123" --yes # chamada notify real
openclaw voicecall smoke --to "+15555550123" # dry run
openclaw voicecall smoke --to "+15555550123" --yes # live notify call
```
## Expondo Webhooks (Tailscale)
@ -60,9 +69,9 @@ openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
Observação de segurança: exponha o endpoint de Webhook apenas a redes em que você confia. Prefira Tailscale Serve a Funnel sempre que possível.
Observação de segurança: exponha o endpoint de Webhook somente para redes em que você confia. Prefira Tailscale Serve em vez de Funnel quando possível.
## Relacionados
## Relacionado
- [Referência da CLI](/pt-BR/cli)
- [Plugin de chamada de voz](/pt-BR/plugins/voice-call)

80
docs/pt-BR/concepts/commitments.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Você quer que o OpenClaw se lembre de continuações naturais
- Você quer entender como os registros inferidos diferem dos lembretes
- Você quer que o OpenClaw se lembre de acompanhamentos naturais
- Você quer entender como as verificações inferidas diferem dos lembretes
- Você quer revisar ou descartar compromissos de acompanhamento
sidebarTitle: Commitments
summary: Memória de acompanhamento inferida para verificações que não são lembretes exatos
title: Compromissos inferidos
x-i18n:
generated_at: "2026-04-30T09:43:56Z"
generated_at: "2026-05-01T05:56:05Z"
model: gpt-5.5
provider: openai
source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111
source_hash: 78841d87fe749aa5b04a967218396df1c1a7884c5767b09215c96aee34fa2014
source_path: concepts/commitments.md
workflow: 16
---
Compromissos são memórias de acompanhamento de curta duração. Quando ativados, o OpenClaw pode
perceber que uma conversa criou uma oportunidade futura de verificação e lembrar
de retomá-la depois.
perceber que uma conversa criou uma oportunidade futura de check-in e lembrar
de trazê-la de volta mais tarde.
Exemplos:
- Você menciona uma entrevista amanhã. O OpenClaw pode verificar depois.
- Você menciona uma entrevista amanhã. O OpenClaw pode fazer check-in depois.
- Você diz que está exausto. O OpenClaw pode perguntar depois se você dormiu.
- O agente diz que fará um acompanhamento depois que algo mudar. O OpenClaw pode rastrear
esse ciclo aberto.
- O agente diz que fará acompanhamento depois que algo mudar. O OpenClaw pode acompanhar
esse loop aberto.
Compromissos não são fatos duráveis como `MEMORY.md`, e não são lembretes
exatos. Eles ficam entre memória e automação: o OpenClaw lembra uma
obrigação vinculada à conversa, então o Heartbeat a entrega quando ela vence.
exatos. Eles ficam entre memória e automação: o OpenClaw lembra uma obrigação
vinculada à conversa, então o Heartbeat a entrega quando ela vence.
## Ativar compromissos
@ -51,7 +51,7 @@ openclaw config set commitments.maxPerDay 3
```
`commitments.maxPerDay` limita quantos acompanhamentos inferidos podem ser entregues
por sessão de agente em um dia contínuo. O padrão é `3`.
por sessão de agente em um dia móvel. O padrão é `3`.
## Como funciona
@ -62,45 +62,49 @@ para raciocinar sobre a extração.
Quando encontra um candidato de alta confiança, o OpenClaw armazena um compromisso com:
- o ID do agente
- o id do agente
- a chave da sessão
- o canal original e o destino de entrega
- o canal original e o alvo de entrega
- uma janela de vencimento
- uma sugestão curta de verificação
- contexto de origem suficiente para o Heartbeat decidir se deve enviá-lo
- um check-in curto sugerido
- metadados não instrucionais para o Heartbeat decidir se deve enviá-lo
A entrega acontece por meio do Heartbeat. Quando um compromisso vence, o Heartbeat
adiciona o compromisso ao turno de Heartbeat para o mesmo agente e escopo de canal.
O modelo pode enviar uma verificação natural ou responder `HEARTBEAT_OK` para descartá-lo.
A entrega acontece pelo Heartbeat. Quando um compromisso vence, o Heartbeat
adiciona o compromisso à rodada de Heartbeat para o mesmo agente e escopo de canal.
O modelo pode enviar um check-in natural ou responder `HEARTBEAT_OK` para dispensá-lo.
Se o Heartbeat estiver configurado com `target: "none"`, os compromissos vencidos permanecem
internos e não enviam check-ins externos. Prompts de entrega de compromisso não
reproduzem o texto da conversa original, e rodadas de Heartbeat de compromisso vencido são executadas
sem ferramentas do OpenClaw.
O OpenClaw nunca entrega um compromisso inferido imediatamente depois de escrevê-lo.
O OpenClaw nunca entrega um compromisso inferido imediatamente depois de gravá-lo.
O horário de vencimento é limitado a pelo menos um intervalo de Heartbeat depois que o compromisso
é criado, para que o acompanhamento não seja repetido no mesmo momento em que foi
é criado, para que o acompanhamento não ecoe de volta no mesmo momento em que foi
inferido.
## Escopo
Compromissos são escopados ao agente e ao contexto de canal exatos em que foram
criados. Um acompanhamento inferido ao conversar com um agente no Discord não é
Compromissos têm escopo limitado ao agente exato e ao contexto de canal em que foram
criados. Um acompanhamento inferido durante uma conversa com um agente no Discord não é
entregue por outro agente, outro canal ou uma sessão não relacionada.
Esse escopo faz parte do recurso. Verificações naturais devem parecer a continuação
da mesma conversa, não um sistema global de lembretes.
Esse escopo faz parte do recurso. Check-ins naturais devem parecer a continuação da mesma
conversa, não um sistema global de lembretes.
## Compromissos vs. lembretes
## Compromissos vs lembretes
| Necessidade | Use |
| Necessidade | Usar |
| ----------------------------------------------- | ---------------------------------------- |
| "Lembre-me às 15h" | [Tarefas agendadas](/pt-BR/automation/cron-jobs) |
| "Me avise em 20 minutos" | [Tarefas agendadas](/pt-BR/automation/cron-jobs) |
| "Execute este relatório todos os dias úteis" | [Tarefas agendadas](/pt-BR/automation/cron-jobs) |
| "Tenho uma entrevista amanhã" | Compromissos |
| "Passei a noite acordado" | Compromissos |
| "Faça acompanhamento se eu não responder a esta conversa aberta" | Compromissos |
| "Tenho uma entrevista amanhã" | Compromissos |
| "Passei a noite inteira acordado" | Compromissos |
| "Faça acompanhamento se eu não responder esta thread aberta" | Compromissos |
Solicitações exatas do usuário já pertencem ao caminho do agendador. Compromissos são apenas
para acompanhamentos inferidos: os momentos em que o usuário não pediu um lembrete,
mas a conversa claramente criou uma verificação futura útil.
mas a conversa claramente criou um check-in futuro útil.
## Gerenciar compromissos
@ -114,13 +118,13 @@ openclaw commitments --status snoozed
openclaw commitments dismiss cm_abc123
```
Veja [`openclaw commitments`](/pt-BR/cli/commitments) para a referência do comando.
Consulte [`openclaw commitments`](/pt-BR/cli/commitments) para a referência do comando.
## Privacidade e custo
A extração de compromissos usa uma passagem de LLM, então ativá-la adiciona uso de modelo em segundo plano
após turnos elegíveis. A passagem fica oculta da conversa
visível ao usuário, mas pode ler a troca recente necessária para decidir se existe um
após rodadas elegíveis. A passagem fica oculta da conversa visível ao usuário,
mas pode ler a troca recente necessária para decidir se existe um
acompanhamento.
Compromissos armazenados são estado local do OpenClaw. Eles são memória operacional, não
@ -132,20 +136,20 @@ openclaw config set commitments.enabled false
## Solução de problemas
Se os acompanhamentos esperados não aparecerem:
Se acompanhamentos esperados não estiverem aparecendo:
- Confirme que `commitments.enabled` é `true`.
- Verifique `openclaw commitments --all` para registros pendentes, descartados, adiados ou expirados.
- Verifique `openclaw commitments --all` em busca de registros pendentes, dispensados, adiados ou expirados.
- Certifique-se de que o Heartbeat esteja em execução para o agente.
- Verifique se `commitments.maxPerDay` já foi atingido para essa
sessão de agente.
- Lembre-se de que lembretes exatos são ignorados pela extração de compromissos e devem
aparecer em [tarefas agendadas](/pt-BR/automation/cron-jobs).
## Relacionado
## Relacionados
- [Visão geral da memória](/pt-BR/concepts/memory)
- [Active Memory](/pt-BR/concepts/active-memory)
- [Active memory](/pt-BR/concepts/active-memory)
- [Heartbeat](/pt-BR/gateway/heartbeat)
- [Tarefas agendadas](/pt-BR/automation/cron-jobs)
- [`openclaw commitments`](/pt-BR/cli/commitments)

216
docs/pt-BR/concepts/openclaw-sdk.md
View File

@ -1,61 +1,69 @@
---
read_when:
- Você está criando um app externo, script, painel, job de CI ou extensão de IDE que se comunica com o OpenClaw
- Você está escolhendo entre o App SDK e o Plugin SDK
- Você está fazendo integração com execuções de agentes, sessões, eventos, aprovações, modelos ou ferramentas do Gateway
- Você está criando um aplicativo externo, script, painel, job de CI ou extensão de IDE que se comunica com o OpenClaw
- Você está escolhendo entre o SDK de App e o SDK de Plugin
- Você está integrando com execuções de agentes do Gateway, sessões, eventos, aprovações, modelos ou ferramentas
sidebarTitle: App SDK
summary: SDK público de aplicativos do OpenClaw para aplicativos externos, scripts, painéis, tarefas de CI e extensões de IDE
title: SDK de Aplicativo do OpenClaw
title: SDK do aplicativo OpenClaw
x-i18n:
generated_at: "2026-04-30T09:45:26Z"
generated_at: "2026-05-01T05:56:07Z"
model: gpt-5.5
provider: openai
source_hash: 9c46454d172a25d329a796461982dc4307d3720a28df777eda8605996505e38c
source_hash: e531e985ca82026b230b03f8df5ab908d66e2b608e09c46af2ec060b9def0c24
source_path: concepts/openclaw-sdk.md
workflow: 16
---
O **SDK de Apps da OpenClaw** é a API cliente pública para apps fora do
processo da OpenClaw. Use `@openclaw/sdk` quando um script, painel, trabalho de CI, extensão de IDE ou outro app externo quiser se conectar ao Gateway, iniciar execuções de agente, transmitir eventos, aguardar resultados, cancelar trabalho ou inspecionar recursos do Gateway.
O **SDK de App da OpenClaw** é a API cliente pública para apps fora do
processo da OpenClaw. Use `@openclaw/sdk` quando um script, dashboard, tarefa
de CI, extensão de IDE ou outro app externo quiser se conectar ao Gateway,
iniciar execuções de agentes, transmitir eventos em streaming, aguardar
resultados, cancelar trabalho ou inspecionar recursos do Gateway.
<Note>
O SDK de Apps é diferente do [Plugin SDK](/pt-BR/plugins/sdk-overview).
`@openclaw/sdk` se comunica com o Gateway de fora da OpenClaw.
`openclaw/plugin-sdk/*` é apenas para plugins que rodam dentro da OpenClaw e registram provedores, canais, ferramentas, hooks ou runtimes confiáveis.
O SDK de App é diferente do [Plugin SDK](/pt-BR/plugins/sdk-overview).
`@openclaw/sdk` fala com o Gateway de fora da OpenClaw.
`openclaw/plugin-sdk/*` é apenas para plugins que rodam dentro da OpenClaw e
registram provedores, canais, ferramentas, hooks ou runtimes confiáveis.
</Note>
## O Que É Disponibilizado Hoje
## O que é fornecido hoje
`@openclaw/sdk` é disponibilizado com:
`@openclaw/sdk` é fornecido com:
| Superfície | Status | O que faz |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| `OpenClaw` | Pronto | Ponto de entrada principal do cliente. Gerencia transporte, conexão, solicitações e eventos. |
| `GatewayClientTransport` | Pronto | Transporte WebSocket apoiado pelo cliente do Gateway. |
| `oc.agents` | Pronto | Lista, cria, atualiza, exclui e obtém handles de agentes. |
| `Agent.run()` | Pronto | Inicia uma execução `agent` do Gateway e retorna um `Run`. |
| `oc.runs` | Pronto | Cria, obtém, aguarda, cancela e transmite execuções. |
| Superfície | Status | O que faz |
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
| `OpenClaw` | Pronto | Ponto de entrada principal do cliente. Controla transporte, conexão, requisições e eventos. |
| `GatewayClientTransport` | Pronto | Transporte WebSocket respaldado pelo cliente do Gateway. |
| `oc.agents` | Pronto | Lista, cria, atualiza, exclui e obtém handles de agente. |
| `Agent.run()` | Pronto | Inicia uma execução `agent` do Gateway e retorna um `Run`. |
| `oc.runs` | Pronto | Cria, obtém, aguarda, cancela e transmite execuções em streaming. |
| `Run.events()` | Pronto | Transmite eventos normalizados por execução com replay para execuções rápidas. |
| `Run.wait()` | Pronto | Chama `agent.wait` e retorna um `RunResult` estável. |
| `Run.wait()` | Pronto | Chama `agent.wait` e retorna um `RunResult` estável. |
| `Run.cancel()` | Pronto | Chama `sessions.abort` pelo id da execução, com chave de sessão quando disponível. |
| `oc.sessions` | Pronto | Cria, resolve, envia para, aplica patches, compacta e obtém handles de sessão. |
| `Session.send()` | Pronto | Chama `sessions.send` e retorna um `Run`. |
| `oc.models` | Pronto | Chama `models.list` e o RPC de status `models.authStatus` atual. |
| `oc.tools` | Parcial | Lista o catálogo de ferramentas e ferramentas efetivas; a invocação direta de ferramentas não está conectada. |
| `oc.approvals` | Pronto | Lista e resolve aprovações de execução por meio de RPCs de aprovação do Gateway. |
| `oc.rawEvents()` | Pronto | Expõe eventos brutos do Gateway para consumidores avançados. |
| `normalizeGatewayEvent()` | Pronto | Converte eventos brutos do Gateway para o formato de evento estável do SDK. |
| `Session.send()` | Pronto | Chama `sessions.send` e retorna um `Run`. |
| `oc.models` | Pronto | Chama `models.list` e o RPC de status `models.authStatus` atual. |
| `oc.tools` | Parcial | Lista o catálogo de ferramentas e as ferramentas efetivas; a invocação direta de ferramentas não está conectada. |
| `oc.artifacts` | Pronto | Lista, obtém e baixa artefatos de transcrição do Gateway. |
| `oc.approvals` | Pronto | Lista e resolve aprovações de exec por meio de RPCs de aprovação do Gateway. |
| `oc.rawEvents()` | Pronto | Expõe eventos brutos do Gateway para consumidores avançados. |
| `normalizeGatewayEvent()` | Pronto | Converte eventos brutos do Gateway para o formato de evento estável do SDK. |
O SDK também exporta os tipos principais usados por essas superfícies:
`AgentRunParams`, `RunResult`, `RunStatus`, `OpenClawEvent`,
`OpenClawEventType`, `GatewayEvent`, `OpenClawTransport`,
`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
`RuntimeSelection`, `EnvironmentSelection`, `WorkspaceSelection`,
`ApprovalMode` e tipos de resultado relacionados.
`ArtifactSummary`, `ArtifactQuery`, `ArtifactsListResult`,
`ArtifactsGetResult`, `ArtifactsDownloadResult`, `RuntimeSelection`,
`EnvironmentSelection`, `WorkspaceSelection`, `ApprovalMode` e tipos de
resultado relacionados.
## Conectar A Um Gateway
## Conectar-se a um Gateway
Crie um cliente com uma URL explícita do Gateway ou injete um transporte personalizado para testes e runtimes de apps embarcados.
Crie um cliente com uma URL explícita do Gateway ou injete um transporte
personalizado para testes e runtimes de app embarcados.
```typescript
import { OpenClaw } from "@openclaw/sdk";
@ -70,7 +78,9 @@ await oc.connect();
```
`new OpenClaw({ gateway: "ws://..." })` é equivalente a `url`. A opção
`gateway: "auto"` é aceita pelo construtor, mas a descoberta automática do Gateway ainda não é um recurso separado do SDK; passe `url` quando o app ainda não souber como descobrir o Gateway.
`gateway: "auto"` é aceita pelo construtor, mas a descoberta automática do
Gateway ainda não é um recurso separado do SDK; passe `url` quando o app ainda
não souber como descobrir o Gateway.
Para testes, passe um objeto que implemente `OpenClawTransport`:
@ -85,9 +95,10 @@ const oc = new OpenClaw({
});
```
## Executar Um Agente
## Executar um agente
Use `oc.agents.get(id)` quando o app precisar de um handle de agente e, em seguida, chame `agent.run()`.
Use `oc.agents.get(id)` quando o app quiser um handle de agente e então chame
`agent.run()`.
```typescript
const agent = await oc.agents.get("main");
@ -110,13 +121,20 @@ const result = await run.wait({ timeoutMs: 120_000 });
console.log(result.status);
```
Referências de modelo qualificadas por provedor, como `openai/gpt-5.5`, são divididas em substituições de `provider` e `model` do Gateway. `timeoutMs` permanece em milissegundos no SDK e é convertido para segundos de timeout do Gateway para o RPC `agent`.
Referências de modelo qualificadas por provedor, como `openai/gpt-5.5`, são
divididas em substituições de `provider` e `model` do Gateway. `timeoutMs`
permanece em milissegundos no SDK e é convertido em segundos de timeout do
Gateway para o RPC `agent`.
`run.wait()` usa o RPC `agent.wait` do Gateway. Um prazo de espera que expira enquanto a execução ainda está ativa retorna `status: "accepted"` em vez de fingir que a própria execução atingiu timeout. Timeouts de runtime, execuções abortadas e execuções canceladas são normalizados para `timed_out` ou `cancelled`.
`run.wait()` usa o RPC `agent.wait` do Gateway. Um prazo de espera que expira
enquanto a execução ainda está ativa retorna `status: "accepted"` em vez de
fingir que a execução em si atingiu timeout. Timeouts de runtime, execuções
abortadas e execuções canceladas são normalizados para `timed_out` ou
`cancelled`.
## Criar E Reutilizar Sessões
## Criar e reutilizar sessões
Use sessões quando o app precisar de estado durável de transcrição.
Use sessões quando o app quiser estado durável de transcrição.
```typescript
const session = await oc.sessions.create({
@ -128,7 +146,8 @@ const run = await session.send("Prepare release notes from the current diff.");
await run.wait();
```
`Session.send()` chama `sessions.send` e retorna um `Run`. Handles de sessão também aceitam:
`Session.send()` chama `sessions.send` e retorna um `Run`. Handles de sessão
também oferecem suporte a:
```typescript
await session.abort(run.id);
@ -136,9 +155,10 @@ await session.patch({ label: "renamed-session" });
await session.compact({ maxLines: 200 });
```
## Transmitir Eventos
## Transmitir eventos em streaming
O SDK normaliza eventos brutos do Gateway em um envelope `OpenClawEvent` estável:
O SDK normaliza eventos brutos do Gateway em um envelope `OpenClawEvent`
estável:
```typescript
type OpenClawEvent = {
@ -158,30 +178,32 @@ type OpenClawEvent = {
Tipos de evento comuns incluem:
| Tipo de evento | Evento de origem do Gateway |
| -------------------- | -------------------------------------------- |
| `run.started` | Início do ciclo de vida de `agent` |
| `run.completed` | Fim do ciclo de vida de `agent` |
| `run.failed` | Erro do ciclo de vida de `agent` |
| `run.cancelled` | Fim do ciclo de vida abortado/cancelado |
| `run.timed_out` | Fim do ciclo de vida por timeout |
| `assistant.delta` | Delta de streaming do assistente |
| `assistant.message` | Mensagem do assistente |
| `thinking.delta` | Fluxo de pensamento ou plano |
| `tool.call.started` | Início de ferramenta/item/comando |
| `tool.call.delta` | Atualização de ferramenta/item/comando |
| Tipo de evento | Evento do Gateway de origem |
| -------------------- | ------------------------------------------- |
| `run.started` | Início do ciclo de vida de `agent` |
| `run.completed` | Fim do ciclo de vida de `agent` |
| `run.failed` | Erro do ciclo de vida de `agent` |
| `run.cancelled` | Fim do ciclo de vida abortado/cancelado |
| `run.timed_out` | Fim do ciclo de vida por timeout |
| `assistant.delta` | Delta de streaming do assistente |
| `assistant.message` | Mensagem do assistente |
| `thinking.delta` | Fluxo de raciocínio ou plano |
| `tool.call.started` | Início de ferramenta/item/comando |
| `tool.call.delta` | Atualização de ferramenta/item/comando |
| `tool.call.completed` | Conclusão de ferramenta/item/comando |
| `tool.call.failed` | Falha ou status bloqueado de ferramenta/item/comando |
| `approval.requested` | Solicitação de aprovação de execução ou Plugin |
| `approval.resolved` | Resolução de aprovação de execução ou Plugin |
| `session.created` | Criação de `sessions.changed` |
| `session.updated` | Atualização de `sessions.changed` |
| `session.compacted` | Compaction de `sessions.changed` |
| `task.updated` | Eventos de atualização de tarefa |
| `artifact.updated` | Eventos de fluxo de patch |
| `raw` | Qualquer evento ainda sem um mapeamento estável do SDK |
| `tool.call.failed` | Falha de ferramenta/item/comando ou status bloqueado |
| `approval.requested` | Solicitação de aprovação de exec ou Plugin |
| `approval.resolved` | Resolução de aprovação de exec ou Plugin |
| `session.created` | Criação de `sessions.changed` |
| `session.updated` | Atualização de `sessions.changed` |
| `session.compacted` | Compaction de `sessions.changed` |
| `task.updated` | Eventos de atualização de tarefa |
| `artifact.updated` | Eventos de fluxo de patch |
| `raw` | Qualquer evento ainda sem mapeamento estável do SDK |
`Run.events()` filtra eventos para um único id de execução e reproduz eventos já vistos para execuções rápidas. Isso significa que o fluxo documentado é seguro:
`Run.events()` filtra eventos para um único id de execução e reproduz eventos
já vistos para execuções rápidas. Isso significa que o fluxo documentado é
seguro:
```typescript
const run = await agent.run("Summarize the latest session.");
@ -193,10 +215,10 @@ for await (const event of run.events()) {
}
```
Para fluxos de todo o app, use `oc.events()`. Para frames brutos do Gateway, use
`oc.rawEvents()`.
Para fluxos de todo o app, use `oc.events()`. Para frames brutos do Gateway,
use `oc.rawEvents()`.
## Modelos, Ferramentas E Aprovações
## Modelos, ferramentas, artefatos e aprovações
Helpers de modelo mapeiam para métodos atuais do Gateway:
@ -205,23 +227,41 @@ await oc.models.list();
await oc.models.status({ probe: false }); // calls models.authStatus
```
Helpers de ferramenta expõem o catálogo do Gateway e a visualização de ferramentas efetivas:
Helpers de ferramenta expõem o catálogo do Gateway e a visualização de
ferramentas efetivas:
```typescript
await oc.tools.list();
await oc.tools.effective({ sessionKey: "main" });
```
Helpers de aprovação usam os RPCs de aprovação de execução:
Helpers de artefato expõem a projeção de artefatos do Gateway para contexto de
sessão, execução ou tarefa. Cada chamada exige um escopo explícito
`sessionKey`, `runId` ou `taskId`:
```typescript
const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
const first = artifacts[0];
if (first) {
const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
console.log(download.encoding, download.url);
}
```
Helpers de aprovação usam os RPCs de aprovação de exec:
```typescript
const approvals = await oc.approvals.list();
await oc.approvals.respond("approval-id", { decision: "approve" });
```
## Explicitamente Sem Suporte Hoje
## Explicitamente sem suporte hoje
O SDK inclui nomes para o modelo de produto que queremos, mas não finge silenciosamente que RPCs do Gateway existem. Atualmente, estas chamadas lançam erros explícitos de falta de suporte:
O SDK inclui nomes para o modelo de produto que queremos, mas não finge
silenciosamente que RPCs do Gateway existem. Estas chamadas atualmente lançam
erros explícitos de ausência de suporte:
```typescript
await oc.tasks.list();
@ -230,28 +270,28 @@ await oc.tasks.cancel("task-id");
await oc.tools.invoke("tool-name", {});
await oc.artifacts.list();
await oc.artifacts.get("artifact-id");
await oc.artifacts.download("artifact-id");
await oc.environments.list();
await oc.environments.create({});
await oc.environments.status("environment-id");
await oc.environments.delete("environment-id");
```
Campos por execução `workspace`, `runtime`, `environment` e `approvals` são tipados como formato futuro, mas o Gateway atual não oferece suporte a essas substituições no RPC `agent`. Se chamadores os passarem, o SDK lança erro antes de enviar a execução para que o trabalho não seja executado acidentalmente com o comportamento padrão de workspace, runtime, ambiente ou aprovação.
Os campos por execução `workspace`, `runtime`, `environment` e `approvals` são
tipados como formato futuro, mas o Gateway atual não oferece suporte a essas
substituições no RPC `agent`. Se chamadores os passarem, o SDK lança erro antes
de enviar a execução, para que o trabalho não seja executado acidentalmente com
o comportamento padrão de workspace, runtime, ambiente ou aprovação.
## SDK de Apps Versus Plugin SDK
## SDK de App versus Plugin SDK
Use o SDK de Apps quando o código estiver fora da OpenClaw:
Use o SDK de App quando o código vive fora da OpenClaw:
- scripts Node que iniciam ou observam execuções de agente
- trabalhos de CI que chamam um Gateway
- painéis e painéis administrativos
- extensões de IDE
- pontes externas que não precisam se tornar plugins de canal
- testes de integração com transportes Gateway falsos ou reais
- Scripts Node que iniciam ou observam execuções de agentes
- Tarefas de CI que chamam um Gateway
- dashboards e painéis administrativos
- Extensões de IDE
- Pontes externas que não precisam se tornar plugins de canal
- Testes de integração com transportes de Gateway falsos ou reais
Use o Plugin SDK quando o código roda dentro da OpenClaw:
@ -261,13 +301,15 @@ Use o Plugin SDK quando o código roda dentro da OpenClaw:
- plugins de harness de agente
- helpers de runtime confiável
Código do SDK de Apps deve importar de `@openclaw/sdk`. Código de Plugin deve importar dos subcaminhos documentados de `openclaw/plugin-sdk/*`. Não misture os dois contratos.
Código do SDK de App deve importar de `@openclaw/sdk`. Código de Plugin deve
importar de subcaminhos documentados `openclaw/plugin-sdk/*`. Não misture os
dois contratos.
## Documentação Relacionada
## Documentação relacionada
- [Design da API do SDK de Apps da OpenClaw](/pt-BR/reference/openclaw-sdk-api-design)
- [Design da API do SDK de App da OpenClaw](/pt-BR/reference/openclaw-sdk-api-design)
- [Referência de RPC do Gateway](/pt-BR/reference/rpc)
- [Loop de agente](/pt-BR/concepts/agent-loop)
- [Loop do agente](/pt-BR/concepts/agent-loop)
- [Runtimes de agente](/pt-BR/concepts/agent-runtimes)
- [Sessões](/pt-BR/concepts/session)
- [Tarefas em segundo plano](/pt-BR/automation/tasks)

292
docs/pt-BR/gateway/config-channels.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Configurando um Plugin de canal (autenticação, controle de acesso, múltiplas contas)
- Solução de problemas de chaves de configuração por canal
- Auditando política de DM, política de grupo ou controle de menções
summary: 'Configuração de canais: controle de acesso, pareamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e muito mais'
- Configurando um Plugin de canal (autenticação, controle de acesso, várias contas)
- Solução de problemas das chaves de configuração por canal
- Auditoria da política de mensagens diretas, da política de grupos ou do controle de acesso por menção
summary: 'Configuração de canais: controle de acesso, emparelhamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e mais'
title: Configuração — canais
x-i18n:
generated_at: "2026-04-30T16:28:37Z"
generated_at: "2026-05-01T05:56:04Z"
model: gpt-5.5
provider: openai
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_hash: ce1571d51e026182d49b935780a986780a90b05afc0acca027b2541b80a1aac2
source_path: gateway/config-channels.md
workflow: 16
---
Chaves de configuração por canal em `channels.*`. Abrange acesso a DM e grupos,
configurações multi-conta, controle por menção e chaves por canal para Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage e os outros Plugins de canal incluídos.
Chaves de configuração por canal em `channels.*`. Abrange acesso por DM e grupo,
configurações de múltiplas contas, controle por menção e chaves por canal para Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage e os outros plugins de canal incluídos.
Para agentes, ferramentas, runtime do gateway e outras chaves de nível superior, consulte
Para agents, tools, runtime do Gateway e outras chaves de nível superior, consulte
[Referência de configuração](/pt-BR/gateway/configuration-reference).
## Canais
Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`).
### Acesso a DM e grupos
### Acesso por DM e grupo
Todos os canais oferecem suporte a políticas de DM e políticas de grupo:
| Política de DM | Comportamento |
| ------------------- | -------------------------------------------------------------- |
| `pairing` (default) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Somente remetentes em `allowFrom` (ou armazenamento de permissão pareado) |
| `open` | Permite todas as DMs recebidas (requer `allowFrom: ["*"]`) |
| `disabled` | Ignora todas as DMs recebidas |
| Política de DM | Comportamento |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permitidos pareados) |
| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) |
| `disabled` | Ignorar todas as DMs recebidas |
| Política de grupo | Comportamento |
| -------------------- | -------------------------------------------------------------- |
| `allowlist` (default) | Somente grupos que correspondem à lista de permissões configurada |
| `open` | Ignora listas de permissões de grupo (o controle por menção ainda se aplica) |
| `disabled` | Bloqueia todas as mensagens de grupo/sala |
| Política de grupo | Comportamento |
| --------------------- | ------------------------------------------------------ |
| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada |
| `open` | Ignorar listas de permissões de grupo (controle por menção ainda se aplica) |
| `disabled` | Bloquear todas as mensagens de grupos/salas |
<Note>
`channels.defaults.groupPolicy` define o padrão quando `groupPolicy` de um provedor não está definido.
@ -48,9 +48,9 @@ Códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareame
Se um bloco de provedor estiver totalmente ausente (`channels.<provider>` ausente), a política de grupo em runtime volta para `allowlist` (falha fechada) com um aviso na inicialização.
</Note>
### Substituições de modelo por canal
### Sobrescritas de modelo por canal
Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`).
Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma sobrescrita de modelo (por exemplo, definida via `/model`).
```json5
{
@ -91,15 +91,15 @@ Use `channels.defaults` para comportamento compartilhado de política de grupo e
}
```
- `channels.defaults.groupPolicy`: política de grupo de fallback quando `groupPolicy` em nível de provedor não está definida.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto de citação/thread/histórico), `allowlist` (inclui apenas contexto de remetentes na lista de permissões), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: inclui status de canais saudáveis na saída de Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída de Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderiza saída de Heartbeat compacta no estilo de indicador.
- `channels.defaults.groupPolicy`: política de grupo de fallback quando um `groupPolicy` no nível do provedor não está definido.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto citado/de thread/de histórico), `allowlist` (inclui apenas contexto de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Sobrescrita por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: incluir status saudáveis de canais na saída de Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: incluir status degradados/com erro na saída de Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderizar saída compacta de Heartbeat em estilo de indicador.
### WhatsApp
O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando uma sessão vinculada existe.
WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada.
```json5
{
@ -139,7 +139,7 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
}
```
<Accordion title="WhatsApp multi-conta">
<Accordion title="WhatsApp com múltiplas contas">
```json5
{
@ -157,10 +157,10 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
}
```
- Comandos de saída usam a conta `default` por padrão, se presente; caso contrário, o primeiro id de conta configurado (ordenado).
- `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um id de conta configurado.
- Comandos de saída usam por padrão a conta `default`, se presente; caso contrário, o primeiro id de conta configurado (ordenado).
- `channels.whatsapp.defaultAccount` opcional sobrescreve essa seleção de conta padrão de fallback quando corresponde a um id de conta configurado.
- O diretório de autenticação Baileys legado de conta única é migrado por `openclaw doctor` para `whatsapp/default`.
- Substituições por conta: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
- Sobrescritas por conta: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
</Accordion>
@ -219,12 +219,12 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
}
```
- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (somente arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão.
- `apiRoot` é somente a raiz da API Bot do Telegram. Use `https://api.telegram.org` ou sua raiz auto-hospedada/proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo `/bot<TOKEN>` final acidental.
- `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um id de conta configurado.
- Em configurações multi-conta (2+ ids de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou inválido.
- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão.
- `apiRoot` é apenas a raiz da API de Bot do Telegram. Use `https://api.telegram.org` ou sua raiz auto-hospedada/de proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo `/bot<TOKEN>` final acidental.
- `channels.telegram.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um id de conta configurado.
- Em configurações de múltiplas contas (2+ ids de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou inválido.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram associações ACP persistentes para tópicos de fórum (use o `chatId:topic:topicId` canônico em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para tópicos de fórum (use o `chatId:topic:topicId` canônico em `match.peer.id`). A semântica dos campos é compartilhada em [Agents ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Pré-visualizações de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e de grupo).
- Política de repetição: consulte [Política de repetição](/pt-BR/concepts/retry).
@ -329,36 +329,36 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
```
- Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão.
- Chamadas diretas de saída que fornecem um `token` do Discord explícito usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de repetição/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
- `channels.discord.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- Use `user:<id>` (DM) ou `channel:<id>` (canal de guild) para destinos de entrega; IDs numéricos sem prefixo são rejeitados.
- Slugs de guild ficam em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições por canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (exceto @everyone/@here).
- Use `user:<id>` (DM) ou `channel:<id>` (canal de guilda) para destinos de entrega; IDs numéricos simples são rejeitados.
- Slugs de guildas ficam em minúsculas, com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guilda.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar somente mensagens de bots que mencionam o bot (mensagens próprias ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições de canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here).
- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando têm menos de 2000 caracteres.
- `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord:
- `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados)
- `idleHours`: substituição do Discord para auto-unfocus por inatividade em horas (`0` desabilita)
- `maxAgeHours`: substituição do Discord para idade máxima absoluta em horas (`0` desabilita)
- `spawnSubagentSessions`: opção de adesão para criação/vinculação automática de thread em `sessions_spawn({ thread: true })`
- `enabled`: substituição do Discord para recursos de sessão vinculada a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados)
- `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desativa)
- `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desativa)
- `spawnSubagentSessions`: chave de opt-in para criação/vinculação automática de thread por `sessions_spawn({ thread: true })`
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para canais e threads (use o id de canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres v2 de componentes do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de autoentrada + LLM + TTS.
- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres de componentes v2 do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + LLM + TTS.
- `channels.discord.voice.model` substitui opcionalmente o modelo de LLM usado para respostas em canais de voz do Discord.
- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para as opções DAVE de `@discordjs/voice` (`true` e `24` por padrão).
- O OpenClaw também tenta recuperar o recebimento de voz saindo/reentrando em uma sessão de voz após falhas repetidas de descriptografia.
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados de `streamMode` e `streaming` booleano são migrados automaticamente.
- `channels.discord.autoPresence` mapeia a disponibilidade de runtime para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status.
- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência mutável por nome/tag (modo de compatibilidade break-glass).
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados `streamMode` e booleanos `streaming` são migrados automaticamente.
- `channels.discord.autoPresence` mapeia disponibilidade de runtime para presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status.
- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência mutável de nome/tag (modo de compatibilidade de emergência).
- `channels.discord.execApprovals`: entrega de aprovação de exec nativa do Discord e autorização de aprovadores.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo auto, aprovações de exec são ativadas quando aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido.
- `agentFilter`: lista de permissão opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuários do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido.
- `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos.
- `target`: para onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos.
- `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout.
**Modos de notificação por reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
**Modos de notificação de reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
### Google Chat
@ -389,11 +389,11 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
}
```
- JSON da conta de serviço: inline (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`).
- JSON de conta de serviço: inline (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`).
- SecretRef de conta de serviço também é compatível (`serviceAccountRef`).
- Fallbacks de env: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Use `spaces/<spaceId>` ou `users/<userId>` para destinos de entrega.
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência mutável por principal de e-mail (modo de compatibilidade break-glass).
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência mutável de principal de e-mail (modo de compatibilidade de emergência).
### Slack
@ -465,35 +465,44 @@ O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticame
}
```
- **Modo Socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de env da conta padrão).
- **Modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta).
- `socketMode` repassa o ajuste de transporte Socket Mode do SDK do Slack para a API pública do receptor Bolt. Use apenas ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef.
- Snapshots de conta do Slack expõem campos de origem/status por credencial, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo.
- **Modo Socket** exige `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de env da conta padrão).
- **Modo HTTP** exige `botToken` mais `signingSecret` (na raiz ou por conta).
- `socketMode` repassa o ajuste de transporte Socket Mode do SDK do Slack para a API pública do receiver Bolt. Use-o somente ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples
ou objetos SecretRef.
- Snapshots de conta do Slack expõem campos de origem/status por credencial, como
`botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP,
`signingSecretStatus`. `configured_unavailable` significa que a conta está
configurada via SecretRef, mas o caminho atual de comando/runtime não conseguiu
resolver o valor do segredo.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack.
- `channels.slack.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados de `streamMode`, `streaming` booleano e `nativeStreaming` são migrados automaticamente.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente.
- Use `user:<id>` (DM) ou `channel:<id>` para destinos de entrega.
**Modos de notificação por reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
**Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
**Isolamento de sessão de thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
- Streaming nativo do Slack mais o status de thread "is typing..." no estilo de assistente do Slack exigem um destino de thread de resposta. DMs de nível superior ficam fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da prévia no estilo de thread.
- `typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em execução, depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo esquema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
- Streaming nativo do Slack mais o status de thread "está digitando..." no estilo de assistente do Slack exigem um destino de thread de resposta. DMs de nível superior permanecem fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da prévia no estilo de thread.
- `typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto uma resposta está em execução, depois a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo schema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuários do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
| Grupo de ações | Padrão | Observações |
| -------------- | --------- | ----------------------- |
| reactions | habilitado | Reagir + listar reações |
| messages | habilitado | Ler/enviar/editar/excluir |
| pins | habilitado | Fixar/desafixar/listar |
| memberInfo | habilitado | Informações do membro |
| emojiList | habilitado | Lista de emojis personalizados |
| Grupo de ações | Padrão | Observações |
| -------------- | ------- | ----------------------- |
| reactions | ativado | Reagir + listar reações |
| messages | ativado | Ler/enviar/editar/excluir |
| pins | ativado | Fixar/desafixar/listar |
| memberInfo | ativado | Informações de membro |
| emojiList | ativado | Lista de emojis personalizados |
### Mattermost
O Mattermost é distribuído como um Plugin incluído nas versões atuais do OpenClaw. Builds antigas ou personalizadas podem instalar um pacote npm atual com `openclaw plugins install @openclaw/mattermost`; se o npm informar que o pacote de propriedade do OpenClaw está obsoleto, use o Plugin incluído ou um checkout local até que um pacote npm mais novo seja publicado.
Mattermost é fornecido como um Plugin incluído nas versões atuais do OpenClaw. Builds mais antigas ou
personalizadas podem instalar um pacote npm atual com
`openclaw plugins install @openclaw/mattermost`; se o npm relatar o pacote
mantido pelo OpenClaw como obsoleto, use o Plugin incluído ou um checkout local
até que um pacote npm mais novo seja publicado.
```json5
{
@ -523,17 +532,22 @@ O Mattermost é distribuído como um Plugin incluído nas versões atuais do Ope
}
```
Modos de chat: `oncall` (responde em @-mention, padrão), `onmessage` (todas as mensagens), `onchar` (mensagens que começam com prefixo de acionamento).
Modos de chat: `oncall` (responder a @-mention, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com o prefixo de gatilho).
Quando comandos nativos do Mattermost estão habilitados:
- `commands.callbackPath` deve ser um caminho (por exemplo `/api/channels/mattermost/command`), não uma URL completa.
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser alcançável pelo servidor Mattermost.
- Callbacks slash nativos são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do comando slash. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeita callbacks com `Unauthorized: invalid command token.`
- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback. Use valores de host/domínio, não URLs completas.
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser acessível pelo servidor Mattermost.
- Callbacks de slash nativos são autenticados com os tokens por comando retornados
pelo Mattermost durante o registro de slash commands. Se o registro falhar ou nenhum
comando for ativado, o OpenClaw rejeita callbacks com
`Unauthorized: invalid command token.`
- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que
`ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback.
Use valores de host/domínio, não URLs completas.
- `channels.mattermost.configWrites`: permite ou nega gravações de configuração iniciadas pelo Mattermost.
- `channels.mattermost.requireMention`: exige `@mention` antes de responder em canais.
- `channels.mattermost.groups.<channelId>.requireMention`: substituição por canal da exigência de menção (`"*"` para padrão).
- `channels.mattermost.groups.<channelId>.requireMention`: substituição de exigência de menção por canal (`"*"` para padrão).
- `channels.mattermost.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
### Signal
@ -557,13 +571,13 @@ Quando comandos nativos do Mattermost estão habilitados:
**Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
- `channels.signal.account`: fixa a inicialização do canal a uma identidade de conta Signal específica.
- `channels.signal.account`: fixa a inicialização do canal a uma identidade específica de conta do Signal.
- `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal.
- O `channels.signal.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- O `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
### BlueBubbles
BlueBubbles é o caminho recomendado para iMessage (com suporte de Plugin, configurado em `channels.bluebubbles`).
BlueBubbles é o caminho recomendado para iMessage (baseado em Plugin, configurado em `channels.bluebubbles`).
```json5
{
@ -578,8 +592,8 @@ BlueBubbles é o caminho recomendado para iMessage (com suporte de Plugin, confi
}
```
- Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- O `channels.bluebubbles.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- Caminhos de chave principais abordados aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- O `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador do BlueBubbles ou uma string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles).
@ -609,15 +623,15 @@ OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é nec
}
```
- O `channels.imessage.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- O `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Requer Acesso Total ao Disco para o banco de dados do Mensagens.
- Requer Acesso Total ao Disco para o banco de dados do Messages.
- Prefira destinos `chat_id:<id>`. Use `imsg chats --limit 20` para listar chats.
- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos por SCP.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos de entrada (padrão: `/Users/*/Library/Messages/Attachments`).
- O SCP usa verificação estrita de chave de host, portanto garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos via SCP.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`).
- SCP usa verificação estrita de chave de host, então garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage.
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou um destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
<Accordion title="Exemplo de wrapper SSH do iMessage">
@ -630,7 +644,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix tem suporte de Plugin e é configurado em `channels.matrix`.
Matrix é baseado em Plugin e configurado em `channels.matrix`.
```json5
{
@ -661,24 +675,24 @@ Matrix tem suporte de Plugin e é configurado em `channels.matrix`.
```
- A autenticação por token usa `accessToken`; a autenticação por senha usa `userId` + `password`.
- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por meio de um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa adesão de rede são controles independentes.
- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa opção de rede são controles independentes.
- `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas.
- `channels.matrix.autoJoin` tem `off` como padrão, então salas com convite e novos convites no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`.
- `channels.matrix.execApprovals`: entrega de aprovação de exec nativa do Matrix e autorização de aprovador.
- `channels.matrix.autoJoin` usa `off` como padrão, então salas convidadas e novos convites no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`.
- `channels.matrix.execApprovals`: entrega de aprovações de exec nativa do Matrix e autorização de aprovador.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de exec.
- `agentFilter`: lista de permissões opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `approvers`: IDs de usuário do Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de exec.
- `agentFilter`: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: para onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`.
- Substituições por conta: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha pelo par roteado, enquanto `per-room` isola cada sala de DM.
- Sondagens de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy do tráfego em runtime.
- A configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix).
- Sondagens de status do Matrix e consultas ao diretório em tempo real usam a mesma política de proxy do tráfego em runtime.
- A configuração completa do Matrix, regras de direcionamento e exemplos de setup estão documentados em [Matrix](/pt-BR/channels/matrix).
### Microsoft Teams
Microsoft Teams tem suporte de Plugin e é configurado em `channels.msteams`.
Microsoft Teams é baseado em Plugin e configurado em `channels.msteams`.
```json5
{
@ -693,12 +707,12 @@ Microsoft Teams tem suporte de Plugin e é configurado em `channels.msteams`.
}
```
- Caminhos de chave principais cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`.
- Caminhos de chave principais abordados aqui: `channels.msteams`, `channels.msteams.configWrites`.
- A configuração completa do Teams (credenciais, Webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams).
### IRC
IRC tem suporte de Plugin e é configurado em `channels.irc`.
IRC é baseado em Plugin e configurado em `channels.irc`.
```json5
{
@ -719,11 +733,11 @@ IRC tem suporte de Plugin e é configurado em `channels.irc`.
}
```
- Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- O `channels.irc.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissão/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc).
- Caminhos de chave principais abordados aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- O `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissões/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc).
### Várias contas (todos os canais)
### Múltiplas contas (todos os canais)
Execute várias contas por canal (cada uma com seu próprio `accountId`):
@ -748,30 +762,32 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`):
- `default` é usado quando `accountId` é omitido (CLI + roteamento).
- Tokens de ambiente se aplicam somente à conta **padrão**.
- Configurações básicas do canal se aplicam a todas as contas, a menos que sejam substituídas por conta.
- As configurações base do canal se aplicam a todas as contas, salvo substituição por conta.
- Use `bindings[].match.accountId` para rotear cada conta para um agente diferente.
- Se você adicionar uma conta não padrão por meio de `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com conta única, OpenClaw primeiro promove valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Vinculações existentes somente de canal (sem `accountId`) continuam correspondendo à conta padrão; vinculações com escopo de conta permanecem opcionais.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com conta única, o OpenClaw promove primeiro os valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Vínculos existentes somente de canal (sem `accountId`) continuam correspondendo à conta padrão; vínculos com escopo de conta continuam opcionais.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/padrão correspondente existente.
### Outros canais de Plugin
Muitos canais de Plugin são configurados como `channels.<id>` e documentados em suas páginas de canal dedicadas (por exemplo, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch).
Veja o índice completo de canais: [Canais](/pt-BR/channels).
### Controle de menção em chats em grupo
### Bloqueio por menção em chat de grupo
Mensagens de grupo exigem **menção obrigatória** por padrão (menção de metadados ou padrões regex seguros). Aplica-se a chats em grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Mensagens de grupo usam como padrão **exigir menção** (menção por metadados ou padrões regex seguros). Aplica-se a chats de grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam `messages.groupChat.visibleReplies: "message_tool"` como padrão: OpenClaw ainda processa o turno, mas respostas finais normais permanecem privadas, e saída visível na sala requer `message(action=send)`. Defina `"automatic"` somente quando quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível somente por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam `messages.groupChat.visibleReplies: "message_tool"` como padrão: o OpenClaw ainda processa o turno, mas respostas finais normais permanecem privadas e a saída visível na sala exige `message(action=send)`. Defina `"automatic"` somente quando você quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível somente por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`.
O Gateway recarrega a configuração de `messages` a quente após o arquivo ser salvo. Reinicie somente quando a observação de arquivos ou o recarregamento de configuração estiver desativado na implantação.
Se a ferramenta de mensagens estiver indisponível sob a política de ferramentas ativa, o OpenClaw recorre a respostas visíveis automáticas em vez de suprimir silenciosamente a resposta. `openclaw doctor` avisa sobre essa incompatibilidade.
O Gateway recarrega dinamicamente a configuração de `messages` depois que o arquivo é salvo. Reinicie somente quando o monitoramento de arquivos ou o recarregamento de configuração estiver desativado na implantação.
**Tipos de menção:**
- **Menções de metadados**: @menções nativas da plataforma. Ignoradas no modo de autochat do WhatsApp.
- **Menções por metadados**: @menções nativas da plataforma. Ignoradas no modo de autochat do WhatsApp.
- **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetição aninhada insegura são ignorados.
- O controle de menção é aplicado somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
- O bloqueio por menção é aplicado somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
```json5
{
@ -790,7 +806,7 @@ O Gateway recarrega a configuração de `messages` a quente após o arquivo ser
`messages.groupChat.historyLimit` define o padrão global. Canais podem substituir com `channels.<channel>.historyLimit` (ou por conta). Defina `0` para desativar.
`messages.visibleReplies` é o padrão global para turnos de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem em grupo/canal. Listas de permissão de canal e controle de menção ainda decidem se um turno é processado.
`messages.visibleReplies` é o padrão global de turno de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem de grupo/canal. Listas de permissões de canal e bloqueio por menção ainda decidem se um turno é processado.
#### Limites de histórico de DM
@ -809,7 +825,7 @@ O Gateway recarrega a configuração de `messages` a quente após o arquivo ser
Resolução: substituição por DM → padrão do provedor → sem limite (tudo retido).
Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
Suportado: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Modo de autochat
@ -861,40 +877,40 @@ Inclua seu próprio número em `allowFrom` para ativar o modo de autochat (ignor
}
```
<Accordion title="Detalhes dos comandos">
<Accordion title="Detalhes do comando">
- Este bloco configura superfícies de comandos. Para o catálogo atual de comandos integrados + incluídos no pacote, consulte [Comandos de barra](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, pareamento de dispositivos `/pair`, memória `/dreaming`, controle de telefone `/phone` e Talk `/voice`, são documentados nas páginas dos respectivos canais/plugins, além de [Comandos de barra](/pt-BR/tools/slash-commands).
- Este bloco configura superfícies de comando. Para o catálogo atual de comandos integrados + incluídos, consulte [Comandos de barra](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memória `/dreaming`, phone-control `/phone` e Talk `/voice`, são documentados nas páginas dos respectivos canais/plugins e em [Comandos de barra](/pt-BR/tools/slash-commands).
- Comandos de texto devem ser mensagens **independentes** com `/` no início.
- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém Slack desativado.
- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém Slack desativado.
- Substitua por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente.
- Substitua o registro nativo de Skills por canal com `channels.<provider>.commands.nativeSkills`.
- Substitua o registro de Skills nativas por canal com `channels.<provider>.commands.nativeSkills`.
- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram.
- `bash: true` habilita `! <cmd>` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.<channel>`.
- `bash: true` habilita `! <cmd>` para o shell do host. Exige `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.<channel>`.
- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do Gateway, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura permanece disponível para clientes operadores normais com escopo de gravação.
- `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciado pelo OpenClaw em `mcp.servers`.
- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de ativação/desativação de plugins.
- `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`.
- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de ativar/desativar Plugin.
- `channels.<provider>.configWrites` controla mutações de configuração por canal (padrão: true).
- Para canais com várias contas, `channels.<provider>.accounts.<id>.configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account <id>` ou `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` desativa `/restart` e ações da ferramenta de reinício do Gateway. Padrão: `true`.
- `ownerAllowFrom` é a lista de permissão explícita do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` aplica hash aos ids do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissão/pareamento de canais e `useAccessGroups` são ignorados).
- `ownerAllowFrom` é a lista de permissões explícita de proprietários para comandos/ferramentas somente de proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` aplica hash aos IDs de proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissões/pareamento de canal e `useAccessGroups` são ignorados).
- `useAccessGroups: false` permite que comandos contornem políticas de grupos de acesso quando `allowFrom` não está definido.
- Mapa da documentação de comandos:
- catálogo integrado + incluído no pacote: [Comandos de barra](/pt-BR/tools/slash-commands)
- superfícies de comandos específicas de canal: [Canais](/pt-BR/channels)
- catálogo integrado + incluído: [Comandos de barra](/pt-BR/tools/slash-commands)
- superfícies de comando específicas de canal: [Canais](/pt-BR/channels)
- comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot)
- comandos de pareamento: [Pareamento](/pt-BR/channels/pairing)
- comando de cartão do LINE: [LINE](/pt-BR/channels/line)
- dreaming de memória: [Dreaming](/pt-BR/concepts/dreaming)
- comando de cartão LINE: [LINE](/pt-BR/channels/line)
- Dreaming de memória: [Dreaming](/pt-BR/concepts/dreaming)
</Accordion>
---
## Relacionado
## Relacionados
- [Referência de configuração](/pt-BR/gateway/configuration-reference) — chaves de nível superior
- [Configuração — agentes](/pt-BR/gateway/config-agents)

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

@ -1,21 +1,21 @@
---
read_when:
- Configurando a política de `tools.*`, listas de permissões ou recursos experimentais
- Registrando provedores personalizados ou sobrescrevendo URLs base
- Configurando endpoints auto-hospedados compatíveis com OpenAI
- Registro de provedores personalizados ou sobrescrita de URLs base
- Configuração de endpoints auto-hospedados compatíveis com OpenAI
sidebarTitle: Tools and custom providers
summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas baseadas em provedor) e configuração de provedor/URL base personalizada
summary: Configuração de ferramentas (política, alternâncias experimentais, ferramentas respaldadas por provedor) e configuração personalizada de provedor/URL base
title: Configuração — ferramentas e provedores personalizados
x-i18n:
generated_at: "2026-04-30T09:47:38Z"
generated_at: "2026-05-01T05:56:33Z"
model: gpt-5.5
provider: openai
source_hash: 1790c92ecaf822c837326d8e22e9d72cc44e5d4cc0bcc00c154ba5160975002a
source_hash: 97e6bd8c762f6f7a9985b99ec016dde22c8ea8adc925778b11c2ae5103b887a8
source_path: gateway/config-tools.md
workflow: 16
---
Chaves de configuração `tools.*` e configuração de provedor personalizado / URL base. Para agentes, canais e outras chaves de configuração de nível superior, consulte a [Referência de configuração](/pt-BR/gateway/configuration-reference).
`tools.*` chaves de configuração e configuração personalizada de provedor / URL-base. Para agents, channels e outras chaves de configuração de nível superior, consulte a [Referência de configuração](/pt-BR/gateway/configuration-reference).
## Ferramentas
@ -24,7 +24,7 @@ Chaves de configuração `tools.*` e configuração de provedor personalizado /
`tools.profile` define uma lista de permissões base antes de `tools.allow`/`tools.deny`:
<Note>
O onboarding local define novas configurações locais como `tools.profile: "coding"` quando não estiver definido (perfis explícitos existentes são preservados).
A integração local define novas configurações locais como `tools.profile: "coding"` por padrão quando não definido (perfis explícitos existentes são preservados).
</Note>
| Perfil | Inclui |
@ -36,24 +36,24 @@ O onboarding local define novas configurações locais como `tools.profile: "cod
### Grupos de ferramentas
| Grupo | Ferramentas |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| Grupo | Ferramentas |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
| `group:web` | `web_search`, `x_search`, `web_fetch` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `cron`, `gateway` |
| `group:messaging` | `message` |
| `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:memory` | `memory_search`, `memory_get` |
| `group:web` | `web_search`, `x_search`, `web_fetch` |
| `group:ui` | `browser`, `canvas` |
| `group:automation` | `cron`, `gateway` |
| `group:messaging` | `message` |
| `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) |
### `tools.allow` / `tools.deny`
Política global de permissão/bloqueio de ferramentas (bloqueio vence). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desligado.
Política global de permissão/negação de ferramentas (negação vence). Não diferencia maiúsculas de minúsculas, aceita curingas `*`. Aplicada mesmo quando o sandbox do Docker está desativado.
```json5
{
@ -63,7 +63,7 @@ Política global de permissão/bloqueio de ferramentas (bloqueio vence). Não di
### `tools.byProvider`
Restringe ainda mais as ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permitir/bloquear.
Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permissão/negação.
```json5
{
@ -79,7 +79,7 @@ Restringe ainda mais as ferramentas para provedores ou modelos específicos. Ord
### `tools.elevated`
Controla acesso elevado ao exec fora do sandbox:
Controla acesso elevado a exec fora do sandbox:
```json5
{
@ -97,7 +97,7 @@ Controla acesso elevado ao 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 sandboxing e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino do exec é `node`).
- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino de exec é `node`).
### `tools.exec`
@ -121,7 +121,7 @@ Controla acesso elevado ao exec fora do sandbox:
### `tools.loopDetection`
As verificações de segurança de loop 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 para 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`.
```json5
{
@ -143,25 +143,25 @@ As verificações de segurança de loop de ferramentas são **desativadas por pa
```
<ParamField path="historySize" type="number">
Histórico máximo de chamadas de ferramenta retido para análise de loops.
Máximo de histórico de chamadas de ferramentas retido para análise de loop.
</ParamField>
<ParamField path="warningThreshold" type="number">
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.
Limite repetido mais alto para bloquear loops críticos.
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
Limite de parada rígida para qualquer execução sem progresso.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos.
Avisa sobre chamadas repetidas com a mesma ferramenta/mesmos argumentos.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Avisa/bloqueia em ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.).
Avisa/bloqueia ferramentas de sondagem conhecidas (`process.poll`, `command_status` etc.).
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
Avisa/bloqueia em padrões de pares alternados sem progresso.
Avisa/bloqueia padrões alternados de pares sem progresso.
</ParamField>
<Warning>
@ -176,14 +176,14 @@ Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircui
web: {
search: {
enabled: true,
apiKey: "brave_api_key", // or BRAVE_API_KEY env
apiKey: "brave_api_key", // ou env BRAVE_API_KEY
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
fetch: {
enabled: true,
provider: "firecrawl", // optional; omit for auto-detect
provider: "firecrawl", // opcional; omita para detecção automática
maxChars: 50000,
maxCharsCap: 50000,
maxResponseBytes: 2000000,
@ -200,7 +200,7 @@ Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircui
### `tools.media`
Configura a compreensão de mídia de entrada (imagem/áudio/vídeo):
Configura a compreensão de mídia recebida (imagem/áudio/vídeo):
```json5
{
@ -208,7 +208,7 @@ Configura a compreensão de mídia de entrada (imagem/áudio/vídeo):
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async music/video directly to the channel
directSend: false, // opt-in: send finished async video directly to the channel
},
audio: {
enabled: true,
@ -241,27 +241,27 @@ Configura a compreensão de mídia de entrada (imagem/áudio/vídeo):
<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 de `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 em `auth-profiles.json`
**Entrada de CLI** (`type: "cli"`):
- `command`: executável a ser executado
- `args`: argumentos com template (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.; `openclaw doctor --fix` migra placeholders obsoletos de `{input}` para `{{MediaPath}}`)
- `args`: argumentos com modelo (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.; `openclaw doctor --fix` migra placeholders `{input}` obsoletos 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`.
- Falhas recorrem à próxima entrada.
- `tools.media.image.timeoutSeconds` e entradas `timeoutSeconds` correspondentes de modelo de imagem também se aplicam quando o agente chama a ferramenta explícita `image`.
- Falhas passam para a 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 assíncronas `music_generate` e `video_generate` concluídas tentam primeiro a entrega direta no canal. Padrão: `false` (caminho legado de despertar da sessão solicitante/entrega pelo modelo).
- `asyncCompletion.directSend`: quando `true`, tarefas de mídia assíncronas concluídas que oferecem suporte à entrega direta de conclusão tentam primeiro a entrega direta ao canal. Padrão: `false` (caminho de ativação da sessão solicitante/entrega pelo modelo). Hoje, isso se aplica ao `video_generate` assíncrono; conclusões assíncronas de `music_generate` continuam mediadas pela sessão solicitante mesmo quando isto está habilitado.
</Accordion>
</AccordionGroup>
@ -283,7 +283,7 @@ Configura a compreensão de mídia de entrada (imagem/áudio/vídeo):
Controla quais sessões podem ser direcionadas pelas ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`).
Padrão: `tree` (sessão atual + sessões criadas por ela, como subagentes).
Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes).
```json5
{
@ -298,11 +298,11 @@ Padrão: `tree` (sessão atual + sessões criadas por ela, como subagentes).
<AccordionGroup>
<Accordion title="Escopos de visibilidade">
- `self`: somente a chave da sessão atual.
- `tree`: sessão atual + sessões criadas 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`.
- Limite 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"`.
- `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. Direcionamento entre agentes ainda exige `tools.agentToAgent`.
- Limite do 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>
@ -328,13 +328,13 @@ Controla o suporte a anexos inline para `sessions_spawn`.
```
<AccordionGroup>
<Accordion title="Notas sobre anexos">
- Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita.
- Arquivos são materializados no workspace filho em `.openclaw/attachments/<uuid>/` com um `.manifest.json`.
<Accordion title="Observações sobre anexos">
- Anexos só são compatíveis 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 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 somente quando `retainOnSessionKeep: true`.
- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`.
</Accordion>
</AccordionGroup>
@ -343,7 +343,7 @@ Controla o suporte a anexos inline para `sessions_spawn`.
### `tools.experimental`
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.
Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos que uma regra de habilitação automática de GPT-5 estritamente agêntico se aplique.
```json5
{
@ -355,9 +355,9 @@ Flags experimentais de ferramentas integradas. Desativado por padrão, a menos q
}
```
- `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 como `true` para forçar a ativação da ferramenta fora desse escopo, ou como `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 só a utilize em trabalhos substanciais e mantenha no máximo uma etapa `in_progress`.
- `planTool`: habilita a ferramenta estruturada `update_plan` para rastrear trabalhos não triviais com 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 de família GPT-5 da OpenAI ou do OpenAI Codex. Defina como `true` para forçar a ativação da ferramenta fora desse escopo, ou como `false` para mantê-la desativada mesmo para execuções GPT-5 strict-agentic.
- Quando habilitado, o prompt do sistema também adiciona orientação de uso para que o modelo só a utilize em trabalhos substanciais e mantenha no máximo uma etapa `in_progress`.
### `agents.defaults.subagents`
@ -378,9 +378,9 @@ Flags experimentais de ferramentas integradas. Desativado por padrão, a menos q
```
- `model`: modelo padrão para subagentes gerados. Se omitido, os subagentes herdam o modelo do chamador.
- `allowAgents`: lista de permissão 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).
- `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 ferramentas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
- Política de ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
@ -416,84 +416,84 @@ OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizado
```
<AccordionGroup>
<Accordion title="Auth and merge precedence">
- Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas.
<Accordion title="Autenticação e precedência de mesclagem">
- Use `authHeader: true` + `headers` para necessidades de autenticação personalizada.
- Substitua a raiz da 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:
- Precedência de mesclagem para IDs de provedores correspondentes:
- Valores `baseUrl` não vazios do `models.json` do agente prevalecem.
- Valores `apiKey` não vazios do agente prevalecem somente 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/execução), 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/execução).
- Valores `apiKey` não vazios do agente prevalecem 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 dos 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 dos 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` 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.
- `contextWindow`/`maxTokens` de modelos correspondentes 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 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 escritos a partir do snapshot da configuração de origem ativa (pré-resolução), não a partir de valores de segredo de runtime resolvidos.
- A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot da configuração de origem ativa (pré-resolução), não dos valores de segredos resolvidos em runtime.
</Accordion>
</AccordionGroup>
### Detalhes dos campos de provedor
### Detalhes dos campos do provedor
<AccordionGroup>
<Accordion title="Top-level catalog">
<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 pelo id do provedor.
- `models.providers`: mapa de provedores personalizados indexado por ID de 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="Provider connection and auth">
- `models.providers.*.api`: adaptador de solicitação (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). Para backends `/v1/chat/completions` auto-hospedados, 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` somente quando o backend for compatível com `/v1/responses`.
- `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição de env).
<Accordion title="Conexão e autenticação do provedor">
- `models.providers.*.api`: adaptador de solicitação (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). Para backends `/v1/chat/completions` auto-hospedados, 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 oferecer suporte a `/v1/responses`.
- `models.providers.*.apiKey`: credencial do provedor (prefira substituição 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 sob este provedor quando a entrada do modelo não define `contextWindow`.
- `models.providers.*.contextTokens`: limite de contexto de runtime efetivo padrão para modelos sob este provedor quando a entrada do modelo não define `contextTokens`.
- `models.providers.*.contextTokens`: limite de contexto efetivo em runtime padrão para modelos sob este provedor quando a entrada do modelo não define `contextTokens`.
- `models.providers.*.maxTokens`: limite padrão de tokens de saída para modelos sob este provedor quando a entrada do modelo não define `maxTokens`.
- `models.providers.*.timeoutSeconds`: tempo limite opcional por provedor para solicitações HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de cancelamento total da solicitação.
- `models.providers.*.timeoutSeconds`: tempo limite opcional por provedor para solicitações HTTP de modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de cancelamento 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.*.authHeader`: força o transporte da credencial 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="Request transport overrides">
`models.providers.*.request`: substituições de transporte para solicitações HTTP de provedores de modelo.
<Accordion title="Substituições de transporte de solicitação">
`models.providers.*.request`: substituições de transporte para solicitações HTTP de provedor de modelo.
- `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"` (usar 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"` (usar variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional.
- `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). 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.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 intervalos privados, CGNAT ou semelhantes, via a 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 provedores de modelo em local loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isto seja definido explicitamente 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`.
- `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou semelhantes, 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 modelo em loopback, como `localhost`, `127.0.0.1` e `[::1]`, são permitidas automaticamente, a menos que isso seja definido explicitamente 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="Model catalog entries">
<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ó são injetados em turnos do agente quando o modelo selecionado está marcado como compatível com imagem.
- `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 nas rodadas do agente quando o modelo selecionado está marcado como capaz de processar imagens.
- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. Isso substitui o `contextWindow` no nível do provedor para esse modelo.
- `models.providers.*.models.*.contextTokens`: limite opcional de contexto de runtime. Isso substitui `contextTokens` no nível do 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 nativo e não vazio (host não é `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 `messages[].content` de texto puro em strings simples antes de enviar a solicitação.
- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Isso substitui o `contextTokens` no nível do 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 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 apenas string. Quando `true`, OpenClaw achata arrays `messages[].content` de texto puro em strings simples antes de enviar a solicitação.
</Accordion>
<Accordion title="Amazon Bedrock discovery">
<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.providerFilter`: filtro opcional por id de provedor para descoberta direcionada.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de 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 de fallback para modelos descobertos.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos.
- `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.
</Accordion>
</AccordionGroup>
A integração interativa de provedor personalizado 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 modelo desconhecidos ainda solicitam confirmação de 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.
A integração interativa de provedor personalizado 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 modelo 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
<AccordionGroup>
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
O Plugin de provedor `cerebras` incluído pode configurar isto via `openclaw onboard --auth-choice cerebras-api-key`. Use configuração explícita de provedor somente ao substituir os padrões.
O Plugin de provedor `cerebras` incluído pode configurar isso via `openclaw onboard --auth-choice cerebras-api-key`. Use configuração explícita de provedor apenas ao substituir padrões.
```json5
{
@ -547,7 +547,7 @@ A integração interativa de provedor personalizado infere entrada de imagem par
</Accordion>
<Accordion title="Modelos locais (LM Studio)">
Consulte [Modelos locais](/pt-BR/gateway/local-models). TL;DR: execute um modelo local grande via LM Studio Responses API em hardware robusto; mantenha modelos hospedados mesclados como fallback.
Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumo: execute um modelo local grande pela API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para alternativa.
</Accordion>
<Accordion title="MiniMax M2.7 (direto)">
```json5
@ -584,7 +584,7 @@ A integração interativa de provedor personalizado infere entrada de imagem par
}
```
Defina `MINIMAX_API_KEY`. Atalhos: `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. O catálogo de modelos usa apenas M2.7 por padrão. No caminho de streaming compatível com Anthropic, o OpenClaw desativa o raciocínio do MiniMax por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
Defina `MINIMAX_API_KEY`. Atalhos: `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. O catálogo de modelos usa apenas M2.7 por padrão. No caminho de streaming compatível com Anthropic, o OpenClaw desativa o pensamento do MiniMax por padrão, a menos que você defina explicitamente `thinking`. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -623,7 +623,7 @@ A integração interativa de provedor personalizado infere entrada de imagem par
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 compartilhado `openai-completions`, e o OpenClaw determina isso com base nas capacidades do endpoint, não apenas pelo id do provedor integrado.
Endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado `openai-completions`, e o OpenClaw baseia isso nos recursos do endpoint, em vez de apenas no ID do provedor integrado.
</Accordion>
<Accordion title="OpenCode">
@ -638,10 +638,10 @@ A integração interativa de provedor personalizado infere entrada de imagem par
}
```
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`.
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`.
</Accordion>
<Accordion title="Synthetic (compatível com Anthropic)">
<Accordion title="Sintético (compatível com Anthropic)">
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
@ -693,7 +693,7 @@ A integração interativa de provedor personalizado infere entrada de imagem par
Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `openclaw onboard --auth-choice zai-api-key`.
- Endpoint geral: `https://api.z.ai/api/paas/v4`
- Endpoint de programação (padrão): `https://api.z.ai/api/coding/paas/v4`
- Endpoint de codificação (padrão): `https://api.z.ai/api/coding/paas/v4`
- Para o endpoint geral, defina um provedor personalizado com a substituição da URL base.
</Accordion>
@ -701,7 +701,7 @@ A integração interativa de provedor personalizado infere entrada de imagem par
---
## Relacionados
## Relacionado
- [Configuração — agentes](/pt-BR/gateway/config-agents)
- [Configuração — canais](/pt-BR/gateway/config-channels)

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

@ -1,20 +1,20 @@
---
read_when:
- Adicionar ou modificar migrações do doctor
- Introduzindo alterações incompatíveis na configuração
- Introduzindo alterações incompatíveis de configuração
sidebarTitle: Doctor
summary: 'Comando Doctor: verificações de integridade, migrações de configuração e etapas de reparo'
summary: 'Comando doctor: verificações de integridade, migrações de configuração e etapas de reparo'
title: Diagnóstico
x-i18n:
generated_at: "2026-04-30T16:28:43Z"
generated_at: "2026-05-01T05:56:31Z"
model: gpt-5.5
provider: openai
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
source_hash: 52183eaf6024eface20089f9d11143ef1e952d2488eee766dc154512f5d3c6b4
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 config/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
## Início rápido
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Aceita os padrões sem perguntar (incluindo etapas de reparo de reinício/serviço/sandbox quando aplicável).
Aceita os padrões sem solicitar confirmação (incluindo etapas de reparo de reinicialização/serviço/sandbox quando aplicável).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Aplica os reparos recomendados sem perguntar (reparos + reinícios quando seguro).
Aplica os reparos recomendados sem solicitar confirmação (reparos + reinicializações quando seguro).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Aplica também reparos agressivos (sobrescreve configurações personalizadas de supervisor).
Aplica também reparos agressivos (sobrescreve configs personalizadas de supervisor).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Executa sem prompts e aplica apenas migrações seguras (normalização de configuração + movimentações de estado em disco). Ignora ações de reinício/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
Executa sem prompts e aplica apenas migrações seguras (normalização de config + movimentações de estado no disco). Ignora ações de reinicialização/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
</Tab>
<Tab title="--deep">
@ -62,12 +62,12 @@ openclaw doctor
openclaw doctor --deep
```
Examina serviços do sistema em busca de instalações extras do Gateway (launchd/systemd/schtasks).
Varre serviços do sistema em busca de instalações extras do Gateway (launchd/systemd/schtasks).
</Tab>
</Tabs>
Se quiser revisar as alterações antes de gravar, abra o arquivo de configuração primeiro:
Se você quiser revisar as alterações antes de gravar, abra o arquivo de config primeiro:
```bash
cat ~/.openclaw/openclaw.json
@ -76,112 +76,117 @@ cat ~/.openclaw/openclaw.json
## O que ele faz (resumo)
<AccordionGroup>
<Accordion title="Integridade, UI e atualizações">
- Atualização opcional de pré-execução para instalações via git (somente interativo).
<Accordion title="Health, UI, and updates">
- Atualização opcional de pré-verificação para instalações git (somente interativo).
- Verificação de atualização do protocolo da UI (recompila a Control UI quando o esquema de protocolo é mais recente).
- Verificação de integridade + prompt de reinício.
- Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de Plugin.
- Verificação de integridade + prompt de reinicialização.
- Resumo de status de Skills (elegível/ausente/bloqueado) e status de Plugin.
</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 de navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP.
<Accordion title="Config and migrations">
- Normalização de config para valores legados.
- Migração da config Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
- Verificações de migração de navegador para configs 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`).
- 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.
- Migração de estado legado em disco (sessões/diretório do agente/autenticação do WhatsApp).
- Avisos de sombreamento de OAuth do Codex (`models.providers.openai-codex`).
- Verificação de pré-requisitos de TLS para perfis 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 curinga ou ferramentas pertencentes a Plugin.
- Migração de estado legado no disco (sessions/agent dir/auth do WhatsApp).
- Migração de chaves legadas do contrato de manifesto de Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migração da store de Cron legada (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, jobs simples de fallback de Webhook `notify: true`).
- Migração da política de runtime legada do agente 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.
- Migração do armazenamento legado de Cron (`jobId`, `schedule.cron`, campos delivery/payload de nível superior, payload `provider`, jobs simples de fallback de Webhook `notify: true`).
- Migração legada de runtime-policy de agentes para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Limpeza de config obsoleta de Plugin quando Plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como config de contenção inerte e são preservadas.
</Accordion>
<Accordion title="Estado e integridade">
- Inspeção de arquivos de lock de sessão e limpeza de locks obsoletos.
- Reparo de transcritos de sessão para ramificações duplicadas de reescrita de prompt criadas por builds 2026.4.24 afetadas.
- Detecção de tombstones de recuperação por reinício 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 por reinício.
<Accordion title="State and integrity">
- Inspeção de arquivo de bloqueio de sessão e limpeza de bloqueios obsoletos.
- Reparo de transcritos de sessão para ramificações duplicadas de reescrita de prompt criadas por builds afetados de 2026.4.24.
- Detecção de marcações de recuperação por 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 por reinicialização.
- Verificações de integridade de estado e permissões (sessões, transcritos, diretório de estado).
- Verificações de permissão do arquivo de configuração (chmod 600) ao executar localmente.
- Integridade da autenticação de modelo: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e relata estados de cooldown/desabilitação de perfis de autenticação.
- Verificações de permissão do arquivo de config (chmod 600) ao executar localmente.
- Integridade de autenticação do modelo: verifica expiração de OAuth, pode atualizar tokens próximos de expirar e relata estados de cooldown/desabilitado de auth-profile.
- Detecção de diretório extra de workspace (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, serviços e supervisores">
- Reparo da imagem de sandbox quando sandboxing está habilitado.
- Migração de serviço legado e detecção de Gateway extra.
- Migração de estado legado do canal Matrix (no modo `--fix` / `--repair`).
<Accordion title="Gateway, services, and supervisors">
- Reparo de imagem de sandbox quando sandboxing está habilitado.
- Migração de serviço legado e detecção extra de Gateway.
- Migração de estado legado do canal Matrix (em 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 canal (sondados a partir do Gateway em execução).
- Auditoria de configuração de supervisor (launchd/systemd/schtasks) com reparo opcional.
- Limpeza de ambiente de proxy embutido para serviços do Gateway que capturaram valores shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização.
- Verificações de melhores práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciador de versões).
- Diagnósticos de colisão de porta do Gateway (padrão `18789`).
- Auditoria de config de supervisor (launchd/systemd/schtasks) com reparo opcional.
- Limpeza de ambiente de proxy embutido para serviços 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 gerenciador de versões).
- Diagnóstico 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 abertas de DM.
- 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 SecretRef de token).
- Detecção de problemas de pareamento de dispositivo (solicitações pendentes de pareamento inicial, upgrades pendentes de função/escopo, divergência de cache local obsoleto de token de dispositivo e divergência de autenticação de registro pareado).
<Accordion title="Auth, security, and pairing">
- 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 configs SecretRef de token).
- Detecção de problemas de pareamento de dispositivo (solicitações pendentes de pareamento inicial, upgrades pendentes de função/escopo, desvio de cache local obsoleto de token de dispositivo e desvio de autenticação de registro pareado).
</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/quase limite para arquivos de contexto).
<Accordion title="Workspace and shell">
- Verificação de systemd linger no Linux.
- Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/quase-limite para arquivos de contexto).
- 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 de workspace pnpm, assets de UI ausentes, binário tsx ausente).
- Grava configuração atualizada + metadados do assistente.
- Grava config atualizada + metadados do assistente.
</Accordion>
</AccordionGroup>
## Preenchimento retroativo e redefinição da UI Dreams
## Backfill e reset da UI Dreams
A cena Dreams da Control UI inclui 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 Gateway doctor, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
A cena Dreams da Control UI inclui ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de Dreaming fundamentado. Essas ações usam métodos RPC do Gateway no estilo do doctor, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
O que elas fazem:
- **Backfill** examina arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM fundamentada e grava entradas reversíveis de preenchimento retroativo em `DREAMS.md`.
- **Reset** remove apenas essas entradas marcadas de diário de preenchimento retroativo de `DREAMS.md`.
- **Clear Grounded** remove apenas entradas encenadas de curto prazo somente fundamentadas que vieram de replay histórico e ainda não acumularam recall ao vivo ou suporte diário.
- **Backfill** varre arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de 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 staged de curto prazo 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 mesmas:
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 fundamentados na store de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho da CLI encenado primeiro
- elas não colocam automaticamente candidatos fundamentados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho staged da CLI primeiro
Se quiser que o replay histórico fundamentado influencie a lane normal de promoção profunda, use o fluxo da CLI em vez disso:
Se você quiser que o replay histórico fundamentado influencie a faixa 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 fundamentados na store de Dreaming de curto prazo, mantendo `DREAMS.md` como superfície de revisão.
Isso coloca candidatos duráveis fundamentados no armazenamento de Dreaming de curto prazo, mantendo `DREAMS.md` como 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 interativamente, ele oferecerá uma atualização (fetch/rebase/build) antes de executar o doctor.
<Accordion title="0. Optional update (git installs)">
Se isto for um checkout git e o doctor estiver sendo executado interativamente, 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 esquema atual.
<Accordion title="1. Config normalization">
Se a config contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição 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` no mapa de provedores.
Isso inclui campos planos legados de Talk. A config 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
curinga ou entradas de ferramentas pertencentes a Plugin. `tools.allow: ["*"]` corresponde apenas a ferramentas
de Plugins que realmente carregam; ele não contorna a lista exclusiva de permissões de Plugin.
</Accordion>
<Accordion title="2. Migrações de chaves de configuração legadas">
Quando a configuração contém chaves obsoletas, outros comandos se recusam a executar e pedem que você execute `openclaw doctor`.
<Accordion title="2. Legacy config key migrations">
Quando a config contém chaves obsoletas, outros comandos se recusam a executar e pedem que você execute `openclaw doctor`.
O doctor irá:
- Explicar quais chaves legadas foram encontradas.
- Mostrar a migração aplicada.
- Mostrar a migração que ele aplicou.
- Reescrever `~/.openclaw/openclaw.json` com o esquema atualizado.
O Gateway também executa migrações do doctor automaticamente na inicialização quando detecta um formato de configuração legado, para que configurações obsoletas sejam reparadas sem intervenção manual. Migrações da store de jobs 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 config legado, então configs obsoletas são reparadas sem intervenção manual. Migrações do armazenamento de jobs Cron são tratadas por `openclaw doctor --fix`.
Migrações atuais:
@ -206,70 +211,70 @@ Isso encena candidatos duráveis fundamentados na store de Dreaming de curto pra
- `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, move 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 remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; o 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`
- remove `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para timeouts de provedor/modelo lentos
- remova `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para timeouts lentos de provedor/modelo
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- remove `browser.relayBindHost` (configuração legada de relay da extensão)
- `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como valor de enum futuro ou desconhecido, em vez de falhar fechado)
- remova `browser.relayBindHost` (configuração legada de retransmissão de 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 de enumeração futuro ou desconhecido, em vez de falhar de modo fechado)
Os avisos do doctor também incluem orientação de padrão de conta 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.
- 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 + custos por modelo.
</Accordion>
<Accordion title="2c. Migração do navegador e prontidão do Chrome MCP">
Se sua configuração de 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 apontar para o caminho removido da extensão do Chrome, o Doctor a normaliza para o modelo atual de anexação Chrome MCP local do host:
- `browser.profiles.*.driver: "extension"` vira `"existing-session"`
- `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 do 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`)
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 do host ainda exige:
- um navegador baseado em Chromium 144+ no host do gateway/node
- um navegador baseado em Chromium 144+ no host gateway/node
- o navegador em execução localmente
- depuração remota habilitada nesse navegador
- aprovar o primeiro prompt de consentimento de anexação no navegador
- aprovação do primeiro prompt de consentimento de anexação no navegador
A prontidão aqui trata apenas dos 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 downloads e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto.
Esta verificação **não** se aplica a Docker, sandbox, remote-browser ou outros fluxos headless. Esses continuam usando CDP bruto.
Esta verificação **não** se aplica a fluxos 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 sonda o endpoint de autorização da OpenAI para verificar se a pilha TLS local do 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 íntegro.
Quando um perfil OAuth do OpenAI Codex está configurado, o Doctor sonda o endpoint de autorização da OpenAI para verificar se a pilha local Node/OpenSSL TLS 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 íntegro.
</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 mascarar o caminho do provedor OAuth do Codex integrado que versões mais novas usam automaticamente. O doctor avisa quando encontra essas configurações antigas de transporte junto com 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 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 somente de cabeçalho 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 PI padrão. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex via PI, mas é fácil confundi-la com o harness app-server nativo do Codex. O doctor avisa e aponta para a forma explícita de 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 referências de modelo primário `openai-codex/*` ainda são resolvidas 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 app do Codex. O Doctor avisa e aponta para o formato explícito do servidor de app: `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 corrige isso automaticamente porque as duas rotas são válidas:
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo executor normal do OpenClaw."
- `openai/*` + `runtime: "codex"` significa "executar o turno embutido pelo app-server nativo do Codex."
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex pelo chat."
- `openai/*` + `runtime: "codex"` significa "executar o turno incorporado pelo servidor de app 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 que você pretendia 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 OAuth do PI Codex for intencional.
</Accordion>
<Accordion title="3. Migrações de estado legado (layout em disco)">
O doctor pode migrar layouts antigos em disco para a estrutura atual:
<Accordion title="3. Migrações de estado legado (layout de disco)">
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/`
@ -279,84 +284,84 @@ Isso encena candidatos duráveis fundamentados na store de Dreaming de curto pra
- de `~/.openclaw/credentials/*.json` legado (exceto `oauth.json`)
- para `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID da conta padrão: `default`)
Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente as sessões legadas + o 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 é migrada intencionalmente apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diffs apenas de ordem de 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 alguma pasta legada para trás como backup. O Gateway/CLI também migra automaticamente o armazenamento de sessões legadas + diretório do agente na inicialização para que histórico/autenticação/modelos caiam 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 fala agora compara por igualdade estrutural, então diffs apenas de ordem de chaves não acionam mais alterações `doctor --fix` repetidas sem efeito.
</Accordion>
<Accordion title="3a. Migrações de manifestos legados de Plugin">
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 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. Essa 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 do armazenamento de Cron legado">
O doctor também verifica o armazenamento de tarefas cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de tarefa que o agendador ainda aceita por compatibilidade.
<Accordion title="3b. Migrações de armazenamento Cron legado">
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 de cron atuais incluem:
As limpezas Cron atuais incluem:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- 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
- tarefas webhook simples legadas de fallback `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 tarefas `notify: true` quando consegue fazer isso sem alterar o comportamento. Se uma tarefa combina fallback legado de notify com um modo de entrega não webhook existente, o doctor avisa e deixa essa tarefa para revisão manual.
O Doctor só migra automaticamente jobs `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um job combina fallback legado de notificação com um modo de entrega não Webhook existente, o Doctor avisa e deixa esse job para revisão manual.
</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 encerrou de forma anormal. Para cada arquivo de bloqueio encontrado, ele relata: o caminho, PID, se o PID ainda está ativo, 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`.
O Doctor verifica todos os diretórios de sessão de agente em busca de arquivos obsoletos de bloqueio de gravação — arquivos deixados para trás quando uma sessão saiu de forma anormal. Para cada arquivo de bloqueio encontrado, ele informa: o caminho, PID, se o PID ainda está ativo, idade do bloqueio e se ele é considerado obsoleto (PID morto ou com mais de 30 minutos). No modo `--fix` / `--repair`, ele remove automaticamente arquivos de bloqueio obsoletos; caso contrário, imprime uma nota 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: um turno de usuário abandonado com contexto interno de runtime do OpenClaw mais um irmão ativo 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 turnos duplicados.
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: um turno de usuário abandonado com contexto interno de runtime do OpenClaw mais um irmão ativo 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 turnos duplicados.
</Accordion>
<Accordion title="4. Verificações de integridade do estado (persistência de sessão, roteamento e segurança)">
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).
<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 doctor verifica:
O Doctor verifica:
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, pede para recriar o diretório e lembra que não consegue recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica capacidade 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 em nuvem no macOS**: avisa quando o estado é resolvido em 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 é resolvido para uma fonte de montagem `mmcblk*`, porque E/S aleatória apoiada por SD ou eMMC pode ser mais lenta e desgastar mais rapidamente sob escritas de sessões e credenciais.
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não é possível recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica a capacidade 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 a nuvem no macOS**: avisa quando o estado é resolvido em 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 é resolvido para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rápido durante gravações de sessões 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**: avisa quando entradas recentes de sessão têm arquivos de transcrição ausentes.
- **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á acumulando).
- **Múltiplos diretórios de estado**: avisa quando múltiplas pastas `~/.openclaw` existem em diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir 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**: avisa se `~/.openclaw/openclaw.json` está legível por grupo/mundo e oferece restringir para `600`.
- **Múltiplos diretórios de estado**: avisa quando várias pastas `~/.openclaw` existem em diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações).
- **Lembrete do 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**: avisa se `~/.openclaw/openclaw.json` é legível por grupo/todos e oferece restringir para `600`.
</Accordion>
<Accordion title="5. Saúde de autenticação de modelo (expiração de 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 setup-token da Anthropic. Prompts de atualização aparecem apenas quando executado interativamente (TTY); `--non-interactive` ignora tentativas de atualização.
<Accordion title="5. Integridade da autenticação de modelos (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. Solicitações de atualização só aparecem ao executar interativamente (TTY); `--non-interactive` pula tentativas de atualização.
Quando uma atualização de 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 pedindo para você entrar novamente), o doctor informa que a reautenticaçã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 que estão temporariamente inutilizáveis devido a:
- cooldowns curtos (limites de taxa/timeouts/falhas de autenticação)
- desativações mais longas (falhas de cobrança/crédito)
- desativações mais longas (falhas de faturamento/crédito)
</Accordion>
<Accordion title="6. Validação do modelo de hooks">
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo em relação ao catálogo e à allowlist e avisa quando ela não puder ser resolvida ou não for permitida.
<Accordion title="6. Validação de modelo dos hooks">
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo em relação ao catálogo e à lista de permissões e avisa quando ela não puder ser resolvida ou for proibida.
</Accordion>
<Accordion title="7. Reparo de imagem de sandbox">
Quando o sandboxing está habilitado, o doctor verifica as imagens Docker e oferece criar ou alternar para nomes legados se a imagem atual estiver ausente.
<Accordion title="7. Reparo da imagem de sandbox">
Quando o sandbox 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. Dependências de runtime de plugins incluídos">
O Doctor verifica dependências de runtime apenas para plugins incluídos que estão ativos na configuração atual ou habilitados pelo padrão do manifesto incluído, por exemplo `plugins.entries.discord.enabled: true`, o legado `channels.discord.enabled: true`, `models.providers.*` configurados / referências de modelo de agente, ou um plugin incluído habilitado por padrão sem propriedade de provedor. Se alguma estiver ausente, o doctor informa os pacotes e os instala no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Plugins externos ainda usam `openclaw plugins install` / `openclaw plugins update`; o doctor não instala dependências para caminhos arbitrários de plugins.
<Accordion title="7b. Dependências de runtime de Plugin incluído">
O doctor verifica dependências de runtime apenas para plugins incluídos que estão ativos na configuração atual ou habilitados pelo padrão do manifesto incluído, por exemplo `plugins.entries.discord.enabled: true`, o legado `channels.discord.enabled: true`, `models.providers.*` configurados / refs de modelo de agente, ou um Plugin incluído habilitado por padrão sem propriedade de provedor. Se alguma estiver ausente, o doctor relata os pacotes e os instala no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Plugins externos ainda usam `openclaw plugins install` / `openclaw plugins update`; o doctor não instala dependências para caminhos arbitrários de Plugin.
Durante o reparo do doctor, instalações npm de dependências de runtime incluídas relatam progresso por spinner em sessões TTY e progresso periódico em linhas em saída canalizada/headless. O Gateway e a CLI local também podem reparar dependências de runtime de plugins incluídos ativos sob demanda antes de importar um plugin incluído. Essas instalações ficam restritas à raiz de instalação do runtime do plugin, executam com scripts desabilitados, não gravam um package lock e são protegidas por um bloqueio da raiz de instalação para que inicializações simultâneas da CLI ou do Gateway não alterem a mesma árvore `node_modules` ao mesmo tempo.
Durante o reparo do doctor, instalações npm de dependências de runtime incluídas relatam progresso por spinner em sessões TTY e progresso periódico por linha em saída encadeada/headless. O Gateway e a CLI local também podem reparar dependências de runtime de Plugin incluído ativo sob demanda antes de importar um Plugin incluído. Essas instalações são limitadas à raiz de instalação de runtime do Plugin, executadas com scripts desabilitados, não gravam um package lock e são protegidas por um bloqueio da raiz de instalação para que inícios simultâneos da CLI ou do Gateway não modifiquem a mesma árvore `node_modules` ao mesmo tempo.
</Accordion>
<Accordion title="8. Migrações de serviço do Gateway e dicas de limpeza">
O Doctor detecta serviços de gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço do OpenClaw usando a porta atual do gateway. Ele também pode verificar serviços extras semelhantes ao gateway e imprimir dicas de limpeza. Serviços de gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são marcados como "extras".
O doctor detecta serviços legados de 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 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`, depois 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 em nível de usuário estiver ausente mas existir um serviço de Gateway 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`, depois remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor do sistema for dono do 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 depois 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.
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 são não fatais; os erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é ignorada completamente.
</Accordion>
<Accordion title="8c. Pareamento de dispositivos 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 verificação normal de integridade.
O que ele relata:
@ -365,123 +370,123 @@ Isso encena candidatos duráveis fundamentados na store de Dreaming de curto pra
- 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
- registros pareados sem um token ativo para uma função aprovada
- tokens pareados cujos escopos desviaram da linha de base de pareamento aprovada
- entradas locais em cache de token de dispositivo para a máquina atual anteriores a uma rotação de token no lado do gateway ou com metadados de escopo obsoletos
- tokens pareados cujos escopos desviam da linha de base de pareamento aprovada
- entradas de token de dispositivo armazenadas em cache localmente 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
O Doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime os próximos passos exatos:
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 aprove novamente um registro obsoleto com `openclaw devices remove <deviceId>`
- remova e reaprove um registro obsoleto com `openclaw devices remove <deviceId>`
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento obrigatório": o doctor agora distingue primeiro pareamento de upgrades pendentes de função/escopo e de desvio de token/identidade de dispositivo obsoleto.
Isso fecha a falha comum de "já pareado, mas ainda recebendo pareamento obrigatório": o doctor agora distingue 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 allowlist, 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 executando como um serviço de usuário do systemd, o doctor garante que o lingering 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 lingering esteja habilitado para que o Gateway continue 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:
O doctor imprime um resumo do estado do workspace para o agente padrão:
- **Status de Skills**: conta skills elegíveis, com requisitos ausentes e bloqueadas por allowlist.
- **Diretórios legados de workspace**: avisa quando `~/openclaw` ou outros diretórios legados de workspace existem ao lado do workspace atual.
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de plugins para quaisquer erros; relata capacidades de plugins do bundle.
- **Status de Skills**: conta skills elegíveis, com requisitos ausentes e bloqueadas por lista de permissões.
- **Diretórios de workspace legados**: avisa quando `~/openclaw` ou outros diretórios de workspace legados existem ao lado do workspace atual.
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de Plugin para quaisquer erros; relata capacidades de Plugin do bundle.
- **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 de tempo de carregamento emitidos pelo registro de plugins.
- **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros em tempo de carregamento emitidos pelo registro de Plugin.
</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 contagens por arquivo 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 os arquivos são truncados ou se aproximam do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
O doctor verifica se arquivos de bootstrap do workspace (por exemplo `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão perto ou acima do orçamento de caracteres configurado. Ele relata, por arquivo, contagens de caracteres brutos vs. injetados, porcentagem 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 perto 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>`, alvos 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 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 `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal não existe mais, mas a configuração ainda pede ao gateway para se vincular a ele.
</Accordion>
<Accordion title="11c. Autocompletar do shell">
O Doctor verifica se a conclusão por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
<Accordion title="11c. Compleçã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 conclusão dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
- Se a conclusão está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
- Se nenhuma conclusão está configurada, o doctor solicita a instalação (somente no modo interativo; ignorado com `--non-interactive`).
- Se o perfil do shell usa um padrão de completação dinâmica lenta (`source <(openclaw completion ...)`), o doctor o atualiza para a variante de arquivo em cache mais rápida.
- 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 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 não existe fonte de token, o doctor oferece gerar um.
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está 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.
- Se o modo de token precisar de um token e nenhuma origem de token existir, o doctor oferece gerar um.
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o sobrescreve com texto puro.
- `openclaw doctor --generate-gateway-token` força a geração somente 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 de falha rápida do runtime.
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo somente leitura de SecretRef que os comandos da família de status para reparos de configuração direcionados.
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar as credenciais de bot configuradas quando disponíveis.
- Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho do 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 que o token está ausente.
- `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 configuradas do bot quando disponíveis.
- Se o token do bot Telegram estiver configurado via SecretRef, mas indisponível no caminho do comando atual, o doctor relata que a credencial está configurada-mas-indisponível e pula a resolução automática em vez de falhar ou relatar incorretamente o token como ausente.
</Accordion>
<Accordion title="13. Verificação de saúde do Gateway + reinicialização">
O Doctor executa uma verificação de saúde e oferece reiniciar o gateway quando ele parece não saudável.
<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 estar não í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:
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 provedor configurados:
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Se não, imprime orientação 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 alternar para um provedor remoto.
- **Backend QMD**: testa se o binário `qmd` está disponível e pode ser iniciado. Se não estiver, imprime orientação 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 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.
- **Provedor automático**: verifica primeiro a disponibilidade do modelo local e depois tenta cada provedor remoto na ordem de seleção automática.
Quando um resultado de sondagem do gateway em cache está disponível (o gateway estava saudável 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 de memória quando quiser uma verificação ao vivo do provedor.
Quando um resultado em cache da sondagem do gateway está disponível (o gateway estava íntegro no momento da verificação), o doctor cruza o resultado com a configuração visível pela CLI e observa qualquer discrepância. O doctor não inicia um novo ping de embeddings no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ativa do provedor.
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em runtime.
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em tempo de execução.
</Accordion>
<Accordion title="14. Avisos de status de canal">
Se o gateway estiver saudável, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
<Accordion title="14. Avisos de status dos canais">
Se o gateway estiver íntegro, o doctor executa uma sondagem de status dos canais 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 instalado (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências de systemd network-online e atraso de reinício). 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 do supervisor instalada (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências de network-online do systemd e atraso de reinicialização). 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:
- `openclaw doctor` solicita confirmação antes de reescrever a configuração do supervisor.
- `openclaw doctor --yes` aceita os prompts de reparo padrão.
- `openclaw doctor --repair` aplica as correções recomendadas sem prompts.
- `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 de configuração do supervisor e limpeza de serviços legados porque um supervisor externo é dono desse ciclo de vida.
- No Linux, o doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd do Gateway correspondente está ativa. Ele também ignora unidades extras inativas 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 mais 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 fonte de runtime em vez da definição do supervisor.
- O Doctor detecta quando o comando do serviço ainda fixa um `--port` antigo depois que `gateway.port` muda 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ção acionável.
- 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 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 do Doctor se recusam a reescrever, parar ou reiniciar um serviço do 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 em modo 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 sejam de serviço, mas ignora instalação/início/reinício/bootstrap do serviço, reescritas de configuração do supervisor e limpeza de serviço legado porque um supervisor externo é proprietário desse ciclo de vida.
- No Linux, o doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd correspondente do gateway está ativa. Ele também ignora unidades extras inativas semelhantes a gateway que não sejam legadas durante a verificação 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 puro 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 incorporavam inline e reescreve os metadados do serviço para que esses valores sejam carregados da fonte de tempo de execução em vez da definição do supervisor.
- O doctor detecta quando o comando do serviço ainda fixa uma `--port` antiga depois que `gateway.port` muda 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 tanto `gateway.auth.token` quanto `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 systemd de usuário no Linux, as verificações de desvio de token do doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
- Reparos de serviço do doctor se recusam a reescrever, parar ou reiniciar um serviço de gateway de um binário OpenClaw mais antigo quando a configuração foi gravada por último 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óstico 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 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. Práticas recomendadas de runtime do Gateway">
O Doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho de 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 sua inicialização de shell. O Doctor oferece migração para uma instalação de 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 roda no Bun ou em um caminho de Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf`, etc.). 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 Node do sistema quando disponível (Homebrew/apt/choco).
Serviços recém-instalados ou reparados 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 inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco. Isso mantém o PATH gerado do supervisor alinhado à mesma auditoria de PATH mínimo que o doctor executa depois.
Serviços recém-instalados ou reparados 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. Isso mantém o PATH do supervisor gerado alinhado com a mesma auditoria de PATH mínimo que o doctor executa depois.
</Accordion>
<Accordion title="18. Gravação de configuração + metadados do assistente">
O Doctor persiste quaisquer alterações de configuração e marca metadados do assistente para registrar a execução do doctor.
O doctor persiste quaisquer alterações de configuração e registra metadados do assistente para gravar 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 de 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 (recomendado GitHub ou GitLab privado).
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre estrutura de workspace e backup com git (GitHub ou GitLab privado recomendado).
</Accordion>
</AccordionGroup>

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

@ -1,32 +1,32 @@
---
read_when:
- Alterando a saída ou os formatos de log
- Alteração da saída ou dos formatos de log
- Depuração da saída da CLI ou do Gateway
summary: Superfícies de registro, registros em arquivo, estilos de registro WS e formatação do console
title: Registro em log do Gateway
summary: Superfícies de log, logs de arquivo, estilos de log WS e formatação do console
title: Logs do Gateway
x-i18n:
generated_at: "2026-04-30T09:49:42Z"
generated_at: "2026-05-01T05:56:44Z"
model: gpt-5.5
provider: openai
source_hash: 9ce9c78201d2e26760282b08eacb17826b1eac84e80b99d3a9d5cbff4078b5b3
source_hash: f843812a41c25f9ca1884543ad3a5663c8e0bc327027cbd2b58ea6557c466aa9
source_path: gateway/logging.md
workflow: 16
---
# Registro em Log
# Logs
Para uma visão geral voltada ao usuário (CLI + Interface de Controle + config), consulte [/logging](/pt-BR/logging).
Para uma visão geral voltada ao usuário (CLI + UI de Controle + configuração), consulte [/logging](/pt-BR/logging).
O OpenClaw tem duas “superfícies” de log:
- **Saída do console** (o que você vê no terminal / Interface de Depuração).
- **Logs de arquivo** (linhas JSON) gravados pelo logger do Gateway.
- **Saída do console** (o que você vê no terminal / UI de Depuração).
- **Logs em arquivo** (linhas JSON) gravados pelo logger do Gateway.
## Logger baseado em arquivo
## Logger baseado em arquivos
- 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 são rotacionados em `logging.maxFileBytes` (padrão: 100 MB), mantendo
- Arquivos de log ativos rotacionam 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,24 +34,24 @@ O OpenClaw tem duas “superfícies” de log:
O formato do arquivo é um objeto JSON por linha.
A aba Logs da Interface de Controle acompanha esse arquivo via Gateway (`logs.tail`).
A aba Logs da UI de Controle acompanha esse arquivo via Gateway (`logs.tail`).
A CLI pode fazer o mesmo:
```bash
openclaw logs --follow
```
**Verbose vs. níveis de log**
**Detalhado vs. níveis de log**
- **Logs de arquivo** são controlados exclusivamente por `logging.level`.
- **Logs em 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 de log do arquivo.
- Para capturar detalhes disponíveis apenas em modo verboso nos logs de arquivo, defina `logging.level` como `debug` ou
- Para capturar detalhes que aparecem apenas no modo detalhado nos logs em arquivo, defina `logging.level` como `debug` ou
`trace`.
## Captura do console
A CLI captura `console.log/info/warn/error/debug/trace` e grava isso nos logs de arquivo,
A CLI captura `console.log/info/warn/error/debug/trace` e os grava nos logs em arquivo,
enquanto ainda imprime em stdout/stderr.
Você pode ajustar a verbosidade do console de forma independente via:
@ -62,20 +62,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 aos destinos de texto de console, log de arquivo, registros de log OTLP
e transcrições de sessão, de modo que valores secretos correspondentes sejam
mascarados antes que linhas JSONL ou mensagens sejam gravadas em disco.
processo. Essa política de redação de logs é aplicada a coletores de texto de console, log em arquivo, registros
de log OTLP e transcrições de sessão, para que valores secretos correspondentes sejam
mascarados antes que linhas JSONL ou mensagens sejam gravadas no disco.
- `logging.redactSensitive`: `off` | `tools` (padrão: `tools`)
- `logging.redactPatterns`: array 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 comuns de chaves, flags da CLI, campos JSON, cabeçalhos bearer, blocos PEM e prefixos populares de tokens.
- Use strings regex brutas (auto `gi`) 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 comuns de chaves, 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.
Alguns limites de segurança sempre redigem, independentemente de `logging.redactSensitive`.
Isso inclui eventos de chamada de ferramenta da Interface de Controle, saída da ferramenta `sessions_history`,
exportações de suporte a diagnósticos, observações de erro de provedores, exibição de comando de aprovação de exec
e logs do protocolo WebSocket do Gateway. Essas superfícies ainda podem usar
Alguns limites de segurança sempre fazem 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ósticos, observações de erros de provedores, exibição de comandos
de aprovação de execução 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 emitam segredos brutos.
@ -87,15 +87,15 @@ O Gateway imprime logs do protocolo WebSocket em dois modos:
- erros (`ok=false`)
- chamadas lentas (limite padrão: `>= 50ms`)
- erros de análise
- **Modo verboso (`--verbose`)**: imprime todo o tráfego de requisição/resposta WS.
- **Modo detalhado (`--verbose`)**: imprime todo o tráfego de requisição/resposta WS.
### Estilo de log WS
`openclaw gateway` oferece suporte a uma alternância de estilo por Gateway:
`openclaw gateway` oferece suporte a uma troca de estilo por Gateway:
- `--ws-log auto` (padrão): o modo normal é otimizado; o modo verboso usa saída compacta
- `--ws-log compact`: saída compacta (requisição/resposta pareadas) quando verboso
- `--ws-log full`: saída completa por frame quando verboso
- `--ws-log auto` (padrão): o modo normal é otimizado; o modo detalhado usa saída compacta
- `--ws-log compact`: saída compacta (requisição/resposta pareadas) quando detalhado
- `--ws-log full`: saída completa por quadro quando detalhado
- `--compact`: alias para `--ws-log compact`
Exemplos:
@ -111,27 +111,27 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Formatação do console (log por subsistema)
## Formatação do console (logs de subsistema)
O formatador do console é **ciente de TTY** e imprime linhas consistentes, com prefixos.
O formatador de console é **ciente de TTY** e imprime linhas consistentes com prefixo.
Loggers de subsistema mantêm a saída agrupada e fácil de examinar.
Comportamento:
- **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
- **Prefixos de subsistema** em todas as linhas (por exemplo, `[gateway]`, `[canvas]`, `[tailscale]`)
- **Cores de subsistema** (estáveis por subsistema) mais cores de 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**: remove `gateway/` + `channels/` iniciais, mantém os 2 últimos segmentos (por exemplo, `whatsapp/outbound`)
- **Prefixos de subsistema encurtados**: remove `gateway/` + `channels/` iniciais, mantém os últimos 2 segmentos (por exemplo, `whatsapp/outbound`)
- **Sub-loggers 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 do 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` é definido como `debug`/`trace`)
- **Corpos de mensagens do WhatsApp** são registrados em `debug` (use `--verbose` para vê-los)
Isso mantém os logs de arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar.
Isso mantém os logs em arquivo existentes estáveis enquanto torna a saída interativa fácil de examinar.
## Relacionados
## Relacionado
- [Registro em Log](/pt-BR/logging)
- [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry)
- [Logs](/pt-BR/logging)
- [Exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry)
- [Exportação de diagnósticos](/pt-BR/gateway/diagnostics)

396
docs/pt-BR/gateway/protocol.md
View File

@ -6,17 +6,17 @@ read_when:
summary: 'Protocolo WebSocket do Gateway: negociação inicial, quadros, versionamento'
title: Protocolo do Gateway
x-i18n:
generated_at: "2026-04-30T09:50:51Z"
generated_at: "2026-05-01T05:56:49Z"
model: gpt-5.5
provider: openai
source_hash: c0d922e9b4b778c333873e551498b905461f30f944e809555b45669ae2f5c404
source_hash: a6da9ce755b941789ae6b9e866247c8bebb86e9a1530fb8cb258fb0650b24b8a
source_path: gateway/protocol.md
workflow: 16
---
O protocolo WS do Gateway é o **plano de controle único + transporte de Node** para
OpenClaw. Todos os clientes (CLI, interface web, app macOS, nodes iOS/Android, nodes
headless) se conectam por WebSocket e declaram seu **papel** + **escopo** no
O protocolo WS do Gateway é o **plano de controle único + transporte de nós** para o
OpenClaw. Todos os clientes (CLI, UI web, app macOS, nós iOS/Android, nós
headless) se conectam por WebSocket e declaram sua **role** + **scope** no
momento do handshake.
## Transporte
@ -25,11 +25,11 @@ momento do handshake.
- O primeiro frame **deve** ser uma solicitação `connect`.
- Frames antes da conexão são limitados a 64 KiB. Após um handshake bem-sucedido, os clientes
devem seguir os limites `hello-ok.policy.maxPayload` e
`hello-ok.policy.maxBufferedBytes`. Com diagnósticos ativados,
frames de entrada grandes demais e buffers de saída lentos emitem eventos
`payload.large` antes que o Gateway feche ou descarte o frame afetado. Esses eventos mantêm
`hello-ok.policy.maxBufferedBytes`. Com diagnósticos habilitados,
frames de entrada grandes demais e buffers de saída lentos emitem eventos `payload.large`
antes que o gateway feche ou descarte o frame afetado. Esses eventos mantêm
tamanhos, limites, superfícies e códigos de motivo seguros. Eles não mantêm o corpo da mensagem,
conteúdo de anexos, corpo bruto do frame, tokens, cookies ou valores secretos.
o conteúdo de anexos, o corpo bruto do frame, tokens, cookies nem valores secretos.
## Handshake (connect)
@ -105,14 +105,14 @@ Gateway → Cliente:
```
Enquanto o Gateway ainda está finalizando sidecars de inicialização, a solicitação `connect` pode
retornar um erro `UNAVAILABLE` repetível com `details.reason` definido como
retornar um erro `UNAVAILABLE` retentável com `details.reason` definido como
`"startup-sidecars"` e `retryAfterMs`. Os clientes devem tentar novamente essa resposta
dentro do orçamento geral de conexão em vez de apresentá-la como uma falha terminal
de handshake.
`server`, `features`, `snapshot` e `policy` são todos obrigatórios pelo schema
(`src/gateway/protocol/schema/frames.ts`). `auth` também é obrigatório e informa
o papel/escopos negociados. `canvasHostUrl` é opcional.
a role/scopes negociados. `canvasHostUrl` é opcional.
Quando nenhum token de dispositivo é emitido, `hello-ok.auth` informa as permissões
negociadas sem campos de token:
@ -126,13 +126,13 @@ negociadas sem campos de token:
}
```
Clientes de backend confiáveis no mesmo processo (`client.id: "gateway-client"`,
Clientes backend confiáveis no mesmo processo (`client.id: "gateway-client"`,
`client.mode: "backend"`) podem omitir `device` em conexões diretas de loopback quando
se autenticam com o token/senha compartilhado do Gateway. Esse caminho é reservado
para RPCs internos do plano de controle e impede que baselines obsoletas de pareamento
CLI/dispositivo bloqueiem trabalho de backend local, como atualizações de sessão de subagente. Clientes remotos,
clientes com origem em navegador, clientes node e clientes explícitos de token de dispositivo/identidade de dispositivo
ainda usam as verificações normais de pareamento e aumento de escopo.
se autenticam com o token/senha compartilhado do gateway. Esse caminho é reservado
para RPCs internos do plano de controle e evita que baselines obsoletos de pareamento de CLI/dispositivo
bloqueiem trabalho local de backend, como atualizações de sessão de subagente. Clientes remotos,
clientes com origem em navegador, clientes de nó e clientes explícitos com token de dispositivo/identidade de dispositivo
ainda usam as verificações normais de pareamento e upgrade de scope.
Quando um token de dispositivo é emitido, `hello-ok` também inclui:
@ -146,8 +146,8 @@ Quando um token de dispositivo é emitido, `hello-ok` também inclui:
}
```
Durante o repasse de bootstrap confiável, `hello-ok.auth` também pode incluir entradas
adicionais de papel delimitadas em `deviceTokens`:
Durante a entrega de bootstrap confiável, `hello-ok.auth` também pode incluir entradas
adicionais de role delimitadas em `deviceTokens`:
```json
{
@ -166,14 +166,14 @@ adicionais de papel delimitadas em `deviceTokens`:
}
```
Para o fluxo de bootstrap integrado de node/operador, o token primário de node permanece
`scopes: []` e qualquer token de operador repassado permanece delimitado à allowlist de operador
Para o fluxo de bootstrap integrado de nó/operador, o token de nó principal permanece
`scopes: []` e qualquer token de operador entregue permanece limitado à allowlist de operador
de bootstrap (`operator.approvals`, `operator.read`,
`operator.talk.secrets`, `operator.write`). As verificações de escopo de bootstrap permanecem
prefixadas por papel: entradas de operador só satisfazem solicitações de operador, e papéis
que não sejam operador ainda precisam de escopos sob seu próprio prefixo de papel.
`operator.talk.secrets`, `operator.write`). As verificações de scope de bootstrap permanecem
prefixadas por role: entradas de operador só satisfazem solicitações de operador, e roles
não operadoras ainda precisam de scopes sob seu próprio prefixo de role.
### Exemplo de Node
### Exemplo de nó
```json
{
@ -214,18 +214,18 @@ que não sejam operador ainda precisam de escopos sob seu próprio prefixo de pa
- **Resposta**: `{type:"res", id, ok, payload|error}`
- **Evento**: `{type:"event", event, payload, seq?, stateVersion?}`
Métodos com efeitos colaterais exigem **chaves de idempotência** (veja o schema).
Métodos com efeitos colaterais exigem **chaves de idempotência** (consulte o schema).
## Papéis + escopos
## Roles + scopes
### Papéis
### Roles
- `operator` = cliente do plano de controle (CLI/UI/automação).
- `node` = host de capacidade (camera/screen/canvas/system.run).
### Escopos (operador)
### Scopes (operator)
Escopos comuns:
Scopes comuns:
- `operator.read`
- `operator.write`
@ -237,45 +237,45 @@ Escopos comuns:
`talk.config` com `includeSecrets: true` exige `operator.talk.secrets`
(ou `operator.admin`).
Métodos RPC do Gateway registrados por Plugin podem solicitar seu próprio escopo de operador, mas
prefixos administrativos centrais reservados (`config.*`, `exec.approvals.*`, `wizard.*`,
Métodos RPC do gateway registrados por Plugin podem solicitar seu próprio scope de operador, mas
prefixos de administração core reservados (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) sempre resolvem para `operator.admin`.
O escopo do método é apenas o primeiro filtro. Alguns comandos slash acessados por meio de
`chat.send` aplicam verificações mais estritas em nível de comando por cima. Por exemplo, gravações persistentes
`/config set` e `/config unset` exigem `operator.admin`.
O scope do método é apenas a primeira barreira. Alguns comandos de barra acessados por
`chat.send` aplicam verificações em nível de comando mais rigorosas por cima. Por exemplo, gravações persistentes
de `/config set` e `/config unset` exigem `operator.admin`.
`node.pair.approve` também tem uma verificação extra de escopo no momento da aprovação além do
escopo base do método:
`node.pair.approve` também tem uma verificação extra de scope no momento da aprovação além do
scope base do método:
- solicitações sem comando: `operator.pairing`
- solicitações com comandos de node que não sejam exec: `operator.pairing` + `operator.write`
- solicitações com comandos de nó não exec: `operator.pairing` + `operator.write`
- solicitações que incluem `system.run`, `system.run.prepare` ou `system.which`:
`operator.pairing` + `operator.admin`
### Caps/comandos/permissões (node)
### Caps/commands/permissions (node)
Nodes declaram reivindicações de capacidade no momento da conexão:
Nós declaram reivindicações de capacidade no momento da conexão:
- `caps`: categorias de capacidade de alto nível.
- `commands`: allowlist de comandos para invocação.
- `permissions`: alternâncias granulares (por exemplo, `screen.record`, `camera.capture`).
O Gateway trata isso como **reivindicações** e impõe allowlists do lado do servidor.
O Gateway trata isso como **reivindicações** e aplica allowlists do lado do servidor.
## Presença
- `system-presence` retorna entradas indexadas por identidade de dispositivo.
- Entradas de presença incluem `deviceId`, `roles` e `scopes` para que UIs possam mostrar uma única linha por dispositivo
mesmo quando ele se conecta tanto como **operador** quanto como **node**.
- `node.list` inclui campos opcionais `lastSeenAtMs` e `lastSeenReason`. Nodes conectados informam
o horário atual da conexão como `lastSeenAtMs` com motivo `connect`; nodes pareados também podem informar
presença durável em segundo plano quando um evento confiável de node atualiza seus metadados de pareamento.
mesmo quando ele se conecta tanto como **operator** quanto como **node**.
- `node.list` inclui campos opcionais `lastSeenAtMs` e `lastSeenReason`. Nós conectados informam
o horário da conexão atual como `lastSeenAtMs` com motivo `connect`; nós pareados também podem informar
presença durável em segundo plano quando um evento de nó confiável atualiza seus metadados de pareamento.
### Evento de node vivo em segundo plano
### Evento de nó ativo em segundo plano
Nodes podem chamar `node.event` com `event: "node.presence.alive"` para registrar que um node pareado estava
vivo durante um wake em segundo plano sem marcá-lo como conectado.
Nós podem chamar `node.event` com `event: "node.presence.alive"` para registrar que um nó pareado estava
ativo durante um wake em segundo plano sem marcá-lo como conectado.
```json
{
@ -286,8 +286,8 @@ vivo durante um wake em segundo plano sem marcá-lo como conectado.
`trigger` é um enum fechado: `background`, `silent_push`, `bg_app_refresh`,
`significant_location`, `manual` ou `connect`. Strings de trigger desconhecidas são normalizadas para
`background` pelo Gateway antes da persistência. O evento só é durável para sessões autenticadas de dispositivo
node; sessões sem dispositivo ou não pareadas retornam `handled: false`.
`background` pelo gateway antes da persistência. O evento só é durável para sessões autenticadas de dispositivo
de nó; sessões sem dispositivo ou não pareadas retornam `handled: false`.
Gateways bem-sucedidos retornam um resultado estruturado:
@ -300,47 +300,47 @@ Gateways bem-sucedidos retornam um resultado estruturado:
}
```
Gateways mais antigos ainda podem retornar `{ "ok": true }` para `node.event`; os clientes devem tratar isso como uma
RPC confirmada, não como persistência durável de presença.
Gateways mais antigos ainda podem retornar `{ "ok": true }` para `node.event`; clientes devem tratar isso como um
RPC confirmado, não como persistência durável de presença.
## Escopo de eventos de broadcast
Eventos de broadcast WebSocket enviados pelo servidor são filtrados por escopo para que sessões com escopo de pareamento ou somente node não recebam conteúdo de sessão passivamente.
Eventos de broadcast WebSocket enviados pelo servidor são limitados por scope para que sessões com escopo de pareamento ou apenas de nó não recebam conteúdo de sessão passivamente.
- **Frames de chat, agente e resultado de ferramenta** (incluindo eventos `agent` em streaming e resultados de chamadas de ferramenta) exigem pelo menos `operator.read`. Sessões sem `operator.read` ignoram esses frames completamente.
- **Broadcasts `plugin.*` definidos por Plugin** são filtrados para `operator.write` ou `operator.admin`, dependendo de como o Plugin os registrou.
- **Eventos de status e transporte** (`heartbeat`, `presence`, `tick`, ciclo de vida de conexão/desconexão etc.) permanecem irrestritos para que a integridade do transporte continue observável por toda sessão autenticada.
- **Famílias desconhecidas de eventos de broadcast** são filtradas por escopo por padrão (fail-closed), a menos que um manipulador registrado as relaxe explicitamente.
- **Frames de chat, agente e resultado de ferramenta** (incluindo eventos `agent` transmitidos por streaming e resultados de chamadas de ferramentas) exigem pelo menos `operator.read`. Sessões sem `operator.read` ignoram esses frames inteiramente.
- **Broadcasts `plugin.*` definidos por Plugin** são restritos a `operator.write` ou `operator.admin`, dependendo de como o plugin os registrou.
- **Eventos de status e transporte** (`heartbeat`, `presence`, `tick`, ciclo de vida de conexão/desconexão etc.) permanecem irrestritos para que a saúde do transporte continue observável para toda sessão autenticada.
- **Famílias desconhecidas de eventos de broadcast** são limitadas por scope por padrão (fail-closed), a menos que um handler registrado as relaxe explicitamente.
Cada conexão de cliente mantém seu próprio número de sequência por cliente para que broadcasts preservem ordenação monotônica naquele socket mesmo quando clientes diferentes veem subconjuntos diferentes do fluxo de eventos filtrados por escopo.
Cada conexão de cliente mantém seu próprio número de sequência por cliente para que broadcasts preservem ordenação monotônica nesse socket mesmo quando clientes diferentes veem subconjuntos filtrados por scope diferentes do fluxo de eventos.
## Famílias comuns de métodos RPC
A superfície WS pública é mais ampla do que os exemplos de handshake/auth acima. Esta
não é uma listagem gerada — `hello-ok.features.methods` é uma lista conservadora
de descoberta criada a partir de `src/gateway/server-methods-list.ts` mais exportações de métodos
de plugin/canal carregadas. Trate-a como descoberta de recursos, não como uma
enumeração completa de `src/gateway/server-methods/*.ts`.
A superfície pública WS é mais ampla do que os exemplos de handshake/auth acima. Esta
não é uma listagem gerada — `hello-ok.features.methods` é uma lista de descoberta
conservadora construída a partir de `src/gateway/server-methods-list.ts` mais exports de métodos de
plugin/canal carregados. Trate-a como descoberta de recursos, não como uma enumeração completa
de `src/gateway/server-methods/*.ts`.
<AccordionGroup>
<Accordion title="Sistema e identidade">
- `health` retorna o snapshot de integridade do Gateway em cache ou recém-sondado.
- `diagnostics.stability` retorna o registrador de estabilidade diagnóstica recente e delimitado. Ele mantém metadados operacionais, como nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de fila/sessão, nomes de canal/plugin e ids de sessão. Ele não mantém texto de chat, corpos de webhook, saídas de ferramenta, corpos brutos de solicitação ou resposta, tokens, cookies ou valores secretos. Escopo de leitura de operador é obrigatório.
- `status` retorna o resumo do Gateway no estilo `/status`; campos sensíveis são incluídos apenas para clientes operador com escopo de admin.
- `gateway.identity.get` retorna a identidade de dispositivo do Gateway usada por fluxos de relay e pareamento.
- `system-presence` retorna o snapshot de presença atual para dispositivos operador/node conectados.
- `system-event` acrescenta um evento de sistema e pode atualizar/transmitir contexto de presença.
- `last-heartbeat` retorna o evento Heartbeat persistido mais recente.
- `set-heartbeats` alterna o processamento de Heartbeat no Gateway.
<Accordion title="System and identity">
- `health` retorna o snapshot de saúde do gateway em cache ou recém-sondado.
- `diagnostics.stability` retorna o registrador recente e delimitado de estabilidade diagnóstica. Ele mantém metadados operacionais como nomes de eventos, contagens, tamanhos em bytes, leituras de memória, estado de fila/sessão, nomes de canal/plugin e ids de sessão. Ele não mantém texto de chat, corpos de webhook, saídas de ferramentas, corpos brutos de solicitação ou resposta, tokens, cookies nem valores secretos. Scope de leitura de operador é obrigatório.
- `status` retorna o resumo do gateway no estilo `/status`; campos sensíveis são incluídos somente para clientes operadores com escopo de admin.
- `gateway.identity.get` retorna a identidade de dispositivo do gateway usada por fluxos de relay e pareamento.
- `system-presence` retorna o snapshot de presença atual para dispositivos operadores/nós conectados.
- `system-event` adiciona um evento de sistema e pode atualizar/transmitir contexto de presença.
- `last-heartbeat` retorna o evento de heartbeat persistido mais recente.
- `set-heartbeats` alterna o processamento de heartbeat no gateway.
</Accordion>
<Accordion title="Modelos e uso">
- `models.list` retorna o catálogo de modelos permitido pelo runtime. Passe `{ "view": "configured" }` para modelos configurados em tamanho de seletor (`agents.defaults.models` primeiro, depois `models.providers.*.models`), ou `{ "view": "all" }` para o catálogo completo.
- `usage.status` retorna janelas de uso do provedor/resumos da cota restante.
- `usage.cost` retorna resumos agregados de uso de custos para um intervalo de datas.
- `doctor.memory.status` retorna a prontidão da memória vetorial / embeddings em cache para o workspace ativo do agente padrão. Passe `{ "probe": true }` ou `{ "deep": true }` somente quando o chamador quiser explicitamente um ping ao provedor de embeddings ao vivo.
- `doctor.memory.remHarness` retorna uma prévia limitada e somente leitura do harness REM para clientes remotos do plano de controle. Ela pode incluir caminhos de workspace, trechos de memória, markdown fundamentado renderizado e candidatos a promoção profunda, então os chamadores precisam de `operator.read`.
- `models.list` retorna o catálogo de modelos permitido em runtime. Passe `{ "view": "configured" }` para modelos configurados do tamanho do seletor (`agents.defaults.models` primeiro, depois `models.providers.*.models`), ou `{ "view": "all" }` para o catálogo completo.
- `usage.status` retorna resumos de janelas de uso/quotas restantes do provedor.
- `usage.cost` retorna resumos agregados de uso de custo para um intervalo de datas.
- `doctor.memory.status` retorna a prontidão da memória vetorial / embedding em cache para o workspace ativo do agente padrão. Passe `{ "probe": true }` ou `{ "deep": true }` somente quando o chamador quiser explicitamente um ping ao vivo do provedor de embeddings.
- `doctor.memory.remHarness` retorna uma prévia limitada e somente leitura do harness REM para clientes remotos do plano de controle. Ela pode incluir caminhos de workspace, trechos de memória, markdown fundamentado renderizado e candidatos de promoção profunda, portanto os chamadores precisam de `operator.read`.
- `sessions.usage` retorna resumos de uso por sessão.
- `sessions.usage.timeseries` retorna uso em série temporal para uma sessão.
- `sessions.usage.logs` retorna entradas de log de uso para uma sessão.
@ -348,8 +348,8 @@ enumeração completa de `src/gateway/server-methods/*.ts`.
</Accordion>
<Accordion title="Canais e auxiliares de login">
- `channels.status` retorna resumos de status de canais/Plugins integrados + agrupados.
- `channels.logout` desconecta um canal/conta específico quando o canal oferece suporte a logout.
- `channels.status` retorna resumos de status de canais/plugins integrados + empacotados.
- `channels.logout` encerra a sessão de um canal/conta específico quando o canal oferece suporte a logout.
- `web.login.start` inicia um fluxo de login por QR/web para o provedor de canal web atual compatível com QR.
- `web.login.wait` aguarda a conclusão desse fluxo de login por QR/web e inicia o canal em caso de sucesso.
- `push.test` envia um push APNs de teste para um Node iOS registrado.
@ -359,79 +359,80 @@ enumeração completa de `src/gateway/server-methods/*.ts`.
</Accordion>
<Accordion title="Mensagens e logs">
- `send` é o RPC direto de entrega de saída para envios direcionados por canal/conta/thread fora do executor de chat.
- `logs.tail` retorna o tail do log de arquivo configurado do Gateway com cursor/limite e controles de bytes máximos.
- `send` é o RPC direto de entrega de saída para envios direcionados a canal/conta/thread fora do executor de chat.
- `logs.tail` retorna o tail configurado do log de arquivo do Gateway com controles de cursor/limite e bytes máximos.
</Accordion>
<Accordion title="Talk e TTS">
- `talk.config` retorna o payload efetivo da configuração de Talk; `includeSecrets` requer `operator.talk.secrets` (ou `operator.admin`).
- `talk.config` retorna o payload efetivo de configuração do Talk; `includeSecrets` requer `operator.talk.secrets` (ou `operator.admin`).
- `talk.mode` define/transmite o estado atual do modo Talk para clientes WebChat/Control UI.
- `talk.speak` sintetiza fala por meio do provedor de fala Talk ativo.
- `tts.status` retorna o estado habilitado de TTS, provedor ativo, provedores de fallback e estado de configuração do provedor.
- `tts.status` retorna o estado habilitado do TTS, o provedor ativo, provedores de fallback e o estado da configuração do provedor.
- `tts.providers` retorna o inventário visível de provedores TTS.
- `tts.enable` e `tts.disable` alternam o estado de preferências TTS.
- `tts.enable` e `tts.disable` alternam o estado das preferências de TTS.
- `tts.setProvider` atualiza o provedor TTS preferido.
- `tts.convert` executa uma conversão pontual de texto para fala.
</Accordion>
<Accordion title="Segredos, configuração, atualização e assistente">
- `secrets.reload` resolve novamente SecretRefs ativos e troca o estado de segredos do runtime somente em caso de sucesso completo.
- `secrets.resolve` resolve atribuições de segredos direcionadas a comandos para um conjunto específico de comando/alvo.
- `config.get` retorna o snapshot e hash da configuração atual.
- `secrets.reload` resolve novamente SecretRefs ativos e troca o estado de segredos em runtime somente em caso de sucesso total.
- `secrets.resolve` resolve atribuições de segredos direcionadas a comandos para um conjunto específico de comandos/alvos.
- `config.get` retorna o snapshot e o hash da configuração atual.
- `config.set` grava um payload de configuração validado.
- `config.patch` mescla uma atualização parcial de configuração.
- `config.apply` valida + substitui o payload de configuração completo.
- `config.schema` retorna o payload do esquema de configuração ao vivo usado pela Control UI e pelo ferramental CLI: esquema, `uiHints`, versão e metadados de geração, incluindo metadados de esquema de Plugin + canal quando o runtime consegue carregá-los. O esquema inclui metadados de campo `title` / `description` derivados dos mesmos rótulos e texto de ajuda usados pela UI, incluindo objetos aninhados, curinga, item de array e ramificações de composição `anyOf` / `oneOf` / `allOf` quando existe documentação de campo correspondente.
- `config.schema.lookup` retorna um payload de consulta com escopo de caminho para um caminho de configuração: caminho normalizado, um nó de esquema superficial, dica correspondente + `hintPath` e resumos de filhos imediatos para detalhamento na UI/CLI. Os nós de esquema de consulta mantêm a documentação voltada ao usuário e campos comuns de validação (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, limites numéricos/de string/de array/de objeto e flags como `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Os resumos de filhos expõem `key`, `path` normalizado, `type`, `required`, `hasChildren`, além de `hint` / `hintPath` correspondentes.
- `config.apply` valida + substitui o payload completo de configuração.
- `config.schema` retorna o payload do esquema de configuração ao vivo usado pela Control UI e pelas ferramentas CLI: esquema, `uiHints`, versão e metadados de geração, incluindo metadados de esquema de plugin + canal quando o runtime consegue carregá-los. O esquema inclui metadados de campo `title` / `description` derivados dos mesmos rótulos e texto de ajuda usados pela UI, incluindo ramificações de composição de objeto aninhado, curinga, item de array e `anyOf` / `oneOf` / `allOf` quando existe documentação de campo correspondente.
- `config.schema.lookup` retorna um payload de consulta com escopo de caminho para um caminho de configuração: caminho normalizado, um nó de esquema raso, dica correspondente + `hintPath` e resumos de filhos imediatos para detalhamento em UI/CLI. Nós de esquema de consulta mantêm a documentação voltada ao usuário e campos comuns de validação (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, limites numéricos/de string/de array/de objeto e sinalizadores como `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Resumos de filhos expõem `key`, `path` normalizado, `type`, `required`, `hasChildren`, além de `hint` / `hintPath` correspondentes.
- `update.run` executa o fluxo de atualização do Gateway e agenda uma reinicialização somente quando a própria atualização teve sucesso.
- `update.status` retorna o sentinel de reinicialização de atualização em cache mais recente, incluindo a versão em execução pós-reinicialização quando disponível.
- `update.status` retorna o sentinela de reinicialização da atualização em cache mais recente, incluindo a versão em execução após a reinicialização quando disponível.
- `wizard.start`, `wizard.next`, `wizard.status` e `wizard.cancel` expõem o assistente de onboarding por WS RPC.
</Accordion>
<Accordion title="Auxiliares de agente e workspace">
- `agents.list` retorna entradas de agente configuradas, incluindo modelo efetivo e metadados de runtime.
- `agents.create`, `agents.update` e `agents.delete` gerenciam registros de agente e ligação de workspace.
- `agents.files.list`, `agents.files.get` e `agents.files.set` gerenciam os arquivos de workspace de bootstrap expostos para um agente.
- `agents.create`, `agents.update` e `agents.delete` gerenciam registros de agente e a conexão com o workspace.
- `agents.files.list`, `agents.files.get` e `agents.files.set` gerenciam os arquivos de bootstrap do workspace expostos para um agente.
- `artifacts.list`, `artifacts.get` e `artifacts.download` expõem resumos de artefatos derivados de transcrição e downloads para um escopo explícito de `sessionKey`, `runId` ou `taskId`. Consultas de execução e tarefa resolvem a sessão proprietária no lado do servidor e retornam apenas mídia de transcrição com proveniência correspondente; fontes de URL inseguras ou locais retornam downloads sem suporte em vez de buscar no lado do servidor.
- `agent.identity.get` retorna a identidade efetiva do assistente para um agente ou sessão.
- `agent.wait` aguarda a conclusão de uma execução e retorna o snapshot terminal quando disponível.
</Accordion>
<Accordion title="Controle de sessão">
- `sessions.list` retorna o índice de sessões atual, incluindo metadados `agentRuntime` por linha quando um backend de runtime de agente está configurado.
- `sessions.list` retorna o índice de sessão atual, incluindo metadados `agentRuntime` por linha quando um backend de runtime de agente está configurado.
- `sessions.subscribe` e `sessions.unsubscribe` alternam assinaturas de eventos de alteração de sessão para o cliente WS atual.
- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` alternam assinaturas de eventos de transcrição/mensagem para uma sessão.
- `sessions.preview` retorna prévias limitadas de transcrições para chaves de sessão específicas.
- `sessions.resolve` resolve ou canonicaliza um alvo de sessão.
- `sessions.preview` retorna prévias limitadas de transcrição para chaves de sessão específicas.
- `sessions.resolve` resolve ou canoniza um alvo de sessão.
- `sessions.create` cria uma nova entrada de sessão.
- `sessions.send` envia uma mensagem para uma sessão existente.
- `sessions.steer` é a variante de interrupção e direcionamento para uma sessão ativa.
- `sessions.abort` aborta o trabalho ativo de uma sessão. Um chamador pode passar `key` mais `runId` opcional, ou passar apenas `runId` para execuções ativas que o Gateway consegue resolver para uma sessão.
- `sessions.patch` atualiza metadados/substituições da sessão e informa o modelo canônico resolvido mais o `agentRuntime` efetivo.
- `sessions.steer` é a variante de interromper e direcionar para uma sessão ativa.
- `sessions.abort` aborta o trabalho ativo de uma sessão. Um chamador pode passar `key` mais `runId` opcional, ou passar apenas `runId` para execuções ativas que o Gateway consiga resolver para uma sessão.
- `sessions.patch` atualiza metadados/substituições de sessão e informa o modelo canônico resolvido mais o `agentRuntime` efetivo.
- `sessions.reset`, `sessions.delete` e `sessions.compact` executam manutenção de sessão.
- `sessions.get` retorna a linha de sessão armazenada completa.
- A execução do chat ainda usa `chat.history`, `chat.send`, `chat.abort` e `chat.inject`. `chat.history` é normalizado para exibição em clientes de UI: tags de diretiva inline são removidas do texto visível, payloads XML de chamadas de ferramenta em texto simples (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamada de ferramenta) e tokens de controle de modelo ASCII/largura completa vazados são removidos, linhas de assistente contendo apenas tokens silenciosos, como `NO_REPLY` / `no_reply` exatos, são omitidas, e linhas grandes demais podem ser substituídas por placeholders.
- A execução de chat ainda usa `chat.history`, `chat.send`, `chat.abort` e `chat.inject`. `chat.history` é normalizado para exibição para clientes de UI: tags de diretiva inline são removidas do texto visível, payloads XML de chamada de ferramenta em texto simples (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamada de ferramenta) e tokens de controle de modelo ASCII/largura total vazados são removidos, linhas de assistente compostas apenas por tokens silenciosos, como `NO_REPLY` / `no_reply` exatos, são omitidas, e linhas grandes demais podem ser substituídas por placeholders.
</Accordion>
<Accordion title="Pareamento de dispositivos e tokens de dispositivo">
- `device.pair.list` retorna dispositivos pareados pendentes e aprovados.
- `device.pair.approve`, `device.pair.reject` e `device.pair.remove` gerenciam registros de pareamento de dispositivos.
- `device.token.rotate` rotaciona um token de dispositivo pareado dentro dos limites de sua função aprovada e do escopo do chamador.
- `device.token.revoke` revoga um token de dispositivo pareado dentro dos limites de sua função aprovada e do escopo do chamador.
- `device.token.rotate` rotaciona um token de dispositivo pareado dentro de sua função aprovada e dos limites de escopo do chamador.
- `device.token.revoke` revoga um token de dispositivo pareado dentro de sua função aprovada e dos limites de escopo do chamador.
</Accordion>
<Accordion title="Pareamento, invocação e trabalho pendente de Node">
<Accordion title="Pareamento de Node, invocação e trabalho pendente">
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` e `node.pair.verify` cobrem o pareamento de Node e a verificação de bootstrap.
- `node.list` e `node.describe` retornam o estado de Nodes conhecidos/conectados.
- `node.rename` atualiza o rótulo de um Node pareado.
- `node.invoke` encaminha um comando para um Node conectado.
- `node.invoke.result` retorna o resultado de uma solicitação de invocação.
- `node.event` transporta eventos originados no Node de volta para o Gateway.
- `node.event` leva eventos originados no Node de volta ao Gateway.
- `node.canvas.capability.refresh` atualiza tokens de capacidade de canvas com escopo.
- `node.pending.pull` e `node.pending.ack` são as APIs de fila de Node conectado.
- `node.pending.enqueue` e `node.pending.drain` gerenciam trabalho pendente durável para Nodes offline/desconectados.
@ -439,79 +440,84 @@ enumeração completa de `src/gateway/server-methods/*.ts`.
</Accordion>
<Accordion title="Famílias de aprovação">
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` e `exec.approval.resolve` cobrem solicitações pontuais de aprovação de exec mais consulta/replay de aprovações pendentes.
- `exec.approval.waitDecision` aguarda uma aprovação de exec pendente e retorna a decisão final (ou `null` em caso de timeout).
- `exec.approvals.get` e `exec.approvals.set` gerenciam snapshots de política de aprovação de exec do Gateway.
- `exec.approvals.node.get` e `exec.approvals.node.set` gerenciam a política de aprovação de exec local do Node por meio de comandos de retransmissão do Node.
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` e `plugin.approval.resolve` cobrem fluxos de aprovação definidos por Plugin.
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` e `exec.approval.resolve` cobrem solicitações pontuais de aprovação de execução, além de consulta/replay de aprovações pendentes.
- `exec.approval.waitDecision` aguarda uma aprovação de execução pendente e retorna a decisão final (ou `null` em caso de timeout).
- `exec.approvals.get` e `exec.approvals.set` gerenciam snapshots de política de aprovação de execução do Gateway.
- `exec.approvals.node.get` e `exec.approvals.node.set` gerenciam a política de aprovação de execução local do Node por meio de comandos de relay do Node.
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` e `plugin.approval.resolve` cobrem fluxos de aprovação definidos por plugins.
</Accordion>
<Accordion title="Automação, Skills e ferramentas">
- Automação: `wake` agenda uma injeção de texto de ativação imediata ou no próximo Heartbeat; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` gerenciam trabalho agendado.
- Automação: `wake` agenda uma injeção imediata ou no próximo Heartbeat de texto de ativação; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` gerenciam trabalho agendado.
- Skills e ferramentas: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`.
</Accordion>
</AccordionGroup>
### Famílias de eventos comuns
### Famílias comuns de eventos
- `chat`: atualizações de chat da UI, como `chat.inject`, e outros eventos de chat apenas de transcrição.
- `session.message` e `session.tool`: atualizações de transcrição/fluxo de eventos para uma sessão assinada.
- `sessions.changed`: índice de sessões ou metadados alterados.
- `chat`: atualizações de chat da UI, como `chat.inject` e outros eventos de chat
apenas de transcrição.
- `session.message` e `session.tool`: atualizações de transcrição/stream de eventos para uma
sessão assinada.
- `sessions.changed`: índice de sessão ou metadados alterados.
- `presence`: atualizações de snapshot de presença do sistema.
- `tick`: evento periódico de keepalive / atividade.
- `tick`: evento periódico de keepalive / vivacidade.
- `health`: atualização de snapshot de integridade do Gateway.
- `heartbeat`: atualização do fluxo de eventos de Heartbeat.
- `cron`: evento de alteração de execução/job de cron.
- `heartbeat`: atualização de stream de eventos de Heartbeat.
- `cron`: evento de alteração de execução/job Cron.
- `shutdown`: notificação de desligamento do Gateway.
- `node.pair.requested` / `node.pair.resolved`: ciclo de vida de pareamento de Node.
- `node.invoke.request`: transmissão de solicitação de invocação de Node.
- `device.pair.requested` / `device.pair.resolved`: ciclo de vida de dispositivo pareado.
- `voicewake.changed`: configuração de gatilho de palavra de ativação alterada.
- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de aprovação de exec.
- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de aprovação de Plugin.
- `exec.approval.requested` / `exec.approval.resolved`: ciclo de vida de aprovação
de execução.
- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo de vida de aprovação
de plugin.
### Métodos auxiliares de Node
- Nodes podem chamar `skills.bins` para buscar a lista atual de executáveis de Skill para verificações de permissão automática.
- Nodes podem chamar `skills.bins` para buscar a lista atual de executáveis de Skills
para verificações de permissão automática.
### Métodos auxiliares de operador
- Operadores podem chamar `commands.list` (`operator.read`) para buscar o inventário de comandos em tempo de execução de um agente.
- `agentId` é opcional; omita para ler o workspace padrão do agente.
- `scope` controla qual superfície o `name` primário mira:
- `text` retorna o token primário de comando de texto sem a `/` inicial
- Operadores podem chamar `commands.list` (`operator.read`) para buscar o inventário de comandos de runtime de um agente.
- `agentId` é opcional; omita-o para ler o workspace do agente padrão.
- `scope` controla qual superfície o `name` primário segmenta:
- `text` retorna o token do comando de texto primário sem a `/` inicial
- `native` e o caminho padrão `both` retornam nomes nativos cientes do provedor quando disponíveis
- `textAliases` carrega aliases exatos com barra, como `/model` e `/m`.
- `nativeName` carrega o nome de comando nativo ciente do provedor quando existir.
- `provider` é opcional e afeta apenas a nomenclatura nativa e a disponibilidade de comandos nativos do Plugin.
- `includeArgs=false` omite da resposta os metadados serializados de argumentos.
- Operadores podem chamar `tools.catalog` (`operator.read`) para buscar o catálogo de ferramentas em tempo de execução de um agente. A resposta inclui ferramentas agrupadas e metadados de proveniência:
- `provider` é opcional e afeta apenas a nomenclatura nativa mais a disponibilidade de comandos nativos de Plugin.
- `includeArgs=false` omite os metadados de argumento serializados da resposta.
- Operadores podem chamar `tools.catalog` (`operator.read`) para buscar o catálogo de ferramentas de runtime de um agente. A resposta inclui ferramentas agrupadas e metadados de proveniência:
- `source`: `core` ou `plugin`
- `pluginId`: proprietário do Plugin quando `source="plugin"`
- `pluginId`: proprietário do plugin quando `source="plugin"`
- `optional`: se uma ferramenta de Plugin é opcional
- Operadores podem chamar `tools.effective` (`operator.read`) para buscar o inventário de ferramentas efetivo em tempo de execução de uma sessão.
- Operadores podem chamar `tools.effective` (`operator.read`) para buscar o inventário de ferramentas efetivo em runtime de uma sessão.
- `sessionKey` é obrigatório.
- O gateway deriva o contexto de tempo de execução confiável da sessão no lado do servidor, em vez de aceitar contexto de autenticação ou entrega fornecido pelo chamador.
- A resposta é escopada à sessão e reflete o que a conversa ativa pode usar agora, incluindo ferramentas do núcleo, de Plugins e de canais.
- O gateway deriva o contexto de runtime confiável da sessão no lado do servidor em vez de aceitar autenticação ou contexto de entrega fornecidos pelo chamador.
- A resposta é escopada à sessão e reflete o que a conversa ativa pode usar agora, incluindo ferramentas de core, Plugin e canal.
- Operadores podem chamar `skills.status` (`operator.read`) para buscar o inventário visível de Skills de um agente.
- `agentId` é opcional; omita para ler o workspace padrão do agente.
- `agentId` é opcional; omita-o para ler o workspace do agente padrão.
- A resposta inclui elegibilidade, requisitos ausentes, verificações de configuração e opções de instalação sanitizadas sem expor valores brutos de segredos.
- Operadores podem chamar `skills.search` e `skills.detail` (`operator.read`) para metadados de descoberta do ClawHub.
- Operadores podem chamar `skills.install` (`operator.admin`) em dois modos:
- Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala uma pasta de skill no diretório `skills/` do workspace padrão do agente.
- Modo instalador do Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` executa uma ação `metadata.openclaw.install` declarada no host do Gateway.
- Modo ClawHub: `{ source: "clawhub", slug, version?, force? }` instala uma pasta de skill no diretório `skills/` do workspace do agente padrão.
- Modo instalador do Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` executa uma ação `metadata.openclaw.install` declarada no host do gateway.
- Operadores podem chamar `skills.update` (`operator.admin`) em dois modos:
- O modo ClawHub atualiza um slug rastreado ou todas as instalações rastreadas do ClawHub no workspace padrão do agente.
- O modo de configuração aplica patches a valores de `skills.entries.<skillKey>`, como `enabled`, `apiKey` e `env`.
- O modo ClawHub atualiza um slug rastreado ou todas as instalações ClawHub rastreadas no workspace do agente padrão.
- O modo de configuração corrige valores de `skills.entries.<skillKey>`, como `enabled`, `apiKey` e `env`.
### Visões de `models.list`
### Visualizações de `models.list`
`models.list` aceita um parâmetro opcional `view`:
- Omitido ou `"default"`: comportamento atual em tempo de execução. Se `agents.defaults.models` estiver configurado, a resposta será o catálogo permitido; caso contrário, a resposta será o catálogo completo do Gateway.
- `"configured"`: comportamento dimensionado para seletores. Se `agents.defaults.models` estiver configurado, ele ainda prevalece. Caso contrário, a resposta usa entradas explícitas de `models.providers.*.models`, recorrendo ao catálogo completo apenas quando não existirem linhas de modelo configuradas.
- Omitido ou `"default"`: comportamento atual de runtime. Se `agents.defaults.models` estiver configurado, a resposta será o catálogo permitido; caso contrário, a resposta será o catálogo completo do Gateway.
- `"configured"`: comportamento dimensionado para seletor. Se `agents.defaults.models` estiver configurado, ele ainda prevalece. Caso contrário, a resposta usa entradas explícitas de `models.providers.*.models`, recorrendo ao catálogo completo apenas quando não existirem linhas de modelo configuradas.
- `"all"`: catálogo completo do Gateway, ignorando `agents.defaults.models`. Use isto para diagnósticos e UIs de descoberta, não para seletores normais de modelo.
## Aprovações de exec
@ -519,95 +525,95 @@ enumeração completa de `src/gateway/server-methods/*.ts`.
- Quando uma solicitação de exec precisa de aprovação, o gateway transmite `exec.approval.requested`.
- Clientes operadores resolvem chamando `exec.approval.resolve` (requer o escopo `operator.approvals`).
- Para `host=node`, `exec.approval.request` deve incluir `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadados de sessão canônicos). Solicitações sem `systemRunPlan` são rejeitadas.
- Após a aprovação, chamadas encaminhadas de `node.invoke system.run` reutilizam esse `systemRunPlan` canônico como o contexto autoritativo de comando/cwd/sessão.
- Se um chamador alterar `command`, `rawCommand`, `cwd`, `agentId` ou `sessionKey` entre a preparação e o encaminhamento final aprovado de `system.run`, o gateway rejeita a execução em vez de confiar no payload alterado.
- Após a aprovação, chamadas `node.invoke system.run` encaminhadas reutilizam esse `systemRunPlan` canônico como o contexto autoritativo de comando/cwd/sessão.
- Se um chamador modificar `command`, `rawCommand`, `cwd`, `agentId` ou `sessionKey` entre a preparação e o encaminhamento final aprovado de `system.run`, o gateway rejeitará a execução em vez de confiar no payload modificado.
## Fallback de entrega do agente
- Solicitações `agent` podem incluir `deliver=true` para solicitar entrega de saída.
- `bestEffortDeliver=false` mantém o comportamento estrito: alvos de entrega não resolvidos ou apenas internos retornam `INVALID_REQUEST`.
- `bestEffortDeliver=false` mantém o comportamento estrito: destinos de entrega não resolvidos ou somente internos retornam `INVALID_REQUEST`.
- `bestEffortDeliver=true` permite fallback para execução somente na sessão quando nenhuma rota externa entregável puder ser resolvida (por exemplo, sessões internas/webchat ou configurações multicanal ambíguas).
## Versionamento
- `PROTOCOL_VERSION` fica em `src/gateway/protocol/schema/protocol-schemas.ts`.
- Clientes enviam `minProtocol` + `maxProtocol`; o servidor rejeita incompatibilidades.
- Esquemas + modelos são gerados a partir de definições TypeBox:
- Schemas + modelos são gerados a partir de definições TypeBox:
- `pnpm protocol:gen`
- `pnpm protocol:gen:swift`
- `pnpm protocol:check`
### Constantes do cliente
O cliente de referência em `src/gateway/client.ts` usa estes padrões. Os valores são estáveis no protocolo v3 e são a linha de base esperada para clientes de terceiros.
O cliente de referência em `src/gateway/client.ts` usa estes padrões. Os valores são estáveis no protocolo v3 e são a base esperada para clientes de terceiros.
| Constante | Padrão | Origem |
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| Tempo limite da solicitação (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| Tempo limite de pré-autenticação / desafio de conexão | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env pode aumentar o orçamento pareado de servidor/cliente) |
| Backoff inicial de reconexão | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| Backoff máximo de reconexão | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| Limite de repetição rápida após fechamento por token de dispositivo | `250` ms | `src/gateway/client.ts` |
| Período de cortesia de parada forçada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| Tempo limite padrão de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| Intervalo padrão de tick (antes de `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
| Fechamento por tempo limite de tick | código `4000` quando o silêncio excede `tickIntervalMs * 2` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
| Constante | Padrão | Fonte |
| ----------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| Tempo limite da solicitação (por RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| Tempo limite de pré-autenticação / desafio de conexão | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env podem aumentar o orçamento pareado servidor/cliente) |
| Backoff inicial de reconexão | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| Backoff máximo de reconexão | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| Limite de repetição rápida após fechamento por token de dispositivo | `250` ms | `src/gateway/client.ts` |
| Período de carência de parada forçada antes de `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| Tempo limite padrão de `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| Intervalo padrão de tick (pré `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
| Fechamento por tempo limite de tick | código `4000` quando o silêncio excede `tickIntervalMs * 2` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
O servidor anuncia os valores efetivos de `policy.tickIntervalMs`, `policy.maxPayload` e `policy.maxBufferedBytes` em `hello-ok`; clientes devem respeitar esses valores em vez dos padrões anteriores ao handshake.
O servidor anuncia os valores efetivos de `policy.tickIntervalMs`, `policy.maxPayload` e `policy.maxBufferedBytes` em `hello-ok`; os clientes devem respeitar esses valores em vez dos padrões pré-handshake.
## Autenticação
- A autenticação do gateway por segredo compartilhado usa `connect.params.auth.token` ou `connect.params.auth.password`, dependendo do modo de autenticação configurado.
- Modos que carregam identidade, como Tailscale Serve (`gateway.auth.allowTailscale: true`) ou `gateway.auth.mode: "trusted-proxy"` fora de loopback, satisfazem a verificação de autenticação de conexão a partir de cabeçalhos da solicitação em vez de `connect.params.auth.*`.
- `gateway.auth.mode: "none"` em ingresso privado ignora totalmente a autenticação de conexão por segredo compartilhado; não exponha esse modo em ingresso público/não confiável.
- Modos que carregam identidade, como Tailscale Serve (`gateway.auth.allowTailscale: true`) ou `gateway.auth.mode: "trusted-proxy"` sem loopback, satisfazem a verificação de autenticação de conexão a partir de cabeçalhos de solicitação em vez de `connect.params.auth.*`.
- `gateway.auth.mode: "none"` em ingresso privado ignora totalmente a autenticação de conexão por segredo compartilhado; não exponha esse modo em ingressos públicos/não confiáveis.
- Após o pareamento, o Gateway emite um **token de dispositivo** escopado à função + escopos da conexão. Ele é retornado em `hello-ok.auth.deviceToken` e deve ser persistido pelo cliente para conexões futuras.
- Clientes devem persistir o `hello-ok.auth.deviceToken` primário após qualquer conexão bem-sucedida.
- Reconectar com esse token de dispositivo **armazenado** também deve reutilizar o conjunto de escopos aprovados armazenado para esse token. Isso preserva o acesso de leitura/sondagem/status que já foi concedido e evita reduzir silenciosamente as reconexões a um escopo implícito mais estreito, apenas de administrador.
- Montagem da autenticação de conexão no lado do cliente (`selectConnectAuth` em `src/gateway/client.ts`):
- Os clientes devem persistir o `hello-ok.auth.deviceToken` primário após qualquer conexão bem-sucedida.
- Reconectar com esse token de dispositivo **armazenado** também deve reutilizar o conjunto de escopos aprovados armazenado para esse token. Isso preserva o acesso de leitura/sondagem/status que já foi concedido e evita reduzir silenciosamente as reconexões a um escopo implícito mais estreito somente de admin.
- Montagem de autenticação de conexão no lado do cliente (`selectConnectAuth` em `src/gateway/client.ts`):
- `auth.password` é ortogonal e sempre é encaminhado quando definido.
- `auth.token` é preenchido em ordem de prioridade: primeiro o token compartilhado explícito, depois um `deviceToken` explícito, depois um token por dispositivo armazenado (indexado por `deviceId` + `role`).
- `auth.bootstrapToken` é enviado somente quando nenhum dos itens acima resolveu um `auth.token`. Um token compartilhado ou qualquer token de dispositivo resolvido o suprime.
- A promoção automática de um token de dispositivo armazenado na repetição única de `AUTH_TOKEN_MISMATCH` é restrita a **endpoints confiáveis** — loopback, ou `wss://` com `tlsFingerprint` fixado. `wss://` público sem fixação não se qualifica.
- Entradas adicionais de `hello-ok.auth.deviceTokens` são tokens de repasse de bootstrap. Persista-os somente quando a conexão usou autenticação de bootstrap em um transporte confiável, como `wss://` ou pareamento loopback/local.
- Se um cliente fornece um `deviceToken` **explícito** ou `scopes` explícitos, esse conjunto de escopos solicitado pelo chamador permanece autoritativo; escopos em cache são reutilizados somente quando o cliente está reutilizando o token por dispositivo armazenado.
- `auth.token` é preenchido por ordem de prioridade: primeiro token compartilhado explícito, depois um `deviceToken` explícito, depois um token por dispositivo armazenado (indexado por `deviceId` + `role`).
- `auth.bootstrapToken` é enviado apenas quando nenhum dos itens acima resolveu um `auth.token`. Um token compartilhado ou qualquer token de dispositivo resolvido o suprime.
- A promoção automática de um token de dispositivo armazenado na nova tentativa única de `AUTH_TOKEN_MISMATCH` é limitada a **endpoints confiáveis** — loopback ou `wss://` com um `tlsFingerprint` fixado. `wss://` público sem fixação não se qualifica.
- Entradas adicionais de `hello-ok.auth.deviceTokens` são tokens de transferência de bootstrap. Persista-os apenas quando a conexão usou autenticação de bootstrap em um transporte confiável, como `wss://` ou pareamento por loopback/local.
- Se um cliente fornece um `deviceToken` **explícito** ou `scopes` explícitos, esse conjunto de escopos solicitado pelo chamador permanece autoritativo; escopos em cache só são reutilizados quando o cliente está reutilizando o token por dispositivo armazenado.
- Tokens de dispositivo podem ser rotacionados/revogados via `device.token.rotate` e `device.token.revoke` (requer o escopo `operator.pairing`).
- `device.token.rotate` retorna metadados de rotação. Ele ecoa o token bearer substituto somente para chamadas do mesmo dispositivo que já estão autenticadas com esse token de dispositivo, para que clientes somente com token possam persistir a substituição antes de reconectar. Rotações compartilhadas/de administrador não ecoam o token bearer.
- Emissão, rotação e revogação de tokens permanecem limitadas ao conjunto de funções aprovado registrado na entrada de pareamento desse dispositivo; a mutação de token não pode expandir nem mirar uma função de dispositivo que a aprovação de pareamento nunca concedeu.
- Para sessões de token de dispositivo pareado, o gerenciamento de dispositivos é autoescopado, a menos que o chamador também tenha `operator.admin`: chamadores não administradores podem remover/revogar/rotacionar somente a entrada de seu **próprio** dispositivo.
- `device.token.rotate` e `device.token.revoke` também verificam o conjunto de escopos do token de operador alvo em relação aos escopos da sessão atual do chamador. Chamadores não administradores não podem rotacionar nem revogar um token de operador mais amplo do que o que já possuem.
- `device.token.rotate` retorna metadados de rotação. Ele ecoa o token bearer substituto apenas para chamadas do mesmo dispositivo que já estejam autenticadas com esse token de dispositivo, para que clientes somente com token possam persistir a substituição antes de reconectar. Rotações compartilhadas/admin não ecoam o token bearer.
- Emissão, rotação e revogação de tokens permanecem limitadas ao conjunto de funções aprovado registrado na entrada de pareamento desse dispositivo; mutação de token não pode expandir nem segmentar uma função de dispositivo que a aprovação de pareamento nunca concedeu.
- Para sessões de token de dispositivo pareado, o gerenciamento de dispositivos é autoescopado, a menos que o chamador também tenha `operator.admin`: chamadores não admin podem remover/revogar/rotacionar apenas sua **própria** entrada de dispositivo.
- `device.token.rotate` e `device.token.revoke` também verificam o conjunto de escopos do token de operador alvo em relação aos escopos da sessão atual do chamador. Chamadores não admin não podem rotacionar nem revogar um token de operador mais amplo do que já possuem.
- Falhas de autenticação incluem `error.details.code` mais dicas de recuperação:
- `error.details.canRetryWithDeviceToken` (booleano)
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
- Comportamento do cliente para `AUTH_TOKEN_MISMATCH`:
- Clientes confiáveis podem tentar uma repetição limitada com um token por dispositivo em cache.
- Se essa repetição falhar, clientes devem parar loops automáticos de reconexão e expor orientação de ação ao operador.
- Clientes confiáveis podem tentar uma nova tentativa limitada com um token por dispositivo em cache.
- Se essa nova tentativa falhar, os clientes devem interromper loops de reconexão automática e expor orientação de ação ao operador.
## Identidade do dispositivo + pareamento
- Nodes devem incluir uma identidade de dispositivo estável (`device.id`) derivada de uma
impressão digital de par de chaves.
- Gateways emitem tokens por dispositivo + função.
- Aprovações de pareamento são obrigatórias para novos IDs de dispositivo, a menos que a aprovação automática local
- Aprovações de emparelhamento são exigidas para novos IDs de dispositivo, a menos que a aprovação automática local
esteja habilitada.
- A aprovação automática de pareamento é centrada em conexões diretas via local loopback.
- OpenClaw também tem um caminho restrito de autoconexão local ao backend/contêiner para
- A aprovação automática de emparelhamento é centrada em conexões diretas por local loopback.
- O OpenClaw também tem um caminho estreito de autoconexão local ao backend/contêiner para
fluxos auxiliares confiáveis com segredo compartilhado.
- Conexões tailnet ou LAN no mesmo host ainda são tratadas como remotas para pareamento e
- Conexões no mesmo host via tailnet ou LAN ainda são tratadas como remotas para emparelhamento e
exigem aprovação.
- Clientes WS normalmente incluem a identidade `device` durante `connect` (operador +
node). As únicas exceções de operador sem dispositivo são caminhos explícitos de confiança:
- `gateway.controlUi.allowInsecureAuth=true` para compatibilidade com HTTP inseguro apenas em localhost.
- autenticação bem-sucedida da UI de Controle do operador com `gateway.auth.mode: "trusted-proxy"`.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (quebra-emergencial, rebaixamento severo de segurança).
- RPCs de backend `gateway-client` via loopback direto autenticados com o token/senha
compartilhado do Gateway.
node). As únicas exceções de operador sem dispositivo são caminhos de confiança explícitos:
- `gateway.controlUi.allowInsecureAuth=true` para compatibilidade HTTP insegura somente em localhost.
- autenticação bem-sucedida da Control UI do operador com `gateway.auth.mode: "trusted-proxy"`.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, rebaixamento grave de segurança).
- RPCs de backend `gateway-client` por loopback direto autenticados com o token/senha compartilhado
do Gateway.
- Todas as conexões devem assinar o nonce `connect.challenge` fornecido pelo servidor.
### Diagnósticos de migração de autenticação de dispositivo
Para clientes legados que ainda usam o comportamento de assinatura anterior ao desafio, `connect` agora retorna
Para clientes legados que ainda usam o comportamento de assinatura anterior ao challenge, `connect` agora retorna
códigos de detalhe `DEVICE_AUTH_*` em `error.details.code` com um `error.details.reason` estável.
Falhas comuns de migração:
@ -616,32 +622,32 @@ Falhas comuns de migração:
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | O cliente omitiu `device.nonce` (ou enviou em branco). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | O cliente assinou com um nonce obsoleto/incorreto. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | O payload de assinatura não corresponde ao payload v2. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | A carga útil da assinatura não corresponde à carga útil v2. |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | O timestamp assinado está fora da tolerância permitida. |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` não corresponde à impressão digital da chave pública. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | O formato/canonicalização da chave pública falhou. |
Destino da migração:
Alvo de migração:
- Sempre aguarde `connect.challenge`.
- Assine o payload v2 que inclui o nonce do servidor.
- Assine a carga útil v2 que inclui o nonce do servidor.
- Envie o mesmo nonce em `connect.params.device.nonce`.
- O payload de assinatura preferido é `v3`, que vincula `platform` e `deviceFamily`
- A carga útil de assinatura preferida é `v3`, que vincula `platform` e `deviceFamily`
além dos campos de dispositivo/cliente/função/escopos/token/nonce.
- Assinaturas legadas `v2` continuam sendo aceitas por compatibilidade, mas a fixação
de metadados de dispositivos pareados ainda controla a política de comandos na reconexão.
- Assinaturas legadas `v2` continuam aceitas por compatibilidade, mas a fixação de metadados
do dispositivo emparelhado ainda controla a política de comandos na reconexão.
## TLS + fixação
- TLS é compatível com conexões WS.
- Clientes podem opcionalmente fixar a impressão digital do certificado do Gateway (consulte a configuração
`gateway.tls` mais `gateway.remote.tlsFingerprint` ou a CLI `--tls-fingerprint`).
- Clientes podem opcionalmente fixar a impressão digital do certificado do gateway (veja a configuração `gateway.tls`
mais `gateway.remote.tlsFingerprint` ou a CLI `--tls-fingerprint`).
## Escopo
Este protocolo expõe a **API completa do Gateway** (status, canais, modelos, chat,
Este protocolo expõe a **API completa do gateway** (status, canais, modelos, chat,
agente, sessões, nodes, aprovações etc.). A superfície exata é definida pelos
esquemas TypeBox em `src/gateway/protocol/schema.ts`.
schemas TypeBox em `src/gateway/protocol/schema.ts`.
## Relacionados

292
docs/pt-BR/gateway/troubleshooting.md
View File

@ -1,22 +1,22 @@
---
read_when:
- A central de solução de problemas direcionou você para cá para um diagnóstico mais aprofundado
- Você precisa de seções estáveis de runbook baseadas em sintomas com comandos exatos
- Você precisa de seções estáveis de manual de procedimentos baseadas em sintomas com comandos exatos
sidebarTitle: Troubleshooting
summary: Runbook aprofundado de solução de problemas para Gateway, canais, automação, nós e navegador
summary: Manual operacional aprofundado de solução de problemas para Gateway, canais, automação, nós e navegador
title: Solução de problemas
x-i18n:
generated_at: "2026-04-30T09:51:51Z"
generated_at: "2026-05-01T05:57:00Z"
model: gpt-5.5
provider: openai
source_hash: 48735a68daa92678867a9cafb3ceeb37063bb91dee8c4c94e185f74eb0296fcb
source_hash: a808dcfd8527b041f629cff24308550f961e9eeb4d7d4ce6f1ce84dff6bbef89
source_path: gateway/troubleshooting.md
workflow: 16
---
Esta página é o runbook detalhado. Comece em [/help/troubleshooting](/pt-BR/help/troubleshooting) se quiser primeiro o fluxo rápido de triagem.
Esta página é o guia operacional detalhado. Comece em [/help/troubleshooting](/pt-BR/help/troubleshooting) se quiser primeiro o fluxo rápido de triagem.
## Escada de comandos
## Sequência de comandos
Execute estes primeiro, nesta ordem:
@ -28,17 +28,17 @@ openclaw doctor
openclaw channels status --probe
```
Sinais esperados de integridade:
Sinais esperados de funcionamento saudável:
- `openclaw gateway status` mostra `Runtime: running`, `Connectivity probe: ok` e uma linha `Capability: ...`.
- `openclaw doctor` não relata problemas bloqueadores de configuração/serviço.
- `openclaw channels status --probe` mostra o status de transporte ao vivo por conta e, quando houver suporte, resultados de sondagem/auditoria como `works` ou `audit ok`.
- `openclaw doctor` não relata problemas bloqueantes de configuração/serviço.
- `openclaw channels status --probe` mostra o status de transporte ao vivo por conta e, quando compatível, resultados de sondagem/auditoria como `works` ou `audit ok`.
## Instalações split brain e proteção contra configuração mais recente
## Instalações divergentes e proteção contra configuração mais nova
Use isto quando um serviço de Gateway parar inesperadamente após uma atualização, ou quando os logs mostrarem que um binário `openclaw` é mais antigo que a versão que gravou `openclaw.json` pela última vez.
Use isto quando um serviço Gateway parar inesperadamente após uma atualização, ou quando os logs mostrarem que um binário `openclaw` é mais antigo que a versão que gravou `openclaw.json` pela última vez.
O OpenClaw carimba gravações de configuração com `meta.lastTouchedVersion`. Comandos somente leitura ainda podem inspecionar uma configuração gravada por um OpenClaw mais recente, mas mutações de processo e serviço se recusam a continuar a partir de um binário mais antigo. Ações bloqueadas incluem iniciar, parar, reiniciar, desinstalar o serviço de Gateway, reinstalação forçada do serviço, inicialização do Gateway em modo de serviço e limpeza de porta com `gateway --force`.
O OpenClaw marca gravações de configuração com `meta.lastTouchedVersion`. Comandos somente leitura ainda conseguem inspecionar uma configuração gravada por um OpenClaw mais novo, mas alterações de processo e serviço se recusam a continuar a partir de um binário mais antigo. Ações bloqueadas incluem iniciar, parar, reiniciar e desinstalar o serviço Gateway, reinstalação forçada do serviço, inicialização do Gateway em modo de serviço e limpeza de porta com `gateway --force`.
```bash
which openclaw
@ -48,11 +48,11 @@ openclaw config get meta.lastTouchedVersion
```
<Steps>
<Step title="Corrigir PATH">
Corrija `PATH` para que `openclaw` resolva para a instalação mais recente e então execute novamente a ação.
<Step title="Fix PATH">
Corrija `PATH` para que `openclaw` resolva para a instalação mais nova e então execute a ação novamente.
</Step>
<Step title="Reinstalar o serviço de Gateway">
Reinstale o serviço de Gateway pretendido a partir da instalação mais recente:
<Step title="Reinstall the gateway service">
Reinstale o serviço Gateway pretendido a partir da instalação mais nova:
```bash
openclaw gateway install --force
@ -60,16 +60,16 @@ openclaw config get meta.lastTouchedVersion
```
</Step>
<Step title="Remover wrappers obsoletos">
<Step title="Remove stale wrappers">
Remova entradas obsoletas de pacote do sistema ou wrappers antigos que ainda apontam para um binário `openclaw` antigo.
</Step>
</Steps>
<Warning>
Somente para downgrade intencional ou recuperação de emergência, defina `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` para o comando único. Deixe indefinido para operação normal.
Somente para downgrade intencional ou recuperação emergencial, defina `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` para o comando único. Deixe sem definir para operação normal.
</Warning>
## Uso extra da Anthropic 429 exigido para contexto longo
## Uso extra da Anthropic necessário para contexto longo
Use isto quando logs/erros incluírem: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
@ -82,20 +82,20 @@ openclaw config get agents.defaults.models
Procure por:
- O modelo Anthropic Opus/Sonnet selecionado tem `params.context1m: true`.
- A credencial Anthropic atual não é elegível para uso com contexto longo.
- A credencial Anthropic atual não é elegível para uso de contexto longo.
- As solicitações falham apenas em sessões longas/execuções de modelo que precisam do caminho beta de 1M.
Opções de correção:
<Steps>
<Step title="Desabilitar context1m">
Desabilite `context1m` para esse modelo para voltar à janela de contexto normal.
<Step title="Disable context1m">
Desative `context1m` para esse modelo para voltar à janela de contexto normal.
</Step>
<Step title="Usar uma credencial elegível">
Use uma credencial Anthropic elegível para solicitações de contexto longo ou mude para uma chave de API da Anthropic.
<Step title="Use an eligible credential">
Use uma credencial Anthropic elegível para solicitações de contexto longo ou troque para uma chave de API Anthropic.
</Step>
<Step title="Configurar modelos de fallback">
Configure modelos de fallback para que as execuções continuem quando solicitações de contexto longo da Anthropic forem rejeitadas.
<Step title="Configure fallback models">
Configure modelos de fallback para que as execuções continuem quando solicitações Anthropic de contexto longo forem rejeitadas.
</Step>
</Steps>
@ -105,7 +105,7 @@ Relacionado:
- [Uso de tokens e custos](/pt-BR/reference/token-use)
- [Por que estou vendo HTTP 429 da Anthropic?](/pt-BR/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
## Backend local compatível com OpenAI passa em sondagens diretas, mas execuções de agente falham
## Backend local compatível com OpenAI passa em sondagens diretas, mas execuções de agentes falham
Use isto quando:
@ -124,26 +124,27 @@ openclaw logs --follow
Procure por:
- chamadas diretas pequenas têm sucesso, mas execuções do OpenClaw falham apenas em prompts maiores
- erros `model_not_found` ou 404 mesmo que `/v1/chat/completions` direto funcione com o mesmo ID de modelo simples
- erros de backend sobre `messages[].content` esperar uma string
- chamadas diretas pequenas são bem-sucedidas, mas execuções do OpenClaw falham apenas em prompts maiores
- erros `model_not_found` ou 404, embora `/v1/chat/completions` direto
funcione com o mesmo ID de modelo simples
- erros do backend sobre `messages[].content` esperar uma string
- avisos intermitentes `incomplete turn detected ... stopReason=stop payloads=0` com um backend local compatível com OpenAI
- falhas de backend que aparecem apenas com contagens maiores de tokens de prompt ou prompts completos do runtime de agente
- falhas do backend que aparecem apenas com contagens maiores de tokens de prompt ou prompts completos de runtime de agente
<AccordionGroup>
<Accordion title="Assinaturas comuns">
- `model_not_found` com um servidor local no estilo MLX/vLLM → verifique se `baseUrl` inclui `/v1`, se `api` é `"openai-completions"` para backends `/v1/chat/completions` e se `models.providers.<provider>.models[].id` é o ID local simples do provedor. Selecione-o com o prefixo do provedor uma vez, por exemplo `mlx/mlx-community/Qwen3-30B-A3B-6bit`; mantenha a entrada do catálogo como `mlx-community/Qwen3-30B-A3B-6bit`.
- `messages[...].content: invalid type: sequence, expected a string` → o backend rejeita partes de conteúdo estruturado do Chat Completions. Correção: defina `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- `incomplete turn detected ... stopReason=stop payloads=0` → o backend concluiu a solicitação de Chat Completions, mas não retornou texto visível de assistente para esse turno. O OpenClaw tenta novamente uma vez turnos vazios compatíveis com OpenAI que são seguros para reprodução; falhas persistentes geralmente significam que o backend está emitindo conteúdo vazio/não textual ou suprimindo o texto da resposta final.
- solicitações diretas pequenas têm sucesso, mas execuções de agente do OpenClaw falham com travamentos de backend/modelo (por exemplo, Gemma em algumas builds de `inferrs`) → o transporte do OpenClaw provavelmente já está correto; o backend está falhando no formato maior de prompt do runtime de agente.
- falhas diminuem depois de desabilitar ferramentas, mas não desaparecem → os esquemas de ferramenta eram parte da pressão, mas o problema restante ainda é capacidade upstream do modelo/servidor ou um bug de backend.
<Accordion title="Common signatures">
- `model_not_found` com um servidor local estilo MLX/vLLM → verifique se `baseUrl` inclui `/v1`, se `api` é `"openai-completions"` para backends `/v1/chat/completions` e se `models.providers.<provider>.models[].id` é o ID local simples do provedor. Selecione-o com o prefixo do provedor uma vez, por exemplo `mlx/mlx-community/Qwen3-30B-A3B-6bit`; mantenha a entrada do catálogo como `mlx-community/Qwen3-30B-A3B-6bit`.
- `messages[...].content: invalid type: sequence, expected a string` → o backend rejeita partes de conteúdo estruturado de Chat Completions. Correção: defina `models.providers.<provider>.models[].compat.requiresStringContent: true`.
- `incomplete turn detected ... stopReason=stop payloads=0` → o backend concluiu a solicitação Chat Completions, mas não retornou texto de assistente visível ao usuário para esse turno. O OpenClaw tenta novamente, uma vez, turnos vazios compatíveis com OpenAI que são seguros para replay; falhas persistentes normalmente significam que o backend está emitindo conteúdo vazio/não textual ou suprimindo o texto da resposta final.
- solicitações diretas pequenas são bem-sucedidas, mas execuções de agente do OpenClaw falham com travamentos do backend/modelo (por exemplo, Gemma em algumas compilações `inferrs`) → o transporte do OpenClaw provavelmente já está correto; o backend está falhando no formato maior de prompt do runtime de agente.
- as falhas diminuem após desativar ferramentas, mas não desaparecem → schemas de ferramentas faziam parte da pressão, mas o problema restante ainda é capacidade do modelo/servidor upstream ou um bug do backend.
</Accordion>
<Accordion title="Opções de correção">
1. Defina `compat.requiresStringContent: true` para backends de Chat Completions que aceitam apenas strings.
2. Defina `compat.supportsTools: false` para modelos/backends que não conseguem lidar de forma confiável com a superfície de esquemas de ferramenta do OpenClaw.
3. Reduza a pressão de prompt onde possível: bootstrap de workspace menor, histórico de sessão mais curto, modelo local mais leve ou um backend com suporte mais forte a contexto longo.
4. Se solicitações diretas pequenas continuarem passando enquanto turnos de agente do OpenClaw ainda travarem dentro do backend, trate isso como uma limitação upstream do servidor/modelo e registre uma reprodução lá com o formato de payload aceito.
<Accordion title="Fix options">
1. Defina `compat.requiresStringContent: true` para backends Chat Completions que aceitam apenas string.
2. Defina `compat.supportsTools: false` para modelos/backends que não conseguem lidar de forma confiável com a superfície de schema de ferramentas do OpenClaw.
3. Reduza a pressão de prompt quando possível: bootstrap menor do workspace, histórico de sessão mais curto, modelo local mais leve ou um backend com suporte mais forte a contexto longo.
4. Se solicitações diretas pequenas continuarem passando enquanto turnos de agente do OpenClaw ainda travam dentro do backend, trate como uma limitação upstream do servidor/modelo e registre uma reprodução lá com o formato de payload aceito.
</Accordion>
</AccordionGroup>
@ -168,13 +169,13 @@ openclaw logs --follow
Procure por:
- Pareamento pendente para remetentes de DM.
- Controle de menção em grupo (`requireMention`, `mentionPatterns`).
- Incompatibilidades de allowlist de canal/grupo.
- Bloqueio de menção em grupos (`requireMention`, `mentionPatterns`).
- Incompatibilidades de lista de permissões de canal/grupo.
Assinaturas comuns:
- `drop guild message (mention required` → mensagem de grupo ignorada até haver menção.
- `pairing request` → remetente precisa de aprovação.
- `drop guild message (mention required` → mensagem de grupo ignorada até uma menção.
- `pairing request` → o remetente precisa de aprovação.
- `blocked` / `allowlist` → remetente/canal foi filtrado pela política.
Relacionado:
@ -183,9 +184,9 @@ Relacionado:
- [Grupos](/pt-BR/channels/groups)
- [Pareamento](/pt-BR/channels/pairing)
## Conectividade da IU de controle do painel
## Conectividade da interface de controle do painel
Quando a IU de painel/controle não conectar, valide URL, modo de autenticação e pressupostos de contexto seguro.
Quando a interface de controle/painel não conectar, valide a URL, o modo de autenticação e as suposições de contexto seguro.
```bash
openclaw gateway status
@ -199,41 +200,41 @@ Procure por:
- URL de sondagem e URL do painel corretas.
- Incompatibilidade de modo/token de autenticação entre cliente e Gateway.
- Uso de HTTP onde identidade do dispositivo é exigida.
- Uso de HTTP quando a identidade do dispositivo é necessária.
<AccordionGroup>
<Accordion title="Assinaturas de conexão/autenticação">
<Accordion title="Connect / auth signatures">
- `device identity required` → contexto não seguro ou autenticação de dispositivo ausente.
- `origin not allowed` → o `Origin` do navegador não está em `gateway.controlUi.allowedOrigins` (ou você está conectando a partir de uma origem de navegador que não é loopback sem uma allowlist explícita).
- `origin not allowed` → o `Origin` do navegador não está em `gateway.controlUi.allowedOrigins` (ou você está conectando a partir de uma origem de navegador que não é loopback sem uma lista de permissões explícita).
- `device nonce required` / `device nonce mismatch` → o cliente não está concluindo o fluxo de autenticação de dispositivo baseado em desafio (`connect.challenge` + `device.nonce`).
- `device signature invalid` / `device signature expired` → o cliente assinou o payload errado (ou um timestamp obsoleto) para o handshake atual.
- `device signature invalid` / `device signature expired` → o cliente assinou o payload errado (ou timestamp obsoleto) para o handshake atual.
- `AUTH_TOKEN_MISMATCH` com `canRetryWithDeviceToken=true` → o cliente pode fazer uma nova tentativa confiável com token de dispositivo em cache.
- Essa nova tentativa com token em cache reutiliza o conjunto de escopos em cache armazenado com o token de dispositivo pareado. Chamadores explícitos de `deviceToken` / `scopes` explícitos mantêm o conjunto de escopos solicitado.
- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é primeiro token/senha compartilhado explícito, depois `deviceToken` explícito, depois token de dispositivo armazenado e depois token de bootstrap.
- No caminho assíncrono da IU de Controle do Tailscale Serve, tentativas com falha para o mesmo `{scope, ip}` são serializadas antes de o limitador registrar a falha. Portanto, duas novas tentativas ruins concorrentes do mesmo cliente podem mostrar `retry later` na segunda tentativa em vez de duas incompatibilidades simples.
- `too many failed authentication attempts (retry later)` de um cliente loopback de origem de navegador → falhas repetidas dessa mesma `Origin` normalizada são bloqueadas temporariamente; outra origem localhost usa um bucket separado.
- `unauthorized` repetido após essa nova tentativa → divergência de token compartilhado/token de dispositivo; atualize a configuração de token e re-aprove/gire o token de dispositivo se necessário.
- `gateway connect failed:` → alvo de host/porta/url incorreto.
- Essa nova tentativa com token em cache reutiliza o conjunto de escopos em cache armazenado com o token de dispositivo pareado. Chamadores com `deviceToken` explícito / `scopes` explícitos mantêm o conjunto de escopos solicitado.
- Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é primeiro token/senha compartilhado explícito, depois `deviceToken` explícito, depois token de dispositivo armazenado, depois token de bootstrap.
- No caminho assíncrono da interface de controle do Tailscale Serve, tentativas com falha para o mesmo `{scope, ip}` são serializadas antes que o limitador registre a falha. Duas novas tentativas ruins simultâneas do mesmo cliente podem, portanto, mostrar `retry later` na segunda tentativa em vez de duas incompatibilidades simples.
- `too many failed authentication attempts (retry later)` de um cliente loopback com origem de navegador → falhas repetidas dessa mesma `Origin` normalizada são bloqueadas temporariamente; outra origem localhost usa um bucket separado.
- `unauthorized` repetido após essa nova tentativa → divergência de token compartilhado/token de dispositivo; atualize a configuração de token e aprove novamente/rotacione o token de dispositivo se necessário.
- `gateway connect failed:` → destino de host/porta/url incorreto.
</Accordion>
</AccordionGroup>
### Mapa rápido de códigos de detalhe de autenticação
### Mapa rápido de códigos de detalhes de autenticação
Use `error.details.code` da resposta `connect` com falha para escolher a próxima ação:
| Código de detalhe | Significado | Ação recomendada |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | O cliente não enviou um token compartilhado obrigatório. | Cole/defina o token no cliente e tente novamente. Para caminhos do painel: `openclaw config get gateway.auth.token` e depois cole nas configurações da Control UI. |
| `AUTH_TOKEN_MISMATCH` | O token compartilhado não correspondeu ao token de autenticação do gateway. | Se `canRetryWithDeviceToken=true`, permita uma nova tentativa confiável. Novas tentativas com token em cache reutilizam os escopos aprovados armazenados; chamadores explícitos com `deviceToken` / `scopes` mantêm os escopos solicitados. Se ainda falhar, execute a [lista de verificação de recuperação de desvio de token](/pt-BR/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | O token por dispositivo em cache está obsoleto ou foi revogado. | Rotacione/reaprove o token do dispositivo usando a [CLI de dispositivos](/pt-BR/cli/devices) e reconecte. |
| `PAIRING_REQUIRED` | A identidade do dispositivo precisa de aprovação. Verifique `error.details.reason` para `not-paired`, `scope-upgrade`, `role-upgrade` ou `metadata-upgrade`, e use `requestId` / `remediationHint` quando presentes. | Aprove a solicitação pendente: `openclaw devices list` e depois `openclaw devices approve <requestId>`. Atualizações de escopo/função usam o mesmo fluxo depois que você revisar o acesso solicitado. |
| Código de detalhe | Significado | Ação recomendada |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | O cliente não enviou um token compartilhado obrigatório. | Cole/defina o token no cliente e tente novamente. Para caminhos do dashboard: `openclaw config get gateway.auth.token`, depois cole nas configurações da Control UI. |
| `AUTH_TOKEN_MISMATCH` | O token compartilhado não correspondeu ao token de autenticação do gateway. | Se `canRetryWithDeviceToken=true`, permita uma nova tentativa confiável. Novas tentativas com token em cache reutilizam escopos aprovados armazenados; chamadores explícitos de `deviceToken` / `scopes` mantêm os escopos solicitados. Se ainda falhar, execute a [lista de verificação de recuperação de desvio de token](/pt-BR/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | O token em cache por dispositivo está obsoleto ou foi revogado. | Rotacione/reaprove o token do dispositivo usando a [CLI de dispositivos](/pt-BR/cli/devices), depois reconecte. |
| `PAIRING_REQUIRED` | A identidade do dispositivo precisa de aprovação. Verifique `error.details.reason` para `not-paired`, `scope-upgrade`, `role-upgrade` ou `metadata-upgrade`, e use `requestId` / `remediationHint` quando presentes. | Aprove a solicitação pendente: `openclaw devices list`, depois `openclaw devices approve <requestId>`. Atualizações de escopo/função usam o mesmo fluxo depois que você revisa o acesso solicitado. |
<Note>
RPCs diretos de backend via loopback autenticados com o token/senha compartilhado do gateway não devem depender da linha de base de escopo de dispositivo pareado da CLI. Se subagentes ou outras chamadas internas ainda falharem com `scope-upgrade`, verifique se o chamador está usando `client.id: "gateway-client"` e `client.mode: "backend"` e não está forçando um `deviceIdentity` ou token de dispositivo explícito.
RPCs diretos de backend por loopback autenticados com o token/senha compartilhado do gateway não devem depender da linha de base de escopo de dispositivo pareado da CLI. Se subagentes ou outras chamadas internas ainda falharem com `scope-upgrade`, verifique se o chamador está usando `client.id: "gateway-client"` e `client.mode: "backend"` e não está forçando um `deviceIdentity` ou token de dispositivo explícito.
</Note>
Verificação de migração da autenticação de dispositivo v2:
Verificação de migração de autenticação de dispositivo v2:
```bash
openclaw --version
@ -241,23 +242,23 @@ openclaw doctor
openclaw gateway status
```
Se os logs mostrarem erros de nonce/assinatura, atualize o cliente conectado e verifique-o:
Se os logs mostrarem erros de nonce/assinatura, atualize o cliente de conexão e verifique-o:
<Steps>
<Step title="Wait for connect.challenge">
<Step title="Aguardar connect.challenge">
O cliente aguarda o `connect.challenge` emitido pelo gateway.
</Step>
<Step title="Sign the payload">
O cliente assina o payload vinculado ao desafio.
<Step title="Assinar a carga">
O cliente assina a carga vinculada ao desafio.
</Step>
<Step title="Send the device nonce">
<Step title="Enviar o nonce do dispositivo">
O cliente envia `connect.params.device.nonce` com o mesmo nonce do desafio.
</Step>
</Steps>
Se `openclaw devices rotate` / `revoke` / `remove` for negado inesperadamente:
- sessões com token de dispositivo pareado podem gerenciar apenas **seu próprio** dispositivo, a menos que o chamador também tenha `operator.admin`
- sessões de token de dispositivo pareado só podem gerenciar **seu próprio** dispositivo, a menos que o chamador também tenha `operator.admin`
- `openclaw devices rotate --scope ...` só pode solicitar escopos de operador que a sessão do chamador já possui
Relacionado:
@ -277,7 +278,7 @@ openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # também verifica serviços em nível de sistema
openclaw gateway status --deep # also scan system-level services
```
Procure por:
@ -289,13 +290,13 @@ Procure por:
- Dicas de limpeza de `Other gateway-like services detected (best effort)`.
<AccordionGroup>
<Accordion title="Common signatures">
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → o modo de gateway local não está habilitado, ou o arquivo de configuração foi sobrescrito e perdeu `gateway.mode`. Correção: defina `gateway.mode="local"` na sua configuração, ou execute novamente `openclaw onboard --mode local` / `openclaw setup` para regravar a configuração esperada do modo local. Se você estiver executando OpenClaw via Podman, o caminho de configuração padrão é `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → bind fora de loopback sem um caminho válido de autenticação do gateway (token/senha, ou trusted-proxy quando configurado).
<Accordion title="Assinaturas comuns">
- `Gateway start blocked: set gateway.mode=local` ou `existing config is missing gateway.mode` → o modo de gateway local não está habilitado, ou o arquivo de configuração foi sobrescrito indevidamente e perdeu `gateway.mode`. Correção: defina `gateway.mode="local"` na sua configuração, ou execute novamente `openclaw onboard --mode local` / `openclaw setup` para remarcar a configuração de modo local esperada. Se você estiver executando o OpenClaw via Podman, o caminho de configuração padrão é `~/.openclaw/openclaw.json`.
- `refusing to bind gateway ... without auth` → bind fora de loopback sem um caminho válido de autenticação do gateway (token/senha, ou proxy confiável quando configurado).
- `another gateway instance is already listening` / `EADDRINUSE` → conflito de porta.
- `Other gateway-like services detected (best effort)` → unidades launchd/systemd/schtasks obsoletas ou paralelas existem. A maioria das configurações deve manter um gateway por máquina; se você realmente precisar de mais de um, isole portas + configuração/estado/workspace. Consulte [/gateway#multiple-gateways-same-host](/pt-BR/gateway#multiple-gateways-same-host).
- `System-level OpenClaw gateway service detected` do doctor → existe uma unidade systemd de sistema enquanto o serviço em nível de usuário está ausente. Remova ou desative a duplicata antes de permitir que o doctor instale um serviço de usuário, ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` se a unidade de sistema for o supervisor pretendido.
- `Gateway service port does not match current gateway config` → o supervisor instalado ainda fixa a `--port` antiga. Execute `openclaw doctor --fix` ou `openclaw gateway install --force`, depois reinicie o serviço do gateway.
- `Other gateway-like services detected (best effort)` → unidades launchd/systemd/schtasks obsoletas ou paralelas existem. A maioria das configurações deve manter um gateway por máquina; se você precisar de mais de um, isole portas + configuração/estado/workspace. Consulte [/gateway#multiple-gateways-same-host](/pt-BR/gateway#multiple-gateways-same-host).
- `System-level OpenClaw gateway service detected` do doctor → uma unidade de sistema systemd existe enquanto o serviço em nível de usuário está ausente. Remova ou desabilite a duplicata antes de permitir que o doctor instale um serviço de usuário, ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` se a unidade de sistema for o supervisor pretendido.
- `Gateway service port does not match current gateway config` → o supervisor instalado ainda fixa o `--port` antigo. Execute `openclaw doctor --fix` ou `openclaw gateway install --force`, depois reinicie o serviço do gateway.
</Accordion>
</AccordionGroup>
@ -322,19 +323,19 @@ Procure por:
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- Um arquivo `openclaw.json.clobbered.*` com carimbo de data/hora ao lado da configuração ativa
- Um arquivo `openclaw.json.clobbered.*` com registro de data/hora ao lado da configuração ativa
- Um evento de sistema do agente principal que começa com `Config recovery warning`
<AccordionGroup>
<Accordion title="What happened">
- A configuração rejeitada não foi validada durante a inicialização ou o hot reload.
- OpenClaw preservou o payload rejeitado como `.clobbered.*`.
- A configuração ativa foi restaurada da última cópia validada last-known-good.
<Accordion title="O que aconteceu">
- A configuração rejeitada não foi validada durante a inicialização ou recarga a quente.
- O OpenClaw preservou a carga rejeitada como `.clobbered.*`.
- A configuração ativa foi restaurada a partir da última cópia válida conhecida e validada.
- O próximo turno do agente principal é avisado para não reescrever cegamente a configuração rejeitada.
- Se todos os problemas de validação estivessem em `plugins.entries.<id>...`, OpenClaw não restauraria o arquivo inteiro. Falhas locais de Plugin permanecem visíveis enquanto configurações de usuário não relacionadas permanecem na configuração ativa.
- Se todos os problemas de validação estivessem em `plugins.entries.<id>...`, o OpenClaw não restauraria o arquivo inteiro. Falhas locais de Plugin permanecem explícitas enquanto configurações de usuário não relacionadas continuam na configuração ativa.
</Accordion>
<Accordion title="Inspect and repair">
<Accordion title="Inspecionar e reparar">
```bash
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
@ -343,30 +344,31 @@ Procure por:
openclaw doctor
```
</Accordion>
<Accordion title="Common signatures">
<Accordion title="Assinaturas comuns">
- `.clobbered.*` existe → uma edição direta externa ou leitura de inicialização foi restaurada.
- `.rejected.*` existe → uma gravação de configuração pertencente ao OpenClaw falhou no schema ou nas verificações de clobber antes do commit.
- `Config write rejected:` → a gravação tentou remover a estrutura obrigatória, reduzir o arquivo drasticamente ou persistir configuração inválida.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` ou `size-drop-vs-last-good:*` → a inicialização tratou o arquivo atual como sobrescrito porque ele perdeu campos ou tamanho em comparação com o backup last-known-good.
- `.rejected.*` existe → uma gravação de configuração de propriedade do OpenClaw falhou em verificações de schema ou sobrescrita antes do commit.
- `Config write rejected:` → a gravação tentou remover a estrutura obrigatória, reduzir drasticamente o arquivo ou persistir uma configuração inválida.
- `Rejected validation details:` → o log de recuperação ou aviso do agente principal inclui o caminho do schema que causou a restauração, como `agents.defaults.execution` ou `gateway.auth.password.source`.
- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` ou `size-drop-vs-last-good:*` → a inicialização tratou o arquivo atual como sobrescrito indevidamente porque ele perdeu campos ou tamanho em comparação com o backup da última configuração válida conhecida.
- `Config last-known-good promotion skipped` → o candidato continha placeholders de segredo redigidos, como `***`.
</Accordion>
<Accordion title="Fix options">
<Accordion title="Opções de correção">
1. Mantenha a configuração ativa restaurada se ela estiver correta.
2. Copie apenas as chaves pretendidas de `.clobbered.*` ou `.rejected.*`, depois aplique-as com `openclaw config set` ou `config.patch`.
3. Execute `openclaw config validate` antes de reiniciar.
4. Se editar manualmente, mantenha a configuração JSON5 completa, não apenas o objeto parcial que você queria alterar.
4. Se você editar manualmente, mantenha a configuração JSON5 completa, não apenas o objeto parcial que queria alterar.
</Accordion>
</AccordionGroup>
Relacionado:
- [Config](/pt-BR/cli/config)
- [Configuração: hot reload](/pt-BR/gateway/configuration#config-hot-reload)
- [Configuração: recarga a quente](/pt-BR/gateway/configuration#config-hot-reload)
- [Configuração: validação estrita](/pt-BR/gateway/configuration#strict-validation)
- [Doctor](/pt-BR/gateway/doctor)
## Avisos de probe do Gateway
## Avisos de sondagem do Gateway
Use isto quando `openclaw gateway probe` alcançar algo, mas ainda imprimir um bloco de aviso.
@ -379,16 +381,16 @@ openclaw gateway probe --ssh user@gateway-host
Procure por:
- `warnings[].code` e `primaryTargetId` na saída JSON.
- Se o aviso é sobre fallback SSH, múltiplos gateways, escopos ausentes ou refs de autenticação não resolvidas.
- Se o aviso é sobre fallback SSH, múltiplos gateways, escopos ausentes ou referências de autenticação não resolvidas.
Assinaturas comuns:
- `SSH tunnel failed to start; falling back to direct probes.` → a configuração SSH falhou, mas o comando ainda tentou alvos diretos configurados/de loopback.
- `multiple reachable gateways detected` → mais de um alvo respondeu. Normalmente isso significa uma configuração intencional com múltiplos gateways ou listeners obsoletos/duplicados.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → a conexão funcionou, mas o RPC de detalhe é limitado por escopo; pareie a identidade do dispositivo ou use credenciais com `operator.read`.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → a conexão funcionou, mas o conjunto completo de RPCs de diagnóstico expirou ou falhou. Trate isso como um Gateway acessível com diagnósticos degradados; compare `connect.ok` e `connect.rpcOk` na saída `--json`.
- `SSH tunnel failed to start; falling back to direct probes.` → a configuração SSH falhou, mas o comando ainda tentou alvos diretos configurados/loopback.
- `multiple reachable gateways detected` → mais de um alvo respondeu. Geralmente isso significa uma configuração intencional com múltiplos gateways ou listeners obsoletos/duplicados.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → a conexão funcionou, mas o RPC de detalhes é limitado por escopo; pareie a identidade do dispositivo ou use credenciais com `operator.read`.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → a conexão funcionou, mas o conjunto completo de RPCs de diagnóstico expirou ou falhou. Trate isto como um Gateway acessível com diagnósticos degradados; compare `connect.ok` e `connect.rpcOk` na saída `--json`.
- `Capability: pairing-pending` ou `gateway closed (1008): pairing required` → o gateway respondeu, mas este cliente ainda precisa de pareamento/aprovação antes do acesso normal de operador.
- texto de aviso de SecretRef `gateway.auth.*` / `gateway.remote.*` não resolvido → o material de autenticação estava indisponível neste caminho de comando para o alvo com falha.
- texto de aviso de SecretRef `gateway.auth.*` / `gateway.remote.*` não resolvido → o material de autenticação não estava disponível neste caminho de comando para o alvo com falha.
Relacionado:
@ -411,13 +413,13 @@ openclaw config get channels
Procure por:
- Política de DM (`pairing`, `allowlist`, `open`, `disabled`).
- Allowlist de grupo e requisitos de menção.
- Permissões/escopos ausentes da API do canal.
- Allowlist de grupos e requisitos de menção.
- Permissões/escopos de API do canal ausentes.
Assinaturas comuns:
- `mention required` → mensagem ignorada pela política de menção em grupo.
- `pairing` / rastros de aprovação pendente → remetente não está aprovado.
- `pairing` / rastros de aprovação pendente → remetente não foi aprovado.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → problema de autenticação/permissões do canal.
Relacionado:
@ -429,7 +431,7 @@ Relacionado:
## Entrega de Cron e Heartbeat
Se Cron ou Heartbeat não executou ou não entregou, verifique primeiro o estado do agendador e depois o destino da entrega.
Se o cron ou o heartbeat não executou ou não entregou, verifique primeiro o estado do agendador e depois o destino da entrega.
```bash
openclaw cron status
@ -442,18 +444,18 @@ openclaw logs --follow
Procure por:
- Cron habilitado e próxima ativação presente.
- Status do histórico de execução do job (`ok`, `skipped`, `error`).
- Motivos de salto de Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
- Status do histórico de execução da tarefa (`ok`, `skipped`, `error`).
- Motivos para pular Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
<AccordionGroup>
<Accordion title="Assinaturas comuns">
- `cron: scheduler disabled; jobs will not run automatically` → Cron desabilitado.
- `cron: scheduler disabled; jobs will not run automatically` → cron desabilitado.
- `cron: timer tick failed` → tick do agendador falhou; verifique erros de arquivo/log/runtime.
- `heartbeat skipped` com `reason=quiet-hours` → fora da janela de horas ativas.
- `heartbeat skipped` com `reason=quiet-hours` → fora da janela de horário ativo.
- `heartbeat skipped` com `reason=empty-heartbeat-file` → `HEARTBEAT.md` existe, mas contém apenas linhas em branco / cabeçalhos markdown, então o OpenClaw pula a chamada ao modelo.
- `heartbeat skipped` com `reason=no-tasks-due` → `HEARTBEAT.md` contém um bloco `tasks:`, mas nenhuma tarefa vence neste tick.
- `heartbeat: unknown accountId` → id de conta inválido para o destino de entrega do Heartbeat.
- `heartbeat skipped` com `reason=dm-blocked` → o destino do Heartbeat foi resolvido para um destino no estilo DM enquanto `agents.defaults.heartbeat.directPolicy` (ou sobrescrita por agente) está definido como `block`.
- `heartbeat skipped` com `reason=no-tasks-due` → `HEARTBEAT.md` contém um bloco `tasks:`, mas nenhuma das tarefas vence neste tick.
- `heartbeat: unknown accountId` → id de conta inválido para o destino de entrega do heartbeat.
- `heartbeat skipped` com `reason=dm-blocked` → o destino do heartbeat foi resolvido para um destino no estilo DM enquanto `agents.defaults.heartbeat.directPolicy` (ou substituição por agente) está definido como `block`.
</Accordion>
</AccordionGroup>
@ -466,7 +468,7 @@ Relacionado:
## Node pareado, ferramenta falha
Se um Node está pareado, mas as ferramentas falham, isole os estados de primeiro plano, permissão e aprovação.
Se um Node está pareado, mas as ferramentas falham, isole o estado de primeiro plano, permissão e aprovação.
```bash
openclaw nodes status
@ -478,16 +480,16 @@ openclaw status
Procure por:
- Node online com os recursos esperados.
- Concessões de permissão do sistema operacional para câmera/microfone/localização/tela.
- Aprovações de exec e estado da lista de permissões.
- Node online com as capacidades esperadas.
- Concessões de permissão do SO para câmera/microfone/localização/tela.
- Aprovações de exec e estado da allowlist.
Assinaturas comuns:
- `NODE_BACKGROUND_UNAVAILABLE` → o app do Node deve estar em primeiro plano.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permissão do sistema operacional ausente.
- `NODE_BACKGROUND_UNAVAILABLE` → o app do Node precisa estar em primeiro plano.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permissão do SO ausente.
- `SYSTEM_RUN_DENIED: approval required` → aprovação de exec pendente.
- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloqueado pela lista de permissões.
- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloqueado pela allowlist.
Relacionado:
@ -497,7 +499,7 @@ Relacionado:
## Ferramenta de navegador falha
Use isto quando as ações da ferramenta de navegador falharem mesmo que o Gateway em si esteja saudável.
Use isto quando ações da ferramenta de navegador falharem mesmo que o gateway em si esteja íntegro.
```bash
openclaw browser status
@ -516,32 +518,32 @@ Procure por:
<AccordionGroup>
<Accordion title="Assinaturas de Plugin / executável">
- `unknown command "browser"` ou `unknown command 'browser'` → o Plugin de navegador incluído foi excluído por `plugins.allow`.
- ferramenta de navegador ausente / indisponível enquanto `browser.enabled=true` → `plugins.allow` exclui `browser`, então o Plugin nunca foi carregado.
- `unknown command "browser"` ou `unknown command 'browser'` → o plugin de navegador incluído foi excluído por `plugins.allow`.
- ferramenta de navegador ausente / indisponível enquanto `browser.enabled=true` → `plugins.allow` exclui `browser`, então o plugin nunca foi carregado.
- `Failed to start Chrome CDP on port` → o processo do navegador falhou ao iniciar.
- `browser.executablePath not found` → o caminho configurado é inválido.
- `browser.cdpUrl must be http(s) or ws(s)` → a URL CDP configurada usa um esquema sem suporte, como `file:` ou `ftp:`.
- `browser.cdpUrl has invalid port` → a URL CDP configurada tem uma porta incorreta ou fora do intervalo.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → a instalação atual do Gateway não tem a dependência de runtime `playwright-core` do Plugin de navegador incluído; execute `openclaw doctor --fix` e reinicie o Gateway. Snapshots ARIA e capturas de tela básicas de página ainda podem funcionar, mas navegação, snapshots de IA, capturas de tela de elementos por seletor CSS e exportação de PDF continuam indisponíveis.
- `browser.cdpUrl has invalid port` → a URL CDP configurada tem uma porta inválida ou fora do intervalo.
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → a instalação atual do gateway não tem a dependência de runtime `playwright-core` do plugin de navegador incluído; execute `openclaw doctor --fix` e reinicie o gateway. Snapshots ARIA e capturas de tela básicas da página ainda podem funcionar, mas navegação, snapshots de IA, capturas de tela de elementos por seletor CSS e exportação de PDF permanecem indisponíveis.
</Accordion>
<Accordion title="Assinaturas de Chrome MCP / existing-session">
- `Could not find DevToolsActivePort for chrome` → a existing-session do Chrome MCP ainda não conseguiu se anexar ao diretório de dados do navegador selecionado. Abra a página de inspeção do navegador, habilite a depuração remota, mantenha o navegador aberto, aprove o primeiro prompt de anexação e tente novamente. Se o estado de login não for necessário, prefira o perfil gerenciado `openclaw`.
- `Could not find DevToolsActivePort for chrome` → o existing-session do Chrome MCP ainda não conseguiu se anexar ao diretório de dados do navegador selecionado. Abra a página de inspeção do navegador, habilite a depuração remota, mantenha o navegador aberto, aprove o primeiro prompt de anexação e tente novamente. Se o estado autenticado não for necessário, prefira o perfil gerenciado `openclaw`.
- `No Chrome tabs found for profile="user"` → o perfil de anexação do Chrome MCP não tem abas locais do Chrome abertas.
- `Remote CDP for profile "<name>" is not reachable` → o endpoint CDP remoto configurado não está acessível a partir do host do Gateway.
- `Remote CDP for profile "<name>" is not reachable` → o endpoint CDP remoto configurado não está acessível a partir do host do gateway.
- `Browser attachOnly is enabled ... not reachable` ou `Browser attachOnly is enabled and CDP websocket ... is not reachable` → o perfil somente anexação não tem um destino acessível, ou o endpoint HTTP respondeu, mas o WebSocket CDP ainda não pôde ser aberto.
</Accordion>
<Accordion title="Assinaturas de elemento / captura de tela / upload">
- `fullPage is not supported for element screenshots` → a solicitação de captura de tela misturou `--full-page` com `--ref` ou `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → chamadas de captura de tela do Chrome MCP / `existing-session` devem usar captura de página ou um `--ref` de snapshot, não `--element` CSS.
- `fullPage is not supported for element screenshots` → a solicitação de captura de tela combinou `--full-page` com `--ref` ou `--element`.
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → chamadas de captura de tela do Chrome MCP / `existing-session` devem usar captura de página ou um `--ref` de snapshot, não CSS `--element`.
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooks de upload do Chrome MCP precisam de refs de snapshot, não seletores CSS.
- `existing-session file uploads currently support one file at a time.` → envie um upload por chamada em perfis do Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → hooks de diálogo em perfis do Chrome MCP não dão suporte a sobrescritas de timeout.
- `existing-session type does not support timeoutMs overrides.` → omita `timeoutMs` para `act:type` em perfis `profile="user"` / existing-session do Chrome MCP, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.
- `existing-session evaluate does not support timeoutMs overrides.` → omita `timeoutMs` para `act:evaluate` em perfis `profile="user"` / existing-session do Chrome MCP, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.
- `existing-session file uploads currently support one file at a time.` → envie um upload por chamada em perfis Chrome MCP.
- `existing-session dialog handling does not support timeoutMs.` → hooks de diálogo em perfis Chrome MCP não oferecem suporte a substituições de timeout.
- `existing-session type does not support timeoutMs overrides.` → omita `timeoutMs` para `act:type` em perfis `profile="user"` / Chrome MCP existing-session, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.
- `existing-session evaluate does not support timeoutMs overrides.` → omita `timeoutMs` para `act:evaluate` em perfis `profile="user"` / Chrome MCP existing-session, ou use um perfil de navegador gerenciado/CDP quando um timeout personalizado for necessário.
- `response body is not supported for existing-session profiles yet.` → `responsebody` ainda exige um navegador gerenciado ou perfil CDP bruto.
- viewport / modo escuro / localidade / substituições offline obsoletos em perfis somente anexação ou CDP remoto → execute `openclaw browser stop --browser-profile <name>` para fechar a sessão de controle ativa e liberar o estado de emulação Playwright/CDP sem reiniciar todo o Gateway.
- substituições obsoletas de viewport / modo escuro / localidade / offline em perfis somente anexação ou CDP remoto → execute `openclaw browser stop --browser-profile <name>` para fechar a sessão de controle ativa e liberar o estado de emulação do Playwright/CDP sem reiniciar todo o gateway.
</Accordion>
</AccordionGroup>
@ -553,10 +555,10 @@ Relacionado:
## Se você atualizou e algo quebrou de repente
A maioria das quebras pós-atualização é desvio de configuração ou padrões mais rigorosos sendo aplicados agora.
A maioria das quebras pós-atualização é desvio de configuração ou padrões mais rígidos sendo aplicados agora.
<AccordionGroup>
<Accordion title="1. O comportamento de sobrescrita de autenticação e URL mudou">
<Accordion title="1. O comportamento de autenticação e substituição de URL mudou">
```bash
openclaw gateway status
openclaw config get gateway.mode
@ -566,8 +568,8 @@ A maioria das quebras pós-atualização é desvio de configuração ou padrões
O que verificar:
- Se `gateway.mode=remote`, chamadas da CLI podem estar mirando o remoto enquanto o serviço local está OK.
- Chamadas explícitas com `--url` não recorrem às credenciais armazenadas.
- Se `gateway.mode=remote`, chamadas da CLI podem estar mirando o remoto enquanto seu serviço local está funcionando.
- Chamadas explícitas com `--url` não fazem fallback para credenciais armazenadas.
Assinaturas comuns:
@ -575,7 +577,7 @@ A maioria das quebras pós-atualização é desvio de configuração ou padrões
- `unauthorized` → endpoint acessível, mas autenticação errada.
</Accordion>
<Accordion title="2. Guardrails de bind e autenticação estão mais rigorosos">
<Accordion title="2. Guardrails de bind e autenticação estão mais rígidos">
```bash
openclaw config get gateway.bind
openclaw config get gateway.auth.mode
@ -586,13 +588,13 @@ A maioria das quebras pós-atualização é desvio de configuração ou padrões
O que verificar:
- Binds não loopback (`lan`, `tailnet`, `custom`) precisam de um caminho válido de autenticação do Gateway: autenticação por token/senha compartilhados ou uma implantação `trusted-proxy` não loopback configurada corretamente.
- Binds que não são local loopback (`lan`, `tailnet`, `custom`) precisam de um caminho válido de autenticação do gateway: autenticação por token/senha compartilhados ou uma implantação `trusted-proxy` não local loopback configurada corretamente.
- Chaves antigas como `gateway.token` não substituem `gateway.auth.token`.
Assinaturas comuns:
- `refusing to bind gateway ... without auth` → bind não loopback sem um caminho válido de autenticação do Gateway.
- `Connectivity probe: failed` enquanto o runtime está em execução → Gateway ativo, mas inacessível com a autenticação/url atual.
- `refusing to bind gateway ... without auth` → bind que não é local loopback sem um caminho válido de autenticação do gateway.
- `Connectivity probe: failed` enquanto o runtime está em execução → gateway ativo, mas inacessível com a autenticação/url atual.
</Accordion>
<Accordion title="3. O estado de pareamento e identidade do dispositivo mudou">
@ -605,18 +607,18 @@ A maioria das quebras pós-atualização é desvio de configuração ou padrões
O que verificar:
- Aprovações pendentes de dispositivos para painel/nodes.
- Aprovações pendentes de pareamento por DM após mudanças de política ou identidade.
- Aprovações pendentes de dispositivos para dashboard/nodes.
- Aprovações pendentes de pareamento de DM após mudanças de política ou identidade.
Assinaturas comuns:
- `device identity required` → autenticação do dispositivo não satisfeita.
- `pairing required` → remetente/dispositivo deve ser aprovado.
- `pairing required` → remetente/dispositivo precisa ser aprovado.
</Accordion>
</AccordionGroup>
Se a configuração do serviço e o runtime ainda discordarem após as verificações, reinstale os metadados do serviço a partir do mesmo diretório de perfil/estado:
Se a configuração do serviço e o runtime ainda divergirem após as verificações, reinstale os metadados do serviço a partir do mesmo diretório de perfil/estado:
```bash
openclaw gateway install --force

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

File diff suppressed because it is too large Load Diff

175
docs/pt-BR/logging.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Você precisa de uma visão geral para iniciantes sobre os logs do OpenClaw
- Você quer configurar níveis, formatos ou mascaramento de logs
- Você precisa de uma visão geral dos logs do OpenClaw para iniciantes
- Você quer configurar níveis de log, formatos ou mascaramento
- Você está solucionando problemas e precisa encontrar registros rapidamente
summary: Logs de arquivos, saída do console, acompanhamento da CLI em tempo real e a aba Logs da Control UI
title: Registro em log
summary: Registros de arquivo, saída do console, acompanhamento em tempo real pela CLI e a aba Registros da Interface de Controle
title: Registro em logs
x-i18n:
generated_at: "2026-04-30T09:56:29Z"
generated_at: "2026-05-01T05:57:30Z"
model: gpt-5.5
provider: openai
source_hash: 916fb03219d571f0302560a4cb6755940575c92fff0b4eab024b9dad53f841ce
source_hash: d41ce5b1ae30fe1ca65577abe387fc266bd281686acb10098f82b8e78dfaa357
source_path: logging.md
workflow: 16
---
OpenClaw tem duas principais superfícies de logs:
OpenClaw tem duas superfícies principais de logs:
- **Logs de arquivo** (linhas JSON) gravados pelo Gateway.
- **Saída do console** exibida em terminais e na UI de Depuração do Gateway.
- **Logs em arquivo** (linhas JSON) gravados pelo Gateway.
- **Saída do console** exibida em terminais e na IU de Depuração do Gateway.
A aba **Logs** da UI de Controle acompanha o log de arquivo do gateway. Esta página explica onde
A aba **Logs** da IU de Controle acompanha o arquivo de log do gateway. Esta página explica onde
os logs ficam, como lê-los e como configurar níveis e formatos de log.
## Onde os logs ficam
@ -30,7 +30,7 @@ Por padrão, o Gateway grava um arquivo de log rotativo em:
A data usa o fuso horário local do host do gateway.
Cada arquivo rotaciona quando atinge `logging.maxFileBytes` (padrão: 100 MB).
Cada arquivo é rotacionado quando atinge `logging.maxFileBytes` (padrão: 100 MB).
O OpenClaw mantém até cinco arquivos numerados ao lado do arquivo ativo, como
`openclaw-YYYY-MM-DD.1.log`, e continua gravando em um novo log ativo em vez de
suprimir diagnósticos.
@ -47,7 +47,7 @@ Você pode sobrescrever isso em `~/.openclaw/openclaw.json`:
## Como ler logs
### CLI: acompanhamento ao vivo (recomendado)
### CLI: tail em tempo real (recomendado)
Use a CLI para acompanhar o arquivo de log do gateway via RPC:
@ -57,32 +57,32 @@ openclaw logs --follow
Opções atuais úteis:
- `--local-time`: renderiza timestamps no seu fuso horário local
- `--url <url>` / `--token <token>` / `--timeout <ms>`: flags padrão de RPC do Gateway
- `--expect-final`: flag de espera pela resposta final de RPC baseada em agente (aceita aqui pela camada de cliente compartilhada)
- `--local-time`: renderiza carimbos de data/hora no seu fuso horário local
- `--url <url>` / `--token <token>` / `--timeout <ms>`: flags RPC padrão do Gateway
- `--expect-final`: flag de espera por resposta final RPC apoiada por agente (aceita aqui via camada de cliente compartilhada)
Modos de saída:
- **Sessões TTY**: linhas de log estruturadas, bonitas e colorizadas.
- **Sessões TTY**: linhas de log estruturadas, coloridas e bem formatadas.
- **Sessões não TTY**: texto simples.
- `--json`: JSON delimitado por linha (um evento de log por linha).
- `--json`: JSON delimitado por linhas (um evento de log por linha).
- `--plain`: força texto simples em sessões TTY.
- `--no-color`: desativa cores ANSI.
Quando você passa um `--url` explícito, a CLI não aplica automaticamente credenciais de configuração ou
ambiente; inclua `--token` por conta própria se o Gateway de destino
Quando você passa um `--url` explícito, a CLI não aplica automaticamente credenciais
de configuração ou ambiente; inclua `--token` você mesmo se o Gateway de destino
exigir autenticação.
No modo JSON, a CLI emite objetos marcados por `type`:
- `meta`: metadados do stream (arquivo, cursor, tamanho)
- `meta`: metadados do fluxo (arquivo, cursor, tamanho)
- `log`: entrada de log analisada
- `notice`: dicas de truncamento / rotação
- `raw`: linha de log não analisada
Se o Gateway de local loopback implícito pedir pareamento, fechar durante a conexão
ou atingir tempo limite antes de `logs.tail` responder, `openclaw logs` recua automaticamente para o
log de arquivo do Gateway configurado. Destinos `--url` explícitos não usam
Se o Gateway de local loopback implícito solicitar pareamento, fechar durante a conexão
ou exceder o tempo limite antes de `logs.tail` responder, `openclaw logs` volta automaticamente
para o arquivo de log do Gateway configurado. Destinos `--url` explícitos não usam
esse fallback.
Se o Gateway estiver inacessível, a CLI imprime uma dica curta para executar:
@ -91,14 +91,14 @@ Se o Gateway estiver inacessível, a CLI imprime uma dica curta para executar:
openclaw doctor
```
### UI de Controle (web)
### IU de Controle (web)
A aba **Logs** da UI de Controle acompanha o mesmo arquivo usando `logs.tail`.
A aba **Logs** da IU de Controle acompanha o mesmo arquivo usando `logs.tail`.
Veja [/web/control-ui](/pt-BR/web/control-ui) para saber como abri-la.
### Logs somente de canal
### Logs apenas de canais
Para filtrar atividade de canal (WhatsApp/Telegram/etc), use:
Para filtrar atividade de canais (WhatsApp/Telegram/etc), use:
```bash
openclaw channels logs --channel whatsapp
@ -106,12 +106,12 @@ openclaw channels logs --channel whatsapp
## Formatos de log
### Logs de arquivo (JSONL)
### Logs em arquivo (JSONL)
Cada linha no arquivo de log é um objeto JSON. A CLI e a UI de Controle analisam essas
Cada linha no arquivo de log é um objeto JSON. A CLI e a IU de Controle analisam essas
entradas para renderizar saída estruturada (hora, nível, subsistema, mensagem).
Registros JSONL de log de arquivo também incluem campos de nível superior filtráveis por máquina quando
Registros JSONL de log em arquivo também incluem campos de nível superior filtráveis por máquina quando
disponíveis:
- `hostname`: nome do host do gateway.
@ -120,26 +120,26 @@ disponíveis:
- `session_id`: id/chave da sessão ativa quando a chamada de log carrega contexto de sessão.
- `channel`: canal ativo quando a chamada de log carrega contexto de canal.
O OpenClaw preserva os argumentos estruturados originais do log junto com esses campos
para que analisadores existentes que leem chaves numeradas de argumentos tslog continuem funcionando.
O OpenClaw preserva os argumentos de log estruturados originais junto desses campos
para que analisadores existentes que leem chaves de argumentos numeradas do tslog continuem funcionando.
### Saída do console
Logs de console são **cientes de TTY** e formatados para legibilidade:
Logs do console são **cientes de TTY** e formatados para legibilidade:
- Prefixos de subsistema (por exemplo, `gateway/channels/whatsapp`)
- Cores por nível (info/warn/error)
- Coloração por nível (info/warn/error)
- Modo compacto ou JSON opcional
A formatação do console é controlada por `logging.consoleStyle`.
### Logs de WebSocket do Gateway
### Logs WebSocket do Gateway
`openclaw gateway` também tem logging de protocolo WebSocket para tráfego RPC:
- modo normal: somente resultados interessantes (erros, erros de análise, chamadas lentas)
- modo normal: apenas resultados interessantes (erros, erros de análise, chamadas lentas)
- `--verbose`: todo o tráfego de requisição/resposta
- `--ws-log auto|compact|full`: escolhe o estilo de renderização verbosa
- `--ws-log auto|compact|full`: escolhe o estilo de renderização detalhada
- `--compact`: alias para `--ws-log compact`
Exemplos:
@ -150,7 +150,7 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Configuração de logging
## Configurando logging
Toda a configuração de logging fica em `logging` em `~/.openclaw/openclaw.json`.
@ -169,92 +169,97 @@ Toda a configuração de logging fica em `logging` em `~/.openclaw/openclaw.json
### Níveis de log
- `logging.level`: nível dos **logs de arquivo** (JSONL).
- `logging.level`: nível de **logs em arquivo** (JSONL).
- `logging.consoleLevel`: nível de verbosidade do **console**.
Você pode sobrescrever ambos pela variável de ambiente **`OPENCLAW_LOG_LEVEL`** (por exemplo, `OPENCLAW_LOG_LEVEL=debug`). A variável de ambiente tem precedência sobre o arquivo de configuração, então você pode aumentar a verbosidade para uma única execução sem editar `openclaw.json`. Você também pode passar a opção global da CLI **`--log-level <level>`** (por exemplo, `openclaw --log-level debug gateway run`), que sobrescreve a variável de ambiente para esse comando.
Você pode sobrescrever ambos por meio da variável de ambiente **`OPENCLAW_LOG_LEVEL`** (por exemplo, `OPENCLAW_LOG_LEVEL=debug`). A variável de ambiente tem precedência sobre o arquivo de configuração, então você pode aumentar a verbosidade para uma única execução sem editar `openclaw.json`. Você também pode passar a opção global da CLI **`--log-level <level>`** (por exemplo, `openclaw --log-level debug gateway run`), que sobrescreve a variável de ambiente para esse comando.
`--verbose` afeta apenas a saída do console e a verbosidade de logs WS; ele não altera
níveis de log de arquivo.
`--verbose` afeta apenas a saída do console e a verbosidade do log WS; ele não altera
os níveis de log em arquivo.
### Correlação de traces
### Correlação de rastreamento
Logs de arquivo são JSONL. Quando uma chamada de log carrega um contexto válido de trace diagnóstico,
o OpenClaw grava os campos de trace como chaves JSON de nível superior (`traceId`, `spanId`,
Logs em arquivo são JSONL. Quando uma chamada de log carrega um contexto de rastreamento diagnóstico válido,
o OpenClaw grava os campos de rastreamento como chaves JSON de nível superior (`traceId`, `spanId`,
`parentSpanId`, `traceFlags`) para que processadores externos de log possam correlacionar a linha
com spans OTEL e propagação de `traceparent` do provedor.
Requisições HTTP do Gateway e frames WebSocket do Gateway estabelecem um escopo interno de trace de requisição. Logs e eventos diagnósticos emitidos dentro desse escopo assíncrono herdam
o trace da requisição quando não passam um contexto de trace explícito. Traces de execução de agente e
chamadas de modelo se tornam filhos do trace de requisição ativo, então logs locais,
snapshots diagnósticos, spans OTEL e cabeçalhos `traceparent` de provedores confiáveis podem
ser unidos por `traceId` sem registrar conteúdo bruto de requisição ou de modelo.
Requisições HTTP do Gateway e quadros WebSocket do Gateway estabelecem um escopo interno de rastreamento
de requisição. Logs e eventos diagnósticos emitidos dentro desse escopo assíncrono herdam
o rastreamento da requisição quando não passam um contexto de rastreamento explícito. Rastreamentos de execução de agente e
chamadas de modelo se tornam filhos do rastreamento de requisição ativo, para que logs locais,
snapshots diagnósticos, spans OTEL e cabeçalhos `traceparent` de provedores confiáveis possam
ser unidos por `traceId` sem registrar conteúdo bruto de requisição ou modelo.
### Tamanho e timing de chamada de modelo
### Tamanho e tempo de chamada de modelo
Diagnósticos de chamada de modelo registram medições limitadas de requisição/resposta sem
Diagnósticos de chamadas de modelo registram medições limitadas de requisição/resposta sem
capturar conteúdo bruto de prompt ou resposta:
- `requestPayloadBytes`: tamanho em bytes UTF-8 do payload final da requisição ao modelo
- `responseStreamBytes`: tamanho em bytes UTF-8 dos eventos transmitidos da resposta do modelo
- `timeToFirstByteMs`: tempo decorrido antes do primeiro evento transmitido de resposta
- `requestPayloadBytes`: tamanho em bytes UTF-8 do payload final da requisição de modelo
- `responseStreamBytes`: tamanho em bytes UTF-8 dos eventos de resposta de modelo em streaming
- `timeToFirstByteMs`: tempo decorrido antes do primeiro evento de resposta em streaming
- `durationMs`: duração total da chamada de modelo
Esses campos ficam disponíveis para snapshots diagnósticos, hooks de plugin de chamada de modelo e
Esses campos ficam disponíveis para snapshots diagnósticos, hooks de plugins de chamada de modelo e
spans/métricas OTEL de chamada de modelo quando a exportação de diagnósticos está habilitada.
### Estilos de console
`logging.consoleStyle`:
- `pretty`: amigável para humanos, colorido, com timestamps.
- `pretty`: amigável para humanos, colorido, com carimbos de data/hora.
- `compact`: saída mais enxuta (melhor para sessões longas).
- `json`: JSON por linha (para processadores de log).
### Redação
O OpenClaw pode redigir tokens sensíveis antes que cheguem à saída do console, logs de arquivo,
registros de log OTLP, texto persistido de transcrição de sessão ou payloads de eventos de ferramentas da UI de Controle
(argumentos de início de ferramenta, payloads de resultado parcial/final, saída derivada de
exec e resumos de patch):
O OpenClaw pode redigir tokens sensíveis antes que cheguem à saída do console, logs em arquivo,
registros de log OTLP, texto persistido de transcrição de sessão ou payloads de eventos de ferramenta
da IU de Controle (argumentos de início de ferramenta, payloads de resultado parcial/final, saída
exec derivada e resumos de patch):
- `logging.redactSensitive`: `off` | `tools` (padrão: `tools`)
- `logging.redactPatterns`: lista de strings regex para sobrescrever o conjunto padrão. Padrões personalizados se aplicam além dos padrões integrados para payloads de ferramentas da UI de Controle, portanto adicionar um padrão nunca enfraquece a redação de valores já capturados pelos padrões.
- `logging.redactPatterns`: lista de strings regex para sobrescrever o conjunto padrão. Padrões personalizados são aplicados sobre os padrões integrados para payloads de ferramenta da IU de Controle, então adicionar um padrão nunca enfraquece a redação de valores já capturados pelos padrões.
Logs de arquivo e transcrições de sessão permanecem JSONL, mas valores secretos correspondentes são
mascarados antes que a linha ou mensagem seja gravada em disco. A redação é de melhor esforço:
ela se aplica a conteúdo de mensagens com texto e strings de log, não a todo
Logs em arquivo e transcrições de sessão continuam sendo JSONL, mas valores secretos correspondentes são
mascarados antes que a linha ou mensagem seja gravada no disco. A redação é de melhor esforço:
ela se aplica a conteúdo de mensagem com texto e strings de log, não a todo
identificador ou campo de payload binário.
`logging.redactSensitive: "off"` desativa apenas esta política geral de logs/transcrições.
O OpenClaw ainda redige payloads de fronteira de segurança que podem ser exibidos a clientes de UI,
Os padrões integrados cobrem credenciais comuns de API e nomes de campos de credenciais de pagamento
como número do cartão, CVC/CVV, token de pagamento compartilhado e credencial de pagamento
quando aparecem como campos JSON, parâmetros de URL, flags de CLI ou atribuições.
`logging.redactSensitive: "off"` desativa apenas essa política geral de log/transcrição.
O OpenClaw ainda redige payloads de fronteira de segurança que podem ser exibidos para clientes de IU,
pacotes de suporte, observadores de diagnósticos, prompts de aprovação ou ferramentas de agente.
Exemplos incluem eventos de chamada de ferramenta da UI de Controle, saída de `sessions_history`,
exportações de suporte de diagnósticos, observações de erro de provedor, exibição de comando de aprovação de exec
e logs de protocolo WebSocket do Gateway. `logging.redactPatterns` personalizados
Exemplos incluem eventos de chamada de ferramenta da IU de Controle, saída de `sessions_history`,
exportações de suporte de diagnósticos, observações de erro de provedor, exibição de comando de aprovação
exec e logs de protocolo WebSocket do Gateway. `logging.redactPatterns` personalizados
ainda podem adicionar padrões específicos do projeto nessas superfícies.
## Diagnósticos e OpenTelemetry
Diagnósticos são eventos estruturados, legíveis por máquina, para execuções de modelo e
Diagnósticos são eventos estruturados e legíveis por máquina para execuções de modelo e
telemetria de fluxo de mensagens (webhooks, enfileiramento, estado de sessão). Eles **não**
substituem logs — eles alimentam métricas, traces e exportadores. Eventos são emitidos
no processo, exporte-os ou não.
substituem logs — eles alimentam métricas, rastreamentos e exportadores. Eventos são emitidos
em processo, quer você os exporte ou não.
Duas superfícies adjacentes:
- **Exportação OpenTelemetry** — envie métricas, traces e logs via OTLP/HTTP para
- **Exportação do OpenTelemetry** — envia métricas, rastreamentos e logs por OTLP/HTTP para
qualquer coletor ou backend compatível com OpenTelemetry (Grafana, Datadog,
Honeycomb, New Relic, Tempo, etc.). Configuração completa, catálogo de sinais,
nomes de métricas/spans, variáveis de ambiente e modelo de privacidade ficam em uma página dedicada:
[Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry).
- **Flags de diagnósticos** — flags direcionadas de log de depuração que encaminham logs extras para
[Exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry).
- **Flags de diagnóstico** — flags direcionadas de log de depuração que encaminham logs extras para
`logging.file` sem aumentar `logging.level`. Flags não diferenciam maiúsculas de minúsculas
e aceitam curingas (`telegram.*`, `*`). Configure em `diagnostics.flags`
ou pela substituição de ambiente `OPENCLAW_DIAGNOSTICS=...`. Guia completo:
[Flags de diagnósticos](/pt-BR/diagnostics/flags).
ou pela sobrescrita de ambiente `OPENCLAW_DIAGNOSTICS=...`. Guia completo:
[Flags de diagnóstico](/pt-BR/diagnostics/flags).
Para habilitar eventos de diagnósticos para plugins ou coletores personalizados sem exportação OTLP:
Para habilitar eventos diagnósticos para plugins ou destinos personalizados sem exportação OTLP:
```json5
{
@ -262,18 +267,18 @@ Para habilitar eventos de diagnósticos para plugins ou coletores personalizados
}
```
Para exportação OTLP para um coletor, veja [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry).
Para exportação OTLP para um coletor, veja [Exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry).
## Dicas de solução de problemas
- **Gateway inacessível?** Execute `openclaw doctor` primeiro.
- **Logs vazios?** Verifique se o Gateway está em execução e gravando no caminho de arquivo
- **Logs vazios?** Verifique se o Gateway está em execução e gravando no caminho do arquivo
em `logging.file`.
- **Precisa de mais detalhes?** Defina `logging.level` como `debug` ou `trace` e tente novamente.
## Relacionados
- [Exportação OpenTelemetry](/pt-BR/gateway/opentelemetry) — exportação OTLP/HTTP, catálogo de métricas/spans, modelo de privacidade
- [Flags de diagnósticos](/pt-BR/diagnostics/flags) — flags direcionadas de log de depuração
- [Internos de logging do Gateway](/pt-BR/gateway/logging) — estilos de log WS, prefixos de subsistema e captura do console
- [Referência de configuração](/pt-BR/gateway/configuration-reference#diagnostics) — referência completa de campos `diagnostics.*`
- [Exportação do OpenTelemetry](/pt-BR/gateway/opentelemetry) — exportação OTLP/HTTP, catálogo de métricas/spans, modelo de privacidade
- [Flags de diagnóstico](/pt-BR/diagnostics/flags) — flags direcionadas de log de depuração
- [Internos de logging do Gateway](/pt-BR/gateway/logging) — estilos de log WS, prefixos de subsistema e captura de console
- [Referência de configuração](/pt-BR/gateway/configuration-reference#diagnostics) — referência completa dos campos `diagnostics.*`

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

File diff suppressed because it is too large Load Diff

848
docs/pt-BR/plugins/google-meet.md
View File

File diff suppressed because it is too large Load Diff

327
docs/pt-BR/plugins/voice-call.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Você quer fazer uma chamada de voz de saída pelo OpenClaw
- Você está configurando ou desenvolvendo o plugin de chamada de voz
- Você está configurando ou desenvolvendo o Plugin de chamada de voz
- Você precisa de voz em tempo real ou transcrição por streaming em telefonia
sidebarTitle: Voice call
summary: Realize chamadas de voz de saída e aceite chamadas de voz de entrada via Twilio, Telnyx ou Plivo, com voz em tempo real opcional e transcrição por fluxo contínuo
summary: Faça chamadas de voz de saída e aceite chamadas de voz de entrada via Twilio, Telnyx ou Plivo, com voz em tempo real e transcrição por streaming opcionais.
title: Plugin de chamada de voz
x-i18n:
generated_at: "2026-04-30T10:02:54Z"
generated_at: "2026-05-01T05:58:23Z"
model: gpt-5.5
provider: openai
source_hash: 7976b84ce1ee6e29706e595a4a25337632b34a9bb8f7cecdee1d6f833a8ce932
source_hash: 9ec854553cbba692ac9b3e929b107937332949c62aabe7192cdc9dcaa5537d74
source_path: plugins/voice-call.md
workflow: 16
---
Chamadas de voz para OpenClaw por meio de um plugin. Compatível com notificações de saída,
conversas em vários turnos, voz realtime full-duplex, transcrição
por streaming e chamadas de entrada com políticas de lista de permissões.
Chamadas de voz para o OpenClaw por meio de um Plugin. Compatível com notificações de saída,
conversas de vários turnos, voz realtime full-duplex, transcrição em streaming
e chamadas de entrada com políticas de allowlist.
**Provedores atuais:** `twilio` (Programmable Voice + Media Streams),
`telnyx` (Call Control v2), `plivo` (Voice API + transferência XML + GetInput
speech), `mock` (desenvolvimento/sem rede).
<Note>
O plugin Voice Call é executado **dentro do processo do Gateway**. Se você usa um
Gateway remoto, instale e configure o plugin na máquina que executa
o Gateway e reinicie o Gateway para carregá-lo.
O Plugin Voice Call é executado **dentro do processo do Gateway**. Se você usa um
Gateway remoto, instale e configure o Plugin na máquina que executa
o Gateway e depois reinicie o Gateway para carregá-lo.
</Note>
## Início rápido
<Steps>
<Step title="Instale o plugin">
<Step title="Instale o Plugin">
<Tabs>
<Tab title="Do npm">
```bash
@ -48,18 +48,18 @@ o Gateway e reinicie o Gateway para carregá-lo.
</Tab>
</Tabs>
Se o npm informar que o pacote mantido pela OpenClaw está obsoleto, essa versão do pacote
vem de uma linha de pacotes externa mais antiga; use uma build empacotada atual do OpenClaw
Se o npm informar que o pacote pertencente ao OpenClaw está obsoleto, essa versão do pacote
vem de uma linha de pacotes externos mais antiga; use uma build empacotada atual do OpenClaw
ou o caminho da pasta local até que um pacote npm mais novo seja publicado.
Depois, reinicie o Gateway para que o plugin seja carregado.
Reinicie o Gateway depois para que o Plugin seja carregado.
</Step>
<Step title="Configure o provedor e o webhook">
<Step title="Configure o provedor e o Webhook">
Defina a configuração em `plugins.entries.voice-call.config` (veja
[Configuração](#configuration) abaixo para o formato completo). No mínimo:
`provider`, credenciais do provedor, `fromNumber` e uma URL de webhook
acessível publicamente.
`provider`, credenciais do provedor, `fromNumber` e uma URL de Webhook acessível
publicamente.
</Step>
<Step title="Verifique a configuração">
```bash
@ -67,7 +67,7 @@ o Gateway e reinicie o Gateway para carregá-lo.
```
A saída padrão é legível em logs de chat e terminais. Ela verifica
a ativação do plugin, as credenciais do provedor, a exposição do webhook e se
a ativação do Plugin, as credenciais do provedor, a exposição do Webhook e se
apenas um modo de áudio (`streaming` ou `realtime`) está ativo. Use
`--json` para scripts.
@ -78,7 +78,7 @@ o Gateway e reinicie o Gateway para carregá-lo.
openclaw voicecall smoke --to "+15555550123"
```
Ambos são simulações por padrão. Adicione `--yes` para realmente fazer uma chamada curta
Ambos são execuções de simulação por padrão. Adicione `--yes` para realmente fazer uma chamada curta
de notificação de saída:
```bash
@ -89,9 +89,9 @@ o Gateway e reinicie o Gateway para carregá-lo.
</Steps>
<Warning>
Para Twilio, Telnyx e Plivo, a configuração precisa resolver para uma **URL de webhook pública**.
Para Twilio, Telnyx e Plivo, a configuração precisa resolver para uma **URL pública de Webhook**.
Se `publicUrl`, a URL do túnel, a URL do Tailscale ou o fallback de serviço
resolver para loopback ou espaço de rede privada, a configuração falhará em vez de
resolver para loopback ou espaço de rede privada, a configuração falha em vez de
iniciar um provedor que não pode receber webhooks da operadora.
</Warning>
@ -99,11 +99,11 @@ iniciar um provedor que não pode receber webhooks da operadora.
Se `enabled: true`, mas o provedor selecionado não tiver credenciais,
a inicialização do Gateway registra um aviso de configuração incompleta com as chaves ausentes e
pula a inicialização do runtime. Comandos, chamadas RPC e ferramentas de agente ainda
ignora a inicialização do runtime. Comandos, chamadas RPC e ferramentas do agente ainda
retornam a configuração exata ausente do provedor quando usados.
<Note>
As credenciais de voice-call aceitam SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` e `plugins.entries.voice-call.config.tts.providers.*.apiKey` são resolvidas pela superfície padrão de SecretRef; veja [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface).
As credenciais de chamada de voz aceitam SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` e `plugins.entries.voice-call.config.tts.providers.*.apiKey` são resolvidos pela superfície padrão de SecretRef; veja [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface).
</Note>
```json5
@ -164,27 +164,27 @@ As credenciais de voice-call aceitam SecretRefs. `plugins.entries.voice-call.con
```
<AccordionGroup>
<Accordion title="Observações sobre exposição e segurança do provedor">
- Twilio, Telnyx e Plivo exigem uma URL de webhook **publicamente acessível**.
- `mock` é um provedor local de desenvolvimento (sem chamadas de rede).
<Accordion title="Notas de exposição e segurança do provedor">
- Twilio, Telnyx e Plivo exigem uma URL de Webhook **acessível publicamente**.
- `mock` é um provedor de desenvolvimento local (sem chamadas de rede).
- Telnyx exige `telnyx.publicKey` (ou `TELNYX_PUBLIC_KEY`), a menos que `skipSignatureVerification` seja true.
- `skipSignatureVerification` é apenas para testes locais.
- No plano gratuito do ngrok, defina `publicUrl` como a URL exata do ngrok; a verificação de assinatura é sempre aplicada.
- No nível gratuito do ngrok, defina `publicUrl` como a URL exata do ngrok; a verificação de assinatura é sempre aplicada.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` permite webhooks da Twilio com assinaturas inválidas **somente** quando `tunnel.provider="ngrok"` e `serve.bind` é loopback (agente local do ngrok). Apenas desenvolvimento local.
- URLs do plano gratuito do ngrok podem mudar ou adicionar comportamento intersticial; se `publicUrl` se desviar, as assinaturas da Twilio falharão. Produção: prefira um domínio estável ou um funnel do Tailscale.
- URLs do nível gratuito do ngrok podem mudar ou adicionar comportamento intersticial; se `publicUrl` divergir, as assinaturas da Twilio falharão. Produção: prefira um domínio estável ou um funil do Tailscale.
</Accordion>
<Accordion title="Limites de conexão de streaming">
- `streaming.preStartTimeoutMs` fecha sockets que nunca enviam um frame `start` válido.
- `streaming.maxPendingConnections` limita o total de sockets pré-início não autenticados.
- `streaming.maxPendingConnectionsPerIp` limita sockets pré-início não autenticados por IP de origem.
- `streaming.maxConnections` limita o total de sockets abertos de fluxo de mídia (pendentes + ativos).
- `streaming.maxPendingConnectionsPerIp` limita os sockets pré-início não autenticados por IP de origem.
- `streaming.maxConnections` limita o total de sockets de streaming de mídia abertos (pendentes + ativos).
</Accordion>
<Accordion title="Migrações de configuração legada">
Configurações mais antigas que usam `provider: "log"`, `twilio.from` ou chaves legadas
`streaming.*` do OpenAI são reescritas por `openclaw doctor --fix`.
O fallback de runtime ainda aceita as chaves antigas de voice-call por enquanto, mas
Configurações mais antigas que usam `provider: "log"`, `twilio.from` ou chaves OpenAI
`streaming.*` legadas são reescritas por `openclaw doctor --fix`.
O fallback de runtime ainda aceita as chaves antigas de chamada de voz por enquanto, mas
o caminho de reescrita é `openclaw doctor --fix` e o shim de compatibilidade é
temporário.
@ -201,7 +201,7 @@ As credenciais de voice-call aceitam SecretRefs. `plugins.entries.voice-call.con
## Conversas de voz realtime
`realtime` seleciona um provedor de voz realtime full-duplex para áudio de chamadas
`realtime` seleciona um provedor de voz realtime full-duplex para áudio de chamada
ao vivo. Ele é separado de `streaming`, que apenas encaminha áudio para
provedores de transcrição realtime.
@ -213,22 +213,22 @@ modo de áudio por chamada.
Comportamento atual do runtime:
- `realtime.enabled` é compatível com Twilio Media Streams.
- `realtime.provider` é opcional. Se não for definido, o Voice Call usa o primeiro provedor de voz realtime registrado.
- Provedores de voz realtime incluídos: Google Gemini Live (`google`) e OpenAI (`openai`), registrados por seus plugins de provedor.
- `realtime.provider` é opcional. Se não for definido, Voice Call usa o primeiro provedor de voz realtime registrado.
- Provedores de voz realtime incluídos: Google Gemini Live (`google`) e OpenAI (`openai`), registrados por seus Plugins de provedor.
- A configuração bruta pertencente ao provedor fica em `realtime.providers.<providerId>`.
- O Voice Call expõe a ferramenta realtime compartilhada `openclaw_agent_consult` por padrão. O modelo realtime pode chamá-la quando o chamador pede raciocínio mais profundo, informações atuais ou ferramentas normais do OpenClaw.
- Se `realtime.provider` apontar para um provedor não registrado, ou se nenhum provedor de voz realtime estiver registrado, o Voice Call registra um aviso e pula a mídia realtime em vez de falhar o plugin inteiro.
- As chaves de sessão de consulta reutilizam a sessão de voz existente quando disponível e, depois, recorrem ao número de telefone do chamador/destinatário para que chamadas de consulta subsequentes mantenham o contexto durante a chamada.
- Voice Call expõe a ferramenta realtime compartilhada `openclaw_agent_consult` por padrão. O modelo realtime pode chamá-la quando o autor da chamada pedir raciocínio mais aprofundado, informações atuais ou ferramentas normais do OpenClaw.
- Se `realtime.provider` apontar para um provedor não registrado, ou se nenhum provedor de voz realtime estiver registrado, Voice Call registra um aviso e ignora a mídia realtime em vez de falhar todo o Plugin.
- As chaves de sessão de consulta reutilizam a sessão de voz existente quando disponível e, em seguida, fazem fallback para o número de telefone de quem chama/quem recebe, para que chamadas de consulta subsequentes mantenham o contexto durante a chamada.
### Política de ferramentas
`realtime.toolPolicy` controla a execução da consulta:
`realtime.toolPolicy` controla a execução de consulta:
| Política | Comportamento |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | Expõe a ferramenta de consulta e limita o agente comum a `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` e `memory_get`. |
| `owner` | Expõe a ferramenta de consulta e permite que o agente comum use a política normal de ferramentas do agente. |
| `none` | Não expõe a ferramenta de consulta. `realtime.tools` personalizadas ainda são repassadas ao provedor realtime. |
| `safe-read-only` | Expõe a ferramenta de consulta e limita o agente regular a `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` e `memory_get`. |
| `owner` | Expõe a ferramenta de consulta e permite que o agente regular use a política normal de ferramentas do agente. |
| `none` | Não expõe a ferramenta de consulta. `realtime.tools` personalizadas ainda são repassadas para o provedor realtime. |
### Exemplos de provedores realtime
@ -295,16 +295,17 @@ Veja [provedor Google](/pt-BR/providers/google) e
[provedor OpenAI](/pt-BR/providers/openai) para opções de voz realtime
específicas do provedor.
## Transcrição por streaming
## Transcrição em streaming
`streaming` seleciona um provedor de transcrição realtime para áudio de chamadas ao vivo.
`streaming` seleciona um provedor de transcrição realtime para áudio de chamada ao vivo.
Comportamento atual do runtime:
- `streaming.provider` é opcional. Se não for definido, o Voice Call usa o primeiro provedor de transcrição realtime registrado.
- Provedores de transcrição realtime incluídos: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) e xAI (`xai`), registrados por seus plugins de provedor.
- `streaming.provider` é opcional. Se não for definido, Voice Call usa o primeiro provedor de transcrição realtime registrado.
- Provedores de transcrição realtime incluídos: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) e xAI (`xai`), registrados por seus Plugins de provedor.
- A configuração bruta pertencente ao provedor fica em `streaming.providers.<providerId>`.
- Se `streaming.provider` apontar para um provedor não registrado, ou se nenhum estiver registrado, o Voice Call registra um aviso e pula o streaming de mídia em vez de falhar o plugin inteiro.
- Depois que a Twilio envia uma mensagem `start` de stream aceita, Voice Call registra o stream imediatamente, enfileira a mídia de entrada pelo provedor de transcrição enquanto o provedor se conecta e inicia a saudação inicial somente depois que a transcrição realtime estiver pronta.
- Se `streaming.provider` apontar para um provedor não registrado, ou se nenhum estiver registrado, Voice Call registra um aviso e ignora o streaming de mídia em vez de falhar todo o Plugin.
### Exemplos de provedores de streaming
@ -376,9 +377,9 @@ Comportamento atual do runtime:
## TTS para chamadas
Voice Call usa a configuração principal `messages.tts` para fala
por streaming em chamadas. Você pode substituí-la na configuração do Plugin com o
**mesmo formato** — ela faz uma mesclagem profunda com `messages.tts`.
Voice Call usa a configuração principal `messages.tts` para transmissão
de fala em chamadas. Você pode substituí-la na configuração do Plugin com o
**mesmo formato** — ela é mesclada profundamente com `messages.tts`.
```json5
{
@ -395,22 +396,22 @@ por streaming em chamadas. Você pode substituí-la na configuração do Plugin
```
<Warning>
**A fala da Microsoft é ignorada para chamadas de voz.** Áudio de telefonia precisa de PCM;
o transporte atual da Microsoft não expõe saída PCM para telefonia.
**A fala da Microsoft é ignorada para chamadas de voz.** O áudio de telefonia precisa de PCM;
o transporte atual da Microsoft não expõe saída PCM de telefonia.
</Warning>
Notas de comportamento:
- Chaves legadas `tts.<provider>` dentro da configuração do Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) são corrigidas por `openclaw doctor --fix`; a configuração confirmada deve usar `tts.providers.<provider>`.
- O TTS principal é usado quando o streaming de mídia do Twilio está ativado; caso contrário, as chamadas recorrem às vozes nativas do provedor.
- Se um stream de mídia do Twilio já estiver ativo, Voice Call não recorre a TwiML `<Say>`. Se o TTS de telefonia estiver indisponível nesse estado, a solicitação de reprodução falha em vez de misturar dois caminhos de reprodução.
- Chaves legadas `tts.<provider>` dentro da configuração do Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) são reparadas por `openclaw doctor --fix`; a configuração com commit deve usar `tts.providers.<provider>`.
- O TTS principal é usado quando o streaming de mídia do Twilio está habilitado; caso contrário, as chamadas recorrem às vozes nativas do provedor.
- Se um stream de mídia do Twilio já estiver ativo, Voice Call não recorre ao TwiML `<Say>`. Se o TTS de telefonia estiver indisponível nesse estado, a solicitação de reprodução falha em vez de misturar dois caminhos de reprodução.
- Quando o TTS de telefonia recorre a um provedor secundário, Voice Call registra um aviso com a cadeia de provedores (`from`, `to`, `attempts`) para depuração.
- Quando a interrupção por fala ou o encerramento do stream do Twilio limpa a fila pendente de TTS, as solicitações de reprodução enfileiradas são resolvidas em vez de deixar chamadores aguardando a conclusão da reprodução.
- Quando a interrupção por fala do Twilio ou a desmontagem do stream limpa a fila de TTS pendente, as solicitações de reprodução enfileiradas são concluídas em vez de deixar chamadores aguardando a conclusão da reprodução indefinidamente.
### Exemplos de TTS
<Tabs>
<Tab title="Core TTS only">
<Tab title="Somente TTS principal">
```json5
{
messages: {
@ -424,7 +425,7 @@ Notas de comportamento:
}
```
</Tab>
<Tab title="Override to ElevenLabs (calls only)">
<Tab title="Substituir por ElevenLabs (somente chamadas)">
```json5
{
plugins: {
@ -448,7 +449,7 @@ Notas de comportamento:
}
```
</Tab>
<Tab title="OpenAI model override (deep-merge)">
<Tab title="Substituição do modelo OpenAI (mesclagem profunda)">
```json5
{
plugins: {
@ -472,9 +473,9 @@ Notas de comportamento:
</Tab>
</Tabs>
## Chamadas de entrada
## Chamadas recebidas
A política de entrada usa `disabled` por padrão. Para ativar chamadas de entrada, defina:
A política de recebimento usa `disabled` como padrão. Para habilitar chamadas recebidas, defina:
```json5
{
@ -485,11 +486,11 @@ A política de entrada usa `disabled` por padrão. Para ativar chamadas de entra
```
<Warning>
`inboundPolicy: "allowlist"` é uma verificação de ID de chamador de baixa garantia. O
`inboundPolicy: "allowlist"` é uma triagem de ID de chamador de baixa garantia. O
Plugin normaliza o valor `From` fornecido pelo provedor e o compara com
`allowFrom`. A verificação de Webhook autentica a entrega do provedor e
a integridade da carga, mas **não** comprova a propriedade do número de chamador
PSTN/VoIP. Trate `allowFrom` como filtragem de ID de chamador, não como identidade
a integridade do payload, mas **não** comprova a propriedade do número do chamador
PSTN/VoIP. Trate `allowFrom` como filtragem de ID de chamador, não como uma identidade
forte do chamador.
</Warning>
@ -498,51 +499,51 @@ Respostas automáticas usam o sistema de agentes. Ajuste com `responseModel`,
### Contrato de saída falada
Para respostas automáticas, Voice Call acrescenta um contrato estrito de saída falada ao
Para respostas automáticas, Voice Call acrescenta um contrato rigoroso de saída falada ao
prompt do sistema:
```text
{"spoken":"..."}
```
Voice Call extrai o texto de fala defensivamente:
Voice Call extrai texto de fala de forma defensiva:
- Ignora cargas marcadas como conteúdo de raciocínio/erro.
- Analisa JSON direto, JSON cercado por blocos ou chaves `"spoken"` embutidas.
- Ignora payloads marcados como conteúdo de raciocínio/erro.
- Analisa JSON direto, JSON cercado por cercas ou chaves `"spoken"` inline.
- Recorre a texto simples e remove prováveis parágrafos iniciais de planejamento/metadados.
Isso mantém a reprodução falada focada no texto voltado ao chamador e evita
vazamento de texto de planejamento para o áudio.
vazar texto de planejamento para o áudio.
### Comportamento de início de conversa
Para chamadas `conversation` de saída, o tratamento da primeira mensagem é vinculado ao estado de
reprodução ao vivo:
Para chamadas `conversation` de saída, o tratamento da primeira mensagem é vinculado ao estado
de reprodução ao vivo:
- A limpeza da fila por interrupção de fala e a resposta automática são suprimidas apenas enquanto a saudação inicial está sendo falada ativamente.
- Se a reprodução inicial falhar, a chamada retorna para `listening` e a mensagem inicial permanece enfileirada para nova tentativa.
- A reprodução inicial para streaming do Twilio começa na conexão do stream, sem atraso extra.
- A interrupção por fala aborta a reprodução ativa e limpa entradas de TTS do Twilio enfileiradas, mas ainda não em reprodução. As entradas limpas são resolvidas como ignoradas, para que a lógica de resposta seguinte possa continuar sem aguardar áudio que nunca será reproduzido.
- Conversas de voz em tempo real usam o próprio turno de abertura do stream em tempo real. Voice Call **não** publica uma atualização TwiML `<Say>` legada para essa mensagem inicial, então sessões `<Connect><Stream>` de saída permanecem anexadas.
- A interrupção por fala aborta a reprodução ativa e limpa entradas de TTS do Twilio enfileiradas, mas ainda não reproduzidas. As entradas limpas são resolvidas como ignoradas, para que a lógica de resposta subsequente possa continuar sem aguardar um áudio que nunca será reproduzido.
- Conversas de voz em tempo real usam o turno inicial do próprio stream em tempo real. Voice Call **não** publica uma atualização TwiML legada `<Say>` para essa mensagem inicial, então sessões de saída `<Connect><Stream>` permanecem anexadas.
### Período de tolerância para desconexão de stream do Twilio
### Período de carência para desconexão de stream do Twilio
Quando um stream de mídia do Twilio se desconecta, Voice Call aguarda **2000 ms** antes de
encerrar automaticamente a chamada:
Quando um stream de mídia do Twilio se desconecta, Voice Call espera **2000 ms** antes de
encerrar a chamada automaticamente:
- Se o stream se reconectar durante essa janela, o encerramento automático é cancelado.
- Se nenhum stream se registrar novamente após o período de tolerância, a chamada é encerrada para evitar chamadas ativas presas.
- Se nenhum stream for registrado novamente após o período de carência, a chamada é encerrada para evitar chamadas ativas presas.
## Removedor de chamadas obsoletas
## Coletor de chamadas obsoletas
Use `staleCallReaperSeconds` para encerrar chamadas que nunca recebem um
Webhook terminal (por exemplo, chamadas em modo de notificação que nunca são concluídas). O padrão
é `0` (desativado).
é `0` (desabilitado).
Intervalos recomendados:
- **Produção:** `120`–`300` segundos para fluxos no estilo notificação.
- Mantenha este valor **maior que `maxDurationSeconds`** para que chamadas normais possam terminar. Um bom ponto de partida é `maxDurationSeconds + 30–60` segundos.
- **Produção:** `120`–`300` segundos para fluxos do tipo notificação.
- Mantenha esse valor **maior que `maxDurationSeconds`** para que chamadas normais possam terminar. Um bom ponto de partida é `maxDurationSeconds + 30–60` segundos.
```json5
{
@ -561,26 +562,26 @@ Intervalos recomendados:
## Segurança de Webhook
Quando um proxy ou túnel fica na frente do Gateway, o Plugin
Quando um proxy ou túnel fica na frente do Gateway, o plugin
reconstrói a URL pública para verificação de assinatura. Estas opções
controlam quais cabeçalhos encaminhados são confiáveis:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Hosts da lista de permissões a partir de cabeçalhos de encaminhamento.
Hosts permitidos a partir de cabeçalhos de encaminhamento.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Confia em cabeçalhos encaminhados sem uma lista de permissões.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Confia em cabeçalhos encaminhados apenas quando o IP remoto da solicitação corresponde à lista.
Confia em cabeçalhos encaminhados somente quando o IP remoto da solicitação corresponde à lista.
</ParamField>
Proteções adicionais:
- A **proteção contra repetição** de Webhook é ativada para Twilio e Plivo. Solicitações válidas de Webhook repetidas são confirmadas, mas ignoradas quanto a efeitos colaterais.
- Turnos de conversa do Twilio incluem um token por turno em callbacks `<Gather>`, então callbacks de fala obsoletos/repetidos não conseguem satisfazer um turno de transcrição pendente mais recente.
- A **proteção contra repetição** de Webhook é habilitada para Twilio e Plivo. Solicitações de Webhook válidas repetidas são reconhecidas, mas ignoradas para efeitos colaterais.
- Turnos de conversa do Twilio incluem um token por turno em callbacks de `<Gather>`, para que callbacks de fala obsoletos/repetidos não possam satisfazer um turno de transcrição pendente mais recente.
- Solicitações de Webhook não autenticadas são rejeitadas antes da leitura do corpo quando os cabeçalhos de assinatura exigidos pelo provedor estão ausentes.
- O Webhook de voice-call usa o perfil compartilhado de corpo pré-autenticação (64 KB / 5 segundos) mais um limite em andamento por IP antes da verificação de assinatura.
- O Webhook de voice-call usa o perfil de corpo compartilhado de pré-autenticação (64 KB / 5 segundos), além de um limite por IP de solicitações em andamento antes da verificação de assinatura.
Exemplo com um host público estável:
@ -616,16 +617,21 @@ openclaw voicecall latency # summarize turn latency from lo
openclaw voicecall expose --mode funnel
```
`latency` lê `calls.jsonl` do caminho padrão de armazenamento do voice-call.
Quando o Gateway já está em execução, comandos operacionais `voicecall` delegam
ao runtime de voice-call pertencente ao Gateway, para que a CLI não vincule um segundo
servidor de Webhook. Se nenhum Gateway estiver acessível, os comandos recorrem a um
runtime de CLI autônomo.
`latency` lê `calls.jsonl` do caminho padrão de armazenamento de voice-call.
Use `--file <path>` para apontar para um log diferente e `--last <n>` para limitar
a análise aos últimos N registros (padrão 200). A saída inclui p50/p90/p99
para latência de turno e tempos de espera de escuta.
para latência de turno e tempos de espera por escuta.
## Ferramenta de agente
Nome da ferramenta: `voice_call`.
| Ação | Args |
| Ação | Argumentos |
| --------------- | ------------------------- |
| `initiate_call` | `message`, `to?`, `mode?` |
| `continue_call` | `callId`, `message` |
@ -634,11 +640,11 @@ Nome da ferramenta: `voice_call`.
| `end_call` | `callId` |
| `get_status` | `callId` |
Este repo inclui um documento de Skills correspondente em `skills/voice-call/SKILL.md`.
Este repositório inclui um documento de Skills correspondente em `skills/voice-call/SKILL.md`.
## RPC do Gateway
| Método | Args |
| Método | Argumentos |
| ------------------- | ------------------------- |
| `voicecall.initiate` | `to?`, `message`, `mode?` |
| `voicecall.continue` | `callId`, `message` |
@ -647,7 +653,140 @@ Este repo inclui um documento de Skills correspondente em `skills/voice-call/SKI
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
## Relacionado
## Solução de problemas
### A configuração falha na exposição do Webhook
Execute a configuração no mesmo ambiente que executa o Gateway:
```bash
openclaw voicecall setup
openclaw voicecall setup --json
```
Para `twilio`, `telnyx` e `plivo`, `webhook-exposure` deve estar verde. Uma
`publicUrl` configurada ainda falha quando aponta para espaço de rede local ou privada,
porque a operadora não consegue fazer callback para esses endereços. Não use
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
`192.168.x`, `169.254.x`, `fc00::/7` ou `fd00::/8` como `publicUrl`.
Use um caminho de exposição público:
```json5
{
plugins: {
entries: {
"voice-call": {
config: {
publicUrl: "https://voice.example.com/voice/webhook",
// or
tunnel: { provider: "ngrok" },
// or
tailscale: { mode: "funnel", path: "/voice/webhook" },
},
},
},
},
}
```
Depois de alterar a configuração, reinicie ou recarregue o Gateway e execute:
```bash
openclaw voicecall setup
openclaw voicecall smoke
```
`voicecall smoke` é uma simulação, a menos que você passe `--yes`.
### Credenciais do provedor falham
Verifique o provedor selecionado e os campos de credenciais obrigatórios:
- Twilio: `twilio.accountSid`, `twilio.authToken` e `fromNumber`, ou
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` e `TWILIO_FROM_NUMBER`.
- Telnyx: `telnyx.apiKey`, `telnyx.connectionId`, `telnyx.publicKey` e
`fromNumber`.
- Plivo: `plivo.authId`, `plivo.authToken` e `fromNumber`.
As credenciais devem existir no host do Gateway. Editar um perfil de shell local não
afeta um Gateway já em execução até que ele seja reiniciado ou recarregue seu
ambiente.
### As chamadas iniciam, mas os Webhooks do provedor não chegam
Confirme se o console do provedor aponta para a URL pública de Webhook exata:
```text
https://voice.example.com/voice/webhook
```
Depois inspecione o estado em tempo de execução:
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall tail
```
Causas comuns:
- `publicUrl` aponta para um caminho diferente de `serve.path`.
- A URL do túnel mudou depois que o Gateway iniciou.
- Um proxy encaminha a solicitação, mas remove ou reescreve os cabeçalhos de host/proto.
- Firewall ou DNS roteia o hostname público para algum lugar diferente do Gateway.
- O Gateway foi reiniciado sem o Plugin Voice Call habilitado.
Quando um proxy reverso ou túnel estiver na frente do Gateway, defina
`webhookSecurity.allowedHosts` como o hostname público, ou use
`webhookSecurity.trustedProxyIPs` para um endereço de proxy conhecido. Use
`webhookSecurity.trustForwardingHeaders` somente quando o limite do proxy estiver sob
seu controle.
### A verificação de assinatura falha
As assinaturas do provedor são verificadas em relação à URL pública que o OpenClaw reconstrói
a partir da solicitação recebida. Se as assinaturas falharem:
- Confirme se a URL de Webhook do provedor corresponde exatamente a `publicUrl`, incluindo
esquema, host e caminho.
- Para URLs do nível gratuito do ngrok, atualize `publicUrl` quando o hostname do túnel mudar.
- Garanta que o proxy preserve os cabeçalhos de host e proto originais, ou configure
`webhookSecurity.allowedHosts`.
- Não habilite `skipSignatureVerification` fora de testes locais.
### As entradas do Twilio no Google Meet falham
O Google Meet usa este Plugin para entradas por discagem do Twilio. Primeiro verifique o Voice Call:
```bash
openclaw voicecall setup
openclaw voicecall smoke --to "+15555550123"
```
Depois verifique explicitamente o transporte do Google Meet:
```bash
openclaw googlemeet setup --transport twilio
```
Se o Voice Call estiver verde, mas o participante do Meet nunca entrar, verifique o número
de discagem do Meet, o PIN e `--dtmf-sequence`. A chamada telefônica pode estar íntegra enquanto
a reunião rejeita ou ignora uma sequência DTMF incorreta.
### A chamada em tempo real não tem fala
Confirme que apenas um modo de áudio está habilitado. `realtime.enabled` e
`streaming.enabled` não podem ser ambos true.
Para chamadas Twilio em tempo real, verifique também:
- Um Plugin provedor em tempo real está carregado e registrado.
- `realtime.provider` está indefinido ou nomeia um provedor registrado.
- A chave de API do provedor está disponível para o processo do Gateway.
- `openclaw voicecall tail` mostra o stream de mídia aceito e a prontidão do
provedor em tempo real antes da saudação inicial.
## Relacionados
- [Modo de conversa](/pt-BR/nodes/talk)
- [Texto para fala](/pt-BR/tools/tts)

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

@ -1,61 +1,61 @@
---
read_when:
- Procurando definições de canais de lançamento públicos
- Executando a validação de lançamento ou a aceitação de pacote
- Procurando definições públicas de canais 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
summary: Canais 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-04-30T10:07:04Z"
generated_at: "2026-05-01T05:58:30Z"
model: gpt-5.5
provider: openai
source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c
source_hash: dfe579099a9580e2d0400cd0b24f26d3fa3ee917899423604ebc13aa2519b4ee
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw tem três faixas públicas de lançamento:
OpenClaw tem três canais públicos de lançamento:
- stable: lançamentos com tag que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente
- estável: lançamentos marcados com tags 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: a ponta móvel de `main`
- desenvolvimento: o topo móvel de `main`
## Nomenclatura de versões
## Nomeação de versões
- Versão de lançamento estável: `YYYY.M.D`
- Tag Git: `vYYYY.M.D`
- Tag do Git: `vYYYY.M.D`
- Versão de lançamento de correção estável: `YYYY.M.D-N`
- Tag Git: `vYYYY.M.D-N`
- Tag do Git: `vYYYY.M.D-N`
- Versão de pré-lançamento beta: `YYYY.M.D-beta.N`
- Tag Git: `vYYYY.M.D-beta.N`
- Não preencha mês ou dia com zero à esquerda
- Tag do Git: `vYYYY.M.D-beta.N`
- Não adicione zero à esquerda no mês ou no dia
- `latest` significa o lançamento npm estável promovido atual
- `beta` significa o alvo atual de instalação beta
- Lançamentos estáveis e lançamentos de correção estáveis publicam no npm `beta` por padrão; operadores de lançamento podem direcionar para `latest` explicitamente, ou promover uma build beta validada posteriormente
- Todo lançamento estável do OpenClaw envia junto o pacote npm e o app macOS;
- `beta` significa o destino de instalação beta atual
- Lançamentos estáveis e de correção estável publicam no npm `beta` por padrão; operadores de lançamento podem direcionar para `latest` explicitamente, ou promover uma compilação beta validada posteriormente
- Todo lançamento estável do OpenClaw distribui o pacote npm e o app macOS juntos;
lançamentos beta normalmente validam e publicam primeiro o caminho npm/pacote, com
build/assinatura/notarização do app Mac reservados para estável, a menos que solicitados explicitamente
compilação/assinatura/notarização do app Mac reservadas para estáveis, salvo solicitação explícita
## Cadência de lançamentos
## Cadência de lançamento
- Lançamentos seguem primeiro pelo beta
- Os lançamentos seguem primeiro para beta
- O estável 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 do `main` atual, para que a validação e as correções de lançamento não bloqueiem o novo
desenvolvimento em `main`
- Se uma tag beta foi enviada ou publicada e precisa de uma correção, os mantenedores criam
a partir do `main` atual, para que a validação e as correções do lançamento não bloqueiem novos
desenvolvimentos em `main`
- Se uma tag beta foi enviada ou publicada e precisa de uma correção, mantenedores criam
a próxima tag `-beta.N` em vez de excluir ou recriar a tag beta antiga
- Procedimento detalhado de lançamento, aprovações, credenciais e notas de recuperação são
exclusivos para mantenedores
apenas para mantenedores
## Checklist do operador de lançamento
Este checklist é 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 permanecem no
manual de execução de lançamento exclusivo para mantenedores.
assinatura, notarização, recuperação de dist-tag e detalhes de rollback emergencial ficam no
runbook de lançamento restrito a mantenedores.
1. Comece a partir do `main` atual: puxe o mais recente, confirme que o commit de destino foi enviado,
e confirme que o CI do `main` atual está verde o suficiente para criar uma branch a partir dele.
1. Comece do `main` atual: puxe a versão mais recente, confirme que o commit de destino foi enviado
e confirme que o CI atual de `main` está verde o suficiente para criar uma branch a partir dele.
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.
@ -64,178 +64,95 @@ manual de execução de lançamento exclusivo para mantenedores.
`src/commands/doctor/shared/deprecation-compat.ts`. Remova compatibilidade expirada
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 do `main` atual; não faça trabalho normal de lançamento
4. Crie `release/YYYY.M.D` a partir do `main` atual; não faça o trabalho normal de lançamento
diretamente em `main`.
5. Atualize cada local obrigatório de versão para a tag pretendida, depois execute a
pré-validação determinística local:
5. Atualize todos os locais de versão exigidos para a tag pretendida, depois execute o
preflight determinístico local:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build` e `pnpm release:check`.
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 pré-validação
um SHA completo de 40 caracteres da branch de lançamento é permitido para preflight
somente de validação. Salve o `preflight_run_id` bem-sucedido.
7. Inicie todos os testes de pré-lançamento com `Full Release Validation` para a
branch de lançamento, tag ou SHA completo do commit. 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, faixa, job de workflow, perfil de pacote, provedor ou lista de permissão de modelos com falha que
comprove a correção. Execute novamente o guarda-chuva completo somente quando a superfície alterada tornar
8. Se a validação falhar, corrija na branch de lançamento e reexecute 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
as evidências anteriores obsoletas.
9. Para beta, crie a tag `vYYYY.M.D-beta.N`, publique com a dist-tag npm `beta`, depois execute
a aceitação de pacote pós-publicação contra o pacote publicado `openclaw@YYYY.M.D-beta.N`
ou `openclaw@beta`. Se um beta enviado ou publicado precisar de correção, crie
o próximo `-beta.N`; não exclua nem reescreva o beta antigo.
10. Para estável, continue somente depois que o beta validado ou candidato a lançamento tiver as
evidências de validação obrigatórias. A publicação npm estável reutiliza o artefato de
pré-validação bem-sucedido via `preflight_run_id`; a prontidão de lançamento macOS estável
evidências de validação exigidas. A publicação npm estável reutiliza o artefato de
preflight bem-sucedido via `preflight_run_id`; a prontidão do lançamento macOS estável
também exige o `.zip`, `.dmg`, `.dSYM.zip` empacotados e o
`appcast.xml` atualizado em `main`.
11. Após a publicação, execute o verificador npm pós-publicação, o E2E Telegram independente opcional
do npm publicado quando você precisar de prova de canal pós-publicação,
promoção de dist-tag quando necessária, notas de lançamento/pré-lançamento do GitHub a partir da
seção completa correspondente de `CHANGELOG.md` e as etapas de anúncio do lançamento.
11. Após publicar, execute o verificador npm pós-publicação, o E2E Telegram
opcional autônomo do npm publicado quando precisar de prova de canal pós-publicação,
promoção de dist-tag quando necessário, notas de lançamento/pré-lançamento no GitHub a partir da
seção completa correspondente de `CHANGELOG.md`, e as etapas de anúncio do lançamento.
## Pré-validação de lançamento
## Preflight de lançamento
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript dos testes continue
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
`dist/*` e o pacote da Control UI existam para a etapa de validação
do empacotamento
- 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 lanes do Telegram.
Forneça `npm_telegram_package_spec` somente depois que um pacote tiver sido
publicado e o E2E pós-publicação do Telegram também deva ser executado. Forneça
`evidence_package_spec` quando o relatório privado de evidências deve provar que a
validação corresponde a um pacote npm publicado sem forçar o E2E do Telegram.
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript dos testes continue 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 estejam 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 pacote da Control UI existam para a etapa de validação do pacote
- Execute o fluxo de trabalho 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 uma branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para install smoke, aceitação de pacote, suítes do caminho de release do Docker, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e lanes do Telegram. Forneça `npm_telegram_package_spec` somente depois que um pacote tiver sido publicado e o E2E pós-publicação do Telegram também precisar ser executado. Forneça `evidence_package_spec` quando o relatório privado de evidências precisar 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 prova por canal lateral
para um candidato a 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 confiável de `package_ref` com o harness atual
`workflow_ref`; `source=url` para um tarball HTTPS com um 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 E2E do Docker contra esse
tarball e pode executar QA do Telegram contra o mesmo tarball com
`telegram_mode=mock-openai` ou `telegram_mode=live-frontier`.
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 telegram_mode=mock-openai`
- Execute o fluxo de trabalho 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 uma branch/tag/SHA confiável em `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 carregado por outra execução do GitHub Actions. O fluxo de trabalho 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 do pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a linha de base 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`: 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 web da OpenAI e OpenWebUI
- `full`: partes do caminho de release do Docker com OpenWebUI
- `custom`: seleção exata de `docker_lanes` para uma reexecução focada
- Execute o workflow manual `CI` diretamente quando precisar apenas da cobertura completa da CI
normal para o candidato a release. Disparos manuais de CI ignoram o escopo por mudanças
e forçam os shards Linux Node, shards de plugins empacotados, contratos de canal,
compatibilidade com Node 22, `check`, `check-additional`, smoke de build,
verificações de documentação, Skills Python, Windows, macOS, Android e lanes de i18n
da Control UI.
- `package`: lanes nativas do artefato para pacote/atualização/plugin sem OpenWebUI nem ClawHub ao vivo
- `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente, pesquisa web da OpenAI e OpenWebUI
- `full`: partes do caminho de release Docker com OpenWebUI
- `custom`: seleção exata de `docker_lanes` para uma nova execução focada
- Execute diretamente o fluxo de trabalho manual `CI` quando você 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 plugin empacotado, contratos de canal, 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 dos 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 toda release marcada com tag
- As verificações de release agora rodam em um workflow manual separado:
- Execute `pnpm qa:otel:smoke` ao validar a telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes dos 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 todo release com tag
- As verificações de release agora são executadas em um fluxo de trabalho manual separado:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` também executa o gate de paridade mock do QA Lab mais o perfil Matrix
live rápido e a lane de QA do Telegram antes da aprovação de release. As lanes live
usam o ambiente `qa-live-shared`; o Telegram também usa concessões de credenciais
Convex CI. Execute o workflow manual `QA-Lab - All Lanes` com
`matrix_profile=all` e `matrix_shards=true` quando quiser 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
`OpenClaw Release Checks` públicos e do `Full Release Validation`, que chamam o
workflow reutilizável
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` diretamente
- 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 não atrasar nem bloquear a publicação
- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release
Validation` ou a partir da referência 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 ou tag de release do OpenClaw
- O preflight somente de validação de `OpenClaw NPM Release` também aceita o SHA completo
atual de 40 caracteres do commit da branch do workflow sem exigir uma tag enviada
- Esse caminho por SHA é somente para 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 no GitHub,
enquanto o caminho de validação sem mutação 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`
- `OpenClaw Release Checks` também executa o gate de paridade mock do QA Lab, além do perfil Matrix live rápido 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 concessões de credenciais de CI do Convex. Execute o fluxo de trabalho manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser 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 públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o fluxo de trabalho 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 ficam na própria lane 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 da ref de fluxo de trabalho `main`/release para que a lógica do fluxo de trabalho 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 ou tag de release do OpenClaw
- O preflight somente de validação de `OpenClaw NPM Release` também aceita o SHA completo de 40 caracteres do commit atual da branch do fluxo de trabalho sem exigir uma tag enviada
- Esse caminho por SHA é somente de validação e não pode ser promovido para uma publicação real
- No modo SHA, o fluxo de trabalho sintetiza `v<package.json version>` somente para a verificação de metadados do pacote; a publicação real ainda exige uma tag de release real
- Ambos os fluxos de trabalho mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação sem mutações pode usar os runners Linux maiores do Blacksmith
- Esse fluxo de trabalho executa `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` usando os segredos de fluxo de trabalho `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
- 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 do registro
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 o 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 avulsas locais de mantenedores podem omitir as vars Convex e passar as três
credenciais de ambiente `OPENCLAW_QA_TELEGRAM_*` diretamente.
- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions pelo
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-promoção:
- 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
- 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 do registro 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 o onboarding do pacote instalado, a configuração do Telegram e o E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais Telegram concedidas. Execuções locais avulsas de mantenedores podem omitir as variáveis do Convex e passar diretamente as três credenciais de ambiente `OPENCLAW_QA_TELEGRAM_*`.
- Mantenedores podem executar a mesma verificação pós-publicação pelo GitHub Actions por meio do fluxo de trabalho manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não é executado em todo merge.
- A automação de release dos mantenedores agora usa preflight e depois promoção:
- 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 da mesma 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 por input do workflow
- a mutação de dist-tag do 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 com OIDC
- `macOS Release` público é somente validação
- 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 estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação
também verifica 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 de `dist/control-ui/assets/`
para que não enviemos novamente um painel de navegador vazio
- A verificação pós-publicação também verifica que a instalação do registro publicado
contém dependências de runtime não vazias de plugins empacotados sob o layout raiz `dist/*`.
Uma release enviada com payloads ausentes ou vazios de dependências de plugins empacotados
falha no verificador pós-publicação e não pode ser promovida para `latest`.
- `pnpm test:install:smoke` também aplica o orçamento de `unpackedSize` do pacote npm no
tarball candidato de atualização, para que o e2e do instalador capture inchaço acidental do pacote
antes do caminho de publicação da release
- Se o trabalho de release tocou planejamento de CI, manifestos de timing de plugins ou
matrizes de teste de plugins, regenere e revise as saídas de matriz
`plugin-prerelease-extension-shard` pertencentes ao planejador em
`.github/workflows/plugin-prerelease.yml` antes da aprovação para que as notas de release não
descrevam um layout de CI desatualizado
- A prontidão de release estável para macOS também inclui as superfícies do atualizador:
- a release do GitHub deve acabar com os pacotes `.zip`, `.dmg` e `.dSYM.zip`
- `appcast.xml` em `main` deve apontar para o novo zip estável depois da 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 acima do piso canônico de build do Sparkle
para essa versão de release
- a publicação npm estável pode mirar explicitamente em `latest` via entrada do fluxo de trabalho
- 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 apenas por OIDC
- o `macOS Release` público é somente de validação; quando uma tag existe apenas em uma branch de release, mas o fluxo de trabalho é 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 estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação também verifica o mesmo caminho de upgrade 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 `dist/control-ui/index.html` e 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 verifica se a instalação publicada do registro contém dependências de runtime não vazias dos plugins empacotados no layout raiz `dist/*`. Um release entregue com payloads ausentes ou vazios de dependências de plugins empacotados 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 aumento acidental de tamanho do pacote antes do caminho de publicação do release
- Se o trabalho de release tocou no planejamento de CI, manifests de tempo de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard` pertencentes ao planejador 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 do release estável para macOS também inclui as superfícies do 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 ID de bundle não debug, uma URL de feed do Sparkle não vazia e um `CFBundleVersion` no piso canônico de build do Sparkle, ou acima dele, 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. Execute-o a partir da referência confiável de workflow `main` e passe a branch
de release, tag ou SHA completo de commit como `ref`:
`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Execute-o a partir da ref confiável de fluxo de trabalho `main` e passe a branch de release, tag ou SHA completo de commit como `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -243,43 +160,23 @@ gh workflow run full-release-validation.yml \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=full \
-f release_profile=stable \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
O workflow resolve a referência alvo, dispara `CI` manual com
`target_ref=<release-ref>`, dispara `OpenClaw Release Checks` e
opcionalmente dispara E2E autônomo pós-publicação do Telegram quando
`npm_telegram_package_spec` estiver definido. `OpenClaw Release Checks` então expande para
smoke de instalação, verificações de release entre sistemas operacionais, cobertura live/E2E do caminho de release do Docker,
Package Acceptance com QA de pacote do 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, e qualquer filho opcional
`npm_telegram` está bem-sucedido ou foi intencionalmente ignorado. 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.
Workflows filhos são disparados a partir da referência confiável que executa `Full Release
Validation`, normalmente `--ref main`, mesmo quando o `ref` alvo aponta para uma
branch ou tag de release mais antiga. Não há input separado de referência de workflow para Full Release Validation;
escolha o harness confiável escolhendo a referência da execução do workflow.
O fluxo de trabalho resolve a ref de destino, dispara `CI` manual com `target_ref=<release-ref>`, dispara `OpenClaw Release Checks` e, opcionalmente, dispara E2E Telegram pós-publicação independente quando `npm_telegram_package_spec` está definido. `OpenClaw Release Checks` então distribui install smoke, verificações de release entre sistemas operacionais, cobertura live/E2E do caminho de release Docker, Package Acceptance com QA de 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, e qualquer filho opcional `npm_telegram` está bem-sucedido ou foi pulado intencionalmente. 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 estágios, nomes exatos dos jobs de fluxo de trabalho, diferenças entre perfis estável e completo, artefatos e identificadores de nova execução focada.
Fluxos de trabalho filhos são disparados a partir da ref confiável que executa `Full Release Validation`, normalmente `--ref main`, mesmo quando o `ref` de destino aponta para uma branch ou tag de release mais antiga. Não há entrada separada de ref de fluxo de trabalho para Full Release Validation; escolha o harness confiável escolhendo a ref de execução do fluxo de trabalho.
Use `release_profile` para selecionar a amplitude live/provedor:
- `minimum`: caminho live e Docker OpenAI/core crítico para release mais rápido
- `minimum`: caminho live e Docker mais rápido e crítico para release em OpenAI/core
- `stable`: mínimo mais cobertura estável de provedor/backend para aprovação de release
- `full`: estável mais cobertura ampla consultiva de provedor/mídia
- `full`: estável mais cobertura ampla de provedores/mídia consultivos
`OpenClaw Release Checks` usa a referência confiável de workflow para resolver a referência alvo
uma vez como `release-package-under-test` e reutiliza esse artefato tanto nas
verificações Docker de caminho de release quanto em Package Acceptance. Isso mantém todas as
caixas voltadas a pacote nos mesmos bytes e evita builds repetidos de pacote.
O smoke de instalação OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a
variável do repositório/org está definida; caso contrário, `openai/gpt-5.4-mini`, porque essa lane está
provando instalação do pacote, onboarding, inicialização do Gateway e uma rodada 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 de modelo.
`OpenClaw Release Checks` usa a referência de workflow confiável para resolver a referência de destino uma vez como `release-package-under-test` e reutiliza esse artefato tanto nas verificações Docker de caminho de lançamento quanto no Package Acceptance. Isso mantém todas as caixas voltadas a pacotes nos mesmos bytes e evita compilações repetidas de pacotes. A verificação rápida de instalação OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a variável de repo/organização está definida; caso contrário, usa `openai/gpt-5.4-mini`, porque esta lane comprova a instalação do pacote, o onboarding, a inicialização do gateway e uma interação de agente ao vivo, em vez de benchmarkar o modelo padrão mais lento. A matriz mais ampla de provedores ao vivo continua sendo o lugar para cobertura específica de modelos.
Use estas variantes dependendo do estágio da release:
Use estas variantes dependendo do estágio do lançamento:
```bash
# Validate an unpublished release candidate branch.
@ -308,40 +205,22 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Não use o guarda-chuva completo como a primeira reexecução após uma correção focada. Se um bloco
falhar, use o fluxo de trabalho 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 release ou tornado obsoletas as evidências
anteriores de todos os blocos. O verificador final do guarda-chuva verifica novamente os IDs registrados
das execuções dos fluxos de trabalho filhos; portanto, depois que um fluxo de trabalho filho for reexecutado
com sucesso, reexecute somente o job pai `Verify full validation` que falhou.
Não use o guarda-chuva completo como a primeira reexecuçã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 comprovação. Execute o guarda-chuva completo novamente apenas quando a correção alterar a orquestração compartilhada de lançamento ou tornar obsoletas as evidências anteriores de todas as caixas. O verificador final do guarda-chuva revalida os IDs registrados das execuções de workflows filhos; portanto, depois que um workflow filho for reexecutado com sucesso, reexecute apenas o job pai `Verify full validation` que falhou.
Para recuperação limitada, passe `rerun_group` para o guarda-chuva. `all` é a execução real
do candidato a release, `ci` executa somente o filho normal de CI, `plugin-prerelease`
executa somente o filho de Plugin exclusivo de release, `release-checks` executa todos os
blocos de release, e os grupos de release mais restritos são `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` e `npm-telegram` quando a
lane autônoma de pacote Telegram é fornecida.
Para recuperação delimitada, passe `rerun_group` para o 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 restritos são `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` e `npm-telegram` quando a lane Telegram de pacote independente é fornecida.
### Vitest
O bloco Vitest é o fluxo de trabalho filho manual `CI`. A CI manual intencionalmente
ignora o escopo de alterações e força o grafo normal de testes para o candidato a
release: 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 caixa Vitest é o workflow filho manual `CI`. O CI manual ignora intencionalmente o escopo por alterações e força o grafo de testes normal para o candidato a lançamento: shards Linux Node, shards de plugins empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de documentação, Skills em Python, Windows, macOS, Android e i18n da Control UI.
Use este bloco para responder "a árvore de código-fonte passou pela suíte de testes normal completa?"
Ele não é o mesmo que validação de produto do caminho de release. Evidências a manter:
Use esta caixa para responder “a árvore de código-fonte passou no conjunto completo de testes normal?” Ela não é o mesmo que a validação de produto pelo caminho de lançamento. Evidências a manter:
- resumo de `Full Release Validation` mostrando a URL da execução `CI` disparada
- execução `CI` verde no SHA de destino exato
- nomes de shards com falha ou lentos dos jobs de CI ao investigar regressões
- artefatos de tempo do Vitest, como `.artifacts/vitest-shard-timings.json`, quando
uma execução precisar de análise de desempenho
- artefatos de tempo do Vitest, como `.artifacts/vitest-shard-timings.json`, quando uma execução precisa de análise de desempenho
Execute a CI manual diretamente somente quando o release precisar de CI normal determinística, mas
não dos blocos Docker, QA Lab, live, entre sistemas operacionais ou de pacote:
Execute o CI manual diretamente apenas quando o lançamento precisar de CI normal determinístico, mas não das caixas Docker, QA Lab, ao vivo, entre sistemas operacionais ou de pacote:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -349,104 +228,50 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
O bloco Docker fica em `OpenClaw Release Checks` por meio de
`openclaw-live-and-e2e-checks-reusable.yml`, além do fluxo de trabalho
`install-smoke` em modo de release. Ele valida o candidato a release por meio de ambientes
Docker empacotados, em vez de apenas testes no nível de código-fonte.
A caixa Docker vive 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 no nível do código-fonte.
A cobertura Docker de release inclui:
A cobertura Docker de lançamento inclui:
- smoke completo de instalação com o smoke lento de instalação global do Bun habilitado
- preparação/reuso da imagem de smoke do Dockerfile raiz por SHA de destino, com jobs de smoke
de QR, raiz/Gateway e instalador/Bun executados como shards install-smoke separados
- smoke de instalação 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 smoke de QR, raiz/gateway e instalador/Bun executando como shards install-smoke separados
- lanes E2E do repositório
- chunks Docker do 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`,
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
`plugins-runtime-install-g`, `plugins-runtime-install-h`,
`bundled-channels-core`, `bundled-channels-update-a`,
`bundled-channels-update-discord`, `bundled-channels-update-b` e
`bundled-channels-contracts`
- chunks Docker do caminho de lançamento: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `plugins-runtime-install-c`, `plugins-runtime-install-d`, `plugins-runtime-install-e`, `plugins-runtime-install-f`, `plugins-runtime-install-g`, `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` e `bundled-channels-contracts`
- cobertura do OpenWebUI dentro do chunk `plugins-runtime-services` quando solicitada
- lanes de dependências de canais agrupados divididas entre chunks de channel-smoke, update-target
e contratos de setup/runtime, em vez de um único job grande de canais agrupados
- lanes de instalação/desinstalação de Plugins agrupados divididas de
`bundled-plugin-install-uninstall-0` até
`bundled-plugin-install-uninstall-23`
- suítes de provedores live/E2E e cobertura de modelo live Docker quando as verificações de release
incluem suítes live
- lanes divididas de dependências de canais empacotados entre chunks de channel-smoke, update-target e contratos de setup/runtime, em vez de um grande job único de canais empacotados
- lanes divididas de instalação/desinstalação de plugins empacotados de `bundled-plugin-install-uninstall-0` até `bundled-plugin-install-uninstall-23`
- suítes de provedores ao vivo/E2E e cobertura Docker de modelos ao vivo quando as verificações de lançamento incluem suítes ao vivo
Use artefatos Docker antes de reexecutar. O agendador do caminho de release envia
`.artifacts/docker-tests/` com logs de lanes, `summary.json`, `failures.json`,
tempos de fases, JSON do plano do agendador e comandos de reexecução. Para recuperação focada,
use `docker_lanes=<lane[,lane]>` no fluxo de trabalho reutilizável live/E2E em vez de
reexecutar todos os chunks de release. Os comandos de reexecução gerados incluem
`package_artifact_run_id` anterior e entradas de imagens Docker preparadas quando disponíveis, para que uma
lane com falha possa reutilizar o mesmo tarball e as imagens GHCR.
Use artefatos Docker antes de reexecutar. O agendador de caminho de lançamento envia `.artifacts/docker-tests/` com logs de lanes, `summary.json`, `failures.json`, tempos de fases, JSON do plano do agendador e comandos de reexecução. Para recuperação focada, use `docker_lanes=<lane[,lane]>` no workflow reutilizável ao vivo/E2E, em vez de reexecutar todos os chunks de lançamento. Os comandos de reexecução gerados incluem `package_artifact_run_id` anterior e entradas de imagem Docker preparada quando disponíveis, para que uma lane com falha possa reutilizar o mesmo tarball e as imagens GHCR.
### QA Lab
O bloco QA Lab também faz parte de `OpenClaw Release Checks`. Ele é o gate de release de
comportamento agentivo e nível de canal, separado do Vitest e da mecânica de pacotes Docker.
A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de lançamento de comportamento agêntico e no nível de canais, separado do Vitest e da mecânica de pacote Docker.
A cobertura de QA Lab de release inclui:
A cobertura QA Lab de lançamento inclui:
- gate 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 leases de credenciais Convex CI
- `pnpm qa:otel:smoke` quando a telemetria de release precisa de prova local explícita
- gate de paridade mock comparando a lane candidata OpenAI com a linha de base Opus 4.6 usando o pacote de paridade agêntica
- perfil de QA Matrix ao vivo rápido usando o ambiente `qa-live-shared`
- lane QA Telegram ao vivo usando concessões de credenciais Convex CI
- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de comprovação local explícita
Use este bloco para responder "o release se comporta corretamente em cenários de QA e
fluxos de canais live?" Mantenha as URLs dos artefatos das lanes de paridade, Matrix e Telegram
ao aprovar o release. A cobertura Matrix completa continua disponível como uma execução manual
fragmentada do QA-Lab, em vez da lane crítica de release padrão.
Use esta caixa para responder “o lançamento se comporta corretamente em cenários de QA e fluxos de canais ao vivo?” Mantenha as URLs dos artefatos das lanes de paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura Matrix completa permanece disponível como uma execução manual QA-Lab em shards, em vez da lane crítica padrão de lançamento.
### Pacote
O bloco Package é o gate de produto instalável. Ele é baseado em
`Package Acceptance` e no 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 fluxo de trabalho separada da ref de origem do pacote.
A caixa Pacote é o gate de produto instalável. Ela é apoiada por `Package Acceptance` e pelo resolvedor `scripts/resolve-openclaw-package-candidate.mjs`. O resolvedor normaliza um candidato para o 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 referência do harness do workflow separada da referência de origem do pacote.
Fontes de candidato compatíveis:
- `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 confiável em `package_ref`
com o harness `workflow_ref` selecionado
- `source=url`: baixar um `.tgz` HTTPS com `package_sha256` obrigatório
- `source=artifact`: reutilizar um `.tgz` enviado por outra execução do GitHub Actions
- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw
- `source=ref`: empacota 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
`OpenClaw Release Checks` executa Package Acceptance com `source=ref`,
`package_ref=<release-ref>`, `suite_profile=custom`,
`docker_lanes=bundled-channel-deps-compat plugins-offline` e
`telegram_mode=mock-openai`. Os chunks Docker do caminho de release cobrem as
lanes sobrepostas de instalação, atualização e atualização de Plugin; Package Acceptance mantém
compatibilidade de canais agrupados nativa de artefatos, fixtures offline de Plugins e QA de pacote
Telegram contra o mesmo tarball resolvido. Ele é a substituição nativa do GitHub
para a maior parte da cobertura de pacote/atualização que anteriormente exigia
Parallels. As verificações de release entre sistemas operacionais ainda importam para onboarding,
instalador e comportamento específico de plataforma, mas a validação de produto de pacote/atualização deve
preferir Package Acceptance.
`OpenClaw Release Checks` executa Package Acceptance com `source=ref`, `package_ref=<release-ref>`, `suite_profile=custom`, `docker_lanes=bundled-channel-deps-compat plugins-offline` e `telegram_mode=mock-openai`. Os chunks Docker do caminho de lançamento cobrem as lanes sobrepostas de instalação, atualização e atualização de plugins; Package Acceptance mantém compatibilidade de canais empacotados nativa de artefato, fixtures de plugins offline e QA de pacote Telegram contra o mesmo tarball resolvido. 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.
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 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 registro 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 publicado `2026.4.26` pode avisar
sobre arquivos de carimbo de metadados de build local que já foram enviados. Pacotes posteriores
devem satisfazer os contratos de pacote modernos; essas mesmas lacunas falham a validação de
release.
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 do tarball, `gateway install --wrapper` ausente, arquivos de patch ausentes no fixture git derivado do tarball, `update.channel` persistido ausente, locais legados de registros de instalação de plugins, persistência ausente de registros 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 locais de carimbo de metadados de build que já foram enviados. Pacotes posteriores devem satisfazer os contratos de pacote modernos; essas mesmas lacunas fazem a validação de lançamento falhar.
Use perfis mais amplos de Package Acceptance quando a pergunta do release for sobre um
pacote instalável real:
Use perfis mais amplos de Package Acceptance quando a pergunta de lançamento for sobre um pacote realmente instalável:
```bash
gh workflow run package-acceptance.yml \
@ -454,90 +279,76 @@ gh workflow run package-acceptance.yml \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@beta \
-f suite_profile=product
-f suite_profile=product \
-f published_upgrade_survivor_baseline=openclaw@2026.4.26
```
Perfis comuns de pacote:
- `smoke`: lanes rápidas de instalação/canal/agente de pacote, rede do Gateway e recarregamento
de configuração
- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub live; este é o padrão
de release-check
- `product`: `package` mais canais MCP, limpeza de Cron/subagente, pesquisa web OpenAI
e OpenWebUI
- `full`: chunks Docker do caminho de release com OpenWebUI
- `smoke`: lanes rápidas de instalação de pacote/canal/agente, rede de gateway e recarregamento de configuração
- `package`: contratos de pacote de instalação/atualização/plugin sem ClawHub ao vivo; este é o padrão de release-check
- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa web OpenAI e OpenWebUI
- `full`: chunks Docker do caminho de lançamento com OpenWebUI
- `custom`: lista exata de `docker_lanes` para reexecuções focadas
Para prova Telegram de candidato a pacote, habilite `telegram_mode=mock-openai` ou
`telegram_mode=live-frontier` em Package Acceptance. O fluxo de trabalho passa o
tarball `package-under-test` resolvido para a lane Telegram; o fluxo de trabalho Telegram
autônomo ainda aceita uma especificação npm publicada para verificações pós-publicação.
Para comprovação 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 Telegram; o workflow Telegram independente ainda aceita uma especificação npm publicada para verificações pós-publicação.
## Entradas do fluxo de trabalho NPM
## Entradas do workflow NPM
`OpenClaw NPM Release` aceita estas entradas controladas pelo operador:
- `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 completo
de commit de 40 caracteres da branch atual do fluxo de trabalho para preflight apenas de validação
- `preflight_only`: `true` para validação/build/pacote somente, `false` para o
caminho real de publicação
- `preflight_run_id`: obrigatório no caminho real de publicação para que o fluxo de trabalho reutilize
o tarball preparado da execução de preflight bem-sucedida
- `npm_dist_tag`: tag de destino npm para o caminho de publicação; o padrão é `beta`
- `tag`: tag de lançamento 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 completo de commit de 40 caracteres atual da branch de workflow para preflight apenas de validação
- `preflight_only`: `true` para validação/build/pacote apenas, `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
- `npm_dist_tag`: tag npm de destino para o caminho de publicação; o padrão é `beta`
`OpenClaw Release Checks` aceita estas entradas controladas pelo operador:
- `ref`: branch, tag ou SHA completo de commit a validar. Verificações com segredos
exigem que o commit resolvido seja alcançável a partir de uma branch ou
tag de release do OpenClaw.
- `ref`: branch, tag ou SHA completo de commit a validar. Verificações com segredos exigem que o commit resolvido seja alcançável a partir de uma branch ou tag de lançamento do OpenClaw.
Regras:
- Tags estáveis e de correção podem publicar em `beta` ou `latest`
- Tags de pré-release beta podem publicar somente em `beta`
- Para `OpenClaw NPM Release`, entrada de SHA completo de commit é permitida somente quando
`preflight_only=true`
- `OpenClaw Release Checks` e `Full Release Validation` são sempre
somente de validação
- O caminho real de publicação deve usar o mesmo `npm_dist_tag` usado durante o preflight;
o fluxo de trabalho verifica esses metadados antes de a publicação continuar
- Tags beta de pré-lançamento podem publicar apenas em `beta`
- Para `OpenClaw NPM Release`, entrada de SHA completo de commit é permitida apenas quando `preflight_only=true`
- `OpenClaw Release Checks` e `Full Release Validation` são sempre apenas 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 que a publicação continue
## Sequência de release npm estável
## Sequência de lançamento npm estável
Ao cortar um release npm estável:
Ao preparar um lançamento npm estável:
1. Execute `OpenClaw NPM Release` com `preflight_only=true`
- Antes de existir uma tag, você pode usar o SHA completo de commit atual da branch do fluxo de trabalho
para uma simulação apenas de validação do fluxo de trabalho de preflight
2. Escolha `npm_dist_tag=beta` para o fluxo normal beta-first, 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 completo
de commit quando quiser CI normal mais cache de prompts live, Docker, QA Lab,
Matrix e cobertura Telegram a partir de um fluxo de trabalho manual
4. Se você intencionalmente precisar apenas do grafo de testes normal determinístico, execute o
fluxo de trabalho manual `CI` na ref de release
- Antes que uma tag exista, você pode usar o SHA completo atual do commit da branch do fluxo de trabalho
para uma execução simulada apenas de validação do fluxo de trabalho de preflight
2. Escolha `npm_dist_tag=beta` para o fluxo normal com beta primeiro, ou `latest` somente
quando você quiser intencionalmente uma publicação estável direta
3. Execute `Full Release Validation` na branch de lançamento, tag de lançamento ou SHA completo
do commit quando quiser CI normal mais cache de prompts ao vivo, Docker, QA Lab,
Matrix e cobertura do Telegram a partir de um fluxo de trabalho manual
4. Se você intencionalmente precisa apenas do grafo de testes normal determinístico, execute o
fluxo de trabalho manual `CI` na referência de lançamento em vez disso
5. Salve o `preflight_run_id` bem-sucedido
6. Execute `OpenClaw NPM Release` novamente com `preflight_only=false`, a mesma
`tag`, o mesmo `npm_dist_tag` e o `preflight_run_id` salvo
7. Se o release foi lançado em `beta`, use o fluxo de trabalho privado
7. Se o lançamento chegou em `beta`, use o fluxo de trabalho 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 release foi publicado intencionalmente diretamente em `latest` e `beta`
deve seguir o mesmo build estável imediatamente, use esse mesmo fluxo de trabalho privado
para apontar ambas as dist-tags para a versão estável, ou deixe a sincronização agendada
8. Se o lançamento foi publicado intencionalmente diretamente em `latest` e `beta`
deve seguir a mesma build estável imediatamente, use esse mesmo fluxo de trabalho privado
para apontar ambas as dist-tags para a versão estável, ou deixe a sincronização programada
de autocorreção mover `beta` posteriormente
A mutação de dist-tag fica no repositório privado por segurança, porque ela ainda
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 somente com OIDC.
Isso mantém o caminho de publicação direta e o caminho de promoção beta-first ambos
documentados e visíveis ao operador.
Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção com beta primeiro
documentados e visíveis para o operador.
Se um mantenedor precisar recorrer à autenticação npm local, execute qualquer comando da
CLI (`op`) do 1Password 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 tratamento de OTP observáveis e evita alertas repetidos do host.
Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos da CLI
do 1Password (`op`) 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
@ -553,7 +364,7 @@ alertas e o tratamento de OTP observáveis e evita alertas repetidos do host.
Os mantenedores usam a documentação privada de lançamento em
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
como o roteiro operacional real.
para o runbook real.
## Relacionado

172
docs/pt-BR/reference/full-release-validation.md Normal file
View File

@ -0,0 +1,172 @@
---
read_when:
- Executando ou reexecutando a validação completa do lançamento
- Comparando os perfis estável e completo de validação de lançamento
- Depuração de 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 do lançamento
x-i18n:
generated_at: "2026-05-01T05:58:50Z"
model: gpt-5.5
provider: openai
source_hash: dcbfafd744437c160c09a9c508a639781549193669b300e5249023f9f5dd4afe
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` é o guarda-chuva da versão. Ele é o único ponto de entrada
manual para a prova de pré-lançamento, mas a maior parte do trabalho acontece em
workflows filhos para que uma caixa com falha possa ser executada novamente sem
reiniciar a versão inteira.
Execute-o a partir de uma ref de workflow confiável, normalmente `main`, e passe
o branch de versão, a tag ou o SHA completo do commit como `ref`:
```bash
gh workflow run full-release-validation.yml \
--ref main \
-f ref=release/YYYY.M.D \
-f provider=openai \
-f mode=both \
-f release_profile=stable
```
Os workflows filhos usam a ref de workflow 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 um branch ou uma tag de versão mais antiga.
## Estágios de nível superior
| Estágio | Detalhes |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resolução do alvo | **Job:** `Resolve target ref`<br />**Workflow filho:** nenhum<br />**Prova:** resolve o branch de versão, a tag ou o SHA completo do commit e registra as entradas selecionadas.<br />**Executar novamente:** execute novamente o guarda-chuva se isso falhar. |
| Vitest e CI normal | **Job:** `Run normal full CI`<br />**Workflow filho:** `CI`<br />**Prova:** grafo de CI completo manual contra a ref alvo, incluindo lanes de Node no Linux, shards de plugins incluídos, 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 via guarda-chuva.<br />**Executar novamente:** `rerun_group=ci`. |
| Pré-lançamento de Plugin | **Job:** `Run plugin prerelease validation`<br />**Workflow filho:** `Plugin Prerelease`<br />**Prova:** verificações estáticas de plugins somente de versão, cobertura de plugins agênticos, shards de lote completo de extensões e lanes Docker de pré-lançamento de plugins.<br />**Executar novamente:** `rerun_group=plugin-prerelease`. |
| Verificações de versão | **Job:** `Run release/live/Docker/QA validation`<br />**Workflow filho:** `OpenClaw Release Checks`<br />**Prova:** smoke de instalação, verificações de pacote entre sistemas operacionais, suítes live/E2E, partes do caminho de versão Docker, Package Acceptance, paridade do QA Lab, Matrix live e Telegram live.<br />**Executar novamente:** `rerun_group=release-checks` ou um handle mais estreito de release-checks. |
| Telegram pós-publicação | **Job:** `Run post-publish Telegram E2E`<br />**Workflow filho:** `NPM Telegram Beta E2E`<br />**Prova:** prova opcional do Telegram com pacote publicado quando `npm_telegram_package_spec` está definido.<br />**Executar novamente:** `rerun_group=npm-telegram`. |
| Verificador do guarda-chuva | **Job:** `Verify full validation`<br />**Workflow filho:** nenhum<br />**Prova:** verifica novamente as conclusões registradas das execuções filhas e acrescenta tabelas dos jobs mais lentos dos workflows filhos.<br />**Executar novamente:** execute novamente apenas este job depois de executar novamente 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 já tenha
disparado. Execuções de validação de branch e tag de versão não se cancelam entre
si por padrão.
## Estágios das verificações de versão
`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
voltados a pacotes ou Docker precisam dele.
| Estágio | Detalhes |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Alvo da versão | **Job:** `Resolve target ref`<br />**Workflow de suporte:** nenhum<br />**Testes:** ref selecionada, SHA esperado opcional, perfil, grupo de reexecução e filtro focado de suíte live.<br />**Executar novamente:** `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 envia `release-package-under-test` para verificações downstream voltadas a pacotes.<br />**Executar novamente:** o grupo de pacote, cross-OS ou live/E2E afetado. |
| 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 via Bun e E2E Docker rápido de plugins incluídos.<br />**Executar novamente:** `rerun_group=install-smoke`. |
| Cross-OS | **Job:** `cross_os_release_checks`<br />**Workflow de suporte:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Testes:** lanes frescas e de upgrade em Linux, Windows e macOS para o provedor e modo selecionados, usando o tarball candidato mais um pacote de baseline.<br />**Executar novamente:** `rerun_group=cross-os`. |
| E2E de repo e live | **Job:** `Run repo/live E2E validation`<br />**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testes:** E2E de repositório, cache live, streaming websocket da OpenAI, shards de provedor live nativo e plugins, e harnesses live com Docker para modelo/backend/Gateway selecionados por `release_profile`.<br />**Executar novamente:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. |
| Caminho de versão Docker | **Job:** `Run Docker release-path validation`<br />**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Testes:** partes Docker do caminho de versão contra o artefato de pacote compartilhado.<br />**Executar novamente:** `rerun_group=live-e2e`. |
| Package Acceptance | **Job:** `Run package acceptance`<br />**Workflow de suporte:** `Package Acceptance`<br />**Testes:** compatibilidade de dependências de canal incluído nativas do artefato, fixtures offline de pacote de plugin e aceitação de pacote Telegram com OpenAI simulada contra o mesmo tarball.<br />**Executar novamente:** `rerun_group=package`. |
| Paridade 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 do baseline, depois o relatório de paridade.<br />**Executar novamente:** `rerun_group=qa-parity` ou `rerun_group=qa`. |
| Matrix live QA | **Job:** `Run QA Lab live Matrix lane`<br />**Workflow de suporte:** job direto<br />**Testes:** perfil QA rápido da Matrix live no ambiente `qa-live-shared`.<br />**Executar novamente:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Telegram live QA | **Job:** `Run QA Lab live Telegram lane`<br />**Workflow de suporte:** job direto<br />**Testes:** QA live do Telegram com concessões de credenciais Convex CI.<br />**Executar novamente:** `rerun_group=qa-live` ou `rerun_group=qa`. |
| Verificador de versão | **Job:** `Verify release checks`<br />**Workflow de suporte:** nenhum<br />**Testes:** jobs obrigatórios de release-check para o grupo de reexecução selecionado.<br />**Executar novamente:** execute novamente após os jobs filhos focados passarem. |
## Partes do caminho de versão Docker
O estágio de caminho de versão Docker executa estas partes quando `live_suite_filter`
está vazio:
| Parte | Cobertura |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Lanes smoke do caminho de versão Docker do core. |
| `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 comportamento de plugin. |
| `plugins-runtime-services` | Lanes de runtime de Plugin com suporte de serviços; 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 versão. |
| `bundled-channels-core` | Comportamento Docker de canal incluído. |
| `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` | Comportamento de atualização de canal incluído. |
| `bundled-channels-contracts` | Verificações de contrato de canal incluído no caminho de versão Docker. |
Use `docker_lanes=<lane[,lane]>` direcionado no workflow live/E2E reutilizável quando
apenas uma lane do Docker falhou. Os artefatos de release incluem comandos de
rerun por lane com entradas de reutilização de artefato de pacote e imagem quando disponíveis.
## Perfis de release
`release_profile` controla apenas a abrangência live/provider dentro das verificações de release. Ele
não remove CI completa normal, pré-release de Plugin, install smoke, aceitação de pacote,
QA Lab nem partes do caminho de release do Docker.
| Perfil | Uso pretendido | Cobertura live/provider 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 Docker OpenAI. |
| `stable` | Perfil padrão de aprovação de release. | `minimum` mais Anthropic, Google, MiniMax, backend, harness de teste live nativo, backend CLI live do Docker, bind ACP do Docker, harness Codex do Docker e um shard smoke OpenCode Go. |
| `full` | Varredura consultiva ampla. | `stable` mais providers consultivos, shards live de Plugin e shards live de mídia. |
## Adições somente full
Estas suítes são ignoradas por `stable` e incluídas por `full`:
| Área | Cobertura somente full |
| --------------------------------- | ------------------------------------------------------------------------------ |
| Modelos live do Docker | OpenCode Go, OpenRouter, xAI, Z.ai e Fireworks. |
| Gateway live do Docker | Shard consultivo para DeepSeek, Fireworks, OpenCode Go, OpenRouter, xAI e Z.ai. |
| Perfis de provider do gateway nativo | 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-opencode-go-smoke`; `full`
usa os shards mais amplos de modelo OpenCode Go em vez disso.
## Reruns focados
Use `rerun_group` para evitar repetir caixas de release não relacionadas:
| Identificador | Escopo |
| ------------------- | ------------------------------------------------- |
| `all` | Todos os estágios de Full Release Validation. |
| `ci` | Apenas o filho de CI completa manual. |
| `plugin-prerelease` | Apenas o filho de pré-release de Plugin. |
| `release-checks` | Todos os estágios de OpenClaw Release Checks. |
| `install-smoke` | Install Smoke até verificações de release. |
| `cross-os` | Verificações de release entre sistemas operacionais. |
| `live-e2e` | Validação de E2E repo/live e caminho de release do Docker. |
| `package` | Package Acceptance. |
| `qa` | Paridade de QA mais lanes live de QA. |
| `qa-parity` | Apenas lanes de paridade de QA e relatório. |
| `qa-live` | Apenas Matrix live de QA e Telegram. |
| `npm-telegram` | Apenas E2E opcional de Telegram pós-publicação. |
Use `live_suite_filter` com `rerun_group=live-e2e` quando uma suíte live falhar.
Os ids de filtro válidos são definidos no workflow live/E2E reutilizável, 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`.
## Evidência a manter
Mantenha o resumo `Full Release Validation` como índice no 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 faça rerun do menor identificador correspondente acima.
Artefatos úteis:
- `release-package-under-test` de `OpenClaw Release Checks`
- Artefatos do caminho de release do Docker em `.artifacts/docker-tests/`
- `package-under-test` de Package Acceptance e artefatos de aceitação do Docker
- Artefatos de verificações de release entre sistemas operacionais para cada sistema operacional e suíte
- Artefatos de paridade de QA, Matrix e Telegram
## Arquivos de workflow
- `.github/workflows/full-release-validation.yml`
- `.github/workflows/openclaw-release-checks.yml`
- `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml`
- `.github/workflows/plugin-prerelease.yml`
- `.github/workflows/install-smoke.yml`
- `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- `.github/workflows/package-acceptance.yml`

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

@ -1,59 +1,60 @@
---
read_when:
- Executando ou corrigindo testes
summary: Como executar testes localmente (vitest) e quando usar os modos de força/cobertura
summary: Como executar testes localmente (vitest) e quando usar os modos forçado/cobertura
title: Testes
x-i18n:
generated_at: "2026-04-30T18:38:33Z"
generated_at: "2026-05-01T05:58:36Z"
model: gpt-5.5
provider: openai
source_hash: 131f2bad3b2806d28394213cec38d632d106ddbf8ff04d06345ab8046fb8bcf2
source_hash: 4d50f77fdb8dcf7153c59d1bd9f3d61d745ba17ea846eb0610d0f064ad0d1761
source_path: reference/test.md
workflow: 16
---
- Kit completo de testes (suítes, ao vivo, Docker): [Testes](/pt-BR/help/testing)
- `pnpm test:force`: Encerra qualquer processo de 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 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 unitária com cobertura V8 (via `vitest.unit.config.ts`). Este é um gate de cobertura unitária de 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 arquivos carregados pela suíte de cobertura unitária em vez de tratar cada arquivo-fonte de lane dividida como não coberto.
- `pnpm test:force`: Encerra qualquer processo de Gateway remanescente que esteja ocupando a porta de controle padrão e, em seguida, executa a suíte completa do Vitest com uma porta de Gateway isolada para que os testes de servidor não colidam com uma instância em execução. Use isso 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 de todo o repositório. 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 unitária em vez de tratar todos os arquivos-fonte de lanes divididas como descobertos.
- `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 a partir de edições diretas em testes, arquivos `*.test.ts` irmãos, mapeamentos explícitos de código-fonte e o grafo de imports local. Alterações amplas/de configuração/de pacote são ignoradas, a menos que mapeiem 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 voltar ao comportamento mais amplo de testes alterados do Vitest.
- `pnpm test:changed`: execução barata e inteligente de testes alterados. Ela executa alvos precisos a partir de edições diretas em testes, arquivos `*.test.ts` irmãos, mapeamentos explícitos de origem e o grafo de importação local. Alterações amplas/de configuração/de 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 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 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`: direciona alvos explícitos de arquivo/diretório por lanes Vitest com escopo. Execuções sem alvo usam grupos fixos de shards e se expandem para configurações folha para execução paralela local; o grupo de plugins sempre se expande para as configurações de shard por plugin, 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 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 um `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture de configuração, workspace, diretório de agente ou armazenamento de perfil 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 de CLI, captura de logs e limpeza em um só lugar.
- Helpers de E2E Docker/Bash: lanes que carregam `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 com múltiplos homes 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 ser carregado. 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 mock do OpenAI, inicialização do Gateway em foreground/background, probes de prontidão, exportação de ambiente de estado, dumps de log e limpeza de processos.
- Execuções completas, de plugin e de shard com padrão de inclusão atualizam dados de timing locais 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 local de timing.
- 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 voltar 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 os importam, 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 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 não isolado compartilhado habilitado nas configurações do repositório.
- `pnpm test`: roteia alvos explícitos de arquivo/diretório por lanes Vitest com escopo. Execuções sem alvo usam grupos fixos de shards 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 único processo gigante de projeto raiz.
- As 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 detalhe por shard.
- Estado de teste compartilhado do OpenClaw: use `src/test-utils/openclaw-test-state.ts` 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 perfil 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 Vitest precisar de um Gateway em execução, env de 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 env de 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 mock da OpenAI, lançamento do Gateway em foreground/background, probes de prontidão, exportação de env 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 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 por padrão de inclusão acrescentam o nome do shard à chave de timing, o que mantém os timings de shards filtrados visíveis sem substituir os dados de timing de configuração inteira. Defina `OPENCLAW_TEST_PROJECTS_TIMINGS=0` para ignorar o artefato local de timing.
- 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 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 importadores em vez de executar amplamente todos os shards quando o caminho de 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 test:channels` executa `vitest.channels.config.ts`.
- `pnpm test:extensions` e `pnpm test extensions` executam todos os shards de extensões/plugins. Plugins de canal pesados, o Plugin de navegador e OpenAI executam como shards dedicados; outros grupos de plugins permanecem em lotes. Use `pnpm test extensions/<id>` para uma lane de um Plugin incluído.
- `pnpm test:perf:imports`: habilita relatórios de duração de import e detalhamento de imports do Vitest, ainda usando roteamento de lanes com escopo 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 caminho roteado em modo de alterações contra a execução nativa de projeto raiz para o mesmo diff git commitado.
- `pnpm test:perf:changed:bench -- --worktree` mede o conjunto de alterações da worktree atual sem exigir commit primeiro.
- `pnpm test:extensions` e `pnpm test extensions` executam todos os shards de extensões/plugins. Plugins de canal pesados, o Plugin de navegador e OpenAI são executados como shards dedicados; outros grupos de plugins permanecem agrupados. 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ções do Vitest, ainda usando roteamento por lanes com escopo para alvos explícitos de arquivo/diretório.
- `pnpm test:perf:imports:changed`: o mesmo profiling de importação, mas apenas para arquivos alterados desde `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` executa benchmark do caminho roteado em modo de alterações contra a execução nativa do projeto raiz para o mesmo diff git commitado.
- `pnpm test:perf:changed:bench -- --worktree` executa benchmark do conjunto atual de alterações da worktree sem precisar commitar 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 unitário (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: executa serialmente todas as configurações 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 isto como sua linha de base antes de tentar correções de testes lentos.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: executa serialmente todas as configurações 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 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 do Gateway: opte explicitamente via `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` ou `pnpm test:gateway`.
- `pnpm test:e2e`: Executa testes smoke end-to-end do Gateway (pareamento 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 verbosos.
- `pnpm test:live`: Executa testes live de provider (minimax/zai). Exige chaves de API e `LIVE=1` (ou `*_LIVE_TEST=1` específico do provider) para deixar de ser ignorado.
- `pnpm test:docker:all`: Compila a imagem compartilhada de testes live, empacota o OpenClaw uma vez como tarball npm, compila/reusa uma imagem runner Node/Git básica mais uma imagem funcional que instala esse tarball em `/app` e, em seguida, executa lanes smoke de Docker com `OPENCLAW_SKIP_DOCKER_BUILD=1` por meio de um escalonador 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 único empacotador 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 planejador 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 escalonador para lanes selecionadas, tipos de imagem, necessidades de pacote/imagem live, cenários de estado e verificações de credenciais sem compilar 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 provider 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 provider usam por padrão uma lane pesada por provider 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 de baixo paralelismo, ela ainda pode iniciar a partir de um pool vazio e será executada sozinha até liberar capacidade. O início das lanes é escalonado em 2 segundos por padrão para evitar tempestades de criação no daemon Docker local; sobrescreva com `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. O runner faz preflight do Docker por padrão, limpa contêineres E2E antigos do OpenClaw, emite status de lanes ativas a cada 30 segundos, compartilha caches de ferramentas CLI de provider entre lanes compatíveis, tenta novamente falhas transitórias de provider 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 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 timings. Use `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` apenas para lanes determinísticas/locais ou `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` apenas para lanes de provider live; os aliases de pacote são `pnpm test:docker:local:all` e `pnpm test:docker:live:all`. O modo apenas live combina lanes live principais e finais em um único pool do mais longo para o mais curto, para que buckets de provider possam agrupar 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` esteja definido, e cada lane tem um timeout fallback de 120 minutos, sobrescritível com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lanes live/finais selecionadas usam limites por lane mais rígidos. 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 timings 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`: Compila um contêiner E2E de fonte com Chromium, inicia CDP bruto mais um Gateway isolado, executa `browser doctor --deep` e verifica se snapshots de papel do CDP incluem URLs de links, elementos 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, em seguida, executa um chat real proxyado 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/e2e normais.
- `pnpm test:docker:mcp-channels`: Inicia um contêiner de Gateway com seed e um segundo contêiner cliente que executa `openclaw mcp serve`; em seguida, verifica descoberta de conversas roteadas, leituras de transcrição, metadados de anexos, comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + permissão ao estilo Claude pela ponte stdio real. A asserção de notificação do 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 um fixture sujo de usuário antigo, executa a atualização do pacote mais o doctor não interativo sem chaves de provedor ou canal ao vivo, depois inicia um Gateway de local loopback e verifica se agentes, configuração de canal, listas de permissões de Plugin, arquivos de workspace/sessão, estado obsoleto de runtime-deps de Plugin, inicialização e status de RPC sobrevivem.
- Integração do Gateway: habilite explicitamente 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 Node/Git básica e uma imagem funcional que instala esse tarball em `/app`, e então 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é-construído 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 construído. `scripts/package-openclaw-for-docker.mjs` é o empacotador único local/CI e valida o tarball mais `dist/postinstall-inventory.json` antes de o Docker consumi-lo. 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`; `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 imagens 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 provedores e usa 10 por padrão. 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`; limites de provedores 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 de baixo paralelismo, ela ainda pode iniciar a partir de um pool vazio e será executada sozinha até liberar capacidade. O início das lanes é escalonado em 2 segundos por padrão para evitar tempestades de criação no daemon Docker local; sobrescreva 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 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 o reúso de timings. 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 as lanes live principais e finais em um pool único do mais longo para o mais curto para que buckets de provedores 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` esteja definido, e cada lane tem um timeout fallback de 120 minutos sobrescritível com `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lanes live/finais selecionadas usam limites mais rígidos por lane. Comandos de configuração Docker de backend de 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`: Cria um contêiner E2E de origem com Chromium, inicia CDP bruto mais um Gateway isolado, executa `browser doctor --deep` e verifica que snapshots de papéis CDP incluem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame.
- Probes Docker live de backend de 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 com proxy 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 deve ser considerado estável para 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`, depois verifica descoberta de conversas roteadas, leituras de transcrição, 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 sobre a 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 suja de usuário antigo, executa a atualização do pacote e o doctor não interativo sem chaves de provedor ou canal ao vivo, depois inicia um Gateway de loopback e verifica se agentes, configuração de canal, listas de permissões de Plugin, arquivos de workspace/sessão, estado obsoleto de dependências de runtime de Plugin, 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 ao vivo, configura essa linha de base com uma receita integrada de 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 intenções configuradas, arquivos de workspace/sessão, estado obsoleto de configuração/dependências de runtime de Plugin, inicialização e status RPC sobrevivem ou são reparados corretamente. Substitua a linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`; o Package Acceptance expõe o mesmo valor como `published_upgrade_survivor_baseline`.
## Gate de PR local
## Gate local de PR
Para verificações locais de land/gate de PR, execute:
Para verificações locais de gate/land de PR, execute:
- `pnpm check:changed`
- `pnpm check`
@ -62,27 +63,27 @@ Para verificações locais de land/gate de PR, execute:
- `pnpm test`
- `pnpm check:docs`
Se `pnpm test` apresentar flakes em um host carregado, execute novamente uma vez antes de tratar como regressão; depois, isole com `pnpm test <path/to/test>`. Para hosts com restrição de memória, use:
Se `pnpm test` falhar de forma intermitente em um host carregado, execute novamente uma vez antes de tratar como regressão; depois, isole com `pnpm test <path/to/test>`. Para hosts com memória limitada, use:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
## Bench 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)
Uso:
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
- Env opcionais: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt padrão: “Responda com uma única palavra: ok. Sem pontuação nem texto extra.”
- Env opcional: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt padrão: “Responda com uma única palavra: ok. Sem pontuação ou texto extra.”
Última execução (2025-12-31, 20 execuções):
- minimax mediana 1279ms (mín. 1114, máx. 2431)
- opus mediana 2454ms (mín. 1224, máx. 3170)
## Bench de inicialização da CLI
## Benchmark de inicialização da CLI
Script: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
@ -110,7 +111,7 @@ 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. `--cpu-prof-dir` / `--heap-prof-dir` opcionais 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ódigos de saída/sinais e resumos de RSS máximo para cada comando. Opcionalmente, `--cpu-prof-dir` / `--heap-prof-dir` grava perfis V8 por execução, para que a captura de tempo e de perfil use o mesmo harness.
Convenções de saída salva:
@ -124,21 +125,21 @@ Fixture versionado:
- Atualize com `pnpm test:startup:bench:update`
- Compare os resultados atuais com o fixture usando `pnpm test:startup:bench:check`
## Onboarding E2E (Docker)
## E2E de onboarding (Docker)
Docker é opcional; isso só é necessário para testes de smoke de onboarding em contêiner.
Docker é opcional; isto só é necessário para testes de smoke de onboarding em contêiner.
Fluxo completo de cold-start em um contêiner Linux limpo:
Fluxo completo de inicialização a frio 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 configuração/workspace/sessão, depois 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 e então inicia o Gateway e executa `openclaw health`.
## Smoke de importação de QR (Docker)
Garante que o helper mantido de runtime de QR seja carregado nos runtimes Node Docker compatíveis (Node 24 por padrão, Node 22 compatível):
Garante que o helper mantido de runtime de QR carregue nos runtimes Docker Node compatíveis (Node 24 padrão, Node 22 compatível):
```bash
pnpm test:docker:qr

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

@ -1,40 +1,40 @@
---
read_when:
- Você quer defesa em profundidade contra ataques de SSRF e de reassociação de DNS
- Configurando um proxy direto externo para o tráfego 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
- Você quer defesa em profundidade contra ataques de SSRF e de religação de DNS
- Configurando um proxy de encaminhamento externo para o tráfego de tempo de execução do OpenClaw
summary: Como rotear o tráfego HTTP e WebSocket de tempo de execução do OpenClaw por meio de um proxy de filtragem gerenciado pelo operador
title: Proxy de rede
x-i18n:
generated_at: "2026-04-30T10:09:01Z"
generated_at: "2026-05-01T05:58:58Z"
model: gpt-5.5
provider: openai
source_hash: c4e879f787571410acdda55dcdbb5fd77aef1d24045af5c9208cba51330a70ca
source_hash: 9207d349e4410e38631ae7665be19b536e4a4128a4e80dd095e802804dfd66a3
source_path: security/network-proxy.md
workflow: 16
---
# Proxy de rede
O OpenClaw pode rotear o tráfego HTTP e WebSocket de runtime por meio de um proxy de encaminhamento gerenciado pelo operador. Esta é uma defesa em profundidade opcional para implantações que querem controle central de egresso, proteção mais forte contra SSRF e melhor auditabilidade de rede.
O OpenClaw pode rotear tráfego HTTP e WebSocket de runtime por meio de um proxy direto gerenciado pelo operador. Essa é uma defesa opcional em profundidade para implantações que querem controle central de saída, 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 inclui, 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.
## Por que usar um proxy?
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 até fora do reforço 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 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 de DNS e imediatamente antes de o proxy abrir a conexão upstream.
- Defesa contra DNS rebinding: reduza a lacuna entre uma verificação de DNS no nível da aplicação e a conexão de saída real.
- 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.
- 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 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.
- 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.
O roteamento por proxy é uma barreira de proteção em nível de processo para egresso HTTP e WebSocket normal. Ele dá 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 é um sandbox de rede em nível de sistema operacional e não faz o OpenClaw certificar a política de destino do proxy.
O roteamento por proxy é uma proteção no nível do processo para saída HTTP e WebSocket normal. Ele dá aos operadores um caminho fail-closed para rotear clientes HTTP JavaScript compatíveis por seu próprio proxy de filtragem, mas não é um sandbox de rede no nível do sistema operacional e não faz o OpenClaw certificar a política de destino do proxy.
## Como o OpenClaw roteia tráfego
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos de runtime protegidos como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local` roteiam o egresso HTTP e WebSocket normal pelo proxy configurado:
Quando `proxy.enabled=true` e uma URL de proxy está configurada, processos de runtime protegidos como `openclaw gateway run`, `openclaw node run` e `openclaw agent --local` roteiam a saída HTTP e WebSocket normal pelo proxy configurado:
```text
OpenClaw process
@ -43,27 +43,27 @@ OpenClaw process
WebSocket clients -> operator-managed filtering proxy -> public internet
```
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 estreito para tráfego RPC local loopback do Gateway 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. Solicitações HTTP e WebSocket normais de runtime 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 estreito para tráfego RPC do Gateway de 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 de loopback mesmo quando o proxy do operador bloqueia destinos de loopback. Requisições HTTP e WebSocket normais de runtime ainda usam o proxy configurado.
Internamente, o OpenClaw usa dois hooks de roteamento em nível de processo para este recurso:
Internamente, o OpenClaw usa dois hooks de roteamento no nível do processo para este recurso:
- O roteamento por dispatcher do Undici cobre `fetch`, clientes baseados em undici e transportes que fornecem seu próprio dispatcher do 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.
- O roteamento do dispatcher do Undici cobre `fetch`, clientes baseados em undici e transportes que fornecem seu próprio dispatcher do undici.
- O roteamento do `global-agent` cobre chamadores do núcleo do Node `node:http` e `node:https`, incluindo muitas bibliotecas construídas 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 ligaçã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.
Alguns plugins possuem transportes personalizados que precisam de configuração explícita de proxy mesmo quando existe roteamento no nível do 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 própria URL do proxy precisa usar `http://`. Destinos HTTPS ainda são compatíveis por meio do proxy com `CONNECT` HTTP; isso significa apenas que o OpenClaw espera um listener de proxy direto HTTP simples, como `http://127.0.0.1:3128`.
Enquanto o proxy estiver ativo, o OpenClaw limpa `no_proxy`, `NO_PROXY` e `GLOBAL_AGENT_NO_PROXY`. Essas listas de desvio são baseadas em destino, portanto deixar `localhost` ou `127.0.0.1` nelas permitiria que alvos SSRF de alto risco ignorassem o proxy de filtragem.
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 pulassem o proxy de filtragem.
No desligamento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento de processo em cache.
## Termos de proxy relacionados
## Termos relacionados a proxy
- `proxy.enabled` / `proxy.proxyUrl`: roteamento por proxy de encaminhamento de saída para egresso de runtime do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso sensível à identidade de entrada para acesso ao Gateway. Consulte [autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
- `proxy.enabled` / `proxy.proxyUrl`: roteamento por proxy direto de saída para egresso de runtime do OpenClaw. Esta página documenta esse recurso.
- `gateway.auth.mode: "trusted-proxy"`: autenticação de proxy reverso de entrada, ciente de 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 egresso em todo o runtime.
- 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 runtime.
## Configuração
@ -81,7 +81,7 @@ 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 falham na inicialização em vez de recorrerem ao acesso direto à rede.
Se `enabled=true`, mas nenhuma URL de proxy válida estiver configurada, os comandos protegidos falham na inicialização em vez de voltar para acesso direto à rede.
Para serviços de gateway gerenciados iniciados com `openclaw gateway start`, prefira armazenar a URL na configuração:
@ -92,9 +92,9 @@ openclaw gateway install --force
openclaw gateway start
```
O fallback de ambiente é melhor 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`, então reinstale o serviço para que launchd, systemd ou Scheduled Tasks inicie o gateway com esse valor.
O fallback de ambiente é melhor 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.
Para comandos `openclaw --container ...`, o OpenClaw encaminha `OPENCLAW_PROXY_URL` para o CLI filho direcionado 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 direcionados 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 precisa ser alcançável de dentro do contêiner; `127.0.0.1` refere-se ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy de loopback para comandos direcionados ao contêiner, a menos que você substitua explicitamente essa verificação de segurança.
## Requisitos do proxy
@ -102,39 +102,39 @@ A política do proxy é o limite de segurança. O OpenClaw não consegue verific
Configure o proxy para:
- Vincular apenas ao loopback ou a uma interface privada confiável.
- Vincular-se apenas ao 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 de DNS.
- Aplicar política no momento da conexão tanto para solicitações HTTP simples quanto para túneis HTTPS `CONNECT`.
- Rejeitar desvios 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 de DNS.
- Registrar destino, decisão, status e motivo sem registrar corpos de solicitação, cabeçalhos de autorização, cookies ou outros segredos.
- Manter a política de proxy sob controle de versão e revisar alterações como configuração sensível à segurança.
- 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 `CONNECT` HTTPS.
- 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.
- 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
Use esta lista de negação como ponto de partida para qualquer proxy de encaminhamento, firewall ou política de egresso.
Use esta denylist como ponto de partida para qualquer proxy direto, firewall ou política de saída.
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 embutido para NAT64, 6to4, Teredo, ISATAP e formas IPv4-mapped. 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 de classificação no nível da 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 embutido para NAT64, 6to4, Teredo, ISATAP e formas mapeadas em IPv4. 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.
| Intervalo ou host | Por que bloquear |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
| `::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 |
| Intervalo ou host | Por que bloquear |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | loopback IPv4 |
| `::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 |
| `100.64.0.0/10` | Espaço de endereços compartilhado de NAT de grau de operadora |
| `198.18.0.0/15`, `2001:2::/48` | Intervalos de benchmarking |
| `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 |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reservado |
| `fc00::/7`, `fec0::/10` | Intervalos IPv6 locais/privados |
| `100::/64`, `2001:20::/28` | Intervalos IPv6 discard e ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefixos NAT64 com IPv4 embutido |
| `2002::/16`, `2001::/32` | 6to4 e Teredo com IPv4 embutido |
| `::/96`, `::ffff:0:0/96` | IPv6 compatível com IPv4 e IPv6 IPv4-mapped |
| `169.254.169.254`, `metadata.google.internal` | Serviços de metadados de nuvem |
| `100.64.0.0/10` | Espaço de endereços compartilhado de NAT carrier-grade |
| `198.18.0.0/15`, `2001:2::/48` | Intervalos de benchmarking |
| `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 |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reservado |
| `fc00::/7`, `fec0::/10` | Intervalos locais/privados IPv6 |
| `100::/64`, `2001:20::/28` | Intervalos IPv6 discard e ORCHIDv2 |
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefixos NAT64 com IPv4 embutido |
| `2002::/16`, `2001::/32` | 6to4 e Teredo com IPv4 embutido |
| `::/96`, `::ffff:0:0/96` | IPv6 compatível com IPv4 e IPv6 mapeado em IPv4 |
Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou intervalos reservados adicionais, adicione-os também.
@ -142,15 +142,45 @@ Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou
Valide o proxy a partir do mesmo host, contêiner ou conta de serviço que executa o OpenClaw:
```bash
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 temporário de 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 um preflight único antes de alterar a configuração. Use `--allowed-url` e `--denied-url` para testar expectativas específicas da implantação. Destinos negados personalizados são fail-closed: qualquer resposta HTTP significa que o destino estava alcançável pelo 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 falha de validação, o comando sai com código 1.
Use `--json` para automação. A saída JSON contém o resultado geral, a fonte efetiva da configuração de proxy, quaisquer erros de configuração e cada verificação de destino. Credenciais da URL do proxy são redigidas na saída de texto e JSON:
```json
{
"ok": true,
"config": {
"enabled": true,
"proxyUrl": "http://127.0.0.1:3128/",
"source": "override",
"errors": []
},
"checks": [
{
"kind": "allowed",
"url": "https://example.com/",
"ok": true,
"status": 200
}
]
}
```
Você também pode validar manualmente com `curl`:
```bash
curl -x http://127.0.0.1:3128 https://example.com/
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 ter sucesso. As solicitações de loopback e metadados devem falhar no proxy.
A requisição pública deve ter êxito. As requisições de loopback e 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 alcançável. Verificações personalizadas com `--denied-url` não têm esse canário, então trate tanto respostas HTTP quanto 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 por proxy do OpenClaw:
Em seguida, habilite o roteamento de proxy do OpenClaw:
```bash
openclaw config set proxy.enabled true
@ -169,8 +199,8 @@ proxy:
## Limites
- O proxy melhora a cobertura para clientes HTTP e WebSocket JavaScript locais ao processo, mas não é um sandbox de rede em nível de sistema operacional.
- Sockets brutos `net`, `tls` e `http2`, addons nativos e processos filhos podem contornar o roteamento por proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy.
- WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissão da política de proxy do operador quando necessário; o OpenClaw não expõe um desvio geral de rede local para eles.
- O desvio de proxy do plano de controle do Gateway é intencionalmente limitado a `localhost` e URLs de IP literal de loopback. 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.
- 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.
- WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissões na 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 diretas locais ao 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 de política de proxy como mudanças operacionais sensíveis à segurança.
- Trate alterações na política de proxy como mudanças operacionais sensíveis à segurança.

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

@ -1,27 +1,27 @@
---
read_when:
- Instalando ou configurando plugins
- Entendendo as regras de descoberta e carregamento de Plugin
- Como trabalhar com pacotes de Plugin compatíveis com Codex/Claude
- Entendendo a descoberta de plugins e as regras de carregamento
- 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-04-30T10:12:49Z"
generated_at: "2026-05-01T06:00:17Z"
model: gpt-5.5
provider: openai
source_hash: 7a12d158053c13b47a56d8d6b382818962e9b5109fdf8ededd3ecf92b83089e6
source_hash: 69f876df0c2ed3ff356ada9462b56f2b5a65a662b64b328ecc97d8b463036934
source_path: tools/plugin.md
workflow: 16
---
Plugins estendem o OpenClaw com novos recursos: canais, provedores de modelo,
harnesses de agentes, ferramentas, skills, fala, transcrição em tempo real, voz
em tempo real, compreensão de mídia, geração de imagens, geração de vídeo, busca
na web, pesquisa na web e mais. Alguns plugins são **core** (enviados 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 sendo compatível para instalações diretas e para um
conjunto temporário de pacotes de plugins pertencentes ao OpenClaw enquanto essa migração é concluída.
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,
entendimento 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** (enviados com o OpenClaw), outros
são **externos**. A maioria dos plugins externos é publicada e descoberta pelo
[ClawHub](/pt-BR/tools/clawhub). O npm continua com suporte para instalações diretas e para um
conjunto temporário de pacotes de Plugin mantidos pelo OpenClaw enquanto essa migração é concluída.
## Início rápido
@ -54,7 +54,7 @@ conjunto temporário de pacotes de plugins pertencentes ao OpenClaw enquanto ess
</Step>
</Steps>
Se você preferir controle nativo por chat, habilite `commands.plugins: true` e use:
Se preferir controle nativo do chat, habilite `commands.plugins: true` e use:
```text
/plugin install clawhub:<package>
@ -62,60 +62,59 @@ Se você preferir controle nativo por chat, habilite `commands.plugins: true` e
/plugin enable <plugin-id>
```
O caminho de instalação usa o mesmo resolvedor que a CLI: caminho/arquivo local, `clawhub:<pkg>`
explícito, `npm:<pkg>` explícito ou especificação de pacote simples (ClawHub primeiro, depois
O caminho de instalação usa o mesmo resolvedor da CLI: caminho/arquivo local,
`clawhub:<pkg>` explícito, `npm:<pkg>` explícito ou especificação de pacote simples (ClawHub primeiro, depois
fallback para npm).
Se a configuração for inválida, a instalação normalmente falha de modo fechado e aponta para
`openclaw doctor --fix`. A única exceção de recuperação é um caminho estreito de reinstalação de
plugin empacotado para plugins que optam por
Se a configuração for inválida, a instalação normalmente falha fechada e aponta para
`openclaw doctor --fix`. A única exceção de recuperação é um caminho restrito de reinstalação de plugin empacotado
para plugins que optam por
`openclaw.install.allowInvalidConfigRecovery`.
Durante a inicialização do Gateway, a configuração inválida de um plugin é isolada a esse plugin:
a inicialização registra o problema em `plugins.entries.<id>.config`, ignora esse plugin durante
o carregamento e mantém outros plugins e canais online. Execute `openclaw doctor --fix`
para colocar a configuração ruim do plugin em quarentena, 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 de plugin ou nos registros de instalação, a inicialização do Gateway
a inicialização registra o problema de `plugins.entries.<id>.config`, ignora esse plugin durante o
carregamento e mantém outros plugins e canais online. Execute `openclaw doctor --fix`
para colocar em quarentena a configuração incorreta do plugin desabilitando essa entrada de plugin e removendo
seu payload de configuração inválido; 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 do 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 continuem
visíveis.
Se `plugins.enabled: false` estiver definido, referências obsoletas a plugins são tratadas como inertes:
a inicialização do Gateway ignora o trabalho de descoberta/carregamento de plugins 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 plugins obsoletos.
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 os plugins antes de
executar a limpeza do doctor se quiser que ids de plugin obsoletos sejam removidos.
Instalações empacotadas do OpenClaw não instalam avidamente toda a árvore de dependências de runtime
de cada plugin empacotado. Quando um plugin pertencente ao OpenClaw empacotado está ativo pela
configuração de plugins, configuração legada de canal ou um manifesto habilitado por padrão, a inicialização
Instalações empacotadas do OpenClaw não instalam avidamente toda a árvore de dependências
de runtime de cada plugin empacotado. Quando um plugin empacotado mantido pelo OpenClaw está ativo a partir da
configuração de plugin, configuração legada de canal ou manifesto habilitado por padrão, a inicialização
repara apenas as dependências de runtime declaradas desse plugin antes de importá-lo.
Somente o estado persistido de autenticação de canal não ativa um canal empacotado para
O estado persistido de autenticação de canal sozinho não ativa um canal empacotado para
reparo de dependências de runtime na inicialização do Gateway.
A desabilitação explícita ainda prevalece: `plugins.entries.<id>.enabled: false`,
`plugins.deny`, `plugins.enabled: false` e `channels.<id>.enabled: false`
impedem o reparo automático de dependências de runtime empacotadas desse plugin/canal.
Um `plugins.allow` não vazio também limita o reparo de dependências de runtime empacotadas
habilitadas por padrão; a habilitação explícita de canal empacotado (`channels.<id>.enabled: true`) ainda pode
reparar as dependências de plugin desse canal.
impedem o reparo automático das dependências de runtime empacotadas para esse plugin/canal.
Um `plugins.allow` não vazio também limita o reparo de dependências de runtime empacotadas habilitadas por padrão; a habilitação explícita de canal empacotado (`channels.<id>.enabled: true`) ainda pode
reparar as dependências do plugin desse canal.
Plugins externos e caminhos de carregamento personalizados ainda devem ser instalados por meio de
`openclaw plugins install`.
## Tipos de plugin
## Tipos de Plugin
O OpenClaw reconhece dois formatos de plugin:
O OpenClaw reconhece dois formatos de Plugin:
| Formato | Como funciona | Exemplos |
| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade |
| Formato | Como funciona | Exemplos |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Nativo** | `openclaw.plugin.json` + módulo de runtime; executa no processo | Plugins oficiais, pacotes npm da comunidade |
| **Bundle** | 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 [Bundles de Plugin](/pt-BR/plugins/bundles) para detalhes sobre bundles.
Ambos aparecem em `openclaw plugins list`. Consulte [Bundles de Plugin](/pt-BR/plugins/bundles) para detalhes de bundle.
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).
Se você está escrevendo um plugin nativo, comece com [Criando Plugins](/pt-BR/plugins/building-plugins)
e a [Visão geral do Plugin SDK](/pt-BR/plugins/sdk-overview).
## Pontos de entrada de pacote
## Pontos de entrada do 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
@ -123,9 +122,9 @@ runtime legível, ou para um arquivo-fonte TypeScript com um par JavaScript comp
como `src/index.ts` para `dist/index.js`.
Use `openclaw.runtimeExtensions` quando os arquivos de runtime publicados não estiverem nos
mesmos caminhos das entradas de origem. Quando presente, `runtimeExtensions` deve conter
mesmos caminhos que as 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 recorrer silenciosamente aos caminhos de origem.
a descoberta de plugins falharem, em vez de voltar silenciosamente aos caminhos de origem.
```json
{
@ -139,19 +138,19 @@ a descoberta de plugins falharem em vez de recorrer silenciosamente aos caminhos
## Plugins oficiais
### Pacotes npm pertencentes ao OpenClaw durante a migração
### Pacotes npm mantidos pelo OpenClaw durante a migração
ClawHub é o principal caminho de distribuição para a maioria dos plugins. As versões empacotadas atuais
do OpenClaw já incluem muitos plugins oficiais, portanto 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
npm para instalações mais antigas/personalizadas e fluxos diretos de npm.
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 mantidos pelo OpenClaw tenham
migrado para o ClawHub, o OpenClaw ainda envia alguns pacotes de Plugin `@openclaw/*` no
npm para instalações antigas/personalizadas e fluxos diretos de npm.
Se o npm informar que um pacote de plugin `@openclaw/*` está obsoleto, essa versão do pacote
vem de uma linha antiga de pacotes externos. Use o plugin empacotado do
Se o npm reportar um pacote de Plugin `@openclaw/*` como obsoleto, essa versão do pacote
é de uma linha de pacotes externos mais antiga. Use o plugin empacotado do
OpenClaw atual ou um checkout local até que um pacote npm mais novo seja publicado.
| Plugin | Pacote | Docs |
| Plugin | Pacote | Docs |
| --------------- | -------------------------- | ------------------------------------------ |
| BlueBubbles | `@openclaw/bluebubbles` | [BlueBubbles](/pt-BR/channels/bluebubbles) |
| Discord | `@openclaw/discord` | [Discord](/pt-BR/channels/discord) |
@ -180,10 +179,10 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public
<Accordion title="Plugins de memória">
- `memory-core` — busca de memória empacotada (padrão via `plugins.slots.memory`)
- `memory-lancedb` — memória de longo prazo instalada sob demanda com recuperação/captura automática (defina `plugins.slots.memory = "memory-lancedb"`)
- `memory-lancedb` — memória de longo prazo instalada sob demanda 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.
Consulte [Memory LanceDB](/pt-BR/plugins/memory-lancedb) para configuração de
embeddings compatíveis com OpenAI, exemplos do Ollama, limites de rechamada e solução de problemas.
</Accordion>
@ -193,12 +192,12 @@ OpenClaw atual ou um checkout local até que um pacote npm mais novo seja public
<Accordion title="Outros">
- `browser` — plugin de navegador empacotado 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)
- `copilot-proxy` — ponte VS Code Copilot Proxy (desabilitada por padrão)
- `copilot-proxy` — ponte do VS Code Copilot Proxy (desabilitada por padrão)
</Accordion>
</AccordionGroup>
Procurando plugins de terceiros? Consulte [Plugins da comunidade](/pt-BR/plugins/community).
Procurando plugins de terceiros? Consulte [Plugins da Comunidade](/pt-BR/plugins/community).
## Configuração
@ -216,45 +215,50 @@ Procurando plugins de terceiros? Consulte [Plugins da comunidade](/pt-BR/plugins
}
```
| Campo | Descrição |
| Campo | Descrição |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Alternância principal (padrão: `true`) |
| `allow` | Lista de permissões de plugins (opcional) |
| `deny` | Lista de bloqueio de plugins (opcional; deny prevalece) |
| `load.paths` | Arquivos/diretórios extras de plugin |
| `enabled` | Alternância mestre (padrão: `true`) |
| `allow` | Lista de permissões de Plugin (opcional) |
| `deny` | Lista de bloqueio de Plugin (opcional; deny prevalece) |
| `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 |
| `entries.\<id\>` | Alternâncias + configuração por plugin |
Alterações de configuração **exigem reinicialização do gateway**. Se o Gateway estiver rodando com observação de configuração
+ reinicialização em processo habilitada (o caminho padrão `openclaw gateway`), essa
reinicialização geralmente é feita automaticamente um momento depois que a gravação da configuração chega.
Não há caminho de hot-reload compatível para código de runtime de plugin nativo ou hooks de ciclo de vida;
reinicie o processo do Gateway que atende o canal ativo antes de
`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 ao plugin. Se uma lista de permissões de ferramentas referencia 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 **exigem uma reinicialização do gateway**. Se o Gateway estiver em execução com observação de configuração
+ reinicialização em processo habilitadas (o caminho padrão de `openclaw gateway`), essa
reinicialização geralmente é executada automaticamente um momento depois que a gravação da configuração é concluída.
Não há caminho de hot-reload suportado para código de runtime de plugin nativo ou hooks de ciclo de vida; reinicie o processo do Gateway que está servindo o canal ativo antes de
esperar que código `register(api)` atualizado, hooks `api.on(...)`, ferramentas, serviços ou
hooks de provedor/runtime sejam executados.
hooks de provider/runtime sejam executados.
`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 filho remoto do Gateway já em execução
tenha reiniciado com o mesmo código de plugin. Em configurações VPS/container com
processos wrapper, envie reinicializações para o processo real `openclaw gateway run`,
plugin participe. Isso não prova que um processo filho de Gateway remoto já em execução
tenha sido reiniciado com o mesmo código de plugin. Em configurações de VPS/contêiner com
processos wrapper, envie reinicializações ao processo real `openclaw gateway run`,
ou use `openclaw gateway restart` contra o Gateway em execução.
<Accordion title="Estados de plugin: desabilitado vs ausente vs inválido">
- **Desabilitado**: o plugin existe, mas as regras de habilitação o desativaram. A configuração é preservada.
- **Desabilitado**: o plugin existe, mas as regras de habilitaçã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 schema declarado. A inicialização do Gateway ignora apenas esse plugin; `openclaw doctor --fix` pode colocar a entrada inválida em quarentena desabilitando-a e removendo sua carga 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 desabilitando-a e removendo seu payload de configuração.
</Accordion>
## Descoberta e precedência
O OpenClaw procura plugins nesta ordem (a primeira correspondência prevalece):
O OpenClaw verifica plugins nesta ordem (a primeira correspondência vence):
<Steps>
<Step title="Caminhos de configuração">
`plugins.load.paths` — caminhos explícitos de arquivo ou diretório. Caminhos que apontam
de volta para os diretórios de plugins empacotados do próprio OpenClaw são ignorados;
de volta para os próprios diretórios de Plugin empacotados do OpenClaw são ignorados;
execute `openclaw doctor --fix` para remover esses aliases obsoletos.
</Step>
@ -266,59 +270,59 @@ O OpenClaw procura plugins nesta ordem (a primeira correspondência prevalece):
`~/.openclaw/<plugin-root>/*.ts` e `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Bundled plugins">
Incluídos com o OpenClaw. Muitos são habilitados por padrão (provedores de modelo, fala).
<Step title="Plugins incluídos">
Enviados com o OpenClaw. Muitos são habilitados por padrão (provedores de modelo, fala).
Outros exigem habilitação explícita.
</Step>
</Steps>
Instalações empacotadas e imagens Docker normalmente resolvem plugins incluídos a partir da
árvore compilada `dist/extensions`. Se um diretório de código-fonte de plugin incluído for
montado com bind sobre o caminho de código-fonte empacotado correspondente, por exemplo
`/app/extensions/synology-chat`, o OpenClaw trata esse diretório de código-fonte montado
como uma sobreposição de código-fonte incluído e o descobre antes do pacote empacotado
`/app/dist/extensions/synology-chat`. Isso mantém os ciclos de contêiner dos mantenedores
funcionando sem alternar todos os plugins incluídos 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 código-fonte estiverem presentes.
Instalações empacotadas e imagens Docker normalmente resolvem Plugins incluídos a partir da
árvore compilada `dist/extensions`. Se um diretório de origem de Plugin incluído 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 incluída e o descobre antes do bundle empacotado
`/app/dist/extensions/synology-chat`. Isso mantém os ciclos de contêiner de mantenedores
funcionando sem alternar todos os Plugins incluídos de volta para a origem TypeScript.
Defina `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` para forçar os bundles dist empacotados
mesmo quando montagens de sobreposição de origem estiverem presentes.
### Regras de habilitação
- `plugins.enabled: false` desabilita todos os plugins e ignora o trabalho de descoberta/carregamento de plugins
- `plugins.enabled: false` desabilita todos os Plugins e ignora o trabalho de descoberta/carregamento de Plugins
- `plugins.deny` sempre prevalece sobre allow
- `plugins.entries.\<id\>.enabled: false` desabilita esse plugin
- `plugins.entries.\<id\>.enabled: false` desabilita esse Plugin
- Plugins originados do workspace são **desabilitados por padrão** (devem ser habilitados explicitamente)
- Plugins incluídos seguem o conjunto interno habilitado por padrão, a menos que seja sobrescrito
- Slots exclusivos podem forçar a habilitação do plugin selecionado para esse slot
- Alguns plugins incluídos opcionais são habilitados 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
- Plugins incluídos seguem o conjunto interno habilitado por padrão, salvo substituição
- Slots exclusivos podem forçar a habilitação do Plugin selecionado para esse slot
- Alguns Plugins incluídos opt-in são habilitados 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
de harness
- Configuração obsoleta de plugin é preservada enquanto `plugins.enabled: false` está ativo;
reabilite plugins antes de executar a limpeza do doctor se você 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 de servidor de app Codex
- A configuração obsoleta de Plugin é preservada enquanto `plugins.enabled: false` está ativo;
reabilite 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 de servidor de app Codex
incluído é selecionado por `agentRuntime.id: "codex"` ou referências de modelo legadas
`codex/*`
## Solução de problemas de hooks de runtime
Se um plugin aparece em `plugins list`, mas efeitos colaterais ou hooks de `register(api)`
não são executados no tráfego de chat ao vivo, verifique primeiro:
Se um Plugin aparecer em `plugins list`, mas os efeitos colaterais ou hooks de `register(api)`
não forem executados no tráfego de chat ao vivo, verifique primeiro:
- 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 plugin. Em contêineres
wrapper, o PID 1 pode ser apenas um supervisor; reinicie ou envie sinal ao processo filho
- Execute `openclaw gateway status --deep --require-rpc` e confirme que a URL,
o perfil, o caminho de configuração e o processo ativos do Gateway são aqueles que você está editando.
- Reinicie o Gateway ao vivo após mudanças de instalação/configuração/código do Plugin. 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> --json` para confirmar registros de hooks e
- Use `openclaw plugins inspect <id> --json` para confirmar registros de hook e
diagnósticos. Hooks de conversa não incluídos, 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 do modelo para turnos de agente; `llm_output` só é executado depois que uma tentativa de modelo
produz saída do assistente.
- Para comprovar o 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 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 de assistente.
- Para comprovar o modelo de sessão efetivo, use `openclaw sessions` ou as
superfícies de sessão/status do Gateway e, ao depurar payloads de provedor, inicie
o Gateway com `--raw-stream --raw-stream-path <path>`.
### Propriedade duplicada de canal ou ferramenta
@ -329,32 +333,32 @@ Sintomas:
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Isso significa que mais de um plugin habilitado está tentando ser dono 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 incluído que agora fornece o mesmo id de canal.
Isso significa que mais de um Plugin habilitado está tentando possuir o 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 incluído que agora fornece o mesmo id de canal.
Etapas de depuração:
- Execute `openclaw plugins list --enabled --verbose` para ver todos os plugins habilitados
e sua origem.
- Execute `openclaw plugins inspect <id> --json` para cada plugin suspeito e
compare `channels`, `channelConfigs`, `tools` e os diagnósticos.
- Execute `openclaw plugins registry --refresh` após 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.
- Execute `openclaw plugins list --enabled --verbose` para ver todos os Plugins habilitados
e suas origens.
- Execute `openclaw plugins inspect <id> --json` para cada Plugin suspeito e
compare `channels`, `channelConfigs`, `tools` e diagnósticos.
- 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 mudanças de instalação, registro ou configuração.
Opções de correção:
- Se um plugin substituir 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 duplicata for acidental, desabilite um lado com
`plugins.entries.<plugin-id>.enabled: false` ou remova a instalação obsoleta do plugin.
- Se você habilitou 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 ao plugin
- 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. Veja [/plugins/manifest#replacing-another-channel-plugin](/pt-BR/plugins/manifest#replacing-another-channel-plugin).
- Se a duplicidade for acidental, desabilite um lado com
`plugins.entries.<plugin-id>.enabled: false` ou remova a instalação obsoleta do Plugin.
- Se você habilitou explicitamente ambos os Plugins, o OpenClaw mantém essa solicitação e
relata 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 (apenas uma ativa por vez):
@ -362,48 +366,48 @@ Algumas categorias são exclusivas (apenas uma ativa por vez):
{
plugins: {
slots: {
memory: "memory-core", // or "none" to disable
contextEngine: "legacy", // or a plugin id
memory: "memory-core", // ou "none" para desabilitar
contextEngine: "legacy", // ou um id de Plugin
},
},
}
```
| Slot | O que controla | Padrão |
| --------------- | -------------------------- | ------------------- |
| `memory` | Plugin de memória ativa | `memory-core` |
| `contextEngine` | Mecanismo de contexto ativo | `legacy` (interno) |
| Slot | O que controla | Padrão |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin de memória ativo | `memory-core` |
| `contextEngine` | Motor de contexto ativo | `legacy` (interno) |
## Referência da CLI
```bash
openclaw plugins list # compact inventory
openclaw plugins list --enabled # only enabled plugins
openclaw plugins list --verbose # per-plugin detail lines
openclaw plugins list --json # machine-readable inventory
openclaw plugins inspect <id> # deep detail
openclaw plugins inspect <id> --json # machine-readable
openclaw plugins inspect --all # fleet-wide table
openclaw plugins info <id> # inspect alias
openclaw plugins doctor # diagnostics
openclaw plugins registry # inspect persisted registry state
openclaw plugins registry --refresh # rebuild persisted registry
openclaw doctor --fix # repair plugin registry state
openclaw plugins list # inventário compacto
openclaw plugins list --enabled # apenas Plugins habilitados
openclaw plugins list --verbose # linhas de detalhes por Plugin
openclaw plugins list --json # inventário legível por máquina
openclaw plugins inspect <id> # detalhes aprofundados
openclaw plugins inspect <id> --json # legível por máquina
openclaw plugins inspect --all # tabela de toda a frota
openclaw plugins info <id> # alias de inspeção
openclaw plugins doctor # diagnósticos
openclaw plugins registry # inspecionar estado do registro persistido
openclaw plugins registry --refresh # reconstruir registro persistido
openclaw doctor --fix # reparar estado do registro de Plugins
openclaw plugins install <package> # install (ClawHub first, then npm)
openclaw plugins install clawhub:<pkg> # install from ClawHub only
openclaw plugins install npm:<pkg> # install from npm only
openclaw plugins install <spec> --force # overwrite existing install
openclaw plugins install <path> # install from local path
openclaw plugins install -l <path> # link (no copy) for dev
openclaw plugins install <package> # instalar (ClawHub primeiro, depois npm)
openclaw plugins install clawhub:<pkg> # instalar apenas do ClawHub
openclaw plugins install npm:<pkg> # instalar apenas do npm
openclaw plugins install <spec> --force # sobrescrever instalação existente
openclaw plugins install <path> # instalar de caminho local
openclaw plugins install -l <path> # vincular (sem copiar) para dev
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # record exact resolved npm spec
openclaw plugins install <spec> --pin # registrar spec npm resolvida exata
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # update one plugin
openclaw plugins update <id-or-npm-spec> # atualizar um Plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # update all
openclaw plugins uninstall <id> # remove config and plugin index records
openclaw plugins update --all # atualizar todos
openclaw plugins uninstall <id> # remover configuração e registros de índice de Plugin
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -412,80 +416,80 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Plugins incluídos são enviados 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 enviados 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>`.
`--force` sobrescreve um plugin instalado existente ou pacote de hooks no local. Use
`openclaw plugins update <id-or-npm-spec>` para upgrades rotineiros de plugins npm
rastreados. Isso não é compatível com `--link`, que reutiliza o caminho de código-fonte em vez
`--force` sobrescreve um Plugin instalado existente ou hook pack no local. Use
`openclaw plugins update <id-or-npm-spec>` para upgrades rotineiros de Plugins npm
rastreados. Isso 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 lista de permissões antes de habilitá-lo. Se o mesmo id de plugin
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.
instalação explícita seja carregável imediatamente após a reinicialização.
O OpenClaw mantém um registro local persistido de plugins como modelo de leitura a frio para
inventário de plugins, propriedade de contribuições e planejamento de inicialização. Fluxos de instalação,
atualização, desinstalação, habilitação e desabilitação atualizam esse registro após alterar o estado
do plugin. O mesmo arquivo `plugins/installs.json` mantém metadados duráveis de instalação em
O OpenClaw mantém um registro local persistido de Plugins como o 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, habilitação e desabilitaçã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` de 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 de registros de instalação, política de configuração e
metadados de manifesto/pacote sem carregar módulos de runtime de plugin.
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 do plugin rastreado e grava a nova especificação para atualizações futuras.
uma spec 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 spec 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
a linha de lançamento padrão do registro. Se o Plugin npm instalado já corresponder
à versão resolvida e à identidade do artefato registrada, o OpenClaw ignora a atualização
sem baixar, reinstalar ou reescrever a configuração.
`--pin` é apenas para npm. Não é compatível com `--marketplace`, porque
instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm.
instalações de marketplace persistem metadados de origem do marketplace em vez de uma spec 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 ignora bloqueios de política `before_install` do plugin nem bloqueio por falha de varredura.
positivos do scanner de código perigoso interno. Ele permite que instalações de Plugin
e atualizações de Plugin continuem após findings `critical` internos, mas ainda
não ignora bloqueios de política `before_install` de Plugin nem bloqueio 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;
entrypoints de runtime de plugin declarados ainda são varridos mesmo que usem um desses
entrypoints de runtime declarados do Plugin ainda são verificados mesmo que usem um desses
nomes.
Esta flag de 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
Essa flag da CLI se aplica apenas a fluxos de instalação/atualização de Plugin. 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.
Se um plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma varredura, abra o
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 revarrer o plugin nem torna pública uma versão
máquina; ele não pede ao ClawHub para verificar novamente o Plugin nem torna pública uma versão
bloqueada.
Pacotes compatíveis participam do mesmo fluxo de listar/inspecionar/habilitar/desabilitar
plugins. O suporte de runtime atual inclui Skills de pacote, command-skills do Claude,
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
`lspServers` declarados por manifesto, command-skills do Cursor e diretórios de hooks
`lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hook
Codex compatíveis.
`openclaw plugins inspect <id>` também relata capacidades de pacote detectadas, além de
entradas de servidor MCP e LSP compatíveis ou não compatíveis para plugins baseados em pacote.
`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 baseados em bundle.
Origens de marketplace podem ser um nome de marketplace conhecido do Claude a partir de
`~/.claude/plugins/known_marketplaces.json`, uma raiz de marketplace local ou caminho de
`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
`~/.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
GitHub ou uma URL git. Para marketplaces remotos, as entradas de Plugin devem permanecer dentro do
repositório de marketplace clonado e usar apenas origens de caminho relativo.
Consulte a [referência da CLI `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos.
Veja a [referência da CLI `openclaw plugins`](/pt-BR/cli/plugins) para detalhes completos.
## Visão geral da API de plugin
## 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 um alias legado, mas novos plugins devem
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
@ -507,54 +511,53 @@ export default definePluginEntry({
```
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.
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:
`api.registrationMode` informa a um Plugin por que sua entrada está sendo carregada:
| Modo | Significado |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `full` | Ativação em tempo de execução. Registra ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ativos. |
| `discovery` | Descoberta de capacidades somente leitura. Registra provedores e metadados; o código de entrada confiável do Plugin pode ser carregado, mas ignora efeitos colaterais ativos. |
| `setup-only` | Carregamento de metadados de configuração do canal por meio de uma entrada de configuração leve. |
| `setup-runtime` | Carregamento de configuração do canal que também precisa da entrada de runtime. |
| `cli-metadata` | Apenas coleta de metadados de comandos da CLI. |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Ativação em runtime. Registre ferramentas, hooks, serviços, comandos, rotas e outros efeitos colaterais ativos. |
| `discovery` | Descoberta de capacidades somente leitura. Registre provedores e metadados; o código de entrada de Plugin confiável 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 soquetes, bancos de dados, workers em segundo
plano ou clientes de longa duração devem proteger esses efeitos colaterais com
`api.registrationMode === "full"`. Carregamentos de descoberta são armazenados
em cache separadamente dos carregamentos de ativação e não substituem o registro
do Gateway em execução. A descoberta é não ativadora, não livre de importação:
o OpenClaw pode avaliar a entrada confiável do Plugin ou o módulo do 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 dos 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"`. Carregamentos de descoberta são armazenados em
cache separadamente dos carregamentos de ativação e não substituem o registro do
Gateway em execução. A descoberta é não ativadora, não livre de importação:
o OpenClaw pode avaliar a entrada de Plugin confiável 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 caminhos de runtime completo.
Métodos comuns de registro:
| Método | O que ele registra |
| --------------------------------------- | ------------------------------------------ |
| `registerProvider` | Provedor de modelo (LLM) |
| `registerChannel` | Canal de chat |
| `registerTool` | Ferramenta de agente |
| `registerHook` / `on(...)` | Hooks de ciclo de vida |
| `registerSpeechProvider` | Conversão de texto em fala / STT |
| `registerRealtimeTranscriptionProvider` | STT por 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 / extração na Web |
| `registerWebSearchProvider` | Pesquisa na Web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Comandos da CLI |
| `registerContextEngine` | Mecanismo de contexto |
| `registerService` | Serviço em segundo plano |
| Método | O que ele 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 por 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 na Web |
| `registerWebSearchProvider` | Pesquisa na Web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Comandos da CLI |
| `registerContextEngine` | Mecanismo de contexto |
| `registerService` | Serviço em segundo plano |
Comportamento de guarda de hooks para hooks de ciclo de vida tipados:
Comportamento de proteção de hooks para hooks de ciclo de vida tipados:
- `before_tool_call`: `{ block: true }` é terminal; handlers de prioridade mais baixa são ignorados.
- `before_tool_call`: `{ block: false }` é um no-op e não limpa um bloqueio anterior.
@ -563,21 +566,21 @@ Comportamento de guarda de hooks para hooks de ciclo de vida tipados:
- `message_sending`: `{ cancel: true }` é terminal; handlers de prioridade mais baixa são ignorados.
- `message_sending`: `{ cancel: false }` é um no-op e não limpa um cancelamento anterior.
Execuções nativas do app-server do Codex fazem a ponte de eventos de ferramentas
nativas do Codex de volta para esta superfície de hooks. Plugins podem bloquear
Execuções nativas do servidor de app Codex conectam eventos de ferramentas
nativas do Codex de volta a 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 das aprovações de `PermissionRequest`
do Codex. A ponte ainda não reescreve argumentos de ferramentas nativas do
Codex. O limite exato de suporte do runtime do Codex está no
[contrato de suporte do harness v1 do Codex](/pt-BR/plugins/codex-harness#v1-support-contract).
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 do harness Codex v1](/pt-BR/plugins/codex-harness#v1-support-contract).
Para ver o comportamento completo de hooks tipados, consulte 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
- [Criação de Plugins](/pt-BR/plugins/building-plugins) — crie seu próprio Plugin
- [Bundles de Plugin](/pt-BR/plugins/bundles) — compatibilidade de bundles do Codex/Claude/Cursor
- [Manifesto do Plugin](/pt-BR/plugins/manifest) — esquema do manifesto
- [Pacotes de Plugins](/pt-BR/plugins/bundles) — compatibilidade de pacotes Codex/Claude/Cursor
- [Manifesto de Plugin](/pt-BR/plugins/manifest) — esquema do manifesto
- [Registro de ferramentas](/pt-BR/plugins/building-plugins#registering-agent-tools) — adicione ferramentas de agente em um Plugin
- [Componentes internos de Plugin](/pt-BR/plugins/architecture) — modelo de capacidade e pipeline de carregamento
- [Detalhes internos de Plugin](/pt-BR/plugins/architecture) — modelo de capacidades e pipeline de carregamento
- [Plugins da comunidade](/pt-BR/plugins/community) — listagens de terceiros