diff --git a/docs/pt-BR/auth-credential-semantics.md b/docs/pt-BR/auth-credential-semantics.md index 6cac5ebbe..c34caf2da 100644 --- a/docs/pt-BR/auth-credential-semantics.md +++ b/docs/pt-BR/auth-credential-semantics.md @@ -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.` 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.` 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..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..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) diff --git a/docs/pt-BR/automation/tasks.md b/docs/pt-BR/automation/tasks.md index b1dc41664..64e644177 100644 --- a/docs/pt-BR/automation/tasks.md +++ b/docs/pt-BR/automation/tasks.md @@ -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 --- -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. -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. -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. ## 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 - + ```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 ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -74,7 +74,7 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera ``` - + ```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 ``` - + ```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` | - - 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. + + 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. - - 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. + + 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. - + - 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. 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. -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 state_changes openclaw tasks cancel ``` - 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. @@ -231,16 +231,16 @@ openclaw tasks notify 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) | @@ -249,32 +249,32 @@ openclaw tasks notify 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. - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - 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. @@ -283,7 +283,7 @@ openclaw tasks notify 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: - 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`. - 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. - 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. Exclui registros após sua data `cleanupAfter`. @@ -336,26 +337,26 @@ Um varredor é executado a cada **60 segundos** e cuida de quatro coisas: -**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. -## Como tarefas se relacionam com outros sistemas +## Como as tarefas se relacionam com outros sistemas - - [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. + + [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. - 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). - 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. - 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. ## 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 diff --git a/docs/pt-BR/channels/bluebubbles.md b/docs/pt-BR/channels/bluebubbles.md index 9155eaeef..de6d2598f 100644 --- a/docs/pt-BR/channels/bluebubbles.md +++ b/docs/pt-BR/channels/bluebubbles.md @@ -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. -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`. ## 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 - + Instale o servidor BlueBubbles no seu Mac (siga as instruções em [bluebubbles.app/install](https://bluebubbles.app/install)). - - Na configuração do BlueBubbles, ative a API web e defina uma senha. + + Na configuração do BlueBubbles, habilite a API web e defina uma senha. - + 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 ``` - + Aponte os webhooks do BlueBubbles para o seu gateway (exemplo: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). - - Inicie o gateway; ele registrará o manipulador de webhook e começará o emparelhamento. + + Inicie o Gateway; ele registrará o manipulador de Webhook e começará o pareamento. **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=` 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=` 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. -## 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. - + 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 ``` - + 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 ``` - 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. - + ```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. - Caminho do endpoint de webhook. + Caminho do endpoint de Webhook. `pairing`, `allowlist`, `open` ou `disabled`. @@ -180,27 +180,27 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor - 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 ` - - 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) - + - `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (padrão: `allowlist`). - `channels.bluebubbles.groupAllowFrom` controla quem pode acionar em grupos quando `allowlist` está definido. -### 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:` - `chat_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 - - **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. -### 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 -## 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. 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. @@ -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 - - **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. ### 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. - 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 - Os timestamps de eventos de sessão (`~/.openclaw/agents//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//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. - 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. - 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. @@ -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) - - `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) - `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.). - + - `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..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..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. - + - `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..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..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..replyContextApiFallback`. Uma configuração no nível do canal se propaga para contas que omitem a flag. - + - `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 `. -- 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 diff --git a/docs/pt-BR/channels/groups.md b/docs/pt-BR/channels/groups.md index 061885d4a..0aa50cc65 100644 --- a/docs/pt-BR/channels/groups.md +++ b/docs/pt-BR/channels/groups.md @@ -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. **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`). @@ -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. - - - 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. + + - 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. - + - `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. -![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: { "": { ... } }` (sem chave `"*"` ) | -| Apenas você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | +| Somente grupos específicos | `groups: { "": { ... } }` (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::group:`). 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::group:`). 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 -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). - + ```json5 { agents: { @@ -168,8 +170,8 @@ Se você precisa de workspaces/personas realmente separados ("pessoal" e "públi } ``` - - 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: + + 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 `:`. -- `#room` é reservado para salas/canais; chats em grupo usam `g-` (minúsculas, espaços -> `-`, mantém `#@+._-`). +- `#room` é reservado para salas/canais; chats em grupo usam `g-` (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. | - - - `groupPolicy` é separado do bloqueio por menção (que exige @menções). + + - `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..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..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.` 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.` ausente), a política de grupo recorre a um modo de falha fechada (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`. @@ -283,17 +285,17 @@ Modelo mental rápido (ordem de avaliação para mensagens de grupo): `groupPolicy` (open/disabled/allowlist). - - Allowlists de grupo (`*.groups`, `*.groupAllowFrom`, allowlist específica do canal). + + Listas de permissão de grupos (`*.groups`, `*.groupAllowFrom`, lista de permissão específica do canal). - - Bloqueio por menção (`requireMention`, `/activation`). + + Controle por menção (`requireMention`, `/activation`). -## 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 ``` - + - `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..historyLimit` (ou `channels..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..historyLimit` (ou `channels..accounts.*.historyLimit`) para substituições. Defina `0` para desativar. -## 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:`, `e164:`, `username:`, `name:` 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:`, `e164:`, `username:`, `name:` 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): - Correspondência de `toolsBySender` do grupo/canal. + Correspondência de `toolsBySender` de grupo/canal. - `tools` do grupo/canal. + `tools` de grupo/canal. Correspondência de `toolsBySender` padrão (`"*"`). @@ -393,21 +395,21 @@ Exemplo (Telegram): ``` -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.*`). -## 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. -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. Intenções comuns (copiar/colar): - + ```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:` ao rotear ou colocar na lista de permissões. +- Prefira `chat_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) diff --git a/docs/pt-BR/channels/qa-channel.md b/docs/pt-BR/channels/qa-channel.md index 6bab5cf89..55824b77f 100644 --- a/docs/pt-BR/channels/qa-channel.md +++ b/docs/pt-BR/channels/qa-channel.md @@ -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:` - `channel:` + - `group:` - `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) diff --git a/docs/pt-BR/ci.md b/docs/pt-BR/ci.md index e09c20ca0..6a2764c2a 100644 --- a/docs/pt-BR/ci.md +++ b/docs/pt-BR/ci.md @@ -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= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## 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:` 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:` 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=`, `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=`, `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 # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # 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) diff --git a/docs/pt-BR/cli/models.md b/docs/pt-BR/cli/models.md index fa34c0160..929f71b4c 100644 --- a/docs/pt-BR/cli/models.md +++ b/docs/pt-BR/cli/models.md @@ -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 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 ` 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 ` 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 ` 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 ` 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 ` filtra por id de provedor, como `moonshot` ou +- `models list --provider ` 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()` 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 ` - `--max-age-days ` - `--provider ` - `--max-candidates ` -- `--timeout ` (solicitação de catálogo e tempo limite por sondagem) +- `--timeout ` (solicitação de catálogo e timeout por probe) - `--concurrency ` - `--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 ` (sondar um provedor) +- `--probe` (probe ao vivo dos perfis de autenticação configurados) +- `--probe-provider ` (testar um provedor) - `--probe-profile ` (repetir ou ids de perfil separados por vírgula) - `--probe-timeout ` - `--probe-concurrency ` @@ -129,10 +134,10 @@ Opções: - `--agent ` (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.` 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.` 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 ` 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 ` 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) diff --git a/docs/pt-BR/cli/proxy.md b/docs/pt-BR/cli/proxy.md index 8e3115e41..957f61f77 100644 --- a/docs/pt-BR/cli/proxy.md +++ b/docs/pt-BR/cli/proxy.md @@ -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 ] [--port ] openclaw proxy run [--host ] [--port ] -- +openclaw proxy validate [--json] [--proxy-url ] [--allowed-url ] [--denied-url ] [--timeout-ms ] openclaw proxy coverage openclaw proxy sessions [--limit ] openclaw proxy query --preset [--session ] @@ -34,6 +38,28 @@ openclaw proxy blob --id 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 `: valida esta URL de proxy em vez da configuração ou do env. +- `--allowed-url `: adiciona um destino que deve ter sucesso por meio do proxy. Repita para verificar vários destinos. +- `--denied-url `: adiciona um destino que deve ser bloqueado pelo proxy. Repita para verificar vários destinos. +- `--timeout-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 ` 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) diff --git a/docs/pt-BR/cli/voicecall.md b/docs/pt-BR/cli/voicecall.md index 1ff5db852..273ad37f3 100644 --- a/docs/pt-BR/cli/voicecall.md +++ b/docs/pt-BR/cli/voicecall.md @@ -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 openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify openclaw voicecall continue --call-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 ` 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) diff --git a/docs/pt-BR/concepts/commitments.md b/docs/pt-BR/concepts/commitments.md index eec4e0387..3a3398bce 100644 --- a/docs/pt-BR/concepts/commitments.md +++ b/docs/pt-BR/concepts/commitments.md @@ -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) diff --git a/docs/pt-BR/concepts/openclaw-sdk.md b/docs/pt-BR/concepts/openclaw-sdk.md index 806245f26..1eae2326a 100644 --- a/docs/pt-BR/concepts/openclaw-sdk.md +++ b/docs/pt-BR/concepts/openclaw-sdk.md @@ -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. - 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. -## 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) diff --git a/docs/pt-BR/gateway/config-channels.md b/docs/pt-BR/gateway/config-channels.md index 18699f2b2..af9ffe8c9 100644 --- a/docs/pt-BR/gateway/config-channels.md +++ b/docs/pt-BR/gateway/config-channels.md @@ -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 | `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.` ausente), a política de grupo em runtime volta para `allowlist` (falha fechada) com um aviso na inicialização. -### 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..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..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 } ``` - + ```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..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Sobrescritas por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -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`; `openclaw doctor --fix` remove um sufixo `/bot` 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`; `openclaw doctor --fix` remove um sufixo `/bot` 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:` (DM) ou `channel:` (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..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:` (DM) ou `channel:` (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..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..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..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/` ou `users/` 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:` (DM) ou `channel:` 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..requireMention`: substituição por canal da exigência de menção (`"*"` para padrão). +- `channels.mattermost.groups..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:`. 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). @@ -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..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..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..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..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..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.` 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..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 } ``` - + -- 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..commands.nativeSkills`. +- Substitua o registro de Skills nativas por canal com `channels..commands.nativeSkills`. - `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram. -- `bash: true` habilita `! ` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. +- `bash: true` habilita `! ` para o shell do host. Exige `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. - `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..configWrites` controla mutações de configuração por canal (padrão: true). - Para canais com várias contas, `channels..accounts..configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account ` ou `/config set channels..accounts....`). - `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) --- -## 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) diff --git a/docs/pt-BR/gateway/config-tools.md b/docs/pt-BR/gateway/config-tools.md index d18b02d2d..a91a4b3d8 100644 --- a/docs/pt-BR/gateway/config-tools.md +++ b/docs/pt-BR/gateway/config-tools.md @@ -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`: -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). | 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 ``` - 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. Limite de padrão repetido sem progresso para avisos. - Limite de repetição mais alto para bloquear loops críticos. + Limite repetido mais alto para bloquear loops críticos. Limite de parada rígida para qualquer execução sem progresso. - Avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos. + Avisa sobre chamadas repetidas com a mesma ferramenta/mesmos argumentos. - Avisa/bloqueia em ferramentas de sondagem conhecidas (`process.poll`, `command_status`, etc.). + Avisa/bloqueia ferramentas de sondagem conhecidas (`process.poll`, `command_status` etc.). - Avisa/bloqueia em padrões de pares alternados sem progresso. + Avisa/bloqueia padrões alternados de pares sem progresso. @@ -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): **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. @@ -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). - - `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"`. @@ -328,13 +328,13 @@ Controla o suporte a anexos inline para `sessions_spawn`. ``` - - - Anexos são compatíveis apenas com `runtime: "subagent"`. O runtime ACP os rejeita. - - Arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. + + - 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//` 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`. @@ -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 ``` - - - Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas. + + - 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. -### Detalhes dos campos de provedor +### Detalhes dos campos do provedor - + - `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. '' --strict-json --merge` ou `openclaw config set models.providers..models '' --strict-json --merge` para atualizações aditivas. `config set` recusa substituições destrutivas, a menos que você passe `--replace`. - - - `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). + + - `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. - - `models.providers.*.request`: substituições de transporte para solicitações HTTP de provedores de modelo. + + `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`. - + - `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. - + - `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. -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 - 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 - 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. ```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`. @@ -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. @@ -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`. - + ```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. @@ -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) diff --git a/docs/pt-BR/gateway/doctor.md b/docs/pt-BR/gateway/doctor.md index 802cd888c..e33c586dc 100644 --- a/docs/pt-BR/gateway/doctor.md +++ b/docs/pt-BR/gateway/doctor.md @@ -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). @@ -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). @@ -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). @@ -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. @@ -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). -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) - - - Atualização opcional de pré-execução para instalações via git (somente interativo). + + - 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. - - - 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.`. - - Verificações de migração de navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP. + + - Normalização de config para valores legados. + - Migração da config Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.`. + - 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. - - - 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. + + - 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`). - - - 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`). + + - 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`). - - - 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). + + - 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). - - - 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). + + - 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. -## 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 - - 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. + + Se isto for um checkout git e o doctor estiver sendo executado interativamente, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor. - - 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. + + 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.`. 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.`. 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. - - Quando a configuração contém chaves obsoletas, outros comandos se recusam a executar e pedem que você execute `openclaw doctor`. + + 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..timeoutSeconds` para timeouts de provedor/modelo lentos + - remova `agents.defaults.llm`; use `models.providers..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..accounts` estiverem configuradas sem `channels..defaultAccount` ou `accounts.default`, o doctor avisa que o roteamento de fallback pode escolher uma conta inesperada. - - Se `channels..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..accounts` estiverem configuradas sem `channels..defaultAccount` ou `accounts.default`, o Doctor avisa que o roteamento de fallback pode escolher uma conta inesperada. + - Se `channels..defaultAccount` estiver definido como um ID de conta desconhecido, o Doctor avisa e lista os IDs de conta configurados. - - 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. + + 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. - 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. - 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. - - 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. + + 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. - 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. - - O doctor pode migrar layouts antigos em disco para a estrutura atual: + + O Doctor pode migrar layouts em disco mais antigos para a estrutura atual: - Armazenamento de sessões + transcrições: - de `~/.openclaw/sessions/` para `~/.openclaw/agents//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//...` (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. - - 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. + + 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. - - 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. + + 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. - 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`. - 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. - - O diretório de estado é o tronco cerebral operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar). + + O 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`. - - 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. + + 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) - - 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. + + 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. - - 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. + + Quando o sandbox está habilitado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente. - - 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. + + 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. - 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. - 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. - 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 ` - rotacione um token novo com `openclaw devices rotate --device --role ` - - remova e aprove novamente um registro obsoleto com `openclaw devices remove ` + - remova e reaprove um registro obsoleto com `openclaw devices remove ` - 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. - 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. - - 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. + + 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. - 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. - 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`. - - 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.`, alvos de Heartbeat que nomeavam o canal e substituições `agents.*.models["/*"]`. 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. + + 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.`, destinos de Heartbeat que nomeavam o canal e substituições `agents.*.models["/*"]`. 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. - - O Doctor verifica se a conclusão por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell): + + 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. - 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. 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. - - O Doctor executa uma verificação de saúde e oferece reiniciar o gateway quando ele parece não saudável. + + O doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece estar não íntegro. - 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. - - Se o gateway estiver saudável, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas. + + Se o gateway estiver íntegro, o doctor executa uma sondagem de status dos canais e relata avisos com correções sugeridas. - 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`. - - 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). + + 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). - - 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). + + 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. - 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. - 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). diff --git a/docs/pt-BR/gateway/logging.md b/docs/pt-BR/gateway/logging.md index 8752b9042..f6b7d9167 100644 --- a/docs/pt-BR/gateway/logging.md +++ b/docs/pt-BR/gateway/logging.md @@ -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) diff --git a/docs/pt-BR/gateway/protocol.md b/docs/pt-BR/gateway/protocol.md index a947cf9e7..231cf5f9a 100644 --- a/docs/pt-BR/gateway/protocol.md +++ b/docs/pt-BR/gateway/protocol.md @@ -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`. - - - `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. + + - `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. - - `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`. - - `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`. - - `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. - - `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. - - `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. - `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. - - `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 `...`, `...`, `...`, `...` 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 `...`, `...`, `...`, `...` 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. - `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. - + - `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`. - - `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. - - 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`. -### 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.`, 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.`, 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 diff --git a/docs/pt-BR/gateway/troubleshooting.md b/docs/pt-BR/gateway/troubleshooting.md index e89924c66..3b23c47e4 100644 --- a/docs/pt-BR/gateway/troubleshooting.md +++ b/docs/pt-BR/gateway/troubleshooting.md @@ -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 ``` - - Corrija `PATH` para que `openclaw` resolva para a instalação mais recente e então execute novamente a ação. + + Corrija `PATH` para que `openclaw` resolva para a instalação mais nova e então execute a ação novamente. - - Reinstale o serviço de Gateway pretendido a partir da instalação mais recente: + + 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 ``` - + Remova entradas obsoletas de pacote do sistema ou wrappers antigos que ainda apontam para um binário `openclaw` antigo. -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. -## 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: - - Desabilite `context1m` para esse modelo para voltar à janela de contexto normal. + + Desative `context1m` para esse modelo para voltar à janela de contexto normal. - - Use uma credencial Anthropic elegível para solicitações de contexto longo ou mude para uma chave de API da Anthropic. + + Use uma credencial Anthropic elegível para solicitações de contexto longo ou troque para uma chave de API Anthropic. - - Configure modelos de fallback para que as execuções continuem quando solicitações de contexto longo da Anthropic forem rejeitadas. + + Configure modelos de fallback para que as execuções continuem quando solicitações Anthropic de contexto longo forem rejeitadas. @@ -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 - - - `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..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..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. + + - `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..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..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. - - 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. + + 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. @@ -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. - + - `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. -### 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 `. 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 `. Atualizações de escopo/função usam o mesmo fluxo depois que você revisa o acesso solicitado. | -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. -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: - + O cliente aguarda o `connect.challenge` emitido pelo gateway. - - O cliente assina o payload vinculado ao desafio. + + O cliente assina a carga vinculada ao desafio. - + O cliente envia `connect.params.device.nonce` com o mesmo nonce do desafio. 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)`. - - - `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). + + - `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. @@ -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` - - - 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. + + - 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....`, 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....`, 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. - + ```bash CONFIG="$(openclaw config file)" ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head @@ -343,30 +344,31 @@ Procure por: openclaw doctor ``` - + - `.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 `***`. - + 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. 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`). - - `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`. @@ -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: - - `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; '' 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; '' 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. - - `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 "" is not reachable` → o endpoint CDP remoto configurado não está acessível a partir do host do Gateway. + - `Remote CDP for profile "" 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. - - `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 ` 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 ` para fechar a sessão de controle ativa e liberar o estado de emulação do Playwright/CDP sem reiniciar todo o gateway. @@ -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. - + ```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. - + ```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. @@ -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. -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 diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index aee7e5806..0d39da38c 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Executando testes localmente ou em CI - - Adicionando testes de regressão para bugs de modelo/provedor - - Depuração do comportamento do Gateway + agente -summary: 'Kit de testes: suítes unitárias/e2e/ao vivo, executores Docker e o que cada teste cobre' + - Executando testes localmente ou na CI + - Adicionando testes de regressão para falhas de modelo/provedor + - Depuração do Gateway + comportamento do agente +summary: 'Kit de testes: suítes unitárias/e2e/ao vivo, executores Docker e o que cada teste abrange' title: Testes x-i18n: - generated_at: "2026-04-30T18:38:50Z" + generated_at: "2026-05-01T05:57:04Z" model: gpt-5.5 provider: openai - source_hash: 470a96c6b47c2708950d05adc4a4efba5fe290f0675a131e2888d2d0032d5953 + source_hash: 3c28e45c483169f528483f7a27265d89c34f3865eb56b51407639b566e117162 source_path: help/testing.md workflow: 16 --- @@ -18,18 +18,18 @@ OpenClaw tem três suítes Vitest (unitária/integração, e2e, ao vivo) e um pe de executores Docker. Este documento é um guia de "como testamos": - O que cada suíte cobre (e o que ela deliberadamente _não_ cobre). -- Quais comandos executar para fluxos de trabalho comuns (local, antes do push, depuração). +- Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração). - Como os testes ao vivo descobrem credenciais e selecionam modelos/provedores. - Como adicionar regressões para problemas reais de modelos/provedores. -**Pilha de QA (qa-lab, qa-channel, faixas de transporte ao vivo)** é documentada separadamente: +**A pilha de QA (qa-lab, qa-channel, lanes de transporte ao vivo)** é documentada separadamente: -- [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) — arquitetura, superfície de comandos, criação de cenários. -- [QA de Matrix](/pt-BR/concepts/qa-matrix) — referência para `pnpm openclaw qa matrix`. -- [Canal de QA](/pt-BR/channels/qa-channel) — o plugin de transporte sintético usado por cenários baseados no repositório. +- [Visão geral de QA](/pt-BR/concepts/qa-e2e-automation) — arquitetura, superfície de comandos, autoria de cenários. +- [QA Matrix](/pt-BR/concepts/qa-matrix) — referência para `pnpm openclaw qa matrix`. +- [Canal de QA](/pt-BR/channels/qa-channel) — o Plugin de transporte sintético usado por cenários apoiados pelo repositório. -Esta página cobre a execução das suítes de teste regulares e dos executores Docker/Parallels. A seção de executores específicos de QA abaixo ([executores específicos de QA](#qa-specific-runners)) lista as invocações `qa` concretas e aponta de volta para as referências acima. +Esta página cobre a execução das suítes de teste regulares e dos executores Docker/Parallels. A seção de executores específicos de QA abaixo ([Executores específicos de QA](#qa-specific-runners)) lista as invocações `qa` concretas e remete às referências acima. ## Início rápido @@ -38,173 +38,171 @@ Na maioria dos dias: - Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Execução local mais rápida da suíte completa em uma máquina espaçosa: `pnpm test:max` -- Loop de observação direto do Vitest: `pnpm test:watch` -- O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Loop direto de observação do Vitest: `pnpm test:watch` +- O direcionamento direto de arquivo agora também roteia caminhos de extensões/canais: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Prefira execuções direcionadas primeiro quando estiver iterando em uma única falha. - Site de QA apoiado por Docker: `pnpm qa:lab:up` -- Faixa de QA apoiada por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Lane de QA apoiada por VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você tocar em testes ou quiser confiança extra: +Quando você tocar nos testes ou quiser confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` -Ao depurar provedores/modelos reais (requer credenciais reais): +Ao depurar provedores/modelos reais (exige credenciais reais): -- Suíte ao vivo (modelos + sondagens de ferramenta/imagem do Gateway): `pnpm test:live` +- Suíte ao vivo (modelos + sondas de ferramenta/imagem do Gateway): `pnpm test:live` - Direcione um arquivo ao vivo silenciosamente: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Varredura ao vivo de modelos no Docker: `pnpm test:docker:live-models` - - Cada modelo selecionado agora executa um turno de texto mais uma pequena sondagem no estilo leitura de arquivo. - Modelos cujos metadados anunciam entrada `image` também executam um turno minúsculo com imagem. - Desative as sondagens extras com `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` ao isolar falhas de provedor. +- Varredura de modelos ao vivo com Docker: `pnpm test:docker:live-models` + - Cada modelo selecionado agora executa uma rodada de texto mais uma pequena sonda no estilo de leitura de arquivo. + Modelos cujos metadados anunciam entrada de `image` também executam uma pequena rodada com imagem. + Desative as sondas extras com `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` ou + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` ao isolar falhas de provedores. - Cobertura de CI: `OpenClaw Scheduled Live And E2E Checks` diário e - `OpenClaw Release Checks` manual chamam o fluxo de trabalho reutilizável ao vivo/E2E com - `include_live_suites: true`, que inclui jobs separados de matriz de modelos ao vivo no Docker - fragmentados por provedor. - - Para reexecuções de CI focadas, dispare `OpenClaw Live And E2E Checks (Reusable)` + `OpenClaw Release Checks` manual chamam o fluxo de trabalho reutilizável de ao vivo/E2E com + `include_live_suites: true`, o que inclui jobs de matriz de modelos ao vivo em Docker separados + por provedor. + - Para reexecuções focadas de CI, dispare `OpenClaw Live And E2E Checks (Reusable)` com `include_live_suites: true` e `live_models_only: true`. - Adicione novos segredos de provedores de alto sinal a `scripts/ci-hydrate-live-auth.sh` mais `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` e seus chamadores agendados/de release. - Smoke de chat vinculado nativo do Codex: `pnpm test:docker:live-codex-bind` - - Executa uma faixa ao vivo no Docker contra o caminho do servidor de aplicativo do Codex, vincula uma - DM sintética do Slack com `/codex bind`, exercita `/codex fast` e - `/codex permissions`, então verifica uma resposta simples e um anexo de imagem - roteados pela vinculação nativa do plugin em vez de ACP. -- Smoke do harness do servidor de aplicativo do Codex: `pnpm test:docker:live-codex-harness` - - Executa turnos de agente do Gateway pelo harness do servidor de aplicativo do Codex pertencente ao plugin, - verifica `/codex status` e `/codex models` e, por padrão, exercita sondagens de imagem, - MCP de cron, subagente e Guardian. Desative a sondagem de subagente com - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` ao isolar outras falhas do servidor de aplicativo - do Codex. Para uma verificação focada de subagente, desative as outras sondagens: + - Executa uma lane ao vivo em Docker contra o caminho do app-server Codex, vincula uma DM sintética + do Slack com `/codex bind`, exercita `/codex fast` e + `/codex permissions`, depois verifica que uma resposta simples e um anexo de imagem + roteiam pela vinculação nativa do Plugin em vez de ACP. +- Smoke do harness do app-server Codex: `pnpm test:docker:live-codex-harness` + - Executa turnos de agente do Gateway pelo harness do app-server Codex pertencente ao Plugin, + verifica `/codex status` e `/codex models` e, por padrão, exercita sondas de imagem, + cron MCP, subagente e Guardian. Desative a sonda de subagente com + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` ao isolar outras falhas do + app-server Codex. Para uma verificação focada de subagente, desative as outras sondas: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Isso sai após a sondagem de subagente, a menos que + Isso encerra após a sonda de subagente, a menos que `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0` esteja definido. - Smoke do comando de resgate do Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Verificação opt-in de redundância para a superfície do comando de resgate do canal de mensagens. + - Verificação opcional redundante para a superfície do comando de resgate do canal de mensagens. Ela exercita `/crestodian status`, enfileira uma alteração persistente de modelo, responde `/crestodian yes` e verifica o caminho de gravação de auditoria/configuração. -- Smoke Docker do planejador do Crestodian: `pnpm test:docker:crestodian-planner` +- Smoke Docker do planejador Crestodian: `pnpm test:docker:crestodian-planner` - Executa o Crestodian em um contêiner sem configuração com uma CLI Claude falsa no `PATH` - e verifica se o fallback do planejador aproximado é traduzido em uma gravação tipada - de configuração auditada. + e verifica que o fallback do planejador fuzzy se traduz em uma gravação de configuração tipada auditada. - Smoke Docker de primeira execução do Crestodian: `pnpm test:docker:crestodian-first-run` - - Começa de um diretório de estado vazio do OpenClaw, roteia `openclaw` puro para - o Crestodian, aplica gravações de configuração/modelo/agente/plugin Discord + SecretRef, + - Começa de um diretório de estado OpenClaw vazio, roteia `openclaw` puro para + o Crestodian, aplica gravações de configuração/modelo/agente/Plugin Discord + SecretRef, valida a configuração e verifica entradas de auditoria. O mesmo caminho de configuração Ring 0 também é coberto no QA Lab por `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. - Smoke de custo Moonshot/Kimi: com `MOONSHOT_API_KEY` definido, execute `openclaw models list --provider moonshot --json`, depois execute um `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - isolado contra `moonshot/kimi-k2.6`. Verifique se o JSON relata Moonshot/K2.6 e se a + isolado contra `moonshot/kimi-k2.6`. Verifique que o JSON relata Moonshot/K2.6 e que a transcrição do assistente armazena `usage.cost` normalizado. -Quando você só precisa de um caso com falha, prefira restringir testes ao vivo pelas variáveis de ambiente de lista de permissões descritas abaixo. +Quando você precisa de apenas um caso com falha, prefira estreitar os testes ao vivo por meio das variáveis de ambiente de lista de permissões descritas abaixo. ## Executores específicos de QA -Estes comandos ficam ao lado das principais suítes de teste quando você precisa de realismo de QA-lab: +Estes comandos ficam ao lado das suítes de teste principais quando você precisa do realismo do QA Lab: -O CI executa o QA Lab em fluxos de trabalho dedicados. `Parity gate` executa em PRs correspondentes e -por disparo manual com provedores mock. `QA-Lab - All Lanes` executa todas as noites em -`main` e por disparo manual com o gate de paridade mock, faixa Matrix ao vivo, -faixa Telegram ao vivo gerenciada pelo Convex e faixa Discord ao vivo gerenciada pelo Convex como -jobs paralelos. Verificações agendadas de QA e release passam Matrix `--profile fast` -explicitamente, enquanto o padrão da CLI Matrix e da entrada manual do fluxo de trabalho permanece +A CI executa o QA Lab em fluxos de trabalho dedicados. `Parity gate` roda em PRs correspondentes e +por disparo manual com provedores mock. `QA-Lab - All Lanes` roda todas as noites em +`main` e por disparo manual com o gate de paridade mock, lane Matrix ao vivo, +lane Telegram ao vivo gerenciada pelo Convex e lane Discord ao vivo gerenciada pelo Convex como +jobs paralelos. Verificações agendadas de QA e de release passam Matrix `--profile fast` +explicitamente, enquanto a CLI Matrix e a entrada manual do fluxo de trabalho permanecem com padrão `all`; o disparo manual pode fragmentar `all` em jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` e `e2ee-cli`. `OpenClaw Release Checks` executa paridade mais -as faixas rápidas de Matrix e Telegram antes da aprovação de release, usando -`mock-openai/gpt-5.5` para verificações de transporte de release, de modo que permaneçam determinísticas -e evitem a inicialização normal de plugin de provedor. Esses gateways de transporte ao vivo desativam +as lanes rápidas Matrix e Telegram antes da aprovação de release, usando +`mock-openai/gpt-5.5` para verificações de transporte de release, para que permaneçam determinísticas +e evitem a inicialização normal do Plugin de provedor. Esses Gateways de transporte ao vivo desativam a busca de memória; o comportamento de memória permanece coberto pelas suítes de paridade de QA. -Fragmentos de mídia ao vivo de release completo usam +Os shards completos de mídia ao vivo de release usam `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, que já tem -`ffmpeg` e `ffprobe`. Fragmentos Docker de modelos/backends ao vivo usam a imagem compartilhada -`ghcr.io/openclaw/openclaw-live-test:` criada uma vez por commit selecionado, -depois a puxam com `OPENCLAW_SKIP_DOCKER_BUILD=1` em vez de reconstruir -dentro de cada fragmento. +`ffmpeg` e `ffprobe`. Shards Docker de modelos/backends ao vivo usam a imagem compartilhada +`ghcr.io/openclaw/openclaw-live-test:` construída uma vez por commit selecionado, +e depois a puxam com `OPENCLAW_SKIP_DOCKER_BUILD=1` em vez de reconstruir +dentro de cada shard. - `pnpm openclaw qa suite` - - Executa cenários de QA baseados no repositório diretamente no host. - - Executa vários cenários selecionados em paralelo por padrão com workers de + - Executa cenários de QA apoiados pelo repositório diretamente no host. + - Executa vários cenários selecionados em paralelo por padrão com workers Gateway isolados. `qa-channel` usa concorrência 4 por padrão (limitada pela - contagem de cenários selecionados). Use `--concurrency ` para ajustar a contagem de - workers, ou `--concurrency 1` para a faixa serial mais antiga. + contagem de cenários selecionados). Use `--concurrency ` para ajustar a contagem de workers, + ou `--concurrency 1` para a lane serial antiga. - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando você - quiser artefatos sem um código de saída de falha. - - Suporta modos de provedor `live-frontier`, `mock-openai` e `aimock`. + quiser artefatos sem um código de saída com falha. + - Oferece suporte aos modos de provedor `live-frontier`, `mock-openai` e `aimock`. `aimock` inicia um servidor de provedor local apoiado por AIMock para cobertura experimental - de fixtures e mocks de protocolo sem substituir a faixa `mock-openai` - ciente de cenários. + de fixtures e mocks de protocolo sem substituir a lane `mock-openai` ciente de cenários. - `pnpm test:gateway:cpu-scenarios` - Executa o benchmark de inicialização do Gateway mais um pequeno pacote de cenários mock do QA Lab (`channel-chat-baseline`, `memory-failure-fallback`, `gateway-restart-inflight-run`) e grava um resumo combinado de observação de CPU em `.artifacts/gateway-cpu-scenarios/`. - Sinaliza por padrão apenas observações sustentadas de CPU quente (`--cpu-core-warn` - mais `--hot-wall-warn-ms`), então picos curtos de inicialização são registrados como métricas - sem parecerem a regressão de Gateway preso por vários minutos. - - Usa artefatos `dist` compilados; execute uma build primeiro quando o checkout ainda não - tiver saída de runtime fresca. + mais `--hot-wall-warn-ms`), então rajadas curtas de inicialização são registradas como métricas + sem parecer a regressão de Gateway preso por minutos. + - Usa artefatos `dist` construídos; execute uma build primeiro quando o checkout ainda não + tiver saída de runtime recente. - `pnpm openclaw qa suite --runner multipass` - - Executa a mesma suíte de QA dentro de uma VM Linux descartável do Multipass. + - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host. - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`. - - Execuções ao vivo encaminham as entradas de autenticação de QA suportadas que são práticas para o guest: - chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e `CODEX_HOME` + - Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o guest: + chaves de provedores baseadas em env, o caminho de configuração do provedor ao vivo de QA e `CODEX_HOME` quando presente. - Diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado. - Grava o relatório + resumo normais de QA mais logs do Multipass em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA apoiado por Docker para trabalho de QA no estilo operador. + - Inicia o site de QA apoiado por Docker para trabalho de QA em estilo de operador. - `pnpm test:docker:npm-onboard-channel-agent` - - Cria um tarball npm a partir do checkout atual, instala-o globalmente no + - Constrói um tarball npm a partir do checkout atual, instala-o globalmente no Docker, executa onboarding não interativo de chave de API da OpenAI, configura Telegram - por padrão, verifica se habilitar o plugin instala dependências de runtime sob + por padrão, verifica que habilitar o Plugin instala dependências de runtime sob demanda, executa doctor e executa um turno de agente local contra um endpoint OpenAI - mockado. - - Use `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` para executar a mesma faixa de instalação empacotada + simulado. + - Use `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` para executar a mesma lane de instalação empacotada com Discord. - `pnpm test:docker:session-runtime-context` - - Executa um smoke Docker determinístico de aplicativo compilado para transcrições de contexto de runtime - incorporado. Ele verifica se o contexto de runtime oculto do OpenClaw é persistido como uma + - Executa um smoke Docker determinístico do app construído para transcrições de contexto de runtime + embutido. Ele verifica que o contexto de runtime OpenClaw oculto é persistido como uma mensagem customizada sem exibição em vez de vazar para o turno visível do usuário, - então semeia um JSONL de sessão quebrada afetada e verifica se - `openclaw doctor --fix` o reescreve para a branch ativa com um backup. + depois semeia um JSONL de sessão quebrada afetada e verifica que + `openclaw doctor --fix` o reescreve para o ramo ativo com um backup. - `pnpm test:docker:npm-telegram-live` - - Instala um pacote candidato do OpenClaw no Docker, executa onboarding de pacote instalado, - configura Telegram pela CLI instalada, depois reutiliza a faixa ao vivo de QA do Telegram - com esse pacote instalado como o Gateway SUT. - - Usa por padrão `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; defina + - Instala um candidato de pacote OpenClaw no Docker, executa onboarding de pacote instalado, + configura Telegram pela CLI instalada e então reutiliza a + lane de QA Telegram ao vivo com esse pacote instalado como o Gateway SUT. + - O padrão é `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; defina `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` ou `OPENCLAW_CURRENT_PACKAGE_TGZ` para testar um tarball local resolvido em vez de - instalar do registro. - - Usa as mesmas credenciais env do Telegram ou fonte de credenciais Convex que + instalar pelo registro. + - Usa as mesmas credenciais de env do Telegram ou fonte de credenciais Convex que `pnpm openclaw qa telegram`. Para automação de CI/release, defina `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` mais - `OPENCLAW_QA_CONVEX_SITE_URL` e o segredo de função. Se - `OPENCLAW_QA_CONVEX_SITE_URL` e um segredo de função Convex estiverem presentes no CI, + `OPENCLAW_QA_CONVEX_SITE_URL` e o segredo da função. Se + `OPENCLAW_QA_CONVEX_SITE_URL` e um segredo de função Convex estiverem presentes na CI, o wrapper Docker seleciona Convex automaticamente. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` substitui o - `OPENCLAW_QA_CREDENTIAL_ROLE` compartilhado apenas para esta faixa. - - GitHub Actions expõe esta faixa como o fluxo de trabalho manual de mantenedor - `NPM Telegram Beta E2E`. Ele não executa no merge. O fluxo de trabalho usa o ambiente - `qa-live-shared` e leases de credenciais de CI do Convex. -- GitHub Actions também expõe `Package Acceptance` para prova de produto em execução paralela - contra um pacote candidato. Ele aceita uma ref confiável, especificação npm publicada, - URL HTTPS de tarball mais SHA-256, ou artefato de tarball de outra execução, envia - o `openclaw-current.tgz` normalizado como `package-under-test`, então executa o - agendador Docker E2E existente com perfis de faixa smoke, package, product, full ou custom. + `OPENCLAW_QA_CREDENTIAL_ROLE` compartilhado apenas para esta lane. + - O GitHub Actions expõe esta lane como o fluxo de trabalho manual de mantenedor + `NPM Telegram Beta E2E`. Ele não é executado no merge. O fluxo de trabalho usa o + ambiente `qa-live-shared` e leases de credenciais CI do Convex. +- O GitHub Actions também expõe `Package Acceptance` para prova de produto em execução lateral + contra um pacote candidato. Ele aceita uma ref confiável, spec npm publicada, + URL HTTPS de tarball mais SHA-256 ou artefato de tarball de outra execução, envia + o `openclaw-current.tgz` normalizado como `package-under-test` e então executa o + agendador E2E Docker existente com perfis de lane smoke, pacote, produto, completo ou customizado. Defina `telegram_mode=mock-openai` ou `live-frontier` para executar o - fluxo de trabalho de QA do Telegram contra o mesmo artefato `package-under-test`. - - Prova de produto da beta mais recente: + fluxo de trabalho de QA Telegram contra o mesmo artefato `package-under-test`. + - Prova de produto da versão beta mais recente: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -214,7 +212,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Prova de URL exata de tarball requer um digest: +- Prova por URL exata de tarball exige um digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -224,7 +222,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- A prova de artefato baixa um artefato tarball de outra execução do Actions: +- A prova por artefato baixa um artefato tarball de outra execução do Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -236,32 +234,31 @@ gh workflow run package-acceptance.yml --ref main \ - `pnpm test:docker:bundled-channel-deps` - Empacota e instala a build atual do OpenClaw no Docker, inicia o Gateway - com o OpenAI configurado e então habilita canais/plugins agrupados por meio - de edições de configuração. - - Verifica se a descoberta de configuração deixa ausentes as dependências de - runtime de plugins não configurados, se a primeira execução configurada do - Gateway ou do doctor instala sob demanda as dependências de runtime de cada - plugin agrupado e se uma segunda reinicialização não reinstala dependências - que já foram ativadas. - - Também instala uma linha de base npm mais antiga conhecida, habilita o Telegram antes de executar - `openclaw update --tag ` e verifica se o doctor pós-atualização - do candidato repara as dependências de runtime de canais agrupados sem um - reparo postinstall do lado do harness. + com o OpenAI configurado e, em seguida, habilita canais/plugins integrados via edições + de configuração. + - Verifica se a descoberta de configuração deixa ausentes as dependências de runtime + de Plugin não configuradas, se o primeiro Gateway configurado ou a execução do doctor instala as dependências de runtime + de cada Plugin integrado sob demanda, e se uma segunda reinicialização não + reinstala dependências que já foram ativadas. + - Também instala uma linha de base npm mais antiga conhecida, habilita Telegram antes de executar + `openclaw update --tag ` e verifica se o doctor pós-atualização do candidato + repara as dependências de runtime de canais integrados sem um + reparo postinstall no lado do harness. - `pnpm test:parallels:npm-update` - - Executa o smoke de atualização de instalação empacotada nativa em guests do Parallels. Cada + - Executa o smoke de atualização de instalação empacotada nativa em convidados Parallels. Cada plataforma selecionada primeiro instala o pacote de linha de base solicitado, depois executa - o comando `openclaw update` instalado no mesmo guest e verifica a - versão instalada, o status da atualização, a prontidão do gateway e uma - interação de agente local. - - Use `--platform macos`, `--platform windows` ou `--platform linux` durante - a iteração em um guest. Use `--json` para o caminho do artefato de resumo e + o comando `openclaw update` instalado no mesmo convidado e verifica a + versão instalada, o status da atualização, a prontidão do Gateway e uma interação de agente + local. + - Use `--platform macos`, `--platform windows` ou `--platform linux` ao + iterar em um convidado. Use `--json` para o caminho do artefato de resumo e o status por lane. - - A lane do OpenAI usa `openai/gpt-5.5` para a prova de interação de agente - live por padrão. Passe `--model ` ou defina + - A lane do OpenAI usa `openai/gpt-5.5` para a prova de interação de agente ao vivo por + padrão. Passe `--model ` ou defina `OPENCLAW_PARALLELS_OPENAI_MODEL` ao validar deliberadamente outro modelo OpenAI. - - Envolva execuções locais longas em um timeout do host para que travamentos - de transporte do Parallels não consumam o restante da janela de testes: + - Envolva execuções locais longas em um timeout do host para que travamentos de transporte do Parallels não + consumam o restante da janela de testes: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -270,41 +267,41 @@ gh workflow run package-acceptance.yml --ref main \ - O script grava logs de lanes aninhadas em `/tmp/openclaw-parallels-npm-update.*`. Inspecione `windows-update.log`, `macos-update.log` ou `linux-update.log` - antes de presumir que o wrapper externo travou. - - A atualização no Windows pode passar de 10 a 15 minutos no reparo pós-atualização - do doctor/dependências de runtime em um guest frio; isso ainda é saudável quando o log - de depuração npm aninhado está avançando. - - Não execute este wrapper agregado em paralelo com lanes individuais de smoke - macOS, Windows ou Linux do Parallels. Elas compartilham estado de VM e podem colidir na - restauração de snapshot, no serviço de pacotes ou no estado do gateway do guest. - - A prova pós-atualização executa a superfície normal de plugins agrupados porque - fachadas de capacidade como fala, geração de imagens e entendimento de mídia - são carregadas por meio de APIs de runtime agrupadas mesmo quando a interação + antes de assumir que o wrapper externo está travado. + - A atualização no Windows pode passar de 10 a 15 minutos no reparo pós-atualização do doctor/runtime + de dependências em um convidado frio; isso ainda é saudável quando o log de depuração + npm aninhado está avançando. + - Não execute este wrapper agregado em paralelo com lanes de smoke individuais do Parallels + para macOS, Windows ou Linux. Elas compartilham estado da VM e podem colidir na + restauração de snapshot, no serviço de pacotes ou no estado do Gateway do convidado. + - A prova pós-atualização executa a superfície normal de Plugin integrado porque + fachadas de capacidade como fala, geração de imagem e compreensão + de mídia são carregadas por APIs de runtime integradas mesmo quando a interação do agente em si verifica apenas uma resposta de texto simples. - `pnpm openclaw qa aimock` - - Inicia apenas o servidor local do provedor AIMock para testes diretos de smoke - do protocolo. + - Inicia apenas o servidor provedor AIMock local para testes de smoke + diretos do protocolo. - `pnpm openclaw qa matrix` - - Executa a lane live de QA do Matrix contra um homeserver Tuwunel descartável baseado em Docker. Somente checkout de código-fonte — instalações empacotadas não distribuem `qa-lab`. + - Executa a lane de QA ao vivo do Matrix contra um homeserver Tuwunel descartável com suporte do Docker. Apenas checkout do código-fonte — instalações empacotadas não distribuem `qa-lab`. - CLI completa, catálogo de perfis/cenários, variáveis de ambiente e layout de artefatos: [QA do Matrix](/pt-BR/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Executa a lane live de QA do Telegram contra um grupo privado real usando os tokens do bot driver e do bot SUT do env. + - Executa a lane de QA ao vivo do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do ambiente. - Requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. - Aceita `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases em pool. - - Sai com valor diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando você - quiser artefatos sem um código de saída com falha. + - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando você + quiser artefatos sem um código de saída de falha. - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. - - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot no `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots do grupo. - - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. Cenários de resposta incluem RTT desde a solicitação de envio do driver até a resposta SUT observada. + - Para observação bot-para-bot estável, habilite o Modo de Comunicação Bot-to-Bot em `@BotFather` para ambos os bots e garanta que o bot driver consiga observar o tráfego de bots do grupo. + - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. Cenários de resposta incluem RTT desde a solicitação de envio do driver até a resposta observada do SUT. -Lanes de transporte live compartilham um contrato padrão para que novos transportes não divirjam; a matriz de cobertura por lane fica em [visão geral de QA → Cobertura de transporte live](/pt-BR/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` é a suíte sintética ampla e não faz parte dessa matriz. +As lanes de transporte ao vivo compartilham um contrato padrão para que novos transportes não divirjam; a matriz de cobertura por lane fica em [visão geral de QA → Cobertura de transporte ao vivo](/pt-BR/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` é a suíte sintética ampla e não faz parte dessa matriz. ### Credenciais compartilhadas do Telegram via Convex (v1) -Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) é habilitado para -`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool baseado em Convex, envia heartbeats -para esse lease enquanto a lane está em execução e libera o lease no desligamento. +Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para +`openclaw qa telegram`, o QA lab obtém um lease exclusivo de um pool apoiado por Convex, envia heartbeats +desse lease enquanto a lane está em execução e libera o lease no encerramento. Scaffold de projeto Convex de referência: @@ -312,13 +309,13 @@ Scaffold de projeto Convex de referência: Variáveis de ambiente obrigatórias: -- `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) - Um segredo para o papel selecionado: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` -- Seleção do papel da credencial: +- Seleção de papel de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão do env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `ci` em CI, `maintainer` caso contrário) + - Padrão de env: `OPENCLAW_QA_CREDENTIAL_ROLE` (assume `ci` no CI, caso contrário `maintainer`) Variáveis de ambiente opcionais: @@ -328,11 +325,11 @@ Variáveis de ambiente opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento somente local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback para desenvolvimento apenas local. -`OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` na operação normal. +`OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos de mantenedor (adicionar/remover/listar pool) requerem +Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. Helpers de CLI para mantenedores: @@ -344,35 +341,35 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Use `doctor` antes de execuções live para verificar a URL do site Convex, segredos do broker, -prefixo de endpoint, timeout HTTP e acessibilidade de admin/list sem imprimir -valores secretos. Use `--json` para saída legível por máquina em scripts e -utilitários de CI. +Use `doctor` antes de execuções ao vivo para verificar a URL do site Convex, os segredos do broker, +o prefixo do endpoint, o timeout HTTP e a acessibilidade de admin/list sem imprimir +valores secretos. Use `--json` para saída legível por máquina em scripts e utilitários +de CI. Contrato de endpoint padrão (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Solicitação: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Sucesso: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Esgotado/repetível: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Esgotado/tentável novamente: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) - `POST /release` - Solicitação: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Sucesso: `{ status: "ok" }` (ou `2xx` vazio) -- `POST /admin/add` (somente segredo de mantenedor) +- `POST /admin/add` (apenas segredo de mantenedor) - Solicitação: `{ kind, actorId, payload, note?, status? }` - Sucesso: `{ status: "ok", credential }` -- `POST /admin/remove` (somente segredo de mantenedor) +- `POST /admin/remove` (apenas segredo de mantenedor) - Solicitação: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (somente segredo de mantenedor) +- `POST /admin/list` (apenas segredo de mantenedor) - Solicitação: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` -Formato de payload para o tipo Telegram: +Formato do payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId` deve ser uma string de id numérico de chat do Telegram. @@ -380,122 +377,126 @@ Formato de payload para o tipo Telegram: ### Adicionando um canal ao QA -A arquitetura e os nomes de helpers de cenário para novos adaptadores de canal ficam em [visão geral de QA → Adicionando um canal](/pt-BR/concepts/qa-e2e-automation#adding-a-channel). O requisito mínimo: implementar o runner de transporte no seam compartilhado do host `qa-lab`, declarar `qaRunners` no manifesto do plugin, montar como `openclaw qa ` e criar cenários em `qa/scenarios/`. +A arquitetura e os nomes de helpers de cenário para novos adaptadores de canal ficam em [visão geral de QA → Adicionando um canal](/pt-BR/concepts/qa-e2e-automation#adding-a-channel). O requisito mínimo: implementar o runner de transporte na seam compartilhada do host `qa-lab`, declarar `qaRunners` no manifesto do Plugin, montar como `openclaw qa ` e criar cenários em `qa/scenarios/`. -## Suítes de teste (o que executa onde) +## Suítes de teste (o que roda onde) Pense nas suítes como “realismo crescente” (e maior instabilidade/custo): -### Unitário / integração (padrão) +### Unidade / integração (padrão) - Comando: `pnpm test` - Configuração: execuções sem alvo usam o conjunto de shards `vitest.full-*.config.ts` e podem expandir shards multiprojeto em configurações por projeto para agendamento paralelo -- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts` e `test/**/*.test.ts`; testes unitários de UI executam no shard dedicado `unit-ui` +- Arquivos: inventários de core/unidade em `src/**/*.test.ts`, `packages/**/*.test.ts` e `test/**/*.test.ts`; testes unitários de UI rodam no shard dedicado `unit-ui` - Escopo: - Testes unitários puros - - Testes de integração em processo (autenticação do gateway, roteamento, ferramentas, parsing, configuração) + - Testes de integração em processo (autenticação do Gateway, roteamento, ferramentas, parsing, configuração) - Regressões determinísticas para bugs conhecidos - Expectativas: - - Executa em CI - - Não requer chaves reais + - Roda no CI + - Não exige chaves reais - Deve ser rápido e estável - - Testes de resolvedor e loader de superfície pública devem provar o comportamento amplo de fallback de `api.js` e - `runtime-api.js` com fixtures minúsculos de plugin gerados, não - APIs de código-fonte de plugins agrupados reais. Loads de API de plugins reais pertencem às - suítes de contrato/integração pertencentes aos plugins. + - Testes de resolver e loader de superfície pública devem comprovar o comportamento amplo de fallback de `api.js` e + `runtime-api.js` com fixtures minúsculos gerados de Plugin, não + APIs reais de código-fonte de Plugin integrado. Carregamentos reais de API de Plugin pertencem a + suítes de contrato/integração de propriedade do Plugin. - - `pnpm test` sem alvo executa doze configurações de shards menores (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de resposta automática/Plugin deixe suítes não relacionadas sem recursos. - - `pnpm test --watch` ainda usa o grafo de projeto raiz nativo `vitest.config.ts`, porque um loop de observação com múltiplos shards não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam alvos explícitos de arquivo/diretório primeiro por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo completo de inicialização do projeto raiz. - - `pnpm test:changed` expande caminhos git alterados para lanes baratas com escopo por padrão: edições diretas de testes, arquivos irmãos `*.test.ts`, mapeamentos explícitos de código-fonte e dependentes locais do grafo de imports. Edições de configuração/setup/pacote não executam testes amplos, a menos que você use explicitamente `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` é o gate normal de verificação local inteligente para trabalho restrito. Ele classifica o diff em core, testes de core, plugins, testes de plugins, apps, docs, metadados de release, ferramentas live de Docker e tooling, depois executa os comandos correspondentes de typecheck, lint e guardas. Ele não executa testes Vitest; chame `pnpm test:changed` ou `pnpm test ` explícito para comprovação de teste. Aumentos de versão somente de metadados de release executam verificações direcionadas de versão/configuração/dependência raiz, com um guarda que rejeita alterações de pacote fora do campo de versão de nível superior. - - Edições do harness live Docker ACP executam verificações focadas: sintaxe de shell para os scripts de autenticação live Docker e uma simulação do agendador live Docker. Alterações em `package.json` são incluídas somente quando o diff é limitado a `scripts["test:docker:live-*"]`; edições de dependências, exports, versão e outras superfícies de pacote ainda usam os guardas mais amplos. - - Testes unitários leves de import de agentes, comandos, plugins, auxiliares de resposta automática, `plugin-sdk` e áreas semelhantes de utilitários puros passam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado/pesados de runtime permanecem nas lanes existentes. - - Arquivos-fonte auxiliares selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo alterado para testes irmãos explícitos nessas lanes leves, então edições auxiliares evitam executar novamente a suíte pesada completa desse diretório. - - `auto-reply` tem buckets dedicados para auxiliares de core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. O CI ainda divide a subárvore de resposta em shards de agent-runner, dispatch e comandos/roteamento de estado para que um bucket pesado em imports não concentre toda a cauda de Node. - - O CI normal de PR/main intencionalmente ignora a varredura em lote de plugins e o shard `agentic-plugins` somente de release. A Validação Completa de Release dispara o workflow filho separado `Plugin Prerelease` para essas suítes pesadas em plugins em candidatos a release. + - Execuções não direcionadas de `pnpm test` rodam doze configurações menores de shard (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um processo gigante nativo de projeto raiz. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensão prive suites não relacionadas. + - `pnpm test --watch` ainda usa o grafo de projeto raiz nativo de `vitest.config.ts`, porque um loop de observação com múltiplos shards não é prático. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham alvos explícitos de arquivo/diretório primeiro por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo de inicialização completo do projeto raiz. + - `pnpm test:changed` expande caminhos git alterados em lanes baratas com escopo por padrão: edições diretas de teste, arquivos irmãos `*.test.ts`, mapeamentos explícitos de origem e dependentes locais do grafo de imports. Edições de config/setup/pacote não executam testes de forma ampla, a menos que você use explicitamente `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` é o gate normal de verificação local inteligente para trabalho estreito. Ele classifica o diff em core, testes do core, extensões, testes de extensão, apps, docs, metadados de release, tooling de Docker ao vivo e tooling, então executa os comandos correspondentes de typecheck, lint e guard. Ele não executa testes Vitest; chame `pnpm test:changed` ou `pnpm test ` explícito para prova de teste. Bumps de versão somente de metadados de release executam verificações direcionadas de versão/config/dependência raiz, com um guard que rejeita alterações de pacote fora do campo de versão de nível superior. + - Edições do harness ACP de Docker ao vivo executam verificações focadas: sintaxe de shell para os scripts de auth do Docker ao vivo e um dry-run do agendador de Docker ao vivo. Alterações em `package.json` são incluídas somente quando o diff é limitado a `scripts["test:docker:live-*"]`; edições de dependência, export, versão e outras superfícies de pacote ainda usam os guards mais amplos. + - Testes unitários leves em imports de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes passam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado/pesados de runtime permanecem nas lanes existentes. + - Arquivos de origem auxiliares selecionados de `plugin-sdk` e `commands` também mapeiam execuções em modo alterado para testes irmãos explícitos nessas lanes leves, então edições de helpers evitam reexecutar a suite pesada completa desse diretório. + - `auto-reply` tem buckets dedicados para helpers de core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. O CI divide ainda mais a subárvore reply em shards de agent-runner, dispatch e commands/state-routing para que um bucket pesado em imports não fique com toda a cauda do Node. + - O CI normal de PR/main ignora intencionalmente a varredura em lote de extensões e o shard `agentic-plugins` somente de release. A Validação Completa de Release dispara o workflow filho separado `Plugin Prerelease` para essas suites pesadas em plugins/extensões em candidatos a release. - + - - Quando você alterar entradas de descoberta de ferramentas de mensagem ou contexto de runtime de Compaction, - mantenha os dois níveis de cobertura. - - Adicione regressões auxiliares focadas para limites puros de roteamento e normalização. - - Mantenha saudáveis as suítes de integração do runner embutido: + - Quando você alterar entradas de descoberta de message-tool ou o contexto de runtime de Compaction, + mantenha ambos os níveis de cobertura. + - Adicione regressões focadas de helpers para limites puros de roteamento e normalização. + - Mantenha saudáveis as suites de integração do runner embutido: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Essas suítes verificam que ids com escopo e o comportamento de Compaction ainda fluem - pelos caminhos reais de `run.ts` / `compact.ts`; testes apenas de auxiliares + - Essas suites verificam que ids com escopo e comportamento de Compaction ainda fluem + pelos caminhos reais de `run.ts` / `compact.ts`; testes apenas de helper não são um substituto suficiente para esses caminhos de integração. - + - - A configuração base do Vitest usa `threads` por padrão. - - A configuração compartilhada do Vitest fixa `isolate: false` e usa o - runner não isolado nos projetos raiz, nas configurações e2e e live. + - A config base do Vitest usa `threads` por padrão. + - A config compartilhada do Vitest fixa `isolate: false` e usa o + runner não isolado nos projetos raiz, configs e2e e live. - A lane de UI raiz mantém seu setup `jsdom` e otimizador, mas também roda no runner compartilhado não isolado. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` - da configuração compartilhada do Vitest. - - `scripts/run-vitest.mjs` adiciona `--no-maglev` por padrão para processos - Node filhos do Vitest para reduzir churn de compilação do V8 durante grandes execuções locais. - Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` para comparar com o comportamento padrão do V8. + da config compartilhada do Vitest. + - `scripts/run-vitest.mjs` adiciona `--no-maglev` para processos Node filhos do Vitest + por padrão para reduzir churn de compilação do V8 durante execuções locais grandes. + Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` para comparar com o comportamento V8 + padrão. - + - `pnpm changed:lanes` mostra quais lanes arquiteturais um diff aciona. - - O hook de pre-commit é somente de formatação. Ele recoloca em stage os arquivos formatados e - não executa lint, typecheck nem testes. - - Execute `pnpm check:changed` explicitamente antes do handoff ou push quando você - precisar do gate inteligente de verificação local. - - `pnpm test:changed` roteia por lanes baratas com escopo por padrão. Use - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando o agente - decidir que uma edição de harness, configuração, pacote ou contrato realmente precisa de cobertura Vitest mais ampla. + - O hook pre-commit é somente de formatação. Ele restageia arquivos formatados e + não executa lint, typecheck ou testes. + - Execute `pnpm check:changed` explicitamente antes de handoff ou push quando você + precisar do gate de verificação local inteligente. + - `pnpm test:changed` encaminha por lanes baratas com escopo por padrão. Use + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` somente quando o agent + decidir que uma edição de harness, config, pacote ou contrato realmente precisa de cobertura + Vitest mais ampla. - `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers. - - O autoescalonamento de workers locais é intencionalmente conservador e reduz a carga - quando a média de carga do host já está alta, então múltiplas execuções Vitest simultâneas - causam menos impacto por padrão. - - A configuração base do Vitest marca os projetos/arquivos de configuração como - `forceRerunTriggers` para que reexecuções em modo alterado continuem corretas quando a fiação dos testes muda. - - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; - defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser - um local de cache explícito para profiling direto. + - O autoescalonamento local de workers é intencionalmente conservador e recua + quando a média de carga do host já está alta, então múltiplas execuções + Vitest concorrentes causam menos impacto por padrão. + - A config base do Vitest marca os projetos/arquivos de config como + `forceRerunTriggers` para que reexecuções em modo alterado continuem corretas quando a + fiação de testes muda. + - A config mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; + defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se você quiser + um local explícito de cache para profiling direto. - + - `pnpm test:perf:imports` habilita o relatório de duração de imports do Vitest mais - a saída de detalhamento de imports. - - `pnpm test:perf:imports:changed` aplica o mesmo modo de profiling a + saída de detalhamento de imports. + - `pnpm test:perf:imports:changed` limita a mesma visão de profiling a arquivos alterados desde `origin/main`. - - Dados de tempo dos shards são gravados em `.artifacts/vitest-shard-timings.json`. - Execuções de configuração inteira usam o caminho da configuração como chave; shards de CI com padrão de inclusão - acrescentam o nome do shard para que shards filtrados possam ser acompanhados separadamente. + - Dados de tempo de shard são gravados em `.artifacts/vitest-shard-timings.json`. + Execuções de config inteira usam o caminho da config como chave; shards de CI com + padrão de inclusão acrescentam o nome do shard para que shards filtrados possam ser rastreados + separadamente. - Quando um teste quente ainda gasta a maior parte do tempo em imports de inicialização, - mantenha dependências pesadas atrás de uma borda local estreita `*.runtime.ts` e - faça mock dessa borda diretamente em vez de importar profundamente auxiliares de runtime apenas + mantenha dependências pesadas atrás de uma seam local estreita `*.runtime.ts` e + faça mock direto dessa seam em vez de deep-importar helpers de runtime apenas para passá-los por `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` compara o `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado - e imprime tempo total mais RSS máximo no macOS. - - `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore suja atual + e imprime tempo de parede mais RSS máximo do macOS. + - `pnpm test:perf:changed:bench -- --worktree` mede a árvore suja atual roteando a lista de arquivos alterados por - `scripts/test-projects.mjs` e pela configuração raiz do Vitest. + `scripts/test-projects.mjs` e pela config raiz do Vitest. - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para - overhead de inicialização e transform do Vitest/Vite. + overhead de inicialização e transformação do Vitest/Vite. - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a - suíte unitária com paralelismo por arquivo desabilitado. + suite unitária com paralelismo de arquivos desabilitado. @@ -503,36 +504,36 @@ Pense nas suítes como “realismo crescente” (e maior instabilidade/custo): ### Estabilidade (gateway) - Comando: `pnpm test:stability:gateway` -- Configuração: `vitest.gateway.config.ts`, forçada para um worker +- Config: `vitest.gateway.config.ts`, forçada a um worker - Escopo: - - Inicia um Gateway real em loopback com diagnósticos habilitados por padrão - - Conduz churn sintético de mensagem de gateway, memória e payload grande pelo caminho de eventos de diagnóstico - - Consulta `diagnostics.stability` via RPC WS do Gateway - - Cobre auxiliares de persistência do pacote de estabilidade de diagnóstico - - Confirma que o gravador permanece limitado, amostras sintéticas de RSS ficam abaixo do orçamento de pressão e profundidades de fila por sessão drenam de volta para zero + - Inicia um Gateway real de loopback com diagnósticos habilitados por padrão + - Conduz churn sintético de mensagens do gateway, memória e payloads grandes pelo caminho de eventos diagnósticos + - Consulta `diagnostics.stability` pelo RPC WS do Gateway + - Cobre helpers de persistência do bundle de estabilidade diagnóstica + - Afirma que o recorder permanece limitado, amostras sintéticas de RSS ficam abaixo do orçamento de pressão e profundidades de fila por sessão drenam de volta para zero - Expectativas: - Seguro para CI e sem chaves - - Lane estreita para acompanhamento de regressão de estabilidade, não um substituto para a suíte completa de Gateway + - Lane estreita para acompanhamento de regressão de estabilidade, não um substituto para a suite completa do Gateway ### E2E (smoke de gateway) - Comando: `pnpm test:e2e` -- Configuração: `vitest.e2e.config.ts` +- Config: `vitest.e2e.config.ts` - Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` e testes E2E de plugins incluídos em `extensions/` - Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repositório. + - Usa `threads` do Vitest com `isolate: false`, correspondendo ao restante do repo. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Executa em modo silencioso por padrão para reduzir overhead de E/S do console. + - Roda em modo silencioso por padrão para reduzir overhead de I/O de console. - Overrides úteis: - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reabilitar saída detalhada do console. + - `OPENCLAW_E2E_VERBOSE=1` para reabilitar saída detalhada de console. - Escopo: - Comportamento end-to-end de gateway multi-instância - - Superfícies WebSocket/HTTP, pareamento de node e networking mais pesado + - Superfícies WebSocket/HTTP, pareamento de nodes e networking mais pesado - Expectativas: - - Executa no CI (quando habilitado no pipeline) - - Não exige chaves reais - - Mais partes móveis do que testes unitários (pode ser mais lento) + - Roda no CI (quando habilitado no pipeline) + - Nenhuma chave real necessária + - Mais partes móveis que testes unitários (pode ser mais lento) ### E2E: smoke do backend OpenShell @@ -541,165 +542,166 @@ Pense nas suítes como “realismo crescente” (e maior instabilidade/custo): - Escopo: - Inicia um gateway OpenShell isolado no host via Docker - Cria um sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell da OpenClaw sobre `sandbox ssh-config` real + execução SSH - - Verifica o comportamento de sistema de arquivos remoto-canônico pela ponte fs do sandbox + - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` real + execução SSH + - Verifica comportamento de filesystem canônico remoto por meio da bridge fs do sandbox - Expectativas: - Somente opt-in; não faz parte da execução padrão de `pnpm test:e2e` - - Exige uma CLI `openshell` local mais um daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o gateway e o sandbox de teste + - Requer uma CLI local `openshell` mais um daemon Docker funcional + - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o gateway e sandbox de teste - Overrides úteis: - - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário de CLI não padrão ou script wrapper + - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suite e2e mais ampla + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper ### Live (provedores reais + modelos reais) - Comando: `pnpm test:live` -- Configuração: `vitest.live.config.ts` +- Config: `vitest.live.config.ts` - Arquivos: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` e testes live de plugins incluídos em `extensions/` - Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) - Escopo: - “Este provedor/modelo realmente funciona _hoje_ com credenciais reais?” - - Capturar mudanças de formato de provedor, particularidades de chamadas de ferramentas, problemas de autenticação e comportamento de rate limit + - Capturar alterações de formato de provedor, peculiaridades de tool-calling, problemas de auth e comportamento de rate limit - Expectativas: - Não é estável para CI por design (redes reais, políticas reais de provedores, cotas, indisponibilidades) - - Custa dinheiro / usa limites de taxa - - Prefira executar subconjuntos restritos em vez de “tudo” + - Custa dinheiro / usa rate limits + - Prefira executar subconjuntos estreitos em vez de “tudo” - Execuções live carregam `~/.profile` para obter chaves de API ausentes. -- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um home de teste temporário para que fixtures unitárias não possam alterar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` somente quando você intencionalmente precisar que testes live usem seu diretório home real. -- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/ruído de Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser os logs completos de inicialização de volta. -- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou override por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de rate limit. +- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para uma home temporária de teste para que fixtures unitárias não possam mutar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` somente quando você precisar intencionalmente que testes live usem seu diretório home real. +- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/ruído Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser os logs completos de inicialização de volta. +- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou override por live via `OPENCLAW_LIVE_*_KEY`; testes tentam novamente em respostas de rate limit. - Saída de progresso/Heartbeat: - - As suítes live agora emitem linhas de progresso para stderr para que chamadas longas a provedores fiquem visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. + - Suites live agora emitem linhas de progresso para stderr para que chamadas longas de provedor fiquem visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/gateway sejam transmitidas imediatamente durante execuções live. - Ajuste Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - Ajuste Heartbeats de gateway/probe com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Qual suíte devo executar? +## Qual suite devo executar? Use esta tabela de decisão: -- Edição de lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você alterou muita coisa) -- Mexendo em rede do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot está fora do ar” / falhas específicas de provedor / chamada de ferramentas: execute um `pnpm test:live` restrito +- Editar lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou muita coisa) +- Mexer em rede do Gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` +- Depurar “meu bot está fora do ar” / falhas específicas de provedor / chamadas de ferramenta: execute um `pnpm test:live` restringido -## Testes live (que tocam na rede) +## Testes live (que tocam a rede) -Para a matriz de modelos live, smokes de backend da CLI, smokes de ACP, harness do servidor de app do Codex e todos os testes live de provedores de mídia (Deepgram, BytePlus, ComfyUI, imagem, música, vídeo, harness de mídia) — além do tratamento de credenciais para execuções live — consulte [Testing — live suites](/pt-BR/help/testing-live). +Para a matriz de modelos live, smokes de backend da CLI, smokes de ACP, harness do app-server Codex e todos os testes live de provedores de mídia (Deepgram, BytePlus, ComfyUI, imagem, música, vídeo, harness de mídia) — além do tratamento de credenciais para execuções live — consulte [Testes — suítes live](/pt-BR/help/testing-live). -## Runners Docker (verificações opcionais de "funciona no Linux") +## Executores Docker (verificações opcionais de "funciona no Linux") -Estes runners Docker se dividem em dois grupos: +Estes executores Docker se dividem em dois grupos: -- Runners de modelos live: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live de chave de perfil correspondente dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de configuração e o workspace (e carregando `~/.profile`, se montado). Os pontos de entrada locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Runners live Docker usam por padrão um limite de smoke menor para manter uma varredura Docker completa prática: - `test:docker:live-models` usa `OPENCLAW_LIVE_MAX_MODELS=12` por padrão, e - `test:docker:live-gateway` usa `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Executores de modelos live: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live da chave de perfil correspondente dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório de configuração local e workspace (e carregando `~/.profile` se estiver montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Executores live em Docker usam por padrão um limite de smoke menor para que uma varredura completa em Docker continue prática: + `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e + `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000` por padrão. Sobrescreva essas variáveis de ambiente quando você + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Sobrescreva essas variáveis de ambiente quando você quiser explicitamente a varredura exaustiva maior. -- `test:docker:all` cria a imagem Docker live uma vez via `test:docker:live-build`, empacota o OpenClaw uma vez como um tarball npm por meio de `scripts/package-openclaw-for-docker.mjs` e então cria/reutiliza duas imagens `scripts/e2e/Dockerfile`. A imagem básica é apenas o runner Node/Git para vias de instalação/atualização/dependências de Plugin; essas vias montam o tarball pré-criado. A imagem funcional instala o mesmo tarball em `/app` para vias de funcionalidade do app construído. As definições das vias 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. O agregado usa um escalonador local ponderado: `OPENCLAW_DOCKER_ALL_PARALLELISM` controla os slots de processo, enquanto limites de recursos impedem que vias pesadas de live, instalação npm e múltiplos serviços iniciem todas de uma vez. Se uma única via for mais pesada que os limites ativos, o escalonador ainda pode iniciá-la quando o pool estiver vazio e então a mantém rodando sozinha até haver capacidade novamente. Os padrões são 10 slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` e `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; ajuste `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` apenas quando o host Docker tiver mais folga. O runner executa um preflight Docker por padrão, remove contêineres E2E antigos do OpenClaw, imprime status a cada 30 segundos, armazena tempos de vias bem-sucedidas em `.artifacts/docker-tests/lane-timings.json` e usa esses tempos para iniciar vias mais longas primeiro em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto ponderado de vias sem criar nem executar Docker, ou `node scripts/test-docker-all.mjs --plan-json` para imprimir o plano de CI para vias selecionadas, necessidades de pacote/imagem e credenciais. -- `Package Acceptance` é o gate de pacote nativo do GitHub para "este tarball instalável funciona como produto?" Ele resolve um pacote candidato a partir de `source=npm`, `source=ref`, `source=url` ou `source=artifact`, envia-o como `package-under-test` e então executa as vias Docker E2E reutilizáveis contra esse tarball exato em vez de reempacotar a ref selecionada. `workflow_ref` seleciona os scripts confiáveis de workflow/harness, enquanto `package_ref` seleciona o commit/branch/tag de origem a empacotar quando `source=ref`; isso permite que a lógica de aceitação atual valide commits confiáveis mais antigos. Os perfis são ordenados por abrangência: `smoke` é instalação/canal/agente rápidos mais Gateway/configuração, `package` é o contrato de pacote/atualização/Plugin mais a fixture keyless upgrade-survivor e a substituição nativa padrão para a maior parte da cobertura de pacote/atualização do Parallels, `product` adiciona canais MCP, limpeza de cron/subagente, pesquisa web da OpenAI e OpenWebUI, e `full` executa os blocos Docker do caminho de release com OpenWebUI. A validação de release executa um delta de pacote personalizado (`bundled-channel-deps-compat plugins-offline`) mais QA de pacote Telegram porque os blocos Docker do caminho de release já cobrem as vias sobrepostas de pacote/atualização/Plugin. Comandos direcionados de reexecução Docker no GitHub gerados a partir de artefatos incluem o artefato de pacote anterior e entradas de imagem preparadas quando disponíveis, para que vias com falha possam evitar recriar o pacote e as imagens. -- Verificações de build e release executam `scripts/check-cli-bootstrap-imports.mjs` após o tsdown. A proteção percorre o grafo construído estático a partir de `dist/entry.js` e `dist/cli/run-main.js` e falha se a inicialização antes do despacho importar dependências de pacote como Commander, UI de prompt, undici ou logging antes do despacho do comando; ela também mantém o bloco de execução do Gateway empacotado dentro do orçamento e rejeita importações estáticas de caminhos frios conhecidos do Gateway. O smoke da CLI empacotada também cobre ajuda raiz, ajuda de onboarding, ajuda do doctor, status, schema de configuração e um comando de lista de modelos. -- A compatibilidade legada do Package Acceptance é limitada a `2026.4.25` (`2026.4.25-beta.*` incluído). Até esse ponto de corte, o harness tolera apenas lacunas de metadados de pacote enviado: entradas omitidas de inventário privado de QA, ausência de `gateway install --wrapper`, arquivos de patch ausentes na fixture git derivada do tarball, ausência de `update.channel` persistido, locais legados de registros de instalação de Plugin, ausência de persistência de registros de instalação do marketplace e migração de metadados de configuração durante `plugins update`. Para pacotes após `2026.4.25`, esses caminhos são falhas estritas. -- Runners de smoke de contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` e `test:docker:config-reload` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto. +- `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build`, empacota o OpenClaw uma vez como um tarball npm por meio de `scripts/package-openclaw-for-docker.mjs` e então constrói/reutiliza duas imagens `scripts/e2e/Dockerfile`. A imagem básica é apenas o executor Node/Git para faixas de instalação/atualização/dependência de plugins; essas faixas montam o tarball pré-construído. A imagem funcional instala o mesmo tarball em `/app` para faixas de funcionalidade do aplicativo compilado. As definições de faixas 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. O agregado usa um agendador local ponderado: `OPENCLAW_DOCKER_ALL_PARALLELISM` controla slots de processo, enquanto limites de recursos impedem que faixas pesadas live, npm-install e multisserviço comecem todas de uma vez. Se uma única faixa for mais pesada que os limites ativos, o agendador ainda poderá iniciá-la quando o pool estiver vazio e então mantê-la em execução sozinha até que a capacidade esteja disponível novamente. Os padrões são 10 slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` e `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; ajuste `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` ou `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` apenas quando o host Docker tiver mais folga. O executor faz uma pré-verificação do Docker por padrão, remove containers E2E obsoletos do OpenClaw, imprime status a cada 30 segundos, armazena os tempos de faixas bem-sucedidas em `.artifacts/docker-tests/lane-timings.json` e usa esses tempos para iniciar faixas mais longas primeiro em execuções posteriores. Use `OPENCLAW_DOCKER_ALL_DRY_RUN=1` para imprimir o manifesto de faixas ponderado sem construir nem executar Docker, ou `node scripts/test-docker-all.mjs --plan-json` para imprimir o plano de CI para faixas selecionadas, necessidades de pacote/imagem e credenciais. +- `Package Acceptance` é o gate de pacote nativo do GitHub para "este tarball instalável funciona como produto?" Ele resolve um pacote candidato a partir de `source=npm`, `source=ref`, `source=url` ou `source=artifact`, envia-o como `package-under-test` e então executa as faixas Docker E2E reutilizáveis contra esse tarball exato em vez de reempacotar a ref selecionada. `workflow_ref` seleciona os scripts confiáveis de workflow/harness, enquanto `package_ref` seleciona o commit/branch/tag de origem a empacotar quando `source=ref`; isso permite que a lógica de aceitação atual valide commits confiáveis mais antigos. Os perfis são ordenados por abrangência: `smoke` é instalação/canal/agente rápida mais Gateway/configuração, `package` é o contrato de pacote/atualização/Plugin mais o fixture keyless upgrade-survivor, a faixa de sobrevivente de upgrade da baseline publicada e a substituição nativa padrão para a maior parte da cobertura de pacote/atualização do Parallels, `product` adiciona canais MCP, limpeza de cron/subagente, busca web OpenAI e OpenWebUI, e `full` executa os chunks Docker do caminho de release com OpenWebUI. Para `published-upgrade-survivor`, Package Acceptance sempre usa `package-under-test` como candidato e `published_upgrade_survivor_baseline` como baseline publicada, usando por padrão `openclaw@latest`; fragmente uma cobertura mais ampla disparando várias execuções com valores exatos de baseline. A faixa publicada configura sua baseline com uma receita incorporada do comando `openclaw config set` e então registra as etapas da receita no resumo da faixa. A validação de release executa um delta de pacote personalizado (`bundled-channel-deps-compat plugins-offline`) mais QA de pacote do Telegram porque os chunks Docker do caminho de release já cobrem as faixas sobrepostas de pacote/atualização/Plugin. Comandos direcionados de reexecução Docker no GitHub gerados a partir de artefatos incluem o artefato de pacote anterior, entradas de imagem preparadas e a baseline published upgrade-survivor quando disponível, para que faixas com falha possam evitar reconstruir o pacote e as imagens. +- Verificações de build e release executam `scripts/check-cli-bootstrap-imports.mjs` após tsdown. A guarda percorre o grafo compilado estático a partir de `dist/entry.js` e `dist/cli/run-main.js` e falha se a inicialização pré-despacho importar dependências de pacote como Commander, UI de prompt, undici ou logging antes do despacho de comando; ela também mantém o chunk de execução do Gateway empacotado dentro do orçamento e rejeita imports estáticos de caminhos frios conhecidos do Gateway. O smoke de CLI empacotada também cobre ajuda raiz, ajuda de onboarding, ajuda do doctor, status, esquema de configuração e um comando de lista de modelos. +- A compatibilidade legada de Package Acceptance é limitada a `2026.4.25` (`2026.4.25-beta.*` incluído). Até esse corte, o harness tolera apenas lacunas de metadados de pacotes já enviados: entradas omitidas de inventário privado de QA, `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`. Para pacotes posteriores a `2026.4.25`, esses caminhos são falhas estritas. +- Executores de smoke em container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` e `test:docker:config-reload` inicializam um ou mais containers reais e verificam caminhos de integração de nível mais alto. -Os runners Docker de modelos live também montam por bind apenas os diretórios home de autenticação de CLI necessários (ou todos os compatíveis quando a execução não está restrita) e então os copiam para o home do contêiner antes da execução, para que o OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host: +Os executores Docker de modelos live também montam por bind apenas os diretórios home de autenticação da CLI necessários (ou todos os suportados quando a execução não está restringida), então os copiam para o home do container antes da execução para que OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`; cobre Claude, Codex e Gemini por padrão, com cobertura estrita de Droid/OpenCode via `pnpm test:docker:live-acp-bind:droid` e `pnpm test:docker:live-acp-bind:opencode`) -- Smoke do backend da CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Smoke do harness do servidor de app do Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) +- Teste de fumaça de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`; cobre Claude, Codex e Gemini por padrão, com cobertura estrita de Droid/OpenCode via `pnpm test:docker:live-acp-bind:droid` e `pnpm test:docker:live-acp-bind:opencode`) +- Teste de fumaça de backend da CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) +- Teste de fumaça do harness do servidor de aplicativo Codex: `pnpm test:docker:live-codex-harness` (script: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agente de desenvolvimento: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Smoke de observabilidade: `pnpm qa:otel:smoke` é uma lane privada de checkout de código-fonte para QA. Intencionalmente, ela não faz parte das lanes de release Docker do pacote porque o tarball npm omite o QA Lab. -- Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) +- Teste de fumaça de observabilidade: `pnpm qa:otel:smoke` é uma pista privada de QA em checkout de código-fonte. Ela intencionalmente não faz parte das pistas Docker de release do pacote porque o tarball npm omite o QA Lab. +- Teste de fumaça ao vivo do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Smoke de onboarding/canal/agente do tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala o tarball empacotado do OpenClaw globalmente no Docker, configura OpenAI via onboarding com referência de env mais Telegram por padrão, verifica se o doctor reparou as dependências de runtime do plugin ativado e executa uma rodada de agente OpenAI mockada. Reutilize um tarball pré-compilado com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, pule a recompilação no host com `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` ou altere o canal com `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke de troca de canal de atualização: `pnpm test:docker:update-channel-switch` instala o tarball empacotado do OpenClaw globalmente no Docker, troca de pacote `stable` para git `dev`, verifica o canal persistido e o funcionamento pós-atualização do plugin, depois troca de volta para pacote `stable` e verifica o status de atualização. -- Smoke de sobrevivência a upgrade: `pnpm test:docker:upgrade-survivor` instala o tarball empacotado do OpenClaw sobre uma fixture suja de usuário antigo com agentes, configuração de canal, allowlists de plugins, estado obsoleto de dependências de runtime de plugins e arquivos existentes de workspace/sessão. Ele executa atualização de pacote mais doctor não interativo sem chaves live de provedor ou canal, depois inicia um Gateway de loopback e verifica preservação de configuração/estado mais orçamentos de inicialização/status. -- Smoke de contexto de runtime de sessão: `pnpm test:docker:session-runtime-context` verifica a persistência oculta de transcrição do contexto de runtime mais o reparo pelo doctor de branches duplicados afetados de reescrita de prompt. -- Smoke de instalação global com Bun: `bash scripts/e2e/bun-global-install-smoke.sh` empacota a árvore atual, instala com `bun install -g` em um home isolado e verifica se `openclaw infer image providers --json` retorna provedores de imagem incluídos em vez de travar. Reutilize um tarball pré-compilado com `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, pule a build no host com `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` ou copie `dist/` de uma imagem Docker compilada com `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke Docker do instalador: `bash scripts/test-install-sh-docker.sh` compartilha um único cache npm entre seus contêineres root, update e direct-npm. O smoke de update usa npm `latest` por padrão como baseline estável antes de atualizar para o tarball candidato. Sobrescreva com `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` localmente ou com o input `update_baseline_version` do workflow Install Smoke no GitHub. As verificações de instalador não root mantêm um cache npm isolado para que entradas de cache pertencentes ao root não mascarem o comportamento de instalação local do usuário. Defina `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` para reutilizar o cache root/update/direct-npm em reexecuções locais. -- O CI Install Smoke pula a atualização global direct-npm duplicada com `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; execute o script localmente sem essa env quando a cobertura direta de `npm install -g` for necessária. -- Smoke da CLI de exclusão de workspace compartilhado por agentes: `pnpm test:docker:agents-delete-shared-workspace` (script: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) compila a imagem do Dockerfile raiz por padrão, semeia dois agentes com um workspace em um home de contêiner isolado, executa `agents delete --json` e verifica JSON válido mais comportamento de workspace retido. Reutilize a imagem install-smoke com `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Rede do Gateway (dois contêineres, autenticação WS + saúde): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Smoke de snapshot de CDP do navegador: `pnpm test:docker:browser-cdp-snapshot` (script: `scripts/e2e/browser-cdp-snapshot-docker.sh`) compila a imagem E2E de origem mais uma camada Chromium, inicia o Chromium com CDP bruto, executa `browser doctor --deep` e verifica se os snapshots de função do CDP cobrem URLs de links, clicáveis promovidos por cursor, referências de iframe e metadados de frame. -- Regressão de raciocínio mínimo do OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI mockado pelo Gateway, verifica se `web_search` aumenta `reasoning.effort` de `minimal` para `low`, depois força a rejeição do schema do provedor e confere se o detalhe bruto aparece nos logs do Gateway. -- Ponte de canais MCP (Gateway semeado + ponte stdio + smoke de frame de notificação bruto do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Ferramentas MCP do pacote Pi (servidor MCP stdio real + smoke de allow/deny do perfil Pi embutido): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Limpeza MCP de Cron/subagente (Gateway real + encerramento de processo filho MCP stdio após execuções isoladas de cron e subagente one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke de instalação, instalação/desinstalação kitchen-sink do ClawHub, atualizações de marketplace e habilitação/inspeção do pacote Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) - Defina `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` para pular o bloco ClawHub, ou sobrescreva o par padrão pacote/runtime kitchen-sink com `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` e `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sem `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, o teste usa um servidor local hermético de fixture do ClawHub. -- Smoke de atualização de plugin sem alterações: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke de metadados de recarregamento de config: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) -- Dependências de runtime de plugins incluídos: `pnpm test:docker:bundled-channel-deps` compila uma pequena imagem runner Docker por padrão, compila e empacota o OpenClaw uma vez no host e então monta esse tarball em cada cenário de instalação Linux. Reutilize a imagem com `OPENCLAW_SKIP_DOCKER_BUILD=1`, pule a recompilação no host após uma build local recente com `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` ou aponte para um tarball existente com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. O agregado Docker completo e os chunks de bundled-channel do caminho de release pré-empacotam esse tarball uma vez, depois fragmentam as verificações de canais incluídos em lanes independentes, incluindo lanes de atualização separadas para Telegram, Discord, Slack, Feishu, memory-lancedb e ACPX. Os chunks de release separam smokes de canal, alvos de atualização e contratos de setup/runtime em `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` e `bundled-channels-contracts`; o chunk agregado `bundled-channels` permanece disponível para reexecuções manuais. O workflow de release também separa chunks de instalador de provedor e chunks de instalação/desinstalação de plugins incluídos; os chunks legados `package-update`, `plugins-runtime` e `plugins-integrations` permanecem como aliases agregados para reexecuções manuais. Use `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` para restringir a matriz de canais ao executar a lane incluída diretamente, ou `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` para restringir o cenário de atualização. Execuções Docker por cenário usam `OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT=900s` por padrão; o cenário de atualização com múltiplos alvos usa `OPENCLAW_BUNDLED_CHANNEL_UPDATE_DOCKER_RUN_TIMEOUT=2400s` por padrão. A lane também verifica se `channels..enabled=false` e `plugins.entries..enabled=false` suprimem o reparo de dependências de runtime pelo doctor. -- Restrinja as dependências de runtime de plugins incluídos durante a iteração desabilitando cenários não relacionados, por exemplo: +- Teste de fumaça de onboarding/canal/agente do tarball npm: `pnpm test:docker:npm-onboard-channel-agent` instala o tarball empacotado do OpenClaw globalmente no Docker, configura OpenAI via onboarding com referência de env mais Telegram por padrão, verifica que o doctor reparou dependências de runtime de Plugin ativadas e executa uma rodada de agente OpenAI mockada. Reutilize um tarball pré-construído com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore o rebuild no host com `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` ou troque o canal com `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Teste de fumaça de troca de canal de atualização: `pnpm test:docker:update-channel-switch` instala o tarball empacotado do OpenClaw globalmente no Docker, troca de pacote `stable` para git `dev`, verifica o canal persistido e o funcionamento do Plugin pós-atualização, depois troca de volta para o pacote `stable` e verifica o status de atualização. +- Teste de fumaça de sobrevivência a upgrade: `pnpm test:docker:upgrade-survivor` instala o tarball empacotado do OpenClaw sobre uma fixture suja de usuário antigo com agentes, configuração de canal, allowlists de Plugin, estado obsoleto de dependências de runtime de Plugin e arquivos existentes de workspace/sessão. Ele executa atualização do pacote mais doctor não interativo sem provedor ao vivo nem chaves de canal, depois inicia um Gateway de loopback e verifica preservação de configuração/estado mais orçamentos de inicialização/status. +- Teste de fumaça de sobrevivência a upgrade publicado: `pnpm test:docker:published-upgrade-survivor` instala `openclaw@latest` por padrão, semeia arquivos realistas de usuário existente, configura essa linha de base com uma receita de comando incorporada, valida a configuração resultante, atualiza essa instalação publicada para o tarball candidato, executa o doctor não interativo, grava `.artifacts/upgrade-survivor/summary.json`, depois inicia um Gateway de loopback e verifica intenções configuradas, preservação de estado, inicialização e orçamentos de status. Substitua a linha de base com `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`; Package Acceptance expõe o mesmo valor como `published_upgrade_survivor_baseline`. +- Teste de fumaça de contexto de runtime da sessão: `pnpm test:docker:session-runtime-context` verifica persistência de transcrição de contexto de runtime oculto mais reparo pelo doctor de branches duplicados afetados de reescrita de prompt. +- Teste de fumaça de instalação global com Bun: `bash scripts/e2e/bun-global-install-smoke.sh` empacota a árvore atual, instala-a com `bun install -g` em uma home isolada e verifica que `openclaw infer image providers --json` retorna provedores de imagem incluídos em vez de travar. Reutilize um tarball pré-construído com `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, ignore o build no host com `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` ou copie `dist/` de uma imagem Docker construída com `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Teste de fumaça Docker do instalador: `bash scripts/test-install-sh-docker.sh` compartilha um cache npm entre seus contêineres root, update e direct-npm. O teste de fumaça de atualização usa por padrão o npm `latest` como linha de base estável antes de fazer upgrade para o tarball candidato. Substitua com `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` localmente, ou com a entrada `update_baseline_version` do workflow Install Smoke no GitHub. As verificações do instalador sem root mantêm um cache npm isolado para que entradas de cache pertencentes ao root não mascarem o comportamento de instalação local do usuário. Defina `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` para reutilizar o cache root/update/direct-npm em novas execuções locais. +- O CI Install Smoke ignora a atualização global direct-npm duplicada com `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; execute o script localmente sem esse env quando for necessária cobertura direta de `npm install -g`. +- Teste de fumaça da CLI para exclusão de workspace compartilhado de agentes: `pnpm test:docker:agents-delete-shared-workspace` (script: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) constrói a imagem do Dockerfile raiz por padrão, semeia dois agentes com um workspace em uma home isolada de contêiner, executa `agents delete --json` e verifica JSON válido mais comportamento de workspace retido. Reutilize a imagem install-smoke com `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Rede do Gateway (dois contêineres, autenticação WS + integridade): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Teste de fumaça de snapshot CDP do navegador: `pnpm test:docker:browser-cdp-snapshot` (script: `scripts/e2e/browser-cdp-snapshot-docker.sh`) constrói a imagem E2E de código-fonte mais uma camada do Chromium, inicia o Chromium com CDP bruto, executa `browser doctor --deep` e verifica que snapshots de função CDP cobrem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame. +- Regressão de raciocínio mínimo em OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (script: `scripts/e2e/openai-web-search-minimal-docker.sh`) executa um servidor OpenAI mockado por meio do Gateway, verifica que `web_search` eleva `reasoning.effort` de `minimal` para `low`, então força a rejeição do schema do provedor e verifica que o detalhe bruto aparece nos logs do Gateway. +- Ponte de canais MCP (Gateway semeado + ponte stdio + teste de fumaça de frame de notificação bruto do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Ferramentas MCP do pacote Pi (servidor MCP stdio real + teste de fumaça de allow/deny do perfil Pi embutido): `pnpm test:docker:pi-bundle-mcp-tools` (script: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Limpeza MCP de Cron/subagente (Gateway real + encerramento de filho MCP stdio após execuções isoladas de cron e subagente one-shot): `pnpm test:docker:cron-mcp-cleanup` (script: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (teste de fumaça de instalação, instalação/desinstalação kitchen-sink do ClawHub, atualizações do marketplace e habilitação/inspeção do pacote Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) + Defina `OPENCLAW_PLUGINS_E2E_CLAWHUB=0` para ignorar o bloco ClawHub, ou substitua o par padrão de pacote/runtime kitchen-sink com `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` e `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Sem `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL`, o teste usa um servidor local hermético de fixture do ClawHub. +- Teste de fumaça de Plugin inalterado após atualização: `pnpm test:docker:plugin-update` (script: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Teste de fumaça de metadados de recarregamento de configuração: `pnpm test:docker:config-reload` (script: `scripts/e2e/config-reload-source-docker.sh`) +- Dependências de runtime de Plugin incluído: `pnpm test:docker:bundled-channel-deps` constrói uma pequena imagem runner Docker por padrão, constrói e empacota o OpenClaw uma vez no host, então monta esse tarball em cada cenário de instalação Linux. Reutilize a imagem com `OPENCLAW_SKIP_DOCKER_BUILD=1`, ignore o rebuild no host após um build local recente com `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, ou aponte para um tarball existente com `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. O agregado Docker completo e os chunks bundled-channel do caminho de release pré-empacotam esse tarball uma vez, depois fragmentam as verificações de canais incluídos em pistas independentes, incluindo pistas de atualização separadas para Telegram, Discord, Slack, Feishu, memory-lancedb e ACPX. Os chunks de release separam testes de fumaça de canal, alvos de atualização e contratos de configuração/runtime em `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` e `bundled-channels-contracts`; o chunk agregado `bundled-channels` permanece disponível para novas execuções manuais. O workflow de release também separa chunks do instalador de provedores e chunks de instalação/desinstalação de Plugin incluído; os chunks legados `package-update`, `plugins-runtime` e `plugins-integrations` permanecem como aliases agregados para novas execuções manuais. Use `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` para restringir a matriz de canais ao executar a pista incluída diretamente, ou `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx` para restringir o cenário de atualização. Execuções Docker por cenário usam por padrão `OPENCLAW_BUNDLED_CHANNEL_DOCKER_RUN_TIMEOUT=900s`; o cenário de atualização com múltiplos alvos usa por padrão `OPENCLAW_BUNDLED_CHANNEL_UPDATE_DOCKER_RUN_TIMEOUT=2400s`. A pista também verifica que `channels..enabled=false` e `plugins.entries..enabled=false` suprimem o reparo de dependência de runtime pelo doctor. +- Restrinja dependências de runtime de Plugin incluído durante a iteração desabilitando cenários não relacionados, por exemplo: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Para pré-compilar e reutilizar manualmente a imagem funcional compartilhada: +Para pré-construir e reutilizar manualmente a imagem funcional compartilhada: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Sobrescritas de imagem específicas de suíte, como `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, ainda prevalecem quando definidas. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` aponta para uma imagem remota compartilhada, os scripts fazem pull dela se ela ainda não estiver local. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação em vez do runtime compartilhado do app compilado. +Substituições de imagem específicas da suíte, como `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, ainda têm precedência quando definidas. Quando `OPENCLAW_SKIP_DOCKER_BUILD=1` aponta para uma imagem compartilhada remota, os scripts a baixam se ela ainda não estiver local. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação em vez do runtime de aplicativo construído compartilhado. -Os executores Docker de modelos live também montam o checkout atual como somente leitura e +Os executores Docker de modelo em tempo real também montam o checkout atual como somente leitura e o preparam em um diretório de trabalho temporário dentro do contêiner. Isso mantém a imagem de runtime -enxuta, ainda executando o Vitest contra exatamente o seu código-fonte/configuração local. -A etapa de preparação ignora caches grandes apenas locais e saídas de build de apps, como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, e diretórios de saída `.build` locais de apps ou -do Gradle, para que execuções live no Docker não passem minutos copiando +enxuta enquanto ainda executa o Vitest contra sua configuração/código-fonte local exato. +A etapa de preparação ignora caches grandes somente locais e saídas de build de apps, como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios de saída `.build` locais de app ou +do Gradle, para que execuções live no Docker não gastem minutos copiando artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondagens live do gateway não iniciem -trabalhadores de canal reais do Telegram/Discord/etc. dentro do contêiner. -`test:docker:live-models` ainda executa `pnpm test:live`, então repasse -`OPENCLAW_LIVE_GATEWAY_*` também quando precisar restringir ou excluir a cobertura live -do gateway dessa lane Docker. +Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que probes live do Gateway não iniciem +workers de canal reais do Telegram/Discord/etc. dentro do contêiner. +`test:docker:live-models` ainda executa `pnpm test:live`, então repasse também +`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura live do Gateway +dessa lane do Docker. `test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um -contêiner do gateway OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, -inicia um contêiner fixado do Open WebUI contra esse gateway, faz login pelo +contêiner do Gateway do OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, +inicia um contêiner fixado do Open WebUI contra esse Gateway, faz login pelo Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma -solicitação real de chat pelo proxy `/api/chat/completions` do Open WebUI. -A primeira execução pode ser perceptivelmente mais lenta porque o Docker pode precisar baixar a -imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de inicialização fria. -Essa lane espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a principal forma de fornecê-la em execuções Dockerizadas. -Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model": +requisição de chat real pelo proxy `/api/chat/completions` do Open WebUI. +A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar baixar a +imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de inicialização a frio. +Essa lane espera uma chave de modelo em tempo real utilizável, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. +Execuções bem-sucedidas imprimem uma pequena carga JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma conta real do Telegram, Discord ou iMessage. Ele inicializa um contêiner Gateway -com dados semeados, inicia um segundo contêiner que dispara `openclaw mcp serve`, e então +semeado, inicia um segundo contêiner que gera `openclaw mcp serve` e então verifica descoberta de conversas roteadas, leituras de transcrições, metadados de anexos, -comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + -permissão no estilo Claude pela ponte MCP stdio real. A verificação de notificação +comportamento da fila de eventos live, roteamento de envio outbound e notificações de canal + +permissão no estilo Claude pela ponte MCP stdio real. A verificação de notificações inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a -ponte realmente emite, não apenas o que um SDK de cliente específico acaba expondo. -`test:docker:pi-bundle-mcp-tools` é determinístico e não precisa de uma chave de modelo live. -Ele compila a imagem Docker do repositório, inicia um servidor de sondagem MCP stdio real +ponte realmente emite, não apenas o que um SDK de cliente específico por acaso expõe. +`test:docker:pi-bundle-mcp-tools` é determinístico e não precisa de uma chave de +modelo live. Ele compila a imagem Docker do repositório, inicia um servidor probe MCP stdio real dentro do contêiner, materializa esse servidor pelo runtime MCP do bundle Pi embutido, -executa a ferramenta e então verifica se `coding` e `messaging` mantêm +executa a ferramenta e então verifica que `coding` e `messaging` mantêm ferramentas `bundle-mcp`, enquanto `minimal` e `tools.deny: ["bundle-mcp"]` as filtram. -`test:docker:cron-mcp-cleanup` é determinístico e não precisa de uma chave de modelo live. -Ele inicia um Gateway semeado com um servidor de sondagem MCP stdio real, executa um -turno cron isolado e um turno filho one-shot de `/subagents spawn`, e então verifica -se o processo filho MCP encerra após cada execução. +`test:docker:cron-mcp-cleanup` é determinístico e não precisa de uma chave de modelo +live. Ele inicia um Gateway semeado com um servidor probe MCP stdio real, executa um +turno Cron isolado e um turno filho único de `/subagents spawn`, e então verifica +se o processo filho MCP é encerrado após cada execução. -Smoke manual de thread ACP em linguagem simples (não CI): +Smoke manual de thread ACP em linguagem natural (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de threads ACP, então não o exclua. +- Mantenha este script para fluxos de trabalho de regressão/debug. Ele pode ser necessário novamente para validação de roteamento de threads ACP, então não o exclua. Variáveis de ambiente úteis: - `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de configuração/workspace e sem montagens externas de autenticação de CLI +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de configuração/workspace e sem montagens externas de autenticação da CLI - `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações de CLI em cache dentro do Docker -- Diretórios/arquivos externos de autenticação de CLI sob `$HOME` são montados como somente leitura em `/host-auth...` e depois copiados para `/home/node/...` antes do início dos testes +- Diretórios/arquivos externos de autenticação de CLI em `$HOME` são montados como somente leitura em `/host-auth...` e então copiados para `/home/node/...` antes do início dos testes - Diretórios padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Execuções restringidas por provedor montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` @@ -707,78 +709,78 @@ Variáveis de ambiente úteis: - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner - `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reexecuções que não precisam de rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não do ambiente) -- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo gateway para o smoke do Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` para sobrescrever o prompt de verificação de nonce usado pelo smoke do Open WebUI +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que credenciais venham do armazenamento de perfil (não do ambiente) +- `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo Gateway para o smoke do Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` para sobrescrever o prompt de verificação por nonce usado pelo smoke do Open WebUI - `OPENWEBUI_IMAGE=...` para sobrescrever a tag fixada da imagem do Open WebUI ## Sanidade da documentação -Execute verificações de documentação após edições em docs: `pnpm check:docs`. -Execute a validação completa de âncoras Mintlify quando também precisar de verificações de cabeçalhos na página: `pnpm docs:check-links:anchors`. +Execute verificações da documentação após edições em docs: `pnpm check:docs`. +Execute a validação completa de âncoras do Mintlify quando também precisar de verificações de títulos dentro da página: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramentas do Gateway (OpenAI simulado, gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava configuração + autenticação aplicada): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Chamada de ferramentas do Gateway (mock do OpenAI, Gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava configuração + autenticação imposta): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evals de confiabilidade de agente (skills) +## Evals de confiabilidade de agentes (skills) -Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade de agente”: +Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade de agentes”: -- Chamada de ferramentas simulada pelo gateway real + loop de agente (`src/gateway/gateway.test.ts`). +- Chamada de ferramentas simulada pelo Gateway real + loop de agente (`src/gateway/gateway.test.ts`). - Fluxos de assistente de ponta a ponta que validam a ligação de sessão e os efeitos de configuração (`src/gateway/gateway.test.ts`). O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)): -- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill certa (ou evita as irrelevantes)? -- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue etapas/argumentos obrigatórios? -- **Contratos de fluxo de trabalho:** cenários multi-turno que validam ordem de ferramentas, continuidade do histórico da sessão e limites do sandbox. +- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a skill correta (ou evita as irrelevantes)? +- **Conformidade:** o agente lê `SKILL.md` antes de usar e segue as etapas/args exigidos? +- **Contratos de fluxo de trabalho:** cenários multi-turno que afirmam ordem de ferramentas, transporte do histórico de sessão e limites do sandbox. -Evals futuros devem permanecer primeiro determinísticos: +Evals futuros devem permanecer determinísticos primeiro: -- Um executor de cenários usando provedores simulados para validar chamadas de ferramentas + ordem, leituras de arquivos de Skill e ligação de sessão. -- Uma pequena suíte de cenários focados em Skills (usar vs evitar, controles, injeção de prompt). -- Evals live opcionais (opt-in, controlados por env) somente depois que a suíte segura para CI estiver pronta. +- Um executor de cenários usando provedores simulados para afirmar chamadas de ferramenta + ordem, leituras de arquivos de skill e ligação de sessão. +- Uma pequena suíte de cenários focados em skills (usar vs. evitar, gating, injeção de prompt). +- Evals live opcionais (opt-in, protegidos por env) somente depois que a suíte segura para CI estiver pronta. ## Testes de contrato (formato de plugin e canal) -Testes de contrato verificam que cada plugin e canal registrado está em conformidade com seu +Testes de contrato verificam se todo plugin e canal registrado está em conformidade com seu contrato de interface. Eles iteram por todos os plugins descobertos e executam uma suíte de asserções de formato e comportamento. A lane unitária padrão de `pnpm test` intencionalmente -ignora esses arquivos compartilhados de ponto de integração e smoke; execute os comandos de contrato explicitamente -quando tocar superfícies compartilhadas de canal ou provedor. +ignora esses arquivos compartilhados de seam e smoke; execute explicitamente os comandos de contrato +quando tocar em superfícies compartilhadas de canal ou provedor. ### Comandos - Todos os contratos: `pnpm test:contracts` -- Apenas contratos de canal: `pnpm test:contracts:channels` -- Apenas contratos de provedor: `pnpm test:contracts:plugins` +- Apenas contratos de canais: `pnpm test:contracts:channels` +- Apenas contratos de provedores: `pnpm test:contracts:plugins` -### Contratos de canal +### Contratos de canais Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Formato básico do plugin (id, nome, capacidades) - **setup** - Contrato do assistente de configuração - **session-binding** - Comportamento de ligação de sessão -- **outbound-payload** - Estrutura de payload de mensagem -- **inbound** - Tratamento de mensagem de entrada -- **actions** - Manipuladores de ação de canal +- **outbound-payload** - Estrutura da carga da mensagem +- **inbound** - Tratamento de mensagens inbound +- **actions** - Handlers de ação de canal - **threading** - Tratamento de ID de thread -- **directory** - API de diretório/lista +- **directory** - API de diretório/roster - **group-policy** - Aplicação de política de grupo -### Contratos de status de provedor +### Contratos de status de provedores Localizados em `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondagens de status de canal +- **status** - Probes de status de canal - **registry** - Formato do registro de plugins -### Contratos de provedor +### Contratos de provedores Localizados em `src/plugins/contracts/*.contract.test.ts`: @@ -793,26 +795,26 @@ Localizados em `src/plugins/contracts/*.contract.test.ts`: ### Quando executar -- Depois de alterar exports ou subpaths de plugin-sdk +- Depois de alterar exports ou subpaths do plugin-sdk - Depois de adicionar ou modificar um plugin de canal ou provedor - Depois de refatorar registro ou descoberta de plugins -Testes de contrato executam no CI e não exigem chaves de API reais. +Testes de contrato executam em CI e não exigem chaves de API reais. ## Adicionando regressões (orientação) -Quando você corrigir um problema de provedor/modelo descoberto live: +Quando você corrigir um problema de provedor/modelo descoberto em live: -- Adicione uma regressão segura para CI, se possível (provedor simulado/stub ou captura da transformação exata do formato da solicitação) +- Adicione uma regressão segura para CI, se possível (provedor mock/stub, ou capture a transformação exata do formato da requisição) - Se for inerentemente apenas live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in via variáveis de ambiente - Prefira mirar na menor camada que captura o bug: - - bug de conversão/replay de solicitação do provedor → teste direto de modelos - - bug de sessão/histórico/pipeline de ferramentas do gateway → smoke live do gateway ou teste mock do gateway seguro para CI -- Proteção de travessia de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`) e então afirma que ids de exec com segmentos de travessia são rejeitados. + - bug de conversão/replay de requisição do provedor → teste direto de modelos + - bug de pipeline de sessão/histórico/ferramenta do Gateway → smoke live do Gateway ou teste mock seguro para CI do Gateway +- Guardrail de travessia SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe SecretRef dos metadados do registro (`listSecretTargetRegistryEntries()`) e então afirma que ids de exec com segmentos de travessia são rejeitados. - Se você adicionar uma nova família de alvos SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. -## Relacionado +## Relacionados - [Testes live](/pt-BR/help/testing-live) - [CI](/pt-BR/ci) diff --git a/docs/pt-BR/logging.md b/docs/pt-BR/logging.md index 424f7b277..0ef805395 100644 --- a/docs/pt-BR/logging.md +++ b/docs/pt-BR/logging.md @@ -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 ` / `--token ` / `--timeout `: 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 ` / `--token ` / `--timeout `: 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 `** (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 `** (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.*` diff --git a/docs/pt-BR/plugins/codex-harness.md b/docs/pt-BR/plugins/codex-harness.md index 6faafe358..6f7624db4 100644 --- a/docs/pt-BR/plugins/codex-harness.md +++ b/docs/pt-BR/plugins/codex-harness.md @@ -1,204 +1,37 @@ --- read_when: - - Você quer usar o arcabouço de app-server incluído no Codex - - Você precisa de exemplos de configuração do harness do Codex - - Você quer que implantações somente com Codex falhem em vez de recorrer ao PI -summary: Execute turnos do agente incorporado do OpenClaw por meio do mecanismo app-server do Codex incluído + - Você quer usar o arcabouço de app-server do Codex incluído + - Você precisa de exemplos de configuração do ambiente de execução do Codex + - Você quer que implantações somente Codex falhem em vez de recorrer ao PI +summary: Execute interações de agente embutido do OpenClaw pela estrutura de teste de servidor de aplicativo do Codex incluída title: Ambiente de execução do Codex x-i18n: - generated_at: "2026-04-30T20:05:53Z" + generated_at: "2026-05-01T05:58:19Z" model: gpt-5.5 provider: openai - source_hash: 335ec60cbdb76579db833eccb5151ffc5bcd28b370ca2e99587abdb578eeee4f + source_hash: 740e8fa9e6f4a737dfd250fe26b85865a7f7e40839b41e879e9224a45cbe8d72 source_path: plugins/codex-harness.md workflow: 16 --- O Plugin `codex` incluído permite que o OpenClaw execute turnos de agente incorporados por meio do -app-server do Codex em vez do harness Pi integrado. +app-server do Codex em vez do harness PI integrado. -Use isto quando você quiser que o Codex seja responsável pela sessão de agente de baixo nível: descoberta de modelos, retomada nativa de thread, Compaction nativa e execução no app-server. +Use isto quando você quiser que o Codex seja responsável pela sessão de agente de baixo nível: descoberta de +modelos, retomada nativa de threads, Compaction nativa e execução no app-server. O OpenClaw ainda é responsável por canais de chat, arquivos de sessão, seleção de modelo, ferramentas, aprovações, entrega de mídia e o espelho visível da transcrição. -Se você está tentando se orientar, comece por +Se você estiver tentando se orientar, comece por [Runtimes de agente](/pt-BR/concepts/agent-runtimes). A versão curta é: -`openai/gpt-5.5` é a referência de modelo, `codex` é o runtime, e Telegram, -Discord, Slack ou outro canal permanece como a superfície de comunicação. +`openai/gpt-5.5` é a referência do modelo, `codex` é o runtime, e Telegram, +Discord, Slack ou outro canal permanece a superfície de comunicação. -## O que este Plugin muda +## Configuração rápida -O Plugin `codex` incluído contribui com várias capacidades separadas: - -| Capacidade | Como você a usa | O que ela faz | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| Runtime incorporado nativo | `agentRuntime.id: "codex"` | Executa turnos de agente incorporado do OpenClaw por meio do app-server do Codex. | -| Comandos nativos de controle de chat | `/codex bind`, `/codex resume`, `/codex steer`, ... | Vincula e controla threads do app-server do Codex a partir de uma conversa de mensagens. | -| Provedor/catálogo do app-server do Codex | internos de `codex`, expostos por meio do harness | Permite que o runtime descubra e valide modelos do app-server. | -| Caminho de compreensão de mídia do Codex | caminhos de compatibilidade de modelos de imagem `codex/*` | Executa turnos delimitados do app-server do Codex para modelos compatíveis de compreensão de imagem. | -| Relay de hooks nativos | Hooks de Plugin em torno de eventos nativos do Codex | Permite que o OpenClaw observe/bloqueie eventos compatíveis de ferramenta/finalização nativos do Codex. | - -Habilitar o Plugin disponibiliza essas capacidades. Ele **não**: - -- começa a usar Codex para todos os modelos OpenAI -- converte referências de modelo `openai-codex/*` no runtime nativo -- torna ACP/acpx o caminho padrão do Codex -- alterna a quente sessões existentes que já registraram um runtime Pi -- substitui a entrega de canais do OpenClaw, arquivos de sessão, armazenamento de perfil de autenticação ou - roteamento de mensagens - -O mesmo Plugin também é responsável pela superfície nativa de comandos de controle de chat `/codex`. Se -o Plugin estiver habilitado e o usuário pedir para vincular, retomar, orientar, parar ou inspecionar -threads do Codex pelo chat, os agentes devem preferir `/codex ...` em vez de ACP. ACP continua sendo -o fallback explícito quando o usuário pede ACP/acpx ou está testando o adaptador ACP -do Codex. - -Turnos nativos do Codex mantêm hooks de Plugin do OpenClaw como a camada pública de compatibilidade. -Estes são hooks em processo do OpenClaw, não hooks de comando `hooks.json` do Codex: - -- `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` -- `before_tool_call`, `after_tool_call` -- `before_message_write` para registros espelhados de transcrição -- `before_agent_finalize` por meio do relay `Stop` do Codex -- `agent_end` - -Plugins também podem registrar middleware de resultados de ferramenta neutro em relação a runtime para reescrever -resultados dinâmicos de ferramentas do OpenClaw depois que o OpenClaw executa a ferramenta e antes que o -resultado seja retornado ao Codex. Isso é separado do hook público de Plugin -`tool_result_persist`, que transforma gravações de resultados de ferramenta em transcrição pertencentes ao OpenClaw. - -Para a semântica dos hooks de Plugin em si, consulte [Hooks de Plugin](/pt-BR/plugins/hooks) -e [Comportamento de guarda de Plugin](/pt-BR/tools/plugin). - -O harness fica desativado por padrão. Novas configurações devem manter as referências de modelo OpenAI -canônicas como `openai/gpt-*` e forçar explicitamente -`agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex` quando quiserem -execução nativa no app-server. Referências de modelo legadas `codex/*` ainda selecionam automaticamente -o harness por compatibilidade, mas prefixos de provedores legados com suporte de runtime -não são mostrados como escolhas normais de modelo/provedor. - -Se o Plugin `codex` estiver habilitado, mas o modelo primário ainda for -`openai-codex/*`, `openclaw doctor` avisa em vez de alterar a rota. Isso é -intencional: `openai-codex/*` continua sendo o caminho de OAuth/assinatura Pi do Codex, e -a execução nativa no app-server permanece uma escolha explícita de runtime. - -## Mapa de rotas - -Use esta tabela antes de alterar a configuração: - -| Comportamento desejado | Referência de modelo | Configuração de runtime | Requisito de Plugin | Rótulo de status esperado | -| ---------------------------------------- | ------------------------- | -------------------------------------- | --------------------------- | ------------------------------- | -| API da OpenAI pelo runner normal do OpenClaw | `openai/gpt-*` | omitido ou `runtime: "pi"` | Provedor OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/assinatura do Codex por meio do Pi | `openai-codex/gpt-*` | omitido ou `runtime: "pi"` | Provedor OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Turnos incorporados nativos do app-server do Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Provedores mistos com modo automático conservador | referências específicas do provedor | `agentRuntime.id: "auto"` | Runtimes de Plugin opcionais | Depende do runtime selecionado | -| Sessão explícita do adaptador ACP do Codex | dependente de prompt/modelo ACP | `sessions_spawn` com `runtime: "acp"` | backend `acpx` saudável | Status de tarefa/sessão ACP | - -A divisão importante é provedor versus runtime: - -- `openai-codex/*` responde "qual rota de provedor/autenticação o Pi deve usar?" -- `agentRuntime.id: "codex"` responde "qual loop deve executar este - turno incorporado?" -- `/codex ...` responde "qual conversa nativa do Codex este chat deve vincular - ou controlar?" -- ACP responde "qual processo de harness externo o acpx deve iniciar?" - -## Escolha o prefixo de modelo correto - -Rotas da família OpenAI são específicas por prefixo. Use `openai-codex/*` quando quiser -OAuth do Codex por meio do Pi; use `openai/*` quando quiser acesso direto à API da OpenAI ou -quando estiver forçando o harness nativo do app-server do Codex: - -| Referência de modelo | Caminho de runtime | Use quando | -| ------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Provedor OpenAI pelo encanamento OpenClaw/Pi | Você quer acesso direto atual à API da OpenAI Platform com `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex por meio do OpenClaw/Pi | Você quer autenticação de assinatura ChatGPT/Codex com o runner Pi padrão. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness do app-server do Codex | Você quer execução nativa do app-server do Codex para o turno de agente incorporado. | - -GPT-5.5 atualmente só está disponível por assinatura/OAuth no OpenClaw. Use -`openai-codex/gpt-5.5` para OAuth Pi, ou `openai/gpt-5.5` com o harness -do app-server do Codex. O acesso direto por chave de API para `openai/gpt-5.5` é compatível -quando a OpenAI habilitar o GPT-5.5 na API pública. - -Referências legadas `codex/gpt-*` continuam aceitas como aliases de compatibilidade. A migração de compatibilidade -do Doctor reescreve referências legadas de runtime primário para referências de modelo canônicas -e registra a política de runtime separadamente, enquanto referências legadas apenas de fallback -são deixadas inalteradas porque o runtime é configurado para todo o contêiner do agente. -Novas configurações OAuth Pi do Codex devem usar `openai-codex/gpt-*`; novas configurações nativas -de harness do app-server devem usar `openai/gpt-*` mais -`agentRuntime.id: "codex"`. - -`agents.defaults.imageModel` segue a mesma divisão de prefixos. Use -`openai-codex/gpt-*` quando a compreensão de imagem deve rodar pelo caminho do provedor OAuth OpenAI -Codex. Use `codex/gpt-*` quando a compreensão de imagem deve rodar -por meio de um turno delimitado do app-server do Codex. O modelo do app-server do Codex deve -anunciar suporte a entrada de imagem; modelos Codex somente de texto falham antes que o turno de mídia -comece. - -Use `/status` para confirmar o harness efetivo da sessão atual. Se a -seleção for surpreendente, habilite logs de depuração para o subsistema `agents/harness` -e inspecione o registro estruturado `agent harness selected` do gateway. Ele -inclui o id do harness selecionado, o motivo da seleção, a política de runtime/fallback e, -no modo `auto`, o resultado de suporte de cada candidato de Plugin. - -### O que os avisos do doctor significam - -`openclaw doctor` avisa quando tudo isto é verdadeiro: - -- o Plugin `codex` incluído está habilitado ou permitido -- o modelo primário de um agente é `openai-codex/*` -- o runtime efetivo desse agente não é `codex` - -Esse aviso existe porque usuários frequentemente esperam que "Plugin Codex habilitado" implique -"runtime nativo do app-server do Codex." O OpenClaw não faz esse salto. O aviso -significa: - -- **Nenhuma alteração é necessária** se você pretendia usar OAuth ChatGPT/Codex por meio do Pi. -- Altere o modelo para `openai/` e defina - `agentRuntime.id: "codex"` se você pretendia execução nativa no app-server. -- Sessões existentes ainda precisam de `/new` ou `/reset` após uma alteração de runtime, - porque pins de runtime de sessão são persistentes. - -A seleção de harness não é um controle de sessão ao vivo. Quando um turno incorporado roda, -o OpenClaw registra o id do harness selecionado nessa sessão e continua usando-o para -turnos posteriores no mesmo id de sessão. Altere a configuração `agentRuntime` ou -`OPENCLAW_AGENT_RUNTIME` quando quiser que sessões futuras usem outro harness; -use `/new` ou `/reset` para iniciar uma nova sessão antes de alternar uma conversa existente -entre Pi e Codex. Isso evita reproduzir uma transcrição por meio de -dois sistemas de sessão nativa incompatíveis. - -Sessões legadas criadas antes dos pins de harness são tratadas como fixadas em Pi quando -têm histórico de transcrição. Use `/new` ou `/reset` para optar essa conversa pelo -Codex após alterar a configuração. - -`/status` mostra o runtime de modelo efetivo. O harness Pi padrão aparece como -`Runtime: OpenClaw Pi Default`, e o harness do app-server do Codex aparece como -`Runtime: OpenAI Codex`. - -## Requisitos - -- OpenClaw com o Plugin `codex` incluído disponível. -- App-server do Codex `0.125.0` ou mais recente. O Plugin incluído gerencia um binário compatível - do app-server do Codex por padrão, portanto comandos locais `codex` em `PATH` não - afetam a inicialização normal do harness. -- Autenticação do Codex disponível para o processo do app-server ou para a ponte de autenticação Codex - do OpenClaw. Inicializações locais do app-server stdio usam uma home do Codex gerenciada pelo OpenClaw para cada - agente e um `HOME` filho isolado, portanto não leem sua conta pessoal - `~/.codex`, Skills, Plugins, configuração, estado de thread ou - `$HOME/.agents/skills` nativo por padrão. - -O Plugin bloqueia handshakes de app-server mais antigos ou sem versão. Isso mantém -o OpenClaw na superfície de protocolo contra a qual ele foi testado. - -Para testes de fumaça ao vivo e Docker, a autenticação geralmente vem da conta da CLI do Codex -ou de um perfil de autenticação `openai-codex` do OpenClaw. Inicializações locais do app-server stdio também podem -recorrer a `CODEX_API_KEY` / `OPENAI_API_KEY` quando nenhuma conta está presente. - -## Configuração mínima - -Use `openai/gpt-5.5`, habilite o Plugin incluído e force o harness `codex`: +Para usar o harness Codex para turnos de agente GPT, mantenha a referência do modelo canônica como +`openai/gpt-*`, habilite o Plugin `codex` incluído e defina +`agentRuntime.id: "codex"`: ```json5 { @@ -214,13 +47,14 @@ Use `openai/gpt-5.5`, habilite o Plugin incluído e force o harness `codex`: model: "openai/gpt-5.5", agentRuntime: { id: "codex", + fallback: "none", }, }, }, } ``` -Se sua configuração usa `plugins.allow`, inclua `codex` ali também: +Se sua configuração usar `plugins.allow`, inclua `codex` lá também: ```json5 { @@ -235,24 +69,193 @@ Se sua configuração usa `plugins.allow`, inclua `codex` ali também: } ``` -Configurações legadas que definem `agents.defaults.model` ou um modelo de agente como -`codex/` ainda habilitam automaticamente o Plugin `codex` incluído. Novas configurações devem -preferir `openai/` mais a entrada explícita `agentRuntime` acima. +Não use `openai-codex/gpt-*` para este caminho. Isso seleciona OAuth do Codex por meio +do executor PI normal, a menos que você force um runtime separadamente. Alterações de configuração se aplicam +a sessões novas ou redefinidas; sessões existentes mantêm o runtime registrado. -## Adicionar Codex junto de outros modelos +## O que este Plugin muda + +O Plugin `codex` incluído contribui várias capacidades separadas: + +| Capacidade | Como você a usa | O que ela faz | +| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | +| Runtime incorporado nativo | `agentRuntime.id: "codex"` | Executa turnos de agente incorporados do OpenClaw por meio do app-server do Codex. | +| Comandos nativos de controle de chat | `/codex bind`, `/codex resume`, `/codex steer`, ... | Vincula e controla threads do app-server do Codex a partir de uma conversa de mensagens. | +| Provedor/catálogo do app-server do Codex | internos de `codex`, expostos por meio do harness | Permite que o runtime descubra e valide modelos do app-server. | +| Caminho de compreensão de mídia do Codex | caminhos de compatibilidade de modelo de imagem `codex/*` | Executa turnos delimitados do app-server do Codex para modelos compatíveis de compreensão de imagens. | +| Relay de hooks nativos | Hooks de Plugin em torno de eventos nativos do Codex | Permite que o OpenClaw observe/bloqueie eventos compatíveis de ferramenta/finalização nativos do Codex. | + +Habilitar o Plugin disponibiliza essas capacidades. Ele **não**: + +- começa a usar o Codex para todos os modelos OpenAI +- converte referências de modelo `openai-codex/*` para o runtime nativo +- torna ACP/acpx o caminho Codex padrão +- troca a quente sessões existentes que já registraram um runtime PI +- substitui a entrega de canais, arquivos de sessão, armazenamento de perfis de autenticação ou + roteamento de mensagens do OpenClaw + +O mesmo Plugin também é responsável pela superfície nativa de comando de controle de chat `/codex`. Se +o Plugin estiver habilitado e o usuário pedir para vincular, retomar, direcionar, parar ou inspecionar +threads do Codex a partir do chat, os agentes devem preferir `/codex ...` em vez de ACP. ACP permanece +o fallback explícito quando o usuário pede ACP/acpx ou está testando o adaptador ACP +do Codex. + +Turnos nativos do Codex mantêm hooks de Plugin do OpenClaw como a camada pública de compatibilidade. +Estes são hooks em processo do OpenClaw, não hooks de comando `hooks.json` do Codex: + +- `before_prompt_build` +- `before_compaction`, `after_compaction` +- `llm_input`, `llm_output` +- `before_tool_call`, `after_tool_call` +- `before_message_write` para registros de transcrição espelhados +- `before_agent_finalize` por meio do relay `Stop` do Codex +- `agent_end` + +Plugins também podem registrar middleware de resultado de ferramenta neutro em relação ao runtime para reescrever +resultados de ferramentas dinâmicas do OpenClaw depois que o OpenClaw executa a ferramenta e antes que o +resultado seja retornado ao Codex. Isso é separado do hook público de Plugin +`tool_result_persist`, que transforma gravações de resultado de ferramenta de transcrição pertencentes ao OpenClaw. + +Para a semântica dos hooks de Plugin em si, consulte [Hooks de Plugin](/pt-BR/plugins/hooks) +e [Comportamento de guarda de Plugin](/pt-BR/tools/plugin). + +O harness fica desativado por padrão. Novas configurações devem manter referências de modelo OpenAI +canônicas como `openai/gpt-*` e forçar explicitamente +`agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex` quando +quiserem execução nativa no app-server. Referências de modelo legadas `codex/*` ainda selecionam automaticamente +o harness para compatibilidade, mas prefixos legados de provedor com runtime não são +mostrados como escolhas normais de modelo/provedor. + +Se o Plugin `codex` estiver habilitado, mas o modelo primário ainda for +`openai-codex/*`, `openclaw doctor` avisa em vez de alterar a rota. Isso é +intencional: `openai-codex/*` permanece o caminho PI de OAuth/assinatura do Codex, e +a execução nativa no app-server continua sendo uma escolha explícita de runtime. + +## Mapa de rotas + +Use esta tabela antes de alterar a configuração: + +| Comportamento desejado | Referência do modelo | Configuração de runtime | Requisito de Plugin | Rótulo de status esperado | +| ------------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | +| API OpenAI por meio do executor normal do OpenClaw | `openai/gpt-*` | omitido ou `runtime: "pi"` | Provedor OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/assinatura do Codex por meio de PI | `openai-codex/gpt-*` | omitido ou `runtime: "pi"` | Provedor OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | +| Turnos incorporados nativos do app-server do Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Provedores mistos com modo automático conservador | referências específicas do provedor | `agentRuntime.id: "auto"` | Runtimes de Plugin opcionais | Depende do runtime selecionado | +| Sessão explícita do adaptador Codex ACP | dependente de prompt/modelo ACP | `sessions_spawn` com `runtime: "acp"` | backend `acpx` saudável | Status de tarefa/sessão ACP | + +A divisão importante é provedor versus runtime: + +- `openai-codex/*` responde "qual rota de provedor/autenticação o PI deve usar?" +- `agentRuntime.id: "codex"` responde "qual loop deve executar este + turno incorporado?" +- `/codex ...` responde "a qual conversa nativa do Codex este chat deve se vincular + ou controlar?" +- ACP responde "qual processo de harness externo o acpx deve iniciar?" + +## Escolha o prefixo de modelo correto + +Rotas da família OpenAI são específicas por prefixo. Use `openai-codex/*` quando quiser +OAuth do Codex por meio de PI; use `openai/*` quando quiser acesso direto à API OpenAI ou +quando estiver forçando o harness nativo do app-server do Codex: + +| Referência do modelo | Caminho de runtime | Use quando | +| --------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Provedor OpenAI por meio da infraestrutura OpenClaw/PI | Você quer acesso direto atual à API OpenAI Platform com `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OAuth OpenAI Codex por meio do OpenClaw/PI | Você quer autenticação de assinatura ChatGPT/Codex com o executor PI padrão. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Harness do app-server do Codex | Você quer execução nativa no app-server do Codex para o turno de agente incorporado. | + +GPT-5.5 atualmente é apenas por assinatura/OAuth no OpenClaw. Use +`openai-codex/gpt-5.5` para OAuth via PI, ou `openai/gpt-5.5` com o harness +do app-server do Codex. Acesso direto por chave de API para `openai/gpt-5.5` é compatível +quando a OpenAI habilitar o GPT-5.5 na API pública. + +Referências legadas `codex/gpt-*` continuam aceitas como aliases de compatibilidade. A migração de +compatibilidade do doctor reescreve referências legadas de runtime primário para referências canônicas de modelo +e registra a política de runtime separadamente, enquanto referências legadas apenas de fallback +ficam inalteradas porque o runtime é configurado para todo o contêiner do agente. +Novas configurações PI de OAuth do Codex devem usar `openai-codex/gpt-*`; novas configurações do harness +nativo do app-server devem usar `openai/gpt-*` mais +`agentRuntime.id: "codex"`. + +`agents.defaults.imageModel` segue a mesma divisão de prefixos. Use +`openai-codex/gpt-*` quando a compreensão de imagens deve executar por meio do caminho do provedor OAuth OpenAI +Codex. Use `codex/gpt-*` quando a compreensão de imagens deve executar +por meio de um turno delimitado do app-server do Codex. O modelo do app-server do Codex deve +anunciar suporte a entrada de imagem; modelos Codex somente texto falham antes do turno de mídia +começar. + +Use `/status` para confirmar o harness efetivo da sessão atual. Se a +seleção for surpreendente, habilite logs de depuração para o subsistema `agents/harness` +e inspecione o registro estruturado `agent harness selected` do Gateway. Ele +inclui o id do harness selecionado, motivo da seleção, política de runtime/fallback e, +no modo `auto`, o resultado de suporte de cada candidato de Plugin. + +### O que significam os avisos do doctor + +`openclaw doctor` avisa quando tudo isto é verdadeiro: + +- o Plugin `codex` incluído está habilitado ou permitido +- o modelo primário de um agente é `openai-codex/*` +- o runtime efetivo desse agente não é `codex` + +Esse aviso existe porque usuários frequentemente esperam que "Plugin Codex habilitado" implique +"runtime nativo do app-server do Codex." O OpenClaw não faz esse salto. O aviso +significa: + +- **Nenhuma alteração é necessária** se você pretendia usar OAuth ChatGPT/Codex por meio de PI. +- Altere o modelo para `openai/` e defina + `agentRuntime.id: "codex"` se você pretendia execução nativa no app-server. +- Sessões existentes ainda precisam de `/new` ou `/reset` após uma alteração de runtime, + porque pins de runtime de sessão são persistentes. + +A seleção de harness não é um controle de sessão ao vivo. Quando um turno incorporado é executado, +o OpenClaw registra o id do harness selecionado nessa sessão e continua usando-o para +turnos posteriores no mesmo id de sessão. Altere a configuração `agentRuntime` ou +`OPENCLAW_AGENT_RUNTIME` quando quiser que sessões futuras usem outro harness; +use `/new` ou `/reset` para iniciar uma sessão nova antes de alternar uma conversa existente +entre PI e Codex. Isso evita reproduzir uma transcrição por meio +de dois sistemas de sessão nativos incompatíveis. + +Sessões legadas criadas antes dos pins de harness são tratadas como fixadas em PI assim que +têm histórico de transcrição. Use `/new` ou `/reset` para optar essa conversa pelo +Codex após alterar a configuração. + +`/status` mostra o runtime efetivo do modelo. O harness PI padrão aparece como +`Runtime: OpenClaw Pi Default`, e o harness do app-server do Codex aparece como +`Runtime: OpenAI Codex`. + +## Requisitos + +- OpenClaw com o Plugin `codex` incluído disponível. +- app-server do Codex `0.125.0` ou mais recente. O Plugin incluído gerencia um binário + compatível do app-server do Codex por padrão, portanto comandos locais `codex` em `PATH` não + afetam a inicialização normal do harness. +- Autenticação do Codex disponível para o processo do app-server ou para a ponte de autenticação Codex + do OpenClaw. Inicializações locais do app-server por stdio usam uma home Codex gerenciada pelo OpenClaw para cada + agente e um `HOME` filho isolado, portanto não leem sua conta pessoal + `~/.codex`, Skills, plugins, configuração, estado de thread ou + `$HOME/.agents/skills` nativo por padrão. + +O Plugin bloqueia handshakes de app-server mais antigos ou sem versão. Isso mantém +o OpenClaw na superfície de protocolo contra a qual foi testado. + +Para testes smoke ao vivo e em Docker, a autenticação geralmente vem da conta da CLI Codex +ou de um perfil de autenticação `openai-codex` do OpenClaw. Inicializações locais do app-server por stdio também podem +recorrer a `CODEX_API_KEY` / `OPENAI_API_KEY` quando nenhuma conta está presente. + +## Adicionar Codex junto a outros modelos Não defina `agentRuntime.id: "codex"` globalmente se o mesmo agente deve alternar livremente -entre Codex e modelos de provedores que não são Codex. Um runtime forçado se aplica a cada -turno incorporado desse agente ou sessão. Se você selecionar um modelo Anthropic enquanto -esse runtime estiver forçado, o OpenClaw ainda tentará o harness do Codex e falhará fechado +entre modelos de provedores Codex e não Codex. Um runtime forçado se aplica a todo +turno embutido desse agente ou dessa sessão. Se você selecionar um modelo da Anthropic enquanto +esse runtime estiver forçado, o OpenClaw ainda tenta usar o harness do Codex e falha em modo fechado em vez de rotear silenciosamente esse turno pelo PI. Use um destes formatos em vez disso: - Coloque o Codex em um agente dedicado com `agentRuntime.id: "codex"`. -- Mantenha o agente padrão em `agentRuntime.id: "auto"` e fallback para PI para uso normal misto - de provedores. -- Use refs legadas `codex/*` apenas para compatibilidade. Novas configurações devem preferir +- Mantenha o agente padrão em `agentRuntime.id: "auto"` e fallback PI para uso normal com provedores mistos. +- Use referências legadas `codex/*` apenas para compatibilidade. Novas configurações devem preferir `openai/*` mais uma política explícita de runtime do Codex. Por exemplo, isto mantém o agente padrão na seleção automática normal e @@ -295,36 +298,36 @@ adiciona um agente Codex separado: Com este formato: -- O agente padrão `main` usa o caminho normal do provedor e o fallback de compatibilidade do PI. -- O agente `codex` usa o harness app-server do Codex. -- Se o Codex estiver ausente ou sem suporte para o agente `codex`, o turno falhará - em vez de usar o PI silenciosamente. +- O agente `main` padrão usa o caminho normal do provedor e o fallback de compatibilidade PI. +- O agente `codex` usa o harness de app-server do Codex. +- Se o Codex estiver ausente ou não for compatível para o agente `codex`, o turno falha + em vez de usar PI silenciosamente. -## Roteamento de comandos de agente +## Roteamento de comandos do agente -Agentes devem rotear solicitações de usuários por intenção, não apenas pela palavra "Codex": +Os agentes devem rotear solicitações de usuários por intenção, não apenas pela palavra "Codex": -| Usuário pede para... | Agente deve usar... | +| O usuário pede para... | O agente deve usar... | | -------------------------------------------------------- | ------------------------------------------------ | | "Vincule este chat ao Codex" | `/codex bind` | -| "Retome a thread Codex `` aqui" | `/codex resume ` | -| "Mostre as threads do Codex" | `/codex threads` | +| "Retome o thread Codex `` aqui" | `/codex resume ` | +| "Mostre os threads Codex" | `/codex threads` | | "Registre um relatório de suporte para uma execução ruim do Codex" | `/diagnostics [note]` | -| "Envie feedback do Codex apenas para esta thread anexada" | `/codex diagnostics [note]` | -| "Use Codex como runtime para este agente" | alteração de config para `agentRuntime.id` | -| "Use minha assinatura ChatGPT/Codex com OpenClaw normal" | refs de modelo `openai-codex/*` | -| "Execute Codex por meio de ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Inicie Claude Code/Gemini/OpenCode/Cursor em uma thread" | ACP/acpx, não `/codex` e não subagentes nativos | +| "Envie apenas feedback do Codex para este thread anexado" | `/codex diagnostics [note]` | +| "Use Codex como runtime para este agente" | alteração de configuração para `agentRuntime.id` | +| "Use minha assinatura ChatGPT/Codex com OpenClaw normal" | referências de modelo `openai-codex/*` | +| "Execute Codex por ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Inicie Claude Code/Gemini/OpenCode/Cursor em um thread" | ACP/acpx, não `/codex` e não subagentes nativos | -O OpenClaw só anuncia orientação de spawn ACP para agentes quando ACP está habilitado, +O OpenClaw só anuncia orientação de spawn ACP aos agentes quando ACP está habilitado, despachável e respaldado por um backend de runtime carregado. Se ACP não estiver disponível, -o prompt do sistema e as Skills do Plugin não devem ensinar o agente sobre roteamento +o prompt do sistema e as Skills de Plugin não devem ensinar o agente sobre roteamento ACP. ## Implantações somente Codex -Force o harness do Codex quando precisar comprovar que cada turno de agente incorporado -usa Codex. Runtimes explícitos de Plugin usam por padrão nenhum fallback para PI, então +Force o harness do Codex quando você precisar provar que todo turno de agente embutido +usa Codex. Runtimes explícitos de Plugin têm como padrão não usar fallback PI, então `fallback: "none"` é opcional, mas muitas vezes útil como documentação: ```json5 @@ -341,20 +344,20 @@ usa Codex. Runtimes explícitos de Plugin usam por padrão nenhum fallback para } ``` -Substituição por ambiente: +Sobrescrita de ambiente: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Com Codex forçado, o OpenClaw falha cedo se o Plugin Codex estiver desabilitado, o -app-server for antigo demais ou o app-server não conseguir iniciar. Defina -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` somente se você intencionalmente quiser que o PI trate +Com Codex forçado, o OpenClaw falha cedo se o Plugin Codex estiver desabilitado, se o +app-server for antigo demais ou se o app-server não puder iniciar. Defina +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` somente se você quiser intencionalmente que PI lide com seleção de harness ausente. ## Codex por agente -Você pode tornar um agente somente Codex enquanto o agente padrão mantém +Você pode tornar um agente exclusivo para Codex enquanto o agente padrão mantém a seleção automática normal: ```json5 @@ -386,15 +389,15 @@ seleção automática normal: } ``` -Use comandos normais de sessão para alternar agentes e modelos. `/new` cria uma nova -sessão OpenClaw e o harness do Codex cria ou retoma sua thread app-server auxiliar -conforme necessário. `/reset` limpa a vinculação da sessão OpenClaw para essa thread +Use comandos normais de sessão para alternar entre agentes e modelos. `/new` cria uma nova +sessão OpenClaw e o harness do Codex cria ou retoma seu thread app-server auxiliar +conforme necessário. `/reset` limpa a vinculação da sessão OpenClaw para esse thread e permite que o próximo turno resolva o harness a partir da configuração atual novamente. ## Descoberta de modelos -Por padrão, o Plugin Codex pede ao app-server os modelos disponíveis. Se a -descoberta falhar ou atingir timeout, ele usa um catálogo de fallback empacotado para: +Por padrão, o Plugin Codex solicita ao app-server os modelos disponíveis. Se a +descoberta falhar ou atingir timeout, ele usa um catálogo de fallback integrado para: - GPT-5.5 - GPT-5.4 mini @@ -420,8 +423,8 @@ Você pode ajustar a descoberta em `plugins.entries.codex.config.discovery`: } ``` -Desabilite a descoberta quando quiser que a inicialização evite consultar o Codex e se mantenha no -catálogo de fallback: +Desabilite a descoberta quando quiser que a inicialização evite sondar o Codex e use +o catálogo de fallback: ```json5 { @@ -448,17 +451,17 @@ Por padrão, o Plugin inicia localmente o binário Codex gerenciado pelo OpenCla codex app-server --listen stdio:// ``` -O binário gerenciado é declarado como uma dependência de runtime de Plugin empacotada e preparado +O binário gerenciado é declarado como uma dependência de runtime de Plugin integrada e preparado com o restante das dependências do Plugin `codex`. Isso mantém a versão do app-server -vinculada ao Plugin empacotado em vez de qualquer CLI Codex separada -que esteja instalada localmente. Defina `appServer.command` somente quando você -intencionalmente quiser executar um executável diferente. +vinculada ao Plugin integrado em vez de qualquer CLI Codex separada que +por acaso esteja instalada localmente. Defina `appServer.command` somente quando você +quiser intencionalmente executar um executável diferente. -Por padrão, o OpenClaw inicia sessões locais do harness Codex no modo YOLO: +Por padrão, o OpenClaw inicia sessões locais do harness Codex em modo YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` e -`sandbox: "danger-full-access"`. Esta é a postura de operador local confiável usada +`sandbox: "danger-full-access"`. Essa é a postura de operador local confiável usada para Heartbeats autônomos: o Codex pode usar ferramentas de shell e rede sem -parar em prompts de aprovação nativos que ninguém está por perto para responder. +parar em prompts de aprovação nativos que ninguém está presente para responder. Para optar por aprovações revisadas pelo guardião do Codex, defina `appServer.mode: "guardian"`: @@ -481,16 +484,16 @@ Para optar por aprovações revisadas pelo guardião do Codex, defina `appServer } ``` -O modo guardião usa o caminho de aprovação de auto-revisão nativo do Codex. Quando o Codex pede para -sair do sandbox, escrever fora do workspace ou adicionar permissões como acesso -à rede, o Codex roteia essa solicitação de aprovação para o revisor nativo em vez de um +O modo Guardian usa o caminho de aprovação com revisão automática nativo do Codex. Quando o Codex pede para +sair do sandbox, escrever fora do workspace ou adicionar permissões como acesso à rede, +o Codex roteia essa solicitação de aprovação ao revisor nativo em vez de a um prompt humano. O revisor aplica o framework de risco do Codex e aprova ou nega -a solicitação específica. Use Guardião quando quiser mais proteções do que o modo YOLO, -mas ainda precisar que agentes autônomos façam progresso. +a solicitação específica. Use Guardian quando quiser mais proteções do que o modo YOLO, +mas ainda precisar que agentes sem supervisão progridam. O preset `guardian` expande para `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` e `sandbox: "workspace-write"`. -Campos de política individuais ainda substituem `mode`, então implantações avançadas podem combinar +Campos de política individuais ainda sobrescrevem `mode`, então implantações avançadas podem combinar o preset com escolhas explícitas. O valor de revisor mais antigo `guardian_subagent` ainda é aceito como alias de compatibilidade, mas novas configurações devem usar `auto_review`. @@ -517,16 +520,16 @@ Para um app-server já em execução, use transporte WebSocket: } ``` -Inicializações do app-server por stdio herdam o ambiente de processo do OpenClaw por padrão, +Inicializações de app-server por stdio herdam o ambiente de processo do OpenClaw por padrão, mas o OpenClaw possui a ponte de conta do app-server Codex e define tanto -`CODEX_HOME` quanto `HOME` para diretórios por agente no estado OpenClaw -desse agente. O carregador de Skills próprio do Codex lê `$CODEX_HOME/skills` e -`$HOME/.agents/skills`, então ambos os valores são isolados para inicializações locais do app-server. -Isso mantém Skills nativas do Codex, plugins, configuração, contas e estado de thread +`CODEX_HOME` quanto `HOME` para diretórios por agente sob o estado OpenClaw +desse agente. O próprio carregador de Skills do Codex lê `$CODEX_HOME/skills` e +`$HOME/.agents/skills`, então ambos os valores são isolados para inicializações locais de app-server. +Isso mantém Skills, plugins, configuração, contas e estado de thread nativos do Codex escopados ao agente OpenClaw em vez de vazarem da home pessoal da CLI Codex do operador. -Plugins OpenClaw e snapshots de Skills do OpenClaw ainda fluem pelo próprio +Plugins OpenClaw e snapshots de Skills OpenClaw ainda passam pelo próprio registro de Plugin e carregador de Skills do OpenClaw. Ativos pessoais da CLI Codex não. Se você tiver Skills ou plugins úteis da CLI Codex que devam se tornar parte de um agente OpenClaw, inventarie-os explicitamente: @@ -539,23 +542,23 @@ openclaw migrate apply codex --yes O provedor de migração Codex copia Skills para o workspace atual do agente OpenClaw. Plugins nativos do Codex, hooks e arquivos de configuração são relatados ou arquivados para revisão manual em vez de serem ativados automaticamente, porque podem -executar comandos, expor servidores MCP ou conter credenciais. +executar comandos, expor servidores MCP ou carregar credenciais. A autenticação é selecionada nesta ordem: -1. Um perfil de autenticação Codex explícito do OpenClaw para o agente. +1. Um perfil explícito de autenticação Codex do OpenClaw para o agente. 2. A conta existente do app-server na home Codex desse agente. -3. Apenas para inicializações locais do app-server por stdio, `CODEX_API_KEY`, depois - `OPENAI_API_KEY`, quando nenhuma conta do app-server está presente e a autenticação OpenAI - ainda é exigida. +3. Apenas para inicializações locais de app-server por stdio, `CODEX_API_KEY`, depois + `OPENAI_API_KEY`, quando nenhuma conta de app-server estiver presente e a autenticação OpenAI + ainda for necessária. Quando o OpenClaw vê um perfil de autenticação Codex no estilo de assinatura ChatGPT, ele remove `CODEX_API_KEY` e `OPENAI_API_KEY` do processo filho Codex iniciado. Isso mantém chaves de API em nível de Gateway disponíveis para embeddings ou modelos OpenAI diretos sem fazer turnos nativos do app-server Codex serem cobrados pela API por acidente. -Perfis Codex explícitos por chave de API e fallback por chave de ambiente stdio local usam login -do app-server em vez de ambiente herdado do processo filho. Conexões WebSocket do app-server -não recebem fallback de chave de API por env do Gateway; use um perfil de autenticação explícito ou a +Perfis explícitos de chave de API Codex e fallback local por chave de ambiente stdio usam login no app-server +em vez de ambiente herdado do processo filho. Conexões WebSocket com app-server +não recebem fallback de chave de API de ambiente do Gateway; use um perfil explícito de autenticação ou a própria conta do app-server remoto. Se uma implantação precisar de isolamento adicional de ambiente, adicione essas variáveis a @@ -582,35 +585,33 @@ Se uma implantação precisar de isolamento adicional de ambiente, adicione essa Campos `appServer` compatíveis: -| Campo | Padrão | Significado | +| Campo | Padrão | Significado | | ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `transport` | `"stdio"` | `"stdio"` inicia o Codex; `"websocket"` conecta a `url`. | -| `command` | binário Codex gerenciado | Executável para o transporte stdio. Deixe sem definir para usar o binário gerenciado; defina apenas para uma substituição explícita. | -| `args` | `["app-server", "--listen", "stdio://"]` | Argumentos para o transporte stdio. | -| `url` | não definido | URL do app-server WebSocket. | -| `authToken` | não definido | Token bearer para o transporte WebSocket. | +| `command` | binário Codex gerenciado | Executável para transporte stdio. Deixe sem definir para usar o binário gerenciado; defina apenas para uma substituição explícita. | +| `args` | `["app-server", "--listen", "stdio://"]` | Argumentos para transporte stdio. | +| `url` | não definido | URL do app-server WebSocket. | +| `authToken` | não definido | Token Bearer para transporte WebSocket. | | `headers` | `{}` | Cabeçalhos WebSocket extras. | -| `clearEnv` | `[]` | Nomes de variáveis de ambiente extras removidos do processo app-server stdio iniciado depois que o OpenClaw cria seu ambiente herdado. `CODEX_HOME` e `HOME` são reservados para o isolamento Codex por agente do OpenClaw em inicializações locais. | -| `requestTimeoutMs` | `60000` | Tempo limite para chamadas de plano de controle do app-server. | -| `mode` | `"yolo"` | Predefinição para execução YOLO ou revisada pelo guardian. | -| `approvalPolicy` | `"never"` | Política de aprovação nativa do Codex enviada para início/retomada/turno da thread. | -| `sandbox` | `"danger-full-access"` | Modo sandbox nativo do Codex enviado para início/retomada da thread. | +| `clearEnv` | `[]` | Nomes de variáveis de ambiente extras removidos do processo app-server stdio iniciado depois que o OpenClaw monta seu ambiente herdado. `CODEX_HOME` e `HOME` são reservados para o isolamento Codex por agente do OpenClaw em inicializações locais. | +| `requestTimeoutMs` | `60000` | Tempo limite para chamadas do plano de controle do app-server. | +| `mode` | `"yolo"` | Predefinição para execução YOLO ou revisada por guardião. | +| `approvalPolicy` | `"never"` | Política de aprovação nativa do Codex enviada para início/retomada/turno de thread. | +| `sandbox` | `"danger-full-access"` | Modo sandbox nativo do Codex enviado para início/retomada de thread. | | `approvalsReviewer` | `"user"` | Use `"auto_review"` para permitir que o Codex revise prompts de aprovação nativos. `guardian_subagent` permanece como um alias legado. | -| `serviceTier` | não definido | Camada de serviço opcional do app-server Codex: `"fast"`, `"flex"` ou `null`. Valores legados inválidos são ignorados. | +| `serviceTier` | não definido | Camada de serviço opcional do app-server Codex: `"fast"`, `"flex"` ou `null`. Valores legados inválidos são ignorados. | -As chamadas dinâmicas de ferramentas de propriedade do OpenClaw são limitadas -independentemente de `appServer.requestTimeoutMs`: cada solicitação Codex -`item/tool/call` deve receber uma resposta do OpenClaw em até 30 segundos. Ao -atingir o tempo limite, o OpenClaw aborta o sinal da ferramenta quando houver -suporte e retorna uma resposta de ferramenta dinâmica com falha para o Codex para -que o turno possa continuar em vez de deixar a sessão em `processing`. +Chamadas de ferramentas dinâmicas de propriedade do OpenClaw são limitadas independentemente de +`appServer.requestTimeoutMs`: cada solicitação Codex `item/tool/call` deve receber +uma resposta do OpenClaw em até 30 segundos. Em caso de tempo limite, o OpenClaw aborta o sinal da ferramenta +quando houver suporte e retorna uma resposta de ferramenta dinâmica com falha ao Codex para que +o turno possa continuar em vez de deixar a sessão em `processing`. -Depois que o OpenClaw responde a uma solicitação app-server com escopo de turno -do Codex, o harness também espera que o Codex conclua o turno nativo com -`turn/completed`. Se o app-server ficar silencioso por 60 segundos depois dessa -resposta, o OpenClaw faz uma tentativa de interromper o turno do Codex, registra -um tempo limite diagnóstico e libera a faixa da sessão do OpenClaw para que -mensagens de chat de acompanhamento não fiquem enfileiradas atrás de um turno +Depois que o OpenClaw responde a uma solicitação de app-server com escopo de turno do Codex, o harness +também espera que o Codex finalize o turno nativo com `turn/completed`. Se o +app-server ficar silencioso por 60 segundos após essa resposta, o OpenClaw, em melhor esforço, +interrompe o turno do Codex, registra um tempo limite de diagnóstico e libera a +faixa de sessão do OpenClaw para que mensagens de chat subsequentes não fiquem enfileiradas atrás de um turno nativo obsoleto. Substituições de ambiente continuam disponíveis para testes locais: @@ -626,26 +627,24 @@ Substituições de ambiente continuam disponíveis para testes locais: `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` foi removido. Use `plugins.entries.codex.config.appServer.mode: "guardian"` em vez disso, ou -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` para testes locais pontuais. A -configuração é preferível para implantações repetíveis porque mantém o -comportamento do Plugin no mesmo arquivo revisado que o restante da configuração -do harness do Codex. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` para testes locais pontuais. A configuração é +preferida para implantações repetíveis porque mantém o comportamento do Plugin no +mesmo arquivo revisado que o restante da configuração do harness Codex. ## Uso do computador -O Uso do computador é abordado em seu próprio guia de configuração: -[Uso do computador do Codex](/pt-BR/plugins/codex-computer-use). +O Uso do Computador é abordado em seu próprio guia de configuração: +[Uso do Computador do Codex](/pt-BR/plugins/codex-computer-use). -A versão curta: o OpenClaw não incorpora o app de controle da área de trabalho -nem executa ações na área de trabalho por conta própria. Ele prepara o app-server -do Codex, verifica se o servidor MCP `computer-use` está disponível e então -deixa o Codex lidar com as chamadas nativas de ferramentas MCP durante turnos em -modo Codex. +A versão curta: o OpenClaw não inclui como vendor o app de controle de desktop nem executa +ações de desktop por conta própria. Ele prepara o app-server Codex, verifica se o servidor MCP +`computer-use` está disponível e, então, permite que o Codex lide com as chamadas nativas de ferramenta +MCP durante turnos em modo Codex. -Para acesso direto ao driver TryCua fora do fluxo do marketplace do Codex, -registre `cua-driver mcp` com `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. -Consulte [Uso do computador do Codex](/pt-BR/plugins/codex-computer-use) para ver a -distinção entre Uso do computador de propriedade do Codex e registro MCP direto. +Para acesso direto ao driver TryCua fora do fluxo do marketplace Codex, registre +`cua-driver mcp` com `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Consulte [Uso do Computador do Codex](/pt-BR/plugins/codex-computer-use) para a distinção +entre o Uso do Computador de propriedade do Codex e o registro MCP direto. Configuração mínima: @@ -675,28 +674,26 @@ Configuração mínima: } ``` -A configuração pode ser verificada ou instalada pela superfície de comandos: +A configuração pode ser verificada ou instalada pela superfície de comando: - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -O Uso do computador é específico do macOS e pode exigir permissões locais do SO -antes que o servidor MCP do Codex possa controlar apps. Se `computerUse.enabled` -for true e o servidor MCP estiver indisponível, os turnos em modo Codex falham -antes que a thread seja iniciada, em vez de serem executados silenciosamente sem -as ferramentas nativas de Uso do computador. Consulte -[Uso do computador do Codex](/pt-BR/plugins/codex-computer-use) para opções de -marketplace, limites do catálogo remoto, motivos de status e solução de -problemas. +O Uso do Computador é específico do macOS e pode exigir permissões locais do sistema operacional antes que o +servidor MCP do Codex possa controlar apps. Se `computerUse.enabled` for true e o servidor MCP +estiver indisponível, turnos em modo Codex falham antes de a thread iniciar em vez de +executar silenciosamente sem as ferramentas nativas de Uso do Computador. Consulte +[Uso do Computador do Codex](/pt-BR/plugins/codex-computer-use) para opções de marketplace, +limites de catálogo remoto, motivos de status e solução de problemas. -Quando `computerUse.autoInstall` é true, o OpenClaw pode registrar o marketplace -padrão incluído do Codex Desktop a partir de +Quando `computerUse.autoInstall` for true, o OpenClaw pode registrar o marketplace padrão +Codex Desktop empacotado de `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled` se o Codex -ainda não tiver descoberto um marketplace local. Use `/new` ou `/reset` depois -de alterar a configuração de runtime ou de Uso do computador para que sessões -existentes não mantenham uma associação antiga de PI ou de thread Codex. +ainda não tiver descoberto um marketplace local. Use `/new` ou `/reset` depois de +alterar a configuração de runtime ou Uso do Computador para que sessões existentes não mantenham uma vinculação antiga +de PI ou thread Codex. ## Receitas comuns @@ -714,7 +711,7 @@ Codex local com transporte stdio padrão: } ``` -Validação do harness somente com Codex: +Validação de harness somente Codex: ```json5 { @@ -736,7 +733,7 @@ Validação do harness somente com Codex: } ``` -Aprovações Codex revisadas pelo guardian: +Aprovações do Codex revisadas por guardião: ```json5 { @@ -781,176 +778,171 @@ App-server remoto com cabeçalhos explícitos: } ``` -A troca de modelo continua controlada pelo OpenClaw. Quando uma sessão OpenClaw -é anexada a uma thread Codex existente, o próximo turno envia novamente ao -app-server o modelo OpenAI, provedor, política de aprovação, sandbox e camada de -serviço selecionados no momento. Mudar de `openai/gpt-5.5` para -`openai/gpt-5.2` mantém a associação da thread, mas pede ao Codex para continuar -com o modelo recém-selecionado. +A troca de modelo permanece controlada pelo OpenClaw. Quando uma sessão do OpenClaw está anexada +a uma thread Codex existente, o próximo turno envia o modelo +OpenAI selecionado no momento, provedor, política de aprovação, sandbox e camada de serviço para o +app-server novamente. Trocar de `openai/gpt-5.5` para `openai/gpt-5.2` mantém a +vinculação da thread, mas pede ao Codex para continuar com o novo modelo selecionado. ## Comando Codex -O Plugin incluído registra `/codex` como um comando de barra autorizado. Ele é -genérico e funciona em qualquer canal compatível com comandos de texto do -OpenClaw. +O Plugin empacotado registra `/codex` como um comando de barra autorizado. Ele é +genérico e funciona em qualquer canal que ofereça suporte a comandos de texto do OpenClaw. Formas comuns: - `/codex status` mostra conectividade ativa do app-server, modelos, conta, limites de taxa, servidores MCP e Skills. - `/codex models` lista modelos ativos do app-server Codex. - `/codex threads [filter]` lista threads Codex recentes. -- `/codex resume ` anexa a sessão OpenClaw atual a uma thread Codex existente. -- `/codex compact` pede ao app-server Codex para compactar a thread anexada. +- `/codex resume ` anexa a sessão atual do OpenClaw a uma thread Codex existente. +- `/codex compact` solicita que o app-server Codex compacte a thread anexada. - `/codex review` inicia a revisão nativa do Codex para a thread anexada. - `/codex diagnostics [note]` pergunta antes de enviar feedback de diagnóstico do Codex para a thread anexada. -- `/codex computer-use status` verifica o Plugin de Uso do computador configurado e o servidor MCP. -- `/codex computer-use install` instala o Plugin de Uso do computador configurado e recarrega servidores MCP. -- `/codex account` mostra o status da conta e dos limites de taxa. +- `/codex computer-use status` verifica o Plugin de Uso do Computador configurado e o servidor MCP. +- `/codex computer-use install` instala o Plugin de Uso do Computador configurado e recarrega servidores MCP. +- `/codex account` mostra a conta e o status de limite de taxa. - `/codex mcp` lista o status dos servidores MCP do app-server Codex. -- `/codex skills` lista Skills do app-server Codex. +- `/codex skills` lista as Skills do app-server Codex. -### Fluxo de depuração comum +### Fluxo de trabalho comum de depuração -Quando um agente respaldado pelo Codex faz algo inesperado no Telegram, Discord, -Slack ou outro canal, comece pela conversa em que o problema aconteceu: +Quando um agente baseado em Codex faz algo surpreendente no Telegram, Discord, Slack +ou outro canal, comece pela conversa em que o problema aconteceu: 1. Execute `/diagnostics bad tool choice after image upload` ou outra nota curta que descreva o que você viu. -2. Aprove a solicitação de diagnóstico uma vez. A aprovação cria o zip local de - diagnósticos do Gateway e, como a sessão está usando o harness do Codex, - também envia o pacote de feedback Codex relevante para os servidores da - OpenAI. -3. Copie a resposta de diagnóstico concluída para o relatório de bug ou thread - de suporte. Ela inclui o caminho do pacote local, o resumo de privacidade, ids - de sessão OpenClaw, ids de thread Codex e uma linha `Inspect locally` para - cada thread Codex. -4. Se quiser depurar a execução por conta própria, execute o comando impresso - `Inspect locally` em um terminal. Ele se parece com `codex resume ` - e abre a thread nativa do Codex para que você possa inspecionar a conversa, - continuá-la localmente ou perguntar ao Codex por que ele escolheu uma - ferramenta ou plano específico. +2. Aprove a solicitação de diagnóstico uma vez. A aprovação cria o zip de diagnóstico local do Gateway + e, como a sessão está usando o harness Codex, também + envia o pacote de feedback Codex relevante para servidores OpenAI. +3. Copie a resposta de diagnóstico concluída para o relatório de bug ou thread de suporte. + Ela inclui o caminho do pacote local, resumo de privacidade, ids de sessão do OpenClaw, + ids de thread Codex e uma linha `Inspect locally` para cada thread Codex. +4. Se quiser depurar a execução por conta própria, execute o comando `Inspect locally` + impresso em um terminal. Ele se parece com `codex resume ` e abre a + thread nativa do Codex para que você possa inspecionar a conversa, continuá-la localmente + ou perguntar ao Codex por que ele escolheu uma ferramenta ou plano específico. -Use `/codex diagnostics [note]` somente quando você quiser especificamente o envio de feedback do Codex para a thread anexada no momento, sem o pacote completo de diagnósticos do Gateway do OpenClaw. Para a maioria dos relatórios de suporte, `/diagnostics [note]` é o melhor ponto de partida porque vincula o estado local do Gateway e os ids de thread do Codex em uma única resposta. Consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics) para ver o modelo completo de privacidade e o comportamento em chats em grupo. +Use `/codex diagnostics [note]` somente quando você quiser especificamente o upload de feedback do Codex para a thread anexada no momento sem o pacote completo de diagnósticos do Gateway do OpenClaw. Para a maioria dos relatórios de suporte, `/diagnostics [note]` é o melhor ponto de partida, porque ele vincula o estado do Gateway local e os ids de thread do Codex em uma única resposta. Consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics) para o modelo completo de privacidade e o comportamento em chats em grupo. -O núcleo do OpenClaw também expõe `/diagnostics [note]`, restrito a proprietários, como o comando geral de diagnósticos do Gateway. Seu prompt de aprovação mostra o preâmbulo sobre dados sensíveis, inclui links para [Exportação de diagnósticos](/pt-BR/gateway/diagnostics) e solicita `openclaw gateway diagnostics export --json` por meio de aprovação explícita de execução todas as vezes. Não aprove diagnósticos com uma regra de permitir tudo. Após a aprovação, o OpenClaw envia um relatório colável com o caminho do pacote local e o resumo do manifesto. Quando a sessão ativa do OpenClaw está usando o harness do Codex, essa mesma aprovação também autoriza o envio dos pacotes de feedback relevantes do Codex para os servidores da OpenAI. O prompt de aprovação informa que o feedback do Codex será enviado, mas não lista os ids de sessão ou de thread do Codex antes da aprovação. +O núcleo do OpenClaw também expõe `/diagnostics [note]`, exclusivo para proprietários, como o comando geral de diagnósticos do Gateway. O prompt de aprovação exibe o preâmbulo sobre dados sensíveis, vincula a [Exportação de Diagnósticos](/pt-BR/gateway/diagnostics) e solicita `openclaw gateway diagnostics export --json` por meio de aprovação explícita de execução todas as vezes. Não aprove diagnósticos com uma regra permitir tudo. Após a aprovação, o OpenClaw envia um relatório colável com o caminho do pacote local e o resumo do manifesto. Quando a sessão ativa do OpenClaw está usando o ambiente de execução do Codex, essa mesma aprovação também autoriza o envio dos pacotes de feedback relevantes do Codex para os servidores da OpenAI. O prompt de aprovação informa que o feedback do Codex será enviado, mas não lista ids de sessão ou thread do Codex antes da aprovação. -Se `/diagnostics` for invocado por um proprietário em um chat em grupo, o OpenClaw mantém o canal compartilhado limpo: o grupo recebe apenas um aviso curto, enquanto o preâmbulo de diagnósticos, os prompts de aprovação e os ids de sessão/thread do Codex são enviados ao proprietário pela rota privada de aprovação. Se não houver uma rota privada para o proprietário, o OpenClaw recusa a solicitação do grupo e pede que o proprietário a execute por DM. +Se `/diagnostics` for invocado por um proprietário em um chat em grupo, o OpenClaw mantém o canal compartilhado limpo: o grupo recebe apenas um aviso curto, enquanto o preâmbulo de diagnósticos, os prompts de aprovação e os ids de sessão/thread do Codex são enviados ao proprietário pela rota privada de aprovação. Se não houver uma rota privada para o proprietário, o OpenClaw recusa a solicitação do grupo e pede que o proprietário a execute por uma DM. -O upload aprovado do Codex chama o `feedback/upload` do app-server do Codex e pede que o app-server inclua logs para cada thread listada e subthreads geradas do Codex, quando disponíveis. O upload passa pelo caminho normal de feedback do Codex para os servidores da OpenAI; se o feedback do Codex estiver desativado nesse app-server, o comando retorna o erro do app-server. A resposta de diagnósticos concluída lista os canais, ids de sessão do OpenClaw, ids de thread do Codex e comandos locais `codex resume ` para as threads que foram enviadas. Se você negar ou ignorar a aprovação, o OpenClaw não imprime esses ids do Codex. Esse upload não substitui a exportação local de diagnósticos do Gateway. +O upload aprovado do Codex chama `feedback/upload` do app-server do Codex e solicita que o app-server inclua logs para cada thread listada e subthreads do Codex geradas quando disponíveis. O upload passa pelo caminho normal de feedback do Codex para os servidores da OpenAI; se o feedback do Codex estiver desativado nesse app-server, o comando retorna o erro do app-server. A resposta de diagnósticos concluída lista os canais, ids de sessão do OpenClaw, ids de thread do Codex e comandos locais `codex resume ` para as threads que foram enviadas. Se você negar ou ignorar a aprovação, o OpenClaw não imprime esses ids do Codex. Esse upload não substitui a exportação local de diagnósticos do Gateway. -`/codex resume` grava o mesmo arquivo de associação sidecar que o harness usa para turnos normais. Na próxima mensagem, o OpenClaw retoma essa thread do Codex, passa o modelo do OpenClaw selecionado no momento para o app-server e mantém o histórico estendido ativado. +`/codex resume` grava o mesmo arquivo de vinculação sidecar que o ambiente de execução usa para turnos normais. Na próxima mensagem, o OpenClaw retoma essa thread do Codex, passa o modelo do OpenClaw selecionado no momento para o app-server e mantém o histórico estendido ativado. ### Inspecionar uma thread do Codex pela CLI -A forma mais rápida de entender uma execução ruim do Codex muitas vezes é abrir a thread nativa do Codex diretamente: +A maneira mais rápida de entender uma execução problemática do Codex muitas vezes é abrir a thread nativa do Codex diretamente: ```sh codex resume ``` -Use isso quando perceber um bug em uma conversa de canal e quiser inspecionar a sessão problemática do Codex, continuá-la localmente ou perguntar ao Codex por que ele fez uma determinada escolha de ferramenta ou raciocínio. O caminho mais fácil geralmente é executar `/diagnostics [note]` primeiro: depois que você aprova, o relatório concluído lista cada thread do Codex e imprime um comando `Inspecionar localmente`, por exemplo `codex resume `. Você pode copiar esse comando diretamente para um terminal. +Use isso quando você perceber um bug em uma conversa de canal e quiser inspecionar a sessão problemática do Codex, continuá-la localmente ou perguntar ao Codex por que ele fez uma escolha específica de ferramenta ou raciocínio. O caminho mais fácil geralmente é executar `/diagnostics [note]` primeiro: depois que você o aprova, o relatório concluído lista cada thread do Codex e imprime um comando `Inspecionar localmente`, por exemplo `codex resume `. Você pode copiar esse comando diretamente para um terminal. -Você também pode obter um id de thread com `/codex binding` para o chat atual ou `/codex threads [filter]` para threads recentes do app-server do Codex, e então executar o mesmo comando `codex resume` no seu shell. +Você também pode obter um id de thread em `/codex binding` para o chat atual ou `/codex threads [filter]` para threads recentes do app-server do Codex e, em seguida, executar o mesmo comando `codex resume` no seu shell. -A superfície de comando requer o app-server do Codex `0.125.0` ou mais recente. Métodos de controle individuais são relatados como `unsupported by this Codex app-server` se um app-server futuro ou personalizado não expuser esse método JSON-RPC. +A superfície de comandos exige app-server do Codex `0.125.0` ou mais recente. Métodos de controle individuais são relatados como `unsupported by this Codex app-server` se um app-server futuro ou personalizado não expuser esse método JSON-RPC. -## Limites dos hooks +## Limites de hooks -O harness do Codex tem três camadas de hooks: +O ambiente de execução do Codex tem três camadas de hooks: | Camada | Proprietário | Finalidade | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Hooks de Plugin do OpenClaw | OpenClaw | Compatibilidade de produto/Plugin entre harnesses do PI e do Codex. | -| Middleware de extensão do app-server do Codex | Plugins empacotados do OpenClaw | Comportamento do adaptador por turno em torno das ferramentas dinâmicas do OpenClaw. | -| Hooks nativos do Codex | Codex | Ciclo de vida de baixo nível do Codex e política de ferramentas nativas da configuração do Codex. | +| Hooks de Plugin do OpenClaw | OpenClaw | Compatibilidade de produto/Plugin entre ambientes de execução PI e Codex. | +| Middleware de extensão do app-server do Codex | Plugins incluídos no OpenClaw | Comportamento do adaptador por turno em torno das ferramentas dinâmicas do OpenClaw. | +| Hooks nativos do Codex | Codex | Ciclo de vida de baixo nível do Codex e política de ferramentas nativas a partir da configuração do Codex. | -O OpenClaw não usa arquivos `hooks.json` de projeto ou globais do Codex para rotear o comportamento de Plugins do OpenClaw. Para a ponte compatível de ferramenta nativa e permissão, o OpenClaw injeta configuração do Codex por thread para `PreToolUse`, `PostToolUse`, `PermissionRequest` e `Stop`. Outros hooks do Codex, como `SessionStart` e `UserPromptSubmit`, permanecem controles de nível do Codex; eles não são expostos como hooks de Plugin do OpenClaw no contrato v1. +O OpenClaw não usa arquivos `hooks.json` de projeto ou globais do Codex para rotear o comportamento de Plugin do OpenClaw. Para a ponte compatível de ferramentas nativas e permissões, o OpenClaw injeta configuração do Codex por thread para `PreToolUse`, `PostToolUse`, `PermissionRequest` e `Stop`. Outros hooks do Codex, como `SessionStart` e `UserPromptSubmit`, continuam sendo controles no nível do Codex; eles não são expostos como hooks de Plugin do OpenClaw no contrato v1. -Para ferramentas dinâmicas do OpenClaw, o OpenClaw executa a ferramenta depois que o Codex solicita a chamada, então o OpenClaw dispara o comportamento de Plugin e middleware que ele possui no adaptador do harness. Para ferramentas nativas do Codex, o Codex possui o registro canônico da ferramenta. O OpenClaw pode espelhar eventos selecionados, mas não pode reescrever a thread nativa do Codex a menos que o Codex exponha essa operação por meio do app-server ou de callbacks de hooks nativos. +Para ferramentas dinâmicas do OpenClaw, o OpenClaw executa a ferramenta depois que o Codex solicita a chamada, então o OpenClaw dispara o comportamento de Plugin e middleware que ele controla no adaptador do ambiente de execução. Para ferramentas nativas do Codex, o Codex controla o registro canônico da ferramenta. O OpenClaw pode espelhar eventos selecionados, mas não pode reescrever a thread nativa do Codex, a menos que o Codex exponha essa operação por meio do app-server ou de callbacks de hooks nativos. -As projeções de Compaction e do ciclo de vida do LLM vêm de notificações do app-server do Codex e do estado do adaptador do OpenClaw, não de comandos de hooks nativos do Codex. Os eventos `before_compaction`, `after_compaction`, `llm_input` e `llm_output` do OpenClaw são observações de nível de adaptador, não capturas byte a byte da solicitação interna ou dos payloads de compactação do Codex. +Projeções de Compaction e ciclo de vida do LLM vêm de notificações do app-server do Codex e do estado do adaptador do OpenClaw, não de comandos de hooks nativos do Codex. Os eventos `before_compaction`, `after_compaction`, `llm_input` e `llm_output` do OpenClaw são observações no nível do adaptador, não capturas byte a byte da solicitação interna ou dos payloads de Compaction do Codex. As notificações `hook/started` e `hook/completed` nativas do Codex no app-server são projetadas como eventos de agente `codex_app_server.hook` para trajetória e depuração. Elas não invocam hooks de Plugin do OpenClaw. ## Contrato de suporte V1 -O modo Codex não é o PI com uma chamada de modelo diferente por baixo. O Codex possui uma parte maior do loop de modelo nativo, e o OpenClaw adapta suas superfícies de Plugin e sessão em torno desse limite. +O modo Codex não é PI com uma chamada de modelo diferente por baixo. O Codex controla uma parte maior do loop nativo do modelo, e o OpenClaw adapta suas superfícies de Plugin e sessão em torno desse limite. -Compatível no runtime v1 do Codex: +Compatível no runtime Codex v1: -| Superfície | Suporte | Motivo | -| --------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Loop de modelo da OpenAI por meio do Codex | Compatível | O app-server do Codex possui o turno da OpenAI, a retomada de thread nativa e a continuação de ferramentas nativas. | -| Roteamento e entrega de canais do OpenClaw | Compatível | Telegram, Discord, Slack, WhatsApp, iMessage e outros canais ficam fora do runtime do modelo. | -| Ferramentas dinâmicas do OpenClaw | Compatível | O Codex pede que o OpenClaw execute essas ferramentas, então o OpenClaw permanece no caminho de execução. | -| Plugins de prompt e contexto | Compatível | O OpenClaw constrói sobreposições de prompt e projeta contexto no turno do Codex antes de iniciar ou retomar a thread. | -| Ciclo de vida do mecanismo de contexto | Compatível | Montagem, ingestão ou manutenção após o turno e coordenação de Compaction do mecanismo de contexto são executadas para turnos do Codex. | -| Hooks de ferramentas dinâmicas | Compatível | `before_tool_call`, `after_tool_call` e middleware de resultado de ferramenta são executados em torno das ferramentas dinâmicas pertencentes ao OpenClaw. | +| Superfície | Suporte | Por quê | +| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Loop de modelo OpenAI por meio do Codex | Compatível | O app-server do Codex controla o turno da OpenAI, a retomada de thread nativa e a continuação de ferramenta nativa. | +| Roteamento e entrega de canais do OpenClaw | Compatível | Telegram, Discord, Slack, WhatsApp, iMessage e outros canais permanecem fora do runtime do modelo. | +| Ferramentas dinâmicas do OpenClaw | Compatível | O Codex pede que o OpenClaw execute essas ferramentas, então o OpenClaw permanece no caminho de execução. | +| Plugins de prompt e contexto | Compatível | O OpenClaw cria sobreposições de prompt e projeta contexto no turno do Codex antes de iniciar ou retomar a thread. | +| Ciclo de vida do mecanismo de contexto | Compatível | Montagem, ingestão ou manutenção pós-turno e coordenação de Compaction do mecanismo de contexto são executadas para turnos do Codex. | +| Hooks de ferramentas dinâmicas | Compatível | `before_tool_call`, `after_tool_call` e middleware de resultado de ferramenta são executados em torno de ferramentas dinâmicas controladas pelo OpenClaw. | | Hooks de ciclo de vida | Compatível como observações do adaptador | `llm_input`, `llm_output`, `agent_end`, `before_compaction` e `after_compaction` disparam com payloads honestos do modo Codex. | -| Gate de revisão da resposta final | Compatível por meio do relay de hook nativo | O `Stop` do Codex é retransmitido para `before_agent_finalize`; `revise` pede ao Codex mais uma passagem de modelo antes da finalização. | -| Bloqueio ou observação de shell, patch e MCP nativos | Compatível por meio do relay de hook nativo | `PreToolUse` e `PostToolUse` do Codex são retransmitidos para superfícies de ferramentas nativas confirmadas, incluindo payloads MCP no app-server do Codex `0.125.0` ou mais recente. O bloqueio é compatível; a reescrita de argumentos não é. | -| Política de permissões nativa | Compatível por meio do relay de hook nativo | `PermissionRequest` do Codex pode ser roteado pela política do OpenClaw onde o runtime a expõe. Se o OpenClaw não retornar decisão, o Codex continua pelo caminho normal de guardian ou aprovação do usuário. | -| Captura de trajetória do app-server | Compatível | O OpenClaw registra a solicitação que enviou ao app-server e as notificações do app-server que recebe. | +| Gate de revisão da resposta final | Compatível por meio do relay de hook nativo | `Stop` do Codex é retransmitido para `before_agent_finalize`; `revise` pede ao Codex mais uma passagem de modelo antes da finalização. | +| Shell, patch e bloqueio ou observação de MCP nativos | Compatível por meio do relay de hook nativo | `PreToolUse` e `PostToolUse` do Codex são retransmitidos para superfícies de ferramentas nativas confirmadas, incluindo payloads MCP no app-server do Codex `0.125.0` ou mais recente. O bloqueio é compatível; a reescrita de argumentos não é. | +| Política de permissão nativa | Compatível por meio do relay de hook nativo | `PermissionRequest` do Codex pode ser roteado pela política do OpenClaw onde o runtime a expõe. Se o OpenClaw não retornar nenhuma decisão, o Codex continua pelo seu caminho normal de guardião ou aprovação do usuário. | +| Captura de trajetória do app-server | Compatível | O OpenClaw registra a solicitação que enviou ao app-server e as notificações do app-server que recebe. | -Sem suporte no runtime v1 do Codex: +Não compatível no runtime Codex v1: -| Superfície | Limite V1 | Caminho futuro | -| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Mutação de argumentos de ferramentas nativas | Hooks nativos pré-ferramenta do Codex podem bloquear, mas o OpenClaw não reescreve argumentos de ferramentas nativas do Codex. | Requer suporte a hook/schema do Codex para entrada de ferramenta substituta. | -| Histórico editável de transcrição nativa do Codex | O Codex possui o histórico canônico de threads nativas. O OpenClaw possui um espelho e pode projetar contexto futuro, mas não deve mutar internos sem suporte. | Adicionar APIs explícitas do servidor de aplicativo do Codex se for necessária cirurgia de thread nativa. | -| `tool_result_persist` para registros de ferramentas nativas do Codex | Esse hook transforma escritas de transcrição pertencentes ao OpenClaw, não registros de ferramentas nativas do Codex. | Poderia espelhar registros transformados, mas a reescrita canônica precisa de suporte do Codex. | -| Metadados ricos de Compaction nativa | O OpenClaw observa o início e a conclusão da Compaction, mas não recebe uma lista estável de mantidos/descartados, delta de tokens ou payload de resumo. | Precisa de eventos de Compaction mais ricos do Codex. | -| Intervenção de Compaction | Os hooks atuais de Compaction do OpenClaw estão em nível de notificação no modo Codex. | Adicionar hooks de Compaction pré/pós do Codex se Plugins precisarem vetar ou reescrever Compaction nativa. | -| Captura byte a byte da requisição da API do modelo | O OpenClaw pode capturar requisições e notificações do servidor de aplicativo, mas o núcleo do Codex constrói internamente a requisição final da API OpenAI. | Precisa de um evento de rastreamento de requisição de modelo do Codex ou API de depuração. | +| Superfície | Limite da V1 | Caminho futuro | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | +| Mutação de argumentos de ferramenta nativa | Hooks pré-ferramenta nativos do Codex podem bloquear, mas o OpenClaw não reescreve argumentos de ferramentas nativas do Codex. | Requer suporte de hook/schema do Codex para substituir a entrada da ferramenta. | +| Histórico editável de transcrição nativa do Codex | O Codex possui o histórico canônico de threads nativas. O OpenClaw possui um espelho e pode projetar contexto futuro, mas não deve mutar partes internas sem suporte. | Adicionar APIs explícitas do app-server do Codex se for necessária cirurgia em threads nativas. | +| `tool_result_persist` para registros de ferramentas nativas do Codex | Esse hook transforma gravações de transcrição pertencentes ao OpenClaw, não registros de ferramentas nativas do Codex. | Poderia espelhar registros transformados, mas a reescrita canônica precisa de suporte do Codex. | +| Metadados ricos de compaction nativa | O OpenClaw observa o início e a conclusão da compaction, mas não recebe uma lista estável de mantidos/removidos, delta de tokens ou payload de resumo. | Precisa de eventos de compaction mais ricos do Codex. | +| Intervenção de compaction | Os hooks atuais de compaction do OpenClaw são de nível de notificação no modo Codex. | Adicionar hooks pré/pós-compaction do Codex se plugins precisarem vetar ou reescrever a compaction nativa. | +| Captura byte a byte da solicitação da API de modelo | O OpenClaw pode capturar solicitações e notificações do app-server, mas o núcleo do Codex constrói internamente a solicitação final da API da OpenAI. | Precisa de um evento de rastreamento de solicitação de modelo do Codex ou de uma API de depuração. | -## Ferramentas, mídia e Compaction +## Ferramentas, mídia e compaction -O harness do Codex altera apenas o executor de agente embutido de baixo nível. +O harness do Codex altera apenas o executor de agente incorporado de baixo nível. -O OpenClaw ainda cria a lista de ferramentas e recebe resultados dinâmicos de ferramentas do +O OpenClaw ainda cria a lista de ferramentas e recebe resultados de ferramentas dinâmicas do harness. Texto, imagens, vídeo, música, TTS, aprovações e saída de ferramentas de mensagens continuam pelo caminho normal de entrega do OpenClaw. -O relay de hooks nativos é intencionalmente genérico, mas o contrato de suporte v1 é -limitado aos caminhos de ferramentas e permissões nativas do Codex que o OpenClaw testa. No +O retransmissor de hooks nativos é intencionalmente genérico, mas o contrato de suporte da v1 é +limitado aos caminhos de ferramenta nativa e permissão do Codex que o OpenClaw testa. No runtime do Codex, isso inclui payloads de shell, patch e MCP `PreToolUse`, `PostToolUse` e `PermissionRequest`. Não presuma que todo evento futuro de hook do -Codex é uma superfície de Plugin do OpenClaw até que o contrato de runtime o nomeie. +Codex seja uma superfície de plugin do OpenClaw até que o contrato de runtime o nomeie. Para `PermissionRequest`, o OpenClaw retorna apenas decisões explícitas de permitir ou negar -quando a política decide. Um resultado sem decisão não é uma permissão. O Codex o trata como -ausência de decisão de hook e segue para seu próprio guardião ou caminho de aprovação do usuário. +quando a política decide. Um resultado sem decisão não é uma permissão. O Codex o trata como ausência de +decisão de hook e segue para seu próprio guardião ou caminho de aprovação do usuário. -Solicitações de aprovação de ferramenta MCP do Codex são roteadas pelo fluxo de aprovação de -Plugin do OpenClaw quando o Codex marca `_meta.codex_approval_kind` como +As solicitações de aprovação de ferramentas MCP do Codex são roteadas pelo fluxo de aprovação de plugin +do OpenClaw quando o Codex marca `_meta.codex_approval_kind` como `"mcp_tool_call"`. Prompts `request_user_input` do Codex são enviados de volta ao -chat de origem, e a próxima mensagem de acompanhamento na fila responde a essa requisição -nativa do servidor em vez de ser direcionada como contexto extra. Outras requisições de -solicitação MCP ainda falham de forma fechada. +chat de origem, e a próxima mensagem de acompanhamento enfileirada responde a essa solicitação de servidor +nativa em vez de ser direcionada como contexto extra. Outras solicitações de elicitação MCP +ainda falham fechadas. -O direcionamento da fila de execução ativa é mapeado para `turn/steer` do servidor de aplicativo do Codex. Com o -padrão `messages.queue.mode: "steer"`, o OpenClaw agrupa mensagens de chat na fila -pela janela de silêncio configurada e as envia como uma única requisição `turn/steer` na -ordem de chegada. O modo legado `queue` envia requisições `turn/steer` separadas. Turnos de -revisão do Codex e de Compaction manual podem rejeitar direcionamento no mesmo turno, caso em que +O direcionamento de fila de execução ativa mapeia para `turn/steer` do app-server do Codex. Com o +padrão `messages.queue.mode: "steer"`, o OpenClaw agrupa mensagens de chat enfileiradas +pela janela de silêncio configurada e as envia como uma solicitação `turn/steer` em +ordem de chegada. O modo legado `queue` envia solicitações `turn/steer` separadas. Turnos de +revisão e compaction manual do Codex podem rejeitar direcionamento no mesmo turno; nesse caso o OpenClaw usa a fila de acompanhamento quando o modo selecionado permite fallback. Consulte [Fila de direcionamento](/pt-BR/concepts/queue-steering). -Quando o modelo selecionado usa o harness do Codex, a Compaction de thread nativa é -delegada ao servidor de aplicativo do Codex. O OpenClaw mantém um espelho de transcrição para histórico +Quando o modelo selecionado usa o harness do Codex, a compaction de thread nativa é +delegada ao app-server do Codex. O OpenClaw mantém um espelho da transcrição para histórico do canal, busca, `/new`, `/reset` e futura troca de modelo ou harness. O espelho inclui o prompt do usuário, o texto final do assistente e registros leves de -raciocínio ou plano do Codex quando o servidor de aplicativo os emite. Hoje, o OpenClaw apenas -registra sinais de início e conclusão de Compaction nativa. Ele ainda não expõe um -resumo de Compaction legível por humanos nem uma lista auditável de quais entradas o Codex -manteve após a Compaction. +raciocínio ou plano do Codex quando o app-server os emite. Hoje, o OpenClaw apenas +registra sinais de início e conclusão de compaction nativa. Ele ainda não expõe um +resumo de compaction legível por humanos nem uma lista auditável de quais entradas o Codex +manteve após a compaction. -Como o Codex possui a thread nativa canônica, `tool_result_persist` atualmente não -reescreve registros de resultado de ferramenta nativa do Codex. Ele só se aplica quando -o OpenClaw está escrevendo um resultado de ferramenta em transcrição de sessão pertencente ao OpenClaw. +Como o Codex possui a thread nativa canônica, `tool_result_persist` não +reescreve atualmente registros de resultado de ferramentas nativas do Codex. Ele só se aplica quando +o OpenClaw está gravando um resultado de ferramenta de transcrição de sessão pertencente ao OpenClaw. -A geração de mídia não requer PI. Imagem, vídeo, música, PDF, TTS e entendimento de mídia -continuam usando as configurações correspondentes de provedor/modelo, como +A geração de mídia não requer PI. Imagem, vídeo, música, PDF, TTS e compreensão de mídia +continuam usando as configurações de provedor/modelo correspondentes, como `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` e `messages.tts`. @@ -963,14 +955,14 @@ novas configurações. Selecione um modelo `openai/gpt-*` com `codex`. **O OpenClaw usa PI em vez do Codex:** `agentRuntime.id: "auto"` ainda pode usar PI como o -backend de compatibilidade quando nenhum harness do Codex assume a execução. Defina -`agentRuntime.id: "codex"` para forçar a seleção do Codex durante testes. Um +backend de compatibilidade quando nenhum harness do Codex reivindica a execução. Defina +`agentRuntime.id: "codex"` para forçar a seleção do Codex durante os testes. Um runtime Codex forçado agora falha em vez de voltar para PI, a menos que você -defina explicitamente `agentRuntime.fallback: "pi"`. Depois que o servidor de aplicativo do Codex é +defina explicitamente `agentRuntime.fallback: "pi"`. Depois que o app-server do Codex é selecionado, suas falhas aparecem diretamente sem configuração extra de fallback. -**O servidor de aplicativo é rejeitado:** atualize o Codex para que o handshake do servidor de aplicativo -relate a versão `0.125.0` ou mais recente. Pré-lançamentos da mesma versão ou versões com sufixo +**O app-server é rejeitado:** atualize o Codex para que o handshake do app-server +informe a versão `0.125.0` ou mais recente. Pré-lançamentos da mesma versão ou versões com sufixo de build, como `0.125.0-alpha.2` ou `0.125.0+custom`, são rejeitados porque o piso de protocolo estável `0.125.0` é o que o OpenClaw testa. @@ -978,19 +970,19 @@ piso de protocolo estável `0.125.0` é o que o OpenClaw testa. ou desabilite a descoberta. **O transporte WebSocket falha imediatamente:** verifique `appServer.url`, `authToken` -e se o servidor de aplicativo remoto fala a mesma versão de protocolo do servidor de aplicativo do Codex. +e se o app-server remoto fala a mesma versão do protocolo de app-server do Codex. **Um modelo que não é Codex usa PI:** isso é esperado, a menos que você tenha forçado `agentRuntime.id: "codex"` para esse agente ou selecionado uma referência legada -`codex/*`. Referências simples `openai/gpt-*` e de outros provedores permanecem no caminho normal -do provedor em modo `auto`. Se você forçar `agentRuntime.id: "codex"`, todo turno embutido -desse agente deve ser um modelo OpenAI com suporte do Codex. +`codex/*`. Referências simples `openai/gpt-*` e de outros provedores permanecem em seu caminho normal +de provedor no modo `auto`. Se você forçar `agentRuntime.id: "codex"`, todo turno incorporado +desse agente deve ser um modelo OpenAI compatível com o Codex. -**Computer Use está instalado, mas as ferramentas não executam:** verifique -`/codex computer-use status` em uma sessão nova. Se uma ferramenta relatar +**Computer Use está instalado, mas as ferramentas não são executadas:** verifique +`/codex computer-use status` em uma sessão nova. Se uma ferramenta informar `Native hook relay unavailable`, use `/new` ou `/reset`; se persistir, reinicie -o Gateway para limpar registros obsoletos de hooks nativos. Se `computer-use.list_apps` -expirar, reinicie o Codex Computer Use ou o Codex Desktop e tente novamente. +o gateway para limpar registros obsoletos de hooks nativos. Se `computer-use.list_apps` +atingir tempo limite, reinicie o Codex Computer Use ou o Codex Desktop e tente novamente. ## Relacionados @@ -999,6 +991,6 @@ expirar, reinicie o Codex Computer Use ou o Codex Desktop e tente novamente. - [Provedores de modelo](/pt-BR/concepts/model-providers) - [Provedor OpenAI](/pt-BR/providers/openai) - [Status](/pt-BR/cli/status) -- [Hooks de Plugin](/pt-BR/plugins/hooks) +- [Hooks de plugin](/pt-BR/plugins/hooks) - [Referência de configuração](/pt-BR/gateway/configuration-reference) - [Testes](/pt-BR/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/pt-BR/plugins/google-meet.md b/docs/pt-BR/plugins/google-meet.md index a6b15ebfa..2f824d5a5 100644 --- a/docs/pt-BR/plugins/google-meet.md +++ b/docs/pt-BR/plugins/google-meet.md @@ -1,37 +1,38 @@ --- read_when: - - Você quer que um agente OpenClaw participe de uma chamada do Google Meet - - Você quer que um agente do OpenClaw crie uma nova chamada no Google Meet + - Você quer que um agente OpenClaw entre em uma chamada do Google Meet + - Você quer que um agente do OpenClaw crie uma nova chamada do Google Meet - Você está configurando o Chrome, o nó do Chrome ou o Twilio como transporte do Google Meet -summary: 'Plugin do Google Meet: entrar em URLs explícitas do Meet pelo Chrome ou Twilio com padrões de voz em tempo real' +summary: 'Plugin do Google Meet: entrar em URLs explícitas do Meet via Chrome ou Twilio com padrões de voz em tempo real' title: Plugin do Google Meet x-i18n: - generated_at: "2026-04-30T09:59:41Z" + generated_at: "2026-05-01T05:58:13Z" model: gpt-5.5 provider: openai - source_hash: 7b989c872fee0dca31680f67559cd26b715303f7c6f4eeda51fc63889bb0383c + source_hash: 6b7f5505dcc0ee20a5331f1e41206c8a4fd4090f317799d3f8af0018a067772f source_path: plugins/google-meet.md workflow: 16 --- -Suporte a participantes do Google Meet para OpenClaw — o Plugin é explícito por design: +O suporte a participantes do Google Meet para o OpenClaw é explícito por design: -- Ele entra apenas em uma URL explícita `https://meet.google.com/...`. -- Ele pode criar um novo espaço do Meet pela API do Google Meet e, então, entrar na +- Ele só entra em uma URL explícita `https://meet.google.com/...`. +- Ele pode criar um novo espaço do Meet pela API do Google Meet e então entrar na URL retornada. -- Voz `realtime` é o modo padrão. -- A voz em tempo real pode chamar de volta o agente OpenClaw completo quando raciocínio - mais profundo ou ferramentas forem necessários. -- Agentes escolhem o comportamento de entrada com `mode`: use `realtime` para ouvir - e responder ao vivo, ou `transcribe` para entrar/controlar o navegador sem a ponte - de voz em tempo real. -- A autenticação começa como OAuth pessoal do Google ou um perfil do Chrome já conectado. +- A voz `realtime` é o modo padrão. +- A voz em tempo real pode chamar de volta o agente completo do OpenClaw quando + raciocínio mais profundo ou ferramentas forem necessários. +- Os agentes escolhem o comportamento de entrada com `mode`: use `realtime` para + escuta/fala de retorno ao vivo, ou `transcribe` para entrar/controlar o + navegador sem a ponte de voz em tempo real. +- A autenticação começa como Google OAuth pessoal ou um perfil do Chrome já + conectado. - Não há anúncio automático de consentimento. - O backend de áudio padrão do Chrome é `BlackHole 2ch`. -- O Chrome pode rodar localmente ou em um host node pareado. -- O Twilio aceita um número de discagem mais PIN opcional ou sequência DTMF. -- O comando CLI é `googlemeet`; `meet` é reservado para fluxos de teleconferência - mais amplos de agentes. +- O Chrome pode executar localmente ou em um host de nó pareado. +- O Twilio aceita um número de discagem mais PIN ou sequência DTMF opcionais. +- O comando da CLI é `googlemeet`; `meet` fica reservado para fluxos de trabalho + mais amplos de teleconferência do agente. ## Início rápido @@ -47,20 +48,21 @@ export GEMINI_API_KEY=... ``` `blackhole-2ch` instala o dispositivo de áudio virtual `BlackHole 2ch`. O -instalador do Homebrew exige uma reinicialização antes que o macOS exponha o dispositivo: +instalador do Homebrew exige uma reinicialização antes que o macOS exponha o +dispositivo: ```bash sudo reboot ``` -Após reiniciar, verifique os dois componentes: +Após reiniciar, verifique as duas partes: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Habilite o Plugin: +Habilite o plugin: ```json5 { @@ -81,21 +83,34 @@ Verifique a configuração: openclaw googlemeet setup ``` -A saída da configuração foi feita para ser legível por agentes e ciente do modo. Ela informa o perfil do Chrome, -a fixação de node e, para entradas via Chrome em tempo real, a ponte de áudio -BlackHole/SoX e as verificações de introdução em tempo real atrasada. Para entradas somente de observação, verifique o mesmo -transporte com `--mode transcribe`; esse modo pula os pré-requisitos de áudio em tempo real +A saída da configuração foi feita para ser legível por agentes e ciente do modo. +Ela informa o perfil do Chrome, a fixação de nó e, para entradas pelo Chrome em +tempo real, a ponte de áudio BlackHole/SoX e verificações de introdução em tempo +real atrasadas. Para entradas somente observação, verifique o mesmo transporte +com `--mode transcribe`; esse modo pula os pré-requisitos de áudio em tempo real porque não escuta nem fala pela ponte: ```bash openclaw googlemeet setup --transport chrome-node --mode transcribe ``` -Quando a delegação do Twilio estiver configurada, a configuração também informa se o -Plugin `voice-call` e as credenciais do Twilio estão prontos. Trate qualquer verificação -`ok: false` como um bloqueador para o transporte e o modo verificados antes de pedir que um agente -entre. Use `openclaw googlemeet setup --json` para scripts ou saída legível por máquina. Use `--transport chrome`, `--transport chrome-node` ou `--transport twilio` -para pré-verificar um transporte específico antes que um agente tente usá-lo. +Quando a delegação do Twilio está configurada, a configuração também informa se +o plugin `voice-call`, as credenciais do Twilio e a exposição pública do Webhook +estão prontos. Trate qualquer verificação `ok: false` como um bloqueador para o +transporte e modo verificados antes de pedir que um agente entre. Use +`openclaw googlemeet setup --json` para scripts ou saída legível por máquina. +Use `--transport chrome`, `--transport chrome-node` ou `--transport twilio` para +pré-verificar um transporte específico antes que um agente tente usá-lo. + +Para Twilio, sempre pré-verifique o transporte explicitamente quando o transporte +padrão for Chrome: + +```bash +openclaw googlemeet setup --transport twilio +``` + +Isso detecta fiação ausente de `voice-call`, credenciais do Twilio ou exposição +de Webhook inacessível antes que o agente tente ligar para a reunião. Entre em uma reunião: @@ -128,27 +143,30 @@ openclaw googlemeet create --no-join `googlemeet create` tem dois caminhos: -- Criação via API: usada quando as credenciais OAuth do Google Meet estão configuradas. Este é - o caminho mais determinístico e não depende do estado da interface do navegador. -- Fallback do navegador: usado quando credenciais OAuth estão ausentes. O OpenClaw usa o - node Chrome fixado, abre `https://meet.google.com/new`, espera o Google - redirecionar para uma URL real com código de reunião e, então, retorna essa URL. Esse caminho exige - que o perfil do Chrome do OpenClaw no node já esteja conectado ao Google. - A automação do navegador lida com o próprio prompt de microfone de primeira execução do Meet; esse prompt - não é tratado como uma falha de login do Google. - Os fluxos de entrada e criação também tentam reutilizar uma aba existente do Meet antes de abrir uma - nova. A correspondência ignora strings de consulta de URL inofensivas, como `authuser`, então uma - nova tentativa do agente deve focar a reunião já aberta em vez de criar uma segunda - aba do Chrome. +- Criação via API: usada quando credenciais OAuth do Google Meet estão + configuradas. Este é o caminho mais determinístico e não depende do estado da + IU do navegador. +- Fallback pelo navegador: usado quando as credenciais OAuth estão ausentes. O + OpenClaw usa o nó Chrome fixado, abre `https://meet.google.com/new`, espera o + Google redirecionar para uma URL real com código de reunião e então retorna + essa URL. Esse caminho exige que o perfil do Chrome do OpenClaw no nó já esteja + conectado ao Google. + A automação do navegador lida com o próprio prompt de microfone de primeira + execução do Meet; esse prompt não é tratado como falha de login do Google. + Os fluxos de entrada e criação também tentam reutilizar uma aba existente do + Meet antes de abrir uma nova. A correspondência ignora strings de consulta + inofensivas de URL, como `authuser`, então uma nova tentativa do agente deve + focar a reunião já aberta em vez de criar uma segunda aba do Chrome. -A saída do comando/ferramenta inclui um campo `source` (`api` ou `browser`) para que agentes -possam explicar qual caminho foi usado. `create` entra na nova reunião por padrão e -retorna `joined: true` mais a sessão de entrada. Para apenas emitir a URL, use -`create --no-join` na CLI ou passe `"join": false` para a ferramenta. +A saída do comando/ferramenta inclui um campo `source` (`api` ou `browser`) para +que agentes possam explicar qual caminho foi usado. `create` entra na nova +reunião por padrão e retorna `joined: true` mais a sessão de entrada. Para apenas +emitir a URL, use `create --no-join` na CLI ou passe `"join": false` para a +ferramenta. -Ou diga a um agente: "Crie um Google Meet, entre nele com voz em tempo real e me envie -o link." O agente deve chamar `google_meet` com `action: "create"` e -então compartilhar o `meetingUri` retornado. +Ou diga a um agente: "Crie um Google Meet, entre nele com voz em tempo real e me +envie o link." O agente deve chamar `google_meet` com `action: "create"` e então +compartilhar o `meetingUri` retornado. ```json { @@ -158,45 +176,48 @@ então compartilhar o `meetingUri` retornado. } ``` -Para uma entrada somente de observação/controle do navegador, defina `"mode": "transcribe"`. Isso -não inicia a ponte duplex do modelo em tempo real, não exige BlackHole ou SoX -e não responderá falando na reunião. Entradas pelo Chrome nesse modo também evitam -a concessão de permissão de microfone/câmera do OpenClaw e evitam o caminho **Usar -microfone** do Meet. Se o Meet mostrar uma tela intermediária de escolha de áudio, a automação tenta -o caminho sem microfone e, caso contrário, informa uma ação manual em vez de abrir -o microfone local. +Para uma entrada somente observação/controle de navegador, defina +`"mode": "transcribe"`. Isso não inicia a ponte duplex do modelo em tempo real, +não exige BlackHole ou SoX e não responderá com fala na reunião. Entradas pelo +Chrome nesse modo também evitam a concessão de permissão de microfone/câmera do +OpenClaw e evitam o caminho **Use microphone** do Meet. Se o Meet mostrar uma +tela intermediária de escolha de áudio, a automação tenta o caminho sem +microfone e, caso contrário, relata uma ação manual em vez de abrir o microfone +local. -Durante sessões em tempo real, o status de `google_meet` inclui a integridade do navegador e da ponte de áudio, -como `inCall`, `manualActionRequired`, `providerConnected`, -`realtimeReady`, `audioInputActive`, `audioOutputActive`, últimos carimbos de data/hora de entrada/saída, -contadores de bytes e estado fechado da ponte. Se um prompt seguro da página do Meet -aparecer, a automação do navegador lida com ele quando consegue. Login, admissão pelo anfitrião e -prompts de permissão do navegador/SO são informados como ação manual com um motivo e -mensagem para o agente retransmitir. Sessões gerenciadas do Chrome só emitem a introdução ou -frase de teste depois que a integridade do navegador informa `inCall: true`; caso contrário, o status informa -`speechReady: false` e a tentativa de fala é bloqueada em vez de fingir que o -agente falou na reunião. +Durante sessões em tempo real, o status de `google_meet` inclui a integridade do +navegador e da ponte de áudio, como `inCall`, `manualActionRequired`, +`providerConnected`, `realtimeReady`, `audioInputActive`, `audioOutputActive`, +timestamps da última entrada/saída, contadores de bytes e estado fechado da +ponte. Se um prompt seguro da página do Meet aparecer, a automação do navegador +lida com ele quando consegue. Login, admissão pelo anfitrião e prompts de +permissão do navegador/SO são relatados como ação manual, com um motivo e uma +mensagem para o agente repassar. Sessões gerenciadas do Chrome só emitem a +introdução ou frase de teste depois que a integridade do navegador informa +`inCall: true`; caso contrário, o status informa `speechReady: false` e a +tentativa de fala é bloqueada em vez de fingir que o agente falou na reunião. -Entradas pelo Chrome local usam o perfil de navegador conectado do OpenClaw. O modo em tempo real -exige `BlackHole 2ch` para o caminho de microfone/alto-falante usado pelo OpenClaw. Para -áudio duplex limpo, use dispositivos virtuais separados ou um grafo no estilo Loopback; um -único dispositivo BlackHole é suficiente para um primeiro teste de fumaça, mas pode gerar eco. +Entradas pelo Chrome local usam o perfil de navegador conectado do OpenClaw. O +modo em tempo real exige `BlackHole 2ch` para o caminho de microfone/alto-falante +usado pelo OpenClaw. Para áudio duplex limpo, use dispositivos virtuais separados +ou um grafo no estilo Loopback; um único dispositivo BlackHole é suficiente para +um primeiro teste smoke, mas pode gerar eco. -### Gateway local + Chrome do Parallels +### Gateway local + Chrome no Parallels -Você **não** precisa de um Gateway OpenClaw completo nem de uma chave de API de modelo dentro de uma VM macOS -apenas para fazer a VM possuir o Chrome. Rode o Gateway e o agente localmente e, então, rode um -host node na VM. Habilite o Plugin integrado na VM uma vez para que o node -anuncie o comando do Chrome: +Você **não** precisa de um Gateway OpenClaw completo nem de uma chave de API de +modelo dentro de uma VM macOS só para fazer a VM possuir o Chrome. Execute o +Gateway e o agente localmente e então execute um host de nó na VM. Habilite uma +vez o plugin incluído na VM para que o nó anuncie o comando do Chrome: -O que roda onde: +O que executa onde: -- Host do Gateway: OpenClaw Gateway, workspace do agente, chaves de modelo/API, provedor em tempo real - e a configuração do Plugin Google Meet. -- VM macOS do Parallels: OpenClaw CLI/host node, Google Chrome, SoX, BlackHole 2ch - e um perfil do Chrome conectado ao Google. -- Não necessário na VM: serviço Gateway, configuração de agente, chave OpenAI/GPT ou configuração de - provedor de modelo. +- Host do Gateway: Gateway OpenClaw, workspace do agente, chaves de modelo/API, + provedor em tempo real e configuração do plugin Google Meet. +- VM macOS do Parallels: CLI/host de nó do OpenClaw, Google Chrome, SoX, + BlackHole 2ch e um perfil do Chrome conectado ao Google. +- Não necessário na VM: serviço Gateway, configuração de agente, chave + OpenAI/GPT ou configuração de provedor de modelo. Instale as dependências da VM: @@ -204,40 +225,43 @@ Instale as dependências da VM: brew install blackhole-2ch sox ``` -Reinicie a VM após instalar o BlackHole para que o macOS exponha `BlackHole 2ch`: +Reinicie a VM após instalar o BlackHole para que o macOS exponha +`BlackHole 2ch`: ```bash sudo reboot ``` -Após reiniciar, verifique se a VM consegue ver o dispositivo de áudio e os comandos do SoX: +Após reiniciar, verifique se a VM consegue ver o dispositivo de áudio e os +comandos SoX: ```bash system_profiler SPAudioDataType | grep -i BlackHole command -v sox ``` -Instale ou atualize o OpenClaw na VM e, então, habilite o Plugin integrado nela: +Instale ou atualize o OpenClaw na VM e então habilite o plugin incluído ali: ```bash openclaw plugins enable google-meet ``` -Inicie o host node na VM: +Inicie o host de nó na VM: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -Se `` for um IP de LAN e você não estiver usando TLS, o node recusará o -WebSocket em texto puro a menos que você opte por isso para essa rede privada confiável: +Se `` for um IP de LAN e você não estiver usando TLS, o nó recusa o +WebSocket em texto claro a menos que você aceite explicitamente essa rede privada +confiável: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Use a mesma variável de ambiente ao instalar o node como um LaunchAgent: +Use a mesma variável de ambiente ao instalar o nó como LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -245,25 +269,25 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` é ambiente de processo, não uma configuração de -`openclaw.json`. `openclaw node install` a armazena no ambiente do LaunchAgent -quando ela está presente no comando de instalação. +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` é ambiente do processo, não uma +configuração de `openclaw.json`. `openclaw node install` a armazena no ambiente +do LaunchAgent quando ela está presente no comando de instalação. -Aprove o node a partir do host do Gateway: +Aprove o nó a partir do host do Gateway: ```bash openclaw devices list openclaw devices approve ``` -Confirme que o Gateway vê o node e que ele anuncia tanto `googlemeet.chrome` -quanto a capacidade do navegador/`browser.proxy`: +Confirme que o Gateway vê o nó e que ele anuncia tanto `googlemeet.chrome` quanto +a capacidade de navegador/`browser.proxy`: ```bash openclaw nodes status ``` -Roteie o Meet por esse node no host do Gateway: +Encaminhe o Meet por esse nó no host do Gateway: ```json5 { @@ -299,91 +323,94 @@ Agora entre normalmente a partir do host do Gateway: openclaw googlemeet join https://meet.google.com/abc-defg-hij ``` -ou peça ao agente para usar a ferramenta `google_meet` com `transport: "chrome-node"`. +ou peça ao agente para usar a ferramenta `google_meet` com +`transport: "chrome-node"`. -Para um teste de fumaça de um comando que cria ou reutiliza uma sessão, fala uma frase -conhecida e imprime a integridade da sessão: +Para um teste smoke de um comando que cria ou reutiliza uma sessão, fala uma +frase conhecida e imprime a integridade da sessão: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Durante a entrada em tempo real, a automação de navegador do OpenClaw preenche o nome de convidado, clica em -Entrar/Pedir para entrar e aceita a escolha "Usar microfone" de primeira execução do Meet quando esse -prompt aparece. Durante entrada somente de observação ou criação de reunião somente pelo navegador, ela -continua além do mesmo prompt sem microfone quando essa escolha está disponível. -Se o perfil do navegador não estiver conectado, o Meet estiver aguardando admissão do anfitrião, -o Chrome precisar de permissão de microfone/câmera para uma entrada em tempo real, ou o Meet estiver preso -em um prompt que a automação não conseguiu resolver, o resultado de entrada/test-speech informa -`manualActionRequired: true` com `manualActionReason` e -`manualActionMessage`. Agentes devem parar de tentar entrar novamente, relatar essa -mensagem exata mais o `browserUrl`/`browserTitle` atual e tentar novamente apenas depois que a -ação manual no navegador estiver concluída. +Durante a entrada em tempo real, a automação de navegador do OpenClaw preenche o +nome de convidado, clica em Entrar/Solicitar entrada e aceita a escolha de +primeira execução "Use microphone" do Meet quando esse prompt aparece. Durante +entrada somente observação ou criação de reunião somente pelo navegador, ela +continua pelo mesmo prompt sem microfone quando essa escolha está disponível. Se +o perfil do navegador não estiver conectado, o Meet estiver aguardando admissão +pelo anfitrião, o Chrome precisar de permissão de microfone/câmera para uma +entrada em tempo real ou o Meet estiver preso em um prompt que a automação não +conseguiu resolver, o resultado de join/test-speech informa +`manualActionRequired: true` com `manualActionReason` e `manualActionMessage`. +Os agentes devem parar de tentar novamente a entrada, relatar essa mensagem +exata mais o `browserUrl`/`browserTitle` atual, e tentar novamente somente depois +que a ação manual no navegador estiver concluída. -Se `chromeNode.node` for omitido, o OpenClaw seleciona automaticamente apenas quando exatamente um -node conectado anuncia tanto `googlemeet.chrome` quanto controle do navegador. Se -vários nodes capazes estiverem conectados, defina `chromeNode.node` como o id do node, -nome de exibição ou IP remoto. +Se `chromeNode.node` for omitido, o OpenClaw seleciona automaticamente somente +quando exatamente um nó conectado anuncia tanto `googlemeet.chrome` quanto +controle de navegador. Se vários nós compatíveis estiverem conectados, defina +`chromeNode.node` como o ID do nó, nome de exibição ou IP remoto. Verificações comuns de falha: -- `Configured Google Meet node ... is not usable: offline`: o nó fixado é - conhecido pelo Gateway, mas está indisponível. Os agentes devem tratar esse nó - como estado de diagnóstico, não como um host Chrome utilizável, e relatar o - bloqueador de configuração em vez de recorrer a outro transporte, a menos que +- `Configured Google Meet node ... is not usable: offline`: o Node fixado é + conhecido pelo Gateway, mas está indisponível. Os agentes devem tratar esse + Node como estado de diagnóstico, não como um host Chrome utilizável, e relatar + o bloqueio de configuração em vez de recorrer a outro transporte, a menos que o usuário tenha pedido isso. - `No connected Google Meet-capable node`: inicie `openclaw node run` na VM, - aprove o pareamento e confirme que `openclaw plugins enable google-meet` e - `openclaw plugins enable browser` foram executados na VM. Confirme também que - o host do Gateway permite ambos os comandos de nó com + aprove o pareamento e garanta que `openclaw plugins enable google-meet` e + `openclaw plugins enable browser` tenham sido executados na VM. Confirme + também que o host do Gateway permite ambos os comandos de Node com `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. - `BlackHole 2ch audio device not found`: instale `blackhole-2ch` no host que está sendo verificado e reinicie antes de usar áudio local do Chrome. - `BlackHole 2ch audio device not found on the node`: instale `blackhole-2ch` na VM e reinicie a VM. -- O Chrome abre, mas não consegue entrar: faça login no perfil do navegador dentro - da VM, ou mantenha `chrome.guestName` definido para entrada como convidado. A - entrada automática como convidado usa a automação de navegador do OpenClaw por - meio do proxy de navegador do nó; confirme que a configuração de navegador do - nó aponta para o perfil desejado, por exemplo +- O Chrome abre, mas não consegue entrar: faça login no perfil do navegador + dentro da VM ou mantenha `chrome.guestName` definido para entrada como + convidado. A entrada automática como convidado usa a automação de navegador do + OpenClaw pelo proxy de navegador do Node; garanta que a configuração de + navegador do Node aponte para o perfil desejado, por exemplo `browser.defaultProfile: "user"` ou um perfil de sessão existente nomeado. -- Abas duplicadas do Meet: mantenha `chrome.reuseExistingTab: true` ativado. O - OpenClaw ativa uma aba existente para a mesma URL do Meet antes de abrir uma +- Abas duplicadas do Meet: mantenha `chrome.reuseExistingTab: true` habilitado. + O OpenClaw ativa uma aba existente para a mesma URL do Meet antes de abrir uma nova, e a criação de reunião pelo navegador reutiliza uma aba em andamento de `https://meet.google.com/new` ou de solicitação de conta Google antes de abrir outra. -- Sem áudio: no Meet, direcione o microfone/alto-falante pelo caminho de - dispositivo de áudio virtual usado pelo OpenClaw; use dispositivos virtuais - separados ou roteamento estilo Loopback para áudio duplex limpo. +- Sem áudio: no Meet, roteie microfone/alto-falante pelo caminho do dispositivo + de áudio virtual usado pelo OpenClaw; use dispositivos virtuais separados ou + roteamento no estilo Loopback para áudio duplex limpo. ## Notas de instalação O padrão em tempo real do Chrome usa duas ferramentas externas: -- `sox`: utilitário de áudio de linha de comando. O plugin usa comandos +- `sox`: utilitário de áudio de linha de comando. O Plugin usa comandos explícitos de dispositivo CoreAudio para a ponte de áudio PCM16 padrão de 24 kHz. - `blackhole-2ch`: driver de áudio virtual do macOS. Ele cria o dispositivo de áudio `BlackHole 2ch` pelo qual o Chrome/Meet pode rotear. -O OpenClaw não empacota nem redistribui nenhum dos pacotes. A documentação pede -que os usuários os instalem como dependências do host via Homebrew. SoX é -licenciado como `LGPL-2.0-only AND GPL-2.0-only`; BlackHole é GPL-3.0. Se você -criar um instalador ou appliance que empacote BlackHole com OpenClaw, revise os -termos de licenciamento upstream do BlackHole ou obtenha uma licença separada da -Existential Audio. +O OpenClaw não inclui nem redistribui nenhum desses pacotes. A documentação pede +que os usuários os instalem como dependências do host pelo Homebrew. O SoX é +licenciado como `LGPL-2.0-only AND GPL-2.0-only`; o BlackHole é GPL-3.0. Se você +criar um instalador ou appliance que inclua o BlackHole com o OpenClaw, revise +os termos de licenciamento upstream do BlackHole ou obtenha uma licença separada +da Existential Audio. ## Transportes ### Chrome -O transporte Chrome abre a URL do Meet por meio do controle de navegador do -OpenClaw e entra como o perfil de navegador OpenClaw autenticado. No macOS, o -plugin verifica `BlackHole 2ch` antes de iniciar. Se configurado, ele também +O transporte Chrome abre a URL do Meet pelo controle de navegador do OpenClaw e +entra como o perfil de navegador OpenClaw autenticado. No macOS, o Plugin +verifica `BlackHole 2ch` antes da inicialização. Se configurado, ele também executa um comando de integridade da ponte de áudio e um comando de inicialização antes de abrir o Chrome. Use `chrome` quando Chrome/áudio estiverem no host do -Gateway; use `chrome-node` quando Chrome/áudio estiverem em um nó pareado, como -uma VM macOS do Parallels. Para Chrome local, escolha o perfil com +Gateway; use `chrome-node` quando Chrome/áudio estiverem em um Node pareado, +como uma VM Parallels macOS. Para Chrome local, escolha o perfil com `browser.defaultProfile`; `chrome.browserProfile` é passado para hosts `chrome-node`. @@ -392,21 +419,21 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Direcione o áudio do microfone e do alto-falante do Chrome pela ponte de áudio -local do OpenClaw. Se `BlackHole 2ch` não estiver instalado, a entrada falha com -um erro de configuração em vez de entrar silenciosamente sem um caminho de áudio. +Roteie o áudio do microfone e do alto-falante do Chrome pela ponte de áudio local +do OpenClaw. Se `BlackHole 2ch` não estiver instalado, a entrada falha com um +erro de configuração em vez de entrar silenciosamente sem um caminho de áudio. ### Twilio -O transporte Twilio é um plano de discagem estrito delegado ao plugin Voice +O transporte Twilio é um plano de discagem estrito delegado ao Plugin Voice Call. Ele não analisa páginas do Meet em busca de números de telefone. -Use isto quando a participação pelo Chrome não estiver disponível ou quando você +Use isso quando a participação pelo Chrome não estiver disponível ou quando você quiser um fallback de discagem telefônica. O Google Meet deve expor um número de -discagem telefônica e PIN para a reunião; o OpenClaw não descobre esses dados a -partir da página do Meet. +discagem telefônica e um PIN para a reunião; o OpenClaw não descobre esses dados +pela página do Meet. -Ative o plugin Voice Call no host do Gateway, não no nó Chrome: +Habilite o Plugin Voice Call no host do Gateway, não no Node do Chrome: ```json5 { @@ -431,8 +458,8 @@ Ative o plugin Voice Call no host do Gateway, não no nó Chrome: } ``` -Forneça credenciais do Twilio por ambiente ou configuração. O ambiente mantém -segredos fora de `openclaw.json`: +Forneça credenciais da Twilio pelo ambiente ou pela configuração. O ambiente +mantém segredos fora de `openclaw.json`: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -440,11 +467,11 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -Reinicie ou recarregue o Gateway após ativar `voice-call`; alterações de -configuração de plugin não aparecem em um processo do Gateway já em execução até +Reinicie ou recarregue o Gateway depois de habilitar `voice-call`; alterações de +configuração de Plugin não aparecem em um processo do Gateway já em execução até que ele seja recarregado. -Então verifique: +Depois verifique: ```bash openclaw config validate @@ -452,9 +479,9 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Quando a delegação Twilio está conectada, `googlemeet setup` inclui verificações -bem-sucedidas de `twilio-voice-call-plugin` e -`twilio-voice-call-credentials`. +Quando a delegação da Twilio estiver conectada, `googlemeet setup` inclui +verificações bem-sucedidas de `twilio-voice-call-plugin`, +`twilio-voice-call-credentials` e `twilio-voice-call-webhook`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -472,42 +499,40 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -## OAuth e pré-verificação +## OAuth e preflight OAuth é opcional para criar um link do Meet porque `googlemeet create` pode recorrer à automação de navegador. Configure OAuth quando quiser criação pela -API oficial, resolução de espaços ou verificações de pré-verificação da Meet -Media API. +API oficial, resolução de espaços ou verificações de preflight da Meet Media API. -O acesso à Google Meet API usa OAuth de usuário: crie um cliente OAuth do Google -Cloud, solicite os escopos necessários, autorize uma conta Google e então armazene -o refresh token resultante na configuração do plugin Google Meet ou forneça as -variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*`. +O acesso à API do Google Meet usa OAuth de usuário: crie um cliente OAuth no +Google Cloud, solicite os escopos necessários, autorize uma conta Google e então +armazene o token de atualização resultante na configuração do Plugin Google Meet +ou forneça as variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*`. OAuth não substitui o caminho de entrada pelo Chrome. Os transportes Chrome e -Chrome-node ainda entram por meio de um perfil Chrome autenticado, -BlackHole/SoX e um nó conectado quando você usa participação pelo navegador. -OAuth serve apenas para o caminho oficial da Google Meet API: criar espaços de -reunião, resolver espaços e executar verificações de pré-verificação da Meet -Media API. +Chrome-node ainda entram por um perfil Chrome autenticado, BlackHole/SoX e um +Node conectado quando você usa participação pelo navegador. OAuth serve apenas +para o caminho oficial da API do Google Meet: criar espaços de reunião, resolver +espaços e executar verificações de preflight da Meet Media API. ### Criar credenciais do Google No Google Cloud Console: 1. Crie ou selecione um projeto do Google Cloud. -2. Ative a **Google Meet REST API** para esse projeto. +2. Habilite a **Google Meet REST API** para esse projeto. 3. Configure a tela de consentimento OAuth. - - **Internal** é o mais simples para uma organização do Google Workspace. + - **Internal** é mais simples para uma organização do Google Workspace. - **External** funciona para configurações pessoais/de teste; enquanto o app - estiver em Testing, adicione como usuário de teste cada conta Google que - autorizará o app. + estiver em Testing, adicione cada conta Google que autorizará o app como + usuário de teste. 4. Adicione os escopos solicitados pelo OpenClaw: - `https://www.googleapis.com/auth/meetings.space.created` - `https://www.googleapis.com/auth/meetings.space.readonly` - `https://www.googleapis.com/auth/meetings.conference.media.readonly` 5. Crie um ID de cliente OAuth. - - Tipo de aplicação: **Web application**. + - Tipo de aplicativo: **Web application**. - URI de redirecionamento autorizado: ```text @@ -518,23 +543,23 @@ No Google Cloud Console: `meetings.space.created` é exigido por Google Meet `spaces.create`. `meetings.space.readonly` permite que o OpenClaw resolva URLs/códigos do Meet em -espaços. `meetings.conference.media.readonly` é para pré-verificação e trabalho -de mídia da Meet Media API; o Google pode exigir inscrição no Developer Preview -para uso real da Media API. Se você precisa apenas de entradas pelo Chrome com -base no navegador, ignore OAuth totalmente. +espaços. `meetings.conference.media.readonly` é para preflight da Meet Media API +e trabalho de mídia; o Google pode exigir inscrição no Developer Preview para o +uso real da Media API. Se você só precisa de entradas pelo Chrome baseadas em +navegador, ignore OAuth por completo. -### Emitir o refresh token +### Emitir o token de atualização Configure `oauth.clientId` e, opcionalmente, `oauth.clientSecret`, ou passe-os -como variáveis de ambiente, então execute: +como variáveis de ambiente, e então execute: ```bash openclaw googlemeet auth login --json ``` -O comando imprime um bloco de configuração `oauth` com um refresh token. Ele usa -PKCE, callback localhost em `http://localhost:8085/oauth2callback` e um fluxo -manual de copiar/colar com `--manual`. +O comando imprime um bloco de configuração `oauth` com um token de atualização. +Ele usa PKCE, callback localhost em `http://localhost:8085/oauth2callback` e um +fluxo manual de copiar/colar com `--manual`. Exemplos: @@ -544,7 +569,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ openclaw googlemeet auth login --json ``` -Use o modo manual quando o navegador não puder acessar o callback local: +Use o modo manual quando o navegador não conseguir acessar o callback local: ```bash OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ @@ -567,7 +592,7 @@ A saída JSON inclui: } ``` -Armazene o objeto `oauth` na configuração do plugin Google Meet: +Armazene o objeto `oauth` na configuração do Plugin Google Meet: ```json5 { @@ -588,15 +613,15 @@ Armazene o objeto `oauth` na configuração do plugin Google Meet: } ``` -Prefira variáveis de ambiente quando não quiser o refresh token na configuração. -Se valores de configuração e de ambiente estiverem presentes, o plugin resolve -primeiro a configuração e depois o fallback de ambiente. +Prefira variáveis de ambiente quando não quiser o token de atualização na +configuração. Se valores de configuração e de ambiente estiverem presentes, o +Plugin resolve primeiro a configuração e depois usa o ambiente como fallback. O consentimento OAuth inclui criação de espaço do Meet, acesso de leitura a -espaço do Meet e acesso de leitura a mídia de conferência do Meet. Se você se +espaço do Meet e acesso de leitura à mídia de conferência do Meet. Se você se autenticou antes de existir suporte à criação de reuniões, execute novamente -`openclaw googlemeet auth login --json` para que o refresh token tenha o escopo -`meetings.space.created`. +`openclaw googlemeet auth login --json` para que o token de atualização tenha o +escopo `meetings.space.created`. ### Verificar OAuth com doctor @@ -607,51 +632,51 @@ sem segredos: openclaw googlemeet doctor --oauth --json ``` -Isso não carrega o runtime do Chrome nem exige um nó Chrome conectado. Ele -verifica se a configuração OAuth existe e se o refresh token consegue emitir um -access token. O relatório JSON inclui apenas campos de status como `ok`, -`configured`, `tokenSource`, `expiresAt` e mensagens de verificação; ele não -imprime o access token, o refresh token nem o segredo do cliente. +Isso não carrega o runtime do Chrome nem exige um Node do Chrome conectado. Ele +verifica se a configuração OAuth existe e se o token de atualização consegue +emitir um token de acesso. O relatório JSON inclui apenas campos de status como +`ok`, `configured`, `tokenSource`, `expiresAt` e mensagens de verificação; ele +não imprime o token de acesso, o token de atualização nem o segredo do cliente. Resultados comuns: | Verificação | Significado | | -------------------- | -------------------------------------------------------------------------------------- | -| `oauth-config` | `oauth.clientId` mais `oauth.refreshToken`, ou um access token em cache, está presente. | -| `oauth-token` | O access token em cache ainda é válido, ou o refresh token emitiu um novo access token. | -| `meet-spaces-get` | A verificação opcional `--meeting` resolveu um espaço do Meet existente. | -| `meet-spaces-create` | A verificação opcional `--create-space` criou um novo espaço do Meet. | +| `oauth-config` | `oauth.clientId` mais `oauth.refreshToken`, ou um token de acesso em cache, está presente. | +| `oauth-token` | O token de acesso em cache ainda é válido, ou o token de atualização emitiu um novo token de acesso. | +| `meet-spaces-get` | A verificação opcional `--meeting` resolveu um espaço do Meet existente. | +| `meet-spaces-create` | A verificação opcional `--create-space` criou um novo espaço do Meet. | -Para provar também a ativação da Google Meet API e o escopo `spaces.create`, -execute a verificação de criação com efeito colateral: +Para comprovar também a habilitação da Google Meet API e o escopo +`spaces.create`, execute a verificação de criação com efeito colateral: ```bash openclaw googlemeet doctor --oauth --create-space --json openclaw googlemeet create --no-join --json ``` -`--create-space` cria uma URL descartável do Meet. Use quando precisar confirmar -que o projeto do Google Cloud tem a Meet API ativada e que a conta autorizada tem -o escopo `meetings.space.created`. +`--create-space` cria uma URL descartável do Meet. Use isso quando precisar +confirmar que o projeto do Google Cloud tem a API do Meet habilitada e que a +conta autorizada tem o escopo `meetings.space.created`. -Para provar acesso de leitura a um espaço de reunião existente: +Para comprovar acesso de leitura a um espaço de reunião existente: ```bash openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -`doctor --oauth --meeting` e `resolve-space` provam acesso de leitura a um espaço -existente que a conta Google autorizada consegue acessar. Um `403` dessas -verificações geralmente significa que a Google Meet REST API está desativada, que -o refresh token consentido não tem o escopo necessário, ou que a conta Google não -consegue acessar esse espaço do Meet. Um erro de refresh-token significa executar -novamente `openclaw googlemeet auth login --json` e armazenar o novo bloco -`oauth`. +`doctor --oauth --meeting` e `resolve-space` comprovam acesso de leitura a um +espaço existente que a conta Google autorizada consegue acessar. Um `403` nessas +verificações geralmente significa que a Google Meet REST API está desabilitada, +que o token de atualização consentido não tem o escopo necessário ou que a conta +Google não consegue acessar esse espaço do Meet. Um erro de token de atualização +significa executar novamente `openclaw googlemeet auth login --json` e armazenar +o novo bloco `oauth`. -Nenhuma credencial OAuth é necessária para o fallback de navegador. Nesse modo, a -autenticação Google vem do perfil Chrome autenticado no nó selecionado, não da -configuração do OpenClaw. +Nenhuma credencial OAuth é necessária para o fallback de navegador. Nesse modo, +a autenticação do Google vem do perfil Chrome autenticado no Node selecionado, +não da configuração do OpenClaw. Estas variáveis de ambiente são aceitas como fallbacks: @@ -664,13 +689,13 @@ Estas variáveis de ambiente são aceitas como fallbacks: - `OPENCLAW_GOOGLE_MEET_DEFAULT_MEETING` ou `GOOGLE_MEET_DEFAULT_MEETING` - `OPENCLAW_GOOGLE_MEET_PREVIEW_ACK` ou `GOOGLE_MEET_PREVIEW_ACK` -Resolva uma URL, um código ou `spaces/{id}` do Meet por meio de `spaces.get`: +Resolva uma URL do Meet, código ou `spaces/{id}` por meio de `spaces.get`: ```bash openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Execute o preflight antes do trabalho de mídia: +Execute a verificação prévia antes do trabalho de mídia: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij @@ -689,7 +714,7 @@ por padrão. Passe `--all-conference-records` quando quiser todos os registros r para essa reunião. A consulta ao Calendar pode resolver a URL da reunião pelo Google Calendar antes de ler -os artefatos do Meet: +artefatos do Meet: ```bash openclaw googlemeet latest --today @@ -698,14 +723,14 @@ openclaw googlemeet artifacts --event "Weekly sync" openclaw googlemeet attendance --today --format csv --output attendance.csv ``` -`--today` pesquisa o calendário `primary` de hoje por um evento do Calendar com um +`--today` pesquisa o calendário `primary` de hoje em busca de um evento do Calendar com um link do Google Meet. Use `--event ` para pesquisar texto de evento correspondente e `--calendar ` para um calendário não primário. A consulta ao Calendar exige um novo login OAuth que inclua o escopo somente leitura de eventos do Calendar. `calendar-events` pré-visualiza os eventos do Meet correspondentes e marca o evento que `latest`, `artifacts`, `attendance` ou `export` escolherá. -Se você já souber o ID do registro de conferência, enderece-o diretamente: +Se você já souber o id do registro de conferência, acesse-o diretamente: ```bash openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij @@ -729,30 +754,30 @@ openclaw googlemeet export --conference-record conferenceRecords/abc123 \ ``` `artifacts` retorna metadados do registro de conferência mais metadados de recursos de -participantes, gravações, transcrições, entradas de transcrição estruturadas e notas -inteligentes quando o Google os expõe para a reunião. Use `--no-transcript-entries` para pular +participante, gravação, transcrição, entrada de transcrição estruturada e notas inteligentes quando +o Google os expõe para a reunião. Use `--no-transcript-entries` para ignorar a consulta de entradas em reuniões grandes. `attendance` expande participantes em -linhas de sessão de participante com horários da primeira/última visualização, duração total da sessão, +linhas de sessão de participante com horários de primeira/última visualização, duração total da sessão, sinalizadores de atraso/saída antecipada e recursos de participantes duplicados mesclados por usuário -conectado ou nome de exibição. Passe `--no-merge-duplicates` para manter recursos de -participantes brutos separados, `--late-after-minutes` para ajustar a detecção de atraso e +conectado ou nome de exibição. Passe `--no-merge-duplicates` para manter recursos brutos de participante +separados, `--late-after-minutes` para ajustar a detecção de atraso e `--early-before-minutes` para ajustar a detecção de saída antecipada. `export` grava uma pasta contendo `summary.md`, `attendance.csv`, `transcript.md`, `artifacts.json`, `attendance.json` e `manifest.json`. `manifest.json` registra a entrada escolhida, opções de exportação, registros de conferência, -arquivos de saída, contagens, fonte de token, evento do Calendar quando usado e quaisquer +arquivos de saída, contagens, origem do token, evento do Calendar quando usado e quaisquer avisos de recuperação parcial. Passe `--zip` para também gravar um arquivo portátil ao lado -da pasta. Passe `--include-doc-bodies` para exportar o texto de Google Docs vinculados de transcrição e +da pasta. Passe `--include-doc-bodies` para exportar o texto de Google Docs de transcrição vinculada e notas inteligentes por meio de `files.export` do Google Drive; isso exige um novo login OAuth que inclua o escopo somente leitura do Drive Meet. Sem `--include-doc-bodies`, as exportações incluem apenas metadados do Meet e entradas de transcrição -estruturadas. Se o Google retornar uma falha parcial de artefato, como erro de listagem de notas -inteligentes, entrada de transcrição ou corpo de documento do Drive, o resumo e o +estruturadas. Se o Google retornar uma falha parcial de artefato, como um erro de listagem de notas inteligentes, +entrada de transcrição ou corpo de documento do Drive, o resumo e o manifesto mantêm o aviso em vez de falhar a exportação inteira. Use `--dry-run` para buscar os mesmos dados de artefatos/presença e imprimir o JSON do manifesto sem criar a pasta ou o ZIP. Isso é útil antes de gravar -uma exportação grande ou quando um agente só precisa de contagens, registros selecionados e +uma exportação grande ou quando um agente precisa apenas de contagens, registros selecionados e avisos. Agentes também podem criar o mesmo pacote por meio da ferramenta `google_meet`: @@ -767,9 +792,9 @@ Agentes também podem criar o mesmo pacote por meio da ferramenta `google_meet`: } ``` -Defina `"dryRun": true` para retornar apenas o manifesto de exportação e pular gravações de arquivo. +Defina `"dryRun": true` para retornar apenas o manifesto de exportação e ignorar gravações de arquivos. -Execute o smoke live protegido contra uma reunião real retida: +Execute o smoke ao vivo protegido contra uma reunião real retida: ```bash OPENCLAW_LIVE_TEST=1 \ @@ -777,13 +802,12 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \ pnpm test:live -- extensions/google-meet/google-meet.live.test.ts ``` -Ambiente de smoke live: +Ambiente do smoke ao vivo: -- `OPENCLAW_LIVE_TEST=1` habilita testes live protegidos. -- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` aponta para uma URL, código ou - `spaces/{id}` retido do Meet. -- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` ou `GOOGLE_MEET_CLIENT_ID` fornece o ID do cliente - OAuth. +- `OPENCLAW_LIVE_TEST=1` habilita testes ao vivo protegidos. +- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` aponta para uma URL do Meet retida, código ou + `spaces/{id}`. +- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` ou `GOOGLE_MEET_CLIENT_ID` fornece o id de cliente OAuth. - `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` ou `GOOGLE_MEET_REFRESH_TOKEN` fornece o token de atualização. - Opcional: `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`, @@ -791,11 +815,11 @@ Ambiente de smoke live: `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` usam os mesmos nomes de fallback sem o prefixo `OPENCLAW_`. -O smoke live básico de artefatos/presença precisa de +O smoke ao vivo básico de artefatos/presença precisa de `https://www.googleapis.com/auth/meetings.space.readonly` e `https://www.googleapis.com/auth/meetings.conference.media.readonly`. A consulta ao Calendar -precisa de `https://www.googleapis.com/auth/calendar.events.readonly`. A exportação do -corpo de documento do Drive precisa de +precisa de `https://www.googleapis.com/auth/calendar.events.readonly`. A exportação do corpo de documento do Drive +precisa de `https://www.googleapis.com/auth/drive.meet.readonly`. Crie um novo espaço do Meet: @@ -804,11 +828,11 @@ Crie um novo espaço do Meet: openclaw googlemeet create ``` -O comando imprime o novo `meeting uri`, a fonte e a sessão de entrada. Com credenciais -OAuth, ele usa a API oficial do Google Meet. Sem credenciais OAuth, ele -usa como fallback o perfil de navegador conectado do Node do Chrome fixado. Agentes podem +O comando imprime o novo `meeting uri`, a origem e a sessão de entrada. Com credenciais OAuth, +ele usa a API oficial do Google Meet. Sem credenciais OAuth, ele +usa o perfil de navegador conectado do nó Chrome fixado como fallback. Agentes podem usar a ferramenta `google_meet` com `action: "create"` para criar e entrar em uma única -etapa. Para criação apenas por URL, passe `"join": false`. +etapa. Para criação apenas de URL, passe `"join": false`. Exemplo de saída JSON do fallback do navegador: @@ -830,8 +854,8 @@ Exemplo de saída JSON do fallback do navegador: } ``` -Se o fallback do navegador encontrar login do Google ou um bloqueio de permissão do Meet antes que -consiga criar a URL, o método do Gateway retornará uma resposta com falha e a +Se o fallback do navegador encontrar login do Google ou um bloqueador de permissão do Meet antes de +conseguir criar a URL, o método do Gateway retornará uma resposta com falha e a ferramenta `google_meet` retornará detalhes estruturados em vez de uma string simples: ```json @@ -850,11 +874,11 @@ ferramenta `google_meet` retornará detalhes estruturados em vez de uma string s } ``` -Quando um agente vê `manualActionRequired: true`, ele deve informar a -`manualActionMessage` mais o contexto de Node/aba do navegador e parar de abrir novas +Quando um agente vê `manualActionRequired: true`, ele deve relatar a +`manualActionMessage` mais o contexto de nó/aba do navegador e parar de abrir novas abas do Meet até que o operador conclua a etapa no navegador. -Exemplo de saída JSON da criação por API: +Exemplo de saída JSON da criação pela API: ```json { @@ -875,19 +899,19 @@ Exemplo de saída JSON da criação por API: } ``` -Criar um Meet entra por padrão. O transporte do Chrome ou do Node do Chrome ainda -precisa de um perfil conectado do Google Chrome para entrar pelo navegador. Se o -perfil estiver desconectado, o OpenClaw informa `manualActionRequired: true` ou um -erro de fallback do navegador e pede ao operador para concluir o login do Google antes de -tentar novamente. +Criar um Meet entra por padrão. O transporte Chrome ou Chrome-node ainda +precisa de um perfil do Google Chrome conectado para entrar pelo navegador. Se o +perfil estiver desconectado, o OpenClaw relata `manualActionRequired: true` ou um +erro de fallback do navegador e pede ao operador para concluir o login do Google antes +de tentar novamente. -Defina `preview.enrollmentAcknowledged: true` somente depois de confirmar que seu projeto do Cloud, +Defina `preview.enrollmentAcknowledged: true` somente depois de confirmar que seu projeto Cloud, principal OAuth e participantes da reunião estão inscritos no Google Workspace Developer Preview Program para APIs de mídia do Meet. ## Configuração -O caminho comum em tempo real do Chrome só precisa do plugin habilitado, BlackHole, SoX +O caminho comum de tempo real do Chrome precisa apenas do Plugin habilitado, BlackHole, SoX e uma chave de provedor de voz em tempo real de backend. OpenAI é o padrão; defina `realtime.provider: "google"` para usar o Google Gemini Live: @@ -898,7 +922,7 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -Defina a configuração do plugin em `plugins.entries.google-meet.config`: +Defina a configuração do Plugin em `plugins.entries.google-meet.config`: ```json5 { @@ -917,29 +941,29 @@ Padrões: - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`: ID/nome/IP opcional do Node para `chrome-node` +- `chromeNode.node`: id/nome/IP de nó opcional para `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` - `chrome.guestName: "OpenClaw Agent"`: nome usado na tela de convidado desconectado do Meet -- `chrome.autoJoin: true`: preenchimento de nome de convidado em melhor esforço e clique em Entrar agora - por meio da automação de navegador do OpenClaw em `chrome-node` -- `chrome.reuseExistingTab: true`: ativa uma aba existente do Meet em vez de +- `chrome.autoJoin: true`: preenchimento de nome de convidado e clique em Join Now em melhor esforço + por meio da automação de navegador do OpenClaw no `chrome-node` +- `chrome.reuseExistingTab: true`: ativar uma aba existente do Meet em vez de abrir duplicatas -- `chrome.waitForInCallMs: 20000`: espera a aba do Meet informar que está em chamada +- `chrome.waitForInCallMs: 20000`: aguardar a aba do Meet relatar que está em chamada antes que a introdução em tempo real seja acionada -- `chrome.audioFormat: "pcm16-24khz"`: formato de áudio de par de comandos. Use +- `chrome.audioFormat: "pcm16-24khz"`: formato de áudio do par de comandos. Use `"g711-ulaw-8khz"` apenas para pares de comandos legados/personalizados que ainda emitem áudio de telefonia. -- `chrome.audioInputCommand`: comando SoX que lê de `BlackHole 2ch` do CoreAudio - e grava áudio em `chrome.audioFormat` -- `chrome.audioOutputCommand`: comando SoX que lê áudio em `chrome.audioFormat` - e grava em `BlackHole 2ch` do CoreAudio +- `chrome.audioInputCommand`: comando SoX lendo do CoreAudio `BlackHole 2ch` + e gravando áudio em `chrome.audioFormat` +- `chrome.audioOutputCommand`: comando SoX lendo áudio em `chrome.audioFormat` + e gravando no CoreAudio `BlackHole 2ch` - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: respostas faladas breves, com `openclaw_agent_consult` para respostas mais aprofundadas - `realtime.introMessage`: verificação curta de prontidão falada quando a ponte em tempo real - se conecta; defina como `""` para entrar silenciosamente -- `realtime.agentId`: ID opcional de agente do OpenClaw para + conecta; defina como `""` para entrar silenciosamente +- `realtime.agentId`: id opcional de agente do OpenClaw para `openclaw_agent_consult`; o padrão é `main` Substituições opcionais: @@ -974,7 +998,7 @@ Substituições opcionais: } ``` -Configuração somente Twilio: +Configuração apenas de Twilio: ```json5 { @@ -989,10 +1013,10 @@ Configuração somente Twilio: } ``` -`voiceCall.enabled` assume `true` por padrão; com transporte Twilio, ele delega a -chamada PSTN real e o DTMF ao plugin Voice Call. Se `voice-call` não estiver +`voiceCall.enabled` tem como padrão `true`; com transporte Twilio, ele delega a +chamada PSTN real e o DTMF ao Plugin Voice Call. Se `voice-call` não estiver habilitado, o Google Meet ainda pode validar e registrar o plano de discagem, mas não pode -realizar a chamada Twilio. +fazer a chamada Twilio. ## Ferramenta @@ -1008,32 +1032,32 @@ Agentes podem usar a ferramenta `google_meet`: ``` Use `transport: "chrome"` quando o Chrome é executado no host do Gateway. Use -`transport: "chrome-node"` quando o Chrome é executado em um nó pareado, como uma VM -do Parallels. Em ambos os casos, o modelo em tempo real e `openclaw_agent_consult` são executados no +`transport: "chrome-node"` quando o Chrome é executado em um node pareado, como uma VM +Parallels. Em ambos os casos, o modelo realtime e `openclaw_agent_consult` são executados no host do Gateway, então as credenciais do modelo permanecem lá. Use `action: "status"` para listar sessões ativas ou inspecionar um ID de sessão. Use -`action: "speak"` com `sessionId` e `message` para fazer o agente em tempo real +`action: "speak"` com `sessionId` e `message` para fazer o agente realtime falar imediatamente. Use `action: "test_speech"` para criar ou reutilizar a sessão, -acionar uma frase conhecida e retornar a integridade `inCall` quando o host do Chrome puder -relatá-la. `test_speech` sempre força `mode: "realtime"` e falha se solicitado a -executar em `mode: "transcribe"` porque sessões apenas de observação intencionalmente não podem -emitir fala. Seu resultado `speechOutputVerified` é baseado no aumento dos bytes de saída de áudio em tempo real -durante esta chamada de teste, então uma sessão reutilizada com áudio antigo +acionar uma frase conhecida e retornar a integridade `inCall` quando o host Chrome puder +relatá-la. `test_speech` sempre força `mode: "realtime"` e falha se for solicitado a +executar em `mode: "transcribe"` porque sessões somente de observação intencionalmente não podem +emitir fala. O resultado `speechOutputVerified` é baseado no aumento de bytes de saída de áudio +realtime durante esta chamada de teste, então uma sessão reutilizada com áudio anterior não conta como uma nova verificação de fala bem-sucedida. Use `action: "leave"` para marcar uma sessão como encerrada. `status` inclui a integridade do Chrome quando disponível: - `inCall`: o Chrome parece estar dentro da chamada do Meet -- `micMuted`: estado de melhor esforço do microfone do Meet +- `micMuted`: estado do microfone do Meet em melhor esforço - `manualActionRequired` / `manualActionReason` / `manualActionMessage`: o - perfil do navegador precisa de login manual, admissão pelo anfitrião do Meet, permissões ou - reparo do controle do navegador antes que a fala funcione + perfil do navegador precisa de login manual, admissão pelo host do Meet, permissões ou + reparo do controle do navegador antes que a fala possa funcionar - `speechReady` / `speechBlockedReason` / `speechBlockedMessage`: se - a fala gerenciada pelo Chrome é permitida agora. `speechReady: false` significa que o OpenClaw - não enviou a frase de introdução/teste para a ponte de áudio. -- `providerConnected` / `realtimeReady`: estado da ponte de voz em tempo real + a fala gerenciada do Chrome está permitida agora. `speechReady: false` significa que o OpenClaw não + enviou a frase de introdução/teste para a ponte de áudio. +- `providerConnected` / `realtimeReady`: estado da ponte de voz realtime - `lastInputAt` / `lastOutputAt`: último áudio visto vindo da ponte ou enviado para ela ```json @@ -1044,20 +1068,20 @@ uma sessão como encerrada. } ``` -## Consulta do agente em tempo real +## Consulta do agente realtime -O modo em tempo real do Chrome é otimizado para um ciclo de voz ao vivo. O provedor de voz em tempo real +O modo realtime do Chrome é otimizado para um loop de voz ao vivo. O provedor de voz realtime ouve o áudio da reunião e fala pela ponte de áudio configurada. -Quando o modelo em tempo real precisa de raciocínio mais profundo, informações atuais ou ferramentas normais do +Quando o modelo realtime precisa de raciocínio mais profundo, informações atuais ou ferramentas normais do OpenClaw, ele pode chamar `openclaw_agent_consult`. -A ferramenta de consulta executa o agente regular do OpenClaw nos bastidores com o contexto recente -da transcrição da reunião e retorna uma resposta falada concisa para a sessão de voz em tempo real. +A ferramenta de consulta executa o agente OpenClaw regular nos bastidores com contexto recente da +transcrição da reunião e retorna uma resposta falada concisa para a sessão de voz realtime. O modelo de voz pode então falar essa resposta de volta na reunião. -Ela usa a mesma ferramenta compartilhada de consulta em tempo real que o Voice Call. +Ela usa a mesma ferramenta compartilhada de consulta realtime que Voice Call. Por padrão, as consultas são executadas no agente `main`. Defina `realtime.agentId` quando uma -rota do Meet deve consultar um workspace dedicado de agente do OpenClaw, padrões de modelo, +trilha do Meet deve consultar um workspace de agente OpenClaw dedicado, padrões de modelo, política de ferramentas, memória e histórico de sessão. `realtime.toolPolicy` controla a execução da consulta: @@ -1065,20 +1089,20 @@ política de ferramentas, memória e histórico de sessão. - `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 ao modelo de voz em tempo real. +- `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 ao modelo de voz realtime. -A chave da sessão de consulta é escopada por sessão do Meet, então chamadas de consulta de acompanhamento +A chave de sessão da consulta tem escopo por sessão do Meet, então chamadas de consulta de acompanhamento podem reutilizar o contexto de consulta anterior durante a mesma reunião. -Para forçar uma verificação de prontidão falada depois que o Chrome entrou totalmente na chamada: +Para forçar uma verificação de prontidão falada depois que o Chrome entrou completamente na chamada: ```bash openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Para o smoke completo de entrada e fala: +Para o smoke completo de entrar e falar: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -1088,7 +1112,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## Checklist de teste ao vivo -Use esta sequência antes de entregar uma reunião a um agente não supervisionado: +Use esta sequência antes de entregar uma reunião a um agente desacompanhado: ```bash openclaw googlemeet setup @@ -1102,14 +1126,14 @@ Estado esperado do Chrome-node: - `googlemeet setup` está todo verde. - `googlemeet setup` inclui `chrome-node-connected` quando Chrome-node é o - transporte padrão ou um nó está fixado. -- `nodes status` mostra o nó selecionado conectado. -- O nó selecionado anuncia tanto `googlemeet.chrome` quanto `browser.proxy`. -- A aba do Meet entra na chamada e `test-speech` retorna a integridade do Chrome com + transporte padrão ou um node está fixado. +- `nodes status` mostra o node selecionado conectado. +- O node selecionado anuncia tanto `googlemeet.chrome` quanto `browser.proxy`. +- A aba do Meet entra na chamada e `test-speech` retorna integridade do Chrome com `inCall: true`. -Para um host remoto do Chrome, como uma VM macOS do Parallels, esta é a verificação segura -mais curta depois de atualizar o Gateway ou a VM: +Para um host Chrome remoto, como uma VM macOS Parallels, esta é a verificação segura +mais curta após atualizar o Gateway ou a VM: ```bash openclaw googlemeet setup @@ -1120,8 +1144,8 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Isso comprova que o Plugin do Gateway está carregado, o nó da VM está conectado com o -token atual e a ponte de áudio do Meet está disponível antes que um agente abra uma +Isso prova que o Plugin do Gateway está carregado, que o node da VM está conectado com o +token atual e que a ponte de áudio do Meet está disponível antes que um agente abra uma aba de reunião real. Para um smoke do Twilio, use uma reunião que exponha detalhes de discagem por telefone: @@ -1136,11 +1160,11 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Estado esperado do Twilio: -- `googlemeet setup` inclui verificações verdes de `twilio-voice-call-plugin` e - `twilio-voice-call-credentials`. +- `googlemeet setup` inclui verificações verdes de `twilio-voice-call-plugin`, + `twilio-voice-call-credentials` e `twilio-voice-call-webhook`. - `voicecall` está disponível na CLI após o recarregamento do Gateway. - A sessão retornada tem `transport: "twilio"` e um `twilio.voiceCallId`. -- `googlemeet leave ` encerra a chamada de voz delegada. +- `googlemeet leave ` desliga a chamada de voz delegada. ## Solução de problemas @@ -1156,9 +1180,9 @@ openclaw googlemeet setup Se você acabou de editar `plugins.entries.google-meet`, reinicie ou recarregue o Gateway. O agente em execução só vê ferramentas de Plugin registradas pelo processo atual do Gateway. -### Nenhum nó compatível com Google Meet conectado +### Nenhum node compatível com Google Meet conectado -No host do nó, execute: +No host do node, execute: ```bash openclaw plugins enable google-meet @@ -1167,7 +1191,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -No host do Gateway, aprove o nó e verifique os comandos: +No host do Gateway, aprove o node e verifique os comandos: ```bash openclaw devices list @@ -1175,8 +1199,8 @@ openclaw devices approve openclaw nodes status ``` -O nó deve estar conectado e listar `googlemeet.chrome` mais `browser.proxy`. -A configuração do Gateway deve permitir esses comandos de nó: +O node deve estar conectado e listar `googlemeet.chrome` mais `browser.proxy`. +A configuração do Gateway deve permitir esses comandos de node: ```json5 { @@ -1189,7 +1213,7 @@ A configuração do Gateway deve permitir esses comandos de nó: ``` Se `googlemeet setup` falhar em `chrome-node-connected` ou o log do Gateway relatar -`gateway token mismatch`, reinstale ou reinicie o nó com o token atual do Gateway. +`gateway token mismatch`, reinstale ou reinicie o node com o token atual do Gateway. Para um Gateway em LAN, isso geralmente significa: ```bash @@ -1201,7 +1225,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -Em seguida, recarregue o serviço do nó e execute novamente: +Depois recarregue o serviço do node e execute novamente: ```bash openclaw googlemeet setup @@ -1216,77 +1240,77 @@ e pare de tentar novamente até que a ação no navegador esteja concluída. Ações manuais comuns: -- Entre no perfil do Chrome. -- Admita o convidado pela conta anfitriã do Meet. -- Conceda permissões de microfone/câmera ao Chrome quando o prompt de permissão nativo - do Chrome aparecer. +- Faça login no perfil do Chrome. +- Admita o convidado pela conta host do Meet. +- Conceda permissões de microfone/câmera ao Chrome quando o prompt de permissão nativo do Chrome + aparecer. - Feche ou repare uma caixa de diálogo de permissão do Meet travada. Não relate "não conectado" só porque o Meet mostra "Do you want people to hear you in the meeting?" Esse é o intersticial de escolha de áudio do Meet; o OpenClaw clica em **Use microphone** por automação do navegador quando disponível e continua -aguardando o estado real da reunião. Para fallback de navegador apenas de criação, o OpenClaw +aguardando o estado real da reunião. Para fallback de navegador somente de criação, o OpenClaw pode clicar em **Continue without microphone** porque criar a URL não precisa -do caminho de áudio em tempo real. +do caminho de áudio realtime. -### Falha na criação da reunião +### A criação da reunião falha `googlemeet create` primeiro usa o endpoint `spaces.create` da API do Google Meet -quando credenciais OAuth estão configuradas. Sem credenciais OAuth, ele recorre -ao navegador do nó Chrome fixado. Confirme: +quando credenciais OAuth estão configuradas. Sem credenciais OAuth, ele faz fallback +para o navegador do node Chrome fixado. Confirme: -- Para criação por API: `oauth.clientId` e `oauth.refreshToken` estão configurados, +- Para criação via API: `oauth.clientId` e `oauth.refreshToken` estão configurados, ou variáveis de ambiente `OPENCLAW_GOOGLE_MEET_*` correspondentes estão presentes. -- Para criação por API: o token de atualização foi emitido depois que o suporte a criação foi +- Para criação via API: o token de atualização foi emitido depois que o suporte a criação foi adicionado. Tokens mais antigos podem não ter o escopo `meetings.space.created`; execute novamente `openclaw googlemeet auth login --json` e atualize a configuração do Plugin. - Para fallback de navegador: `defaultTransport: "chrome-node"` e - `chromeNode.node` apontam para um nó conectado com `browser.proxy` e + `chromeNode.node` apontam para um node conectado com `browser.proxy` e `googlemeet.chrome`. -- Para fallback de navegador: o perfil do Chrome do OpenClaw nesse nó está conectado +- Para fallback de navegador: o perfil Chrome do OpenClaw nesse node está conectado ao Google e consegue abrir `https://meet.google.com/new`. - Para fallback de navegador: novas tentativas reutilizam uma aba existente de `https://meet.google.com/new` ou de prompt de conta Google antes de abrir uma nova aba. Se um agente expirar, - repita a chamada da ferramenta em vez de abrir manualmente outra aba do Meet. + tente novamente a chamada da ferramenta em vez de abrir manualmente outra aba do Meet. - Para fallback de navegador: se a ferramenta retornar `manualActionRequired: true`, use - os valores retornados de `browser.nodeId`, `browser.targetId`, `browserUrl` e + os valores retornados `browser.nodeId`, `browser.targetId`, `browserUrl` e `manualActionMessage` para orientar o operador. Não tente novamente em loop até que essa ação esteja concluída. - Para fallback de navegador: se o Meet mostrar "Do you want people to hear you in the meeting?", deixe a aba aberta. O OpenClaw deve clicar em **Use microphone** ou, para - fallback apenas de criação, **Continue without microphone** por automação do navegador + fallback somente de criação, **Continue without microphone** por automação do navegador e continuar aguardando a URL do Meet gerada. Se não conseguir, o erro deve mencionar `meet-audio-choice-required`, não `google-login-required`. ### O agente entra, mas não fala -Verifique o caminho em tempo real: +Verifique o caminho realtime: ```bash openclaw googlemeet setup openclaw googlemeet doctor ``` -Use `mode: "realtime"` para ouvir/responder por voz. `mode: "transcribe"` intencionalmente -não inicia a ponte de voz duplex em tempo real. `googlemeet test-speech` -sempre verifica o caminho em tempo real e relata se bytes de saída da ponte foram -observados nessa invocação. Se `speechOutputVerified` for falso e -`speechOutputTimedOut` for verdadeiro, o provedor em tempo real pode ter aceitado a +Use `mode: "realtime"` para escutar/responder por voz. `mode: "transcribe"` intencionalmente +não inicia a ponte de voz realtime duplex. `googlemeet test-speech` +sempre verifica o caminho realtime e relata se bytes de saída da ponte foram +observados para essa invocação. Se `speechOutputVerified` for falso e +`speechOutputTimedOut` for verdadeiro, o provedor realtime pode ter aceitado a fala, mas o OpenClaw não viu novos bytes de saída chegarem à ponte de áudio do Chrome. -Também verifique: +Verifique também: -- Uma chave de provedor em tempo real está disponível no host do Gateway, como +- Uma chave de provedor realtime está disponível no host do Gateway, como `OPENAI_API_KEY` ou `GEMINI_API_KEY`. -- `BlackHole 2ch` está visível no host do Chrome. -- `sox` existe no host do Chrome. +- `BlackHole 2ch` está visível no host Chrome. +- `sox` existe no host Chrome. - O microfone e o alto-falante do Meet estão roteados pelo caminho de áudio virtual usado pelo OpenClaw. -`googlemeet doctor [session-id]` imprime a sessão, o nó, o estado na chamada, -o motivo da ação manual, a conexão do provedor em tempo real, `realtimeReady`, atividade de +`googlemeet doctor [session-id]` imprime a sessão, o node, o estado na chamada, +o motivo da ação manual, a conexão do provedor realtime, `realtimeReady`, atividade de entrada/saída de áudio, últimos timestamps de áudio, contadores de bytes e URL do navegador. -Use `googlemeet status [session-id]` quando precisar do JSON bruto. Use +Use `googlemeet status [session-id] --json` quando precisar do JSON bruto. Use `googlemeet doctor --oauth` quando precisar verificar a atualização OAuth do Google Meet sem expor tokens; adicione `--meeting` ou `--create-space` quando também precisar de uma prova da API do Google Meet. @@ -1300,21 +1324,21 @@ openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` A ação de ferramenta equivalente é `recover_current_tab`. Ela foca e inspeciona uma -aba existente do Meet para o transporte selecionado. Com `chrome`, ela usa o controle local -do navegador por meio do Gateway; com `chrome-node`, ela usa o nó Chrome configurado. +aba existente do Meet para o transporte selecionado. Com `chrome`, ela usa controle de +navegador local por meio do Gateway; com `chrome-node`, usa o node Chrome configurado. Ela não abre uma nova aba nem cria uma nova sessão; ela relata o bloqueador atual, como login, admissão, permissões ou estado de escolha de áudio. O comando da CLI conversa com o Gateway configurado, então o Gateway deve estar em execução; -`chrome-node` também exige que o nó Chrome esteja conectado. +`chrome-node` também exige que o node Chrome esteja conectado. -### Falhas nas verificações de configuração do Twilio +### As verificações de configuração do Twilio falham -`twilio-voice-call-plugin` falha quando `voice-call` não é permitido ou não está habilitado. +`twilio-voice-call-plugin` falha quando `voice-call` não está permitido ou não está habilitado. Adicione-o a `plugins.allow`, habilite `plugins.entries.voice-call` e recarregue o Gateway. -`twilio-voice-call-credentials` falha quando o backend da Twilio não tem o SID da -conta, o token de autenticação ou o número de origem. Defina-os no host do Gateway: +`twilio-voice-call-credentials` falha quando o backend do Twilio não tem account +SID, token de autenticação ou número de origem. Defina-os no host do Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -1322,31 +1346,78 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` +`twilio-voice-call-webhook` falha quando `voice-call` não tem exposição pública de webhook, +ou quando `publicUrl` aponta para local loopback ou espaço de rede privada. +Defina `plugins.entries.voice-call.config.publicUrl` como a URL pública do provedor ou +configure uma exposição de túnel/Tailscale para `voice-call`. + +URLs de loopback e privadas não são válidas para callbacks de operadora. 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`. + +Para uma URL pública estável: + +```json5 +{ + plugins: { + entries: { + "voice-call": { + enabled: true, + config: { + provider: "twilio", + fromNumber: "+15550001234", + publicUrl: "https://voice.example.com/voice/webhook", + }, + }, + }, + }, +} +``` + +Para desenvolvimento local, use um túnel ou uma exposição Tailscale em vez de uma URL de +host privada: + +```json5 +{ + plugins: { + entries: { + "voice-call": { + config: { + tunnel: { provider: "ngrok" }, + // or + tailscale: { mode: "funnel", path: "/voice/webhook" }, + }, + }, + }, + }, +} +``` + Depois reinicie ou recarregue o Gateway e execute: ```bash -openclaw googlemeet setup +openclaw googlemeet setup --transport twilio openclaw voicecall setup openclaw voicecall smoke ``` -`voicecall smoke` é apenas de prontidão por padrão. Para fazer uma simulação com um número específico: +`voicecall smoke` é apenas uma verificação de prontidão por padrão. Para fazer um teste dry-run com um número específico: ```bash openclaw voicecall smoke --to "+15555550123" ``` -Adicione `--yes` somente quando você intencionalmente quiser fazer uma chamada +Adicione `--yes` somente quando você quiser intencionalmente fazer uma chamada de notificação de saída ao vivo: ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### A chamada da Twilio começa, mas nunca entra na reunião +### A chamada Twilio começa, mas nunca entra na reunião -Confirme que o evento do Meet expõe detalhes de discagem por telefone. Passe o -número de discagem exato e o PIN ou uma sequência DTMF personalizada: +Confirme que o evento do Meet expõe detalhes de discagem por telefone. Passe o número de +discagem e o PIN exatos ou uma sequência DTMF personalizada: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -1358,32 +1429,49 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Use `w` inicial ou vírgulas em `--dtmf-sequence` se o provedor precisar de uma pausa antes de inserir o PIN. +Se a chamada telefônica for criada, mas a lista de participantes do Meet nunca mostrar o +participante por discagem: + +- Execute `openclaw voicecall status --call-id ` e confirme que a chamada ainda está + ativa. +- Execute `openclaw voicecall tail` e verifique se os webhooks do Twilio estão chegando ao + Gateway. +- Execute novamente `openclaw googlemeet setup --transport twilio`; uma verificação de configuração verde é + obrigatória, mas não prova que a sequência do PIN da reunião está correta. +- Confirme que o número de discagem pertence ao mesmo convite do Meet e à mesma região do + PIN. +- Aumente as pausas iniciais em `--dtmf-sequence` se o Meet demorar para atender, por + exemplo `wwww123456#`. + +Se os webhooks não chegarem, depure primeiro o Plugin Voice Call: o provedor deve +alcançar `plugins.entries.voice-call.config.publicUrl` ou o túnel configurado. +Consulte [Solução de problemas de chamada de voz](/pt-BR/plugins/voice-call#troubleshooting). + ## Observações -A API oficial de mídia do Google Meet é orientada ao recebimento, portanto falar em uma -chamada do Meet ainda precisa de um caminho de participante. Este plugin mantém esse limite visível: -o Chrome lida com a participação no navegador e o roteamento de áudio local; a Twilio lida com -a participação por discagem telefônica. +A API de mídia oficial do Google Meet é orientada ao recebimento, portanto falar em uma chamada do Meet +ainda precisa de um caminho de participante. Este plugin mantém esse limite visível: +o Chrome cuida da participação pelo navegador e do roteamento de áudio local; o Twilio cuida +da participação por discagem telefônica. -O modo em tempo real do Chrome precisa de `BlackHole 2ch` mais uma destas opções: +O modo em tempo real do Chrome precisa de `BlackHole 2ch` mais uma das seguintes opções: -- `chrome.audioInputCommand` mais `chrome.audioOutputCommand`: o OpenClaw é responsável pela - ponte do modelo em tempo real e encaminha o áudio em `chrome.audioFormat` entre esses +- `chrome.audioInputCommand` mais `chrome.audioOutputCommand`: o OpenClaw controla a + ponte do modelo em tempo real e direciona o áudio em `chrome.audioFormat` entre esses comandos e o provedor de voz em tempo real selecionado. O caminho padrão do Chrome é - PCM16 de 24 kHz; G.711 mu-law de 8 kHz continua disponível para pares de comandos legados. -- `chrome.audioBridgeCommand`: um comando de ponte externo é responsável por todo o caminho - de áudio local e deve sair depois de iniciar ou validar seu daemon. + PCM16 de 24 kHz; G.711 mu-law de 8 kHz permanece disponível para pares de comandos legados. +- `chrome.audioBridgeCommand`: um comando de ponte externo controla todo o caminho de + áudio local e deve sair depois de iniciar ou validar seu daemon. Para áudio duplex limpo, roteie a saída do Meet e o microfone do Meet por dispositivos virtuais separados ou por um grafo de dispositivos virtuais no estilo Loopback. Um único dispositivo BlackHole compartilhado pode ecoar outros participantes de volta para a chamada. -`googlemeet speak` aciona a ponte de áudio em tempo real ativa para uma sessão do Chrome. -`googlemeet leave` interrompe essa ponte. Para sessões da Twilio delegadas -por meio do Plugin de chamada de voz, `leave` também encerra a chamada de voz subjacente. +`googlemeet speak` aciona a ponte de áudio em tempo real ativa para uma sessão do Chrome. `googlemeet leave` interrompe essa ponte. Para sessões Twilio delegadas +por meio do Plugin Voice Call, `leave` também encerra a chamada de voz subjacente. ## Relacionados - [Plugin de chamada de voz](/pt-BR/plugins/voice-call) -- [Modo de conversa](/pt-BR/nodes/talk) +- [Modo de fala](/pt-BR/nodes/talk) - [Criando plugins](/pt-BR/plugins/building-plugins) diff --git a/docs/pt-BR/plugins/voice-call.md b/docs/pt-BR/plugins/voice-call.md index 6a8810dd4..055ccc9bc 100644 --- a/docs/pt-BR/plugins/voice-call.md +++ b/docs/pt-BR/plugins/voice-call.md @@ -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). -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. ## Início rápido - + ```bash @@ -48,18 +48,18 @@ o Gateway e reinicie o Gateway para carregá-lo. - 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. - + 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. ```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. -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. @@ -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. -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). ```json5 @@ -164,27 +164,27 @@ As credenciais de voice-call aceitam SecretRefs. `plugins.entries.voice-call.con ``` - - - Twilio, Telnyx e Plivo exigem uma URL de webhook **publicamente acessível**. - - `mock` é um provedor local de desenvolvimento (sem chamadas de rede). + + - 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. - `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). - 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.`. -- 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.`. -- 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 ``` -**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. Notas de comportamento: -- Chaves legadas `tts.` 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.`. -- 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 ``. 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.` 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.`. +- 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 ``. 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 - + ```json5 { messages: { @@ -424,7 +425,7 @@ Notas de comportamento: } ``` - + ```json5 { plugins: { @@ -448,7 +449,7 @@ Notas de comportamento: } ``` - + ```json5 { plugins: { @@ -472,9 +473,9 @@ Notas de comportamento: -## 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 ``` -`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. @@ -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 `` legada para essa mensagem inicial, então sessões `` 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 `` para essa mensagem inicial, então sessões de saída `` 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: - Hosts da lista de permissões a partir de cabeçalhos de encaminhamento. + Hosts permitidos a partir de cabeçalhos de encaminhamento. Confia em cabeçalhos encaminhados sem uma lista de permissões. - 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. 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 ``, 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 ``, 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 ` para apontar para um log diferente e `--last ` 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 +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) diff --git a/docs/pt-BR/reference/RELEASING.md b/docs/pt-BR/reference/RELEASING.md index 317d730b2..c010f4d5d 100644 --- a/docs/pt-BR/reference/RELEASING.md +++ b/docs/pt-BR/reference/RELEASING.md @@ -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` 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` 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=`, 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=`, 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=` 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=` 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=`, `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=`, `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 diff --git a/docs/pt-BR/reference/full-release-validation.md b/docs/pt-BR/reference/full-release-validation.md new file mode 100644 index 000000000..43ec23fd5 --- /dev/null +++ b/docs/pt-BR/reference/full-release-validation.md @@ -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`
**Workflow filho:** nenhum
**Prova:** resolve o branch de versão, a tag ou o SHA completo do commit e registra as entradas selecionadas.
**Executar novamente:** execute novamente o guarda-chuva se isso falhar. | +| Vitest e CI normal | **Job:** `Run normal full CI`
**Workflow filho:** `CI`
**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.
**Executar novamente:** `rerun_group=ci`. | +| Pré-lançamento de Plugin | **Job:** `Run plugin prerelease validation`
**Workflow filho:** `Plugin Prerelease`
**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.
**Executar novamente:** `rerun_group=plugin-prerelease`. | +| Verificações de versão | **Job:** `Run release/live/Docker/QA validation`
**Workflow filho:** `OpenClaw Release Checks`
**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.
**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`
**Workflow filho:** `NPM Telegram Beta E2E`
**Prova:** prova opcional do Telegram com pacote publicado quando `npm_telegram_package_spec` está definido.
**Executar novamente:** `rerun_group=npm-telegram`. | +| Verificador do guarda-chuva | **Job:** `Verify full validation`
**Workflow filho:** nenhum
**Prova:** verifica novamente as conclusões registradas das execuções filhas e acrescenta tabelas dos jobs mais lentos dos workflows filhos.
**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`
**Workflow de suporte:** nenhum
**Testes:** ref selecionada, SHA esperado opcional, perfil, grupo de reexecução e filtro focado de suíte live.
**Executar novamente:** `rerun_group=release-checks`. | +| Artefato de pacote | **Job:** `Prepare release package artifact`
**Workflow de suporte:** nenhum
**Testes:** empacota ou resolve um tarball candidato e envia `release-package-under-test` para verificações downstream voltadas a pacotes.
**Executar novamente:** o grupo de pacote, cross-OS ou live/E2E afetado. | +| Smoke de instalação | **Job:** `Run install smoke`
**Workflow de suporte:** `Install Smoke`
**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.
**Executar novamente:** `rerun_group=install-smoke`. | +| Cross-OS | **Job:** `cross_os_release_checks`
**Workflow de suporte:** `OpenClaw Cross-OS Release Checks (Reusable)`
**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.
**Executar novamente:** `rerun_group=cross-os`. | +| E2E de repo e live | **Job:** `Run repo/live E2E validation`
**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`
**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`.
**Executar novamente:** `rerun_group=live-e2e`, opcionalmente com `live_suite_filter`. | +| Caminho de versão Docker | **Job:** `Run Docker release-path validation`
**Workflow de suporte:** `OpenClaw Live And E2E Checks (Reusable)`
**Testes:** partes Docker do caminho de versão contra o artefato de pacote compartilhado.
**Executar novamente:** `rerun_group=live-e2e`. | +| Package Acceptance | **Job:** `Run package acceptance`
**Workflow de suporte:** `Package Acceptance`
**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.
**Executar novamente:** `rerun_group=package`. | +| Paridade QA | **Job:** `Run QA Lab parity lane` e `Run QA Lab parity report`
**Workflow de suporte:** jobs diretos
**Testes:** pacotes de paridade agêntica do candidato e do baseline, depois o relatório de paridade.
**Executar novamente:** `rerun_group=qa-parity` ou `rerun_group=qa`. | +| Matrix live QA | **Job:** `Run QA Lab live Matrix lane`
**Workflow de suporte:** job direto
**Testes:** perfil QA rápido da Matrix live no ambiente `qa-live-shared`.
**Executar novamente:** `rerun_group=qa-live` ou `rerun_group=qa`. | +| Telegram live QA | **Job:** `Run QA Lab live Telegram lane`
**Workflow de suporte:** job direto
**Testes:** QA live do Telegram com concessões de credenciais Convex CI.
**Executar novamente:** `rerun_group=qa-live` ou `rerun_group=qa`. | +| Verificador de versão | **Job:** `Verify release checks`
**Workflow de suporte:** nenhum
**Testes:** jobs obrigatórios de release-check para o grupo de reexecução selecionado.
**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=` 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` diff --git a/docs/pt-BR/reference/test.md b/docs/pt-BR/reference/test.md index 91029b010..0f93ddf1b 100644 --- a/docs/pt-BR/reference/test.md +++ b/docs/pt-BR/reference/test.md @@ -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 ` 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 -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.\` | Alternâncias + configuração por plugin | +| `entries.\` | 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. - - **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. ## 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): `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. @@ -266,59 +270,59 @@ O OpenClaw procura plugins nesta ordem (a primeira correspondência prevalece): `~/.openclaw//*.ts` e `~/.openclaw//*/index.ts`. - - Incluídos com o OpenClaw. Muitos são habilitados por padrão (provedores de modelo, fala). + + Enviados com o OpenClaw. Muitos são habilitados por padrão (provedores de modelo, fala). Outros exigem habilitação explícita. -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.\.enabled: false` desabilita esse plugin +- `plugins.entries.\.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 --json` para confirmar registros de hooks e +- Use `openclaw plugins inspect --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..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 `. ### Propriedade duplicada de canal ou ferramenta @@ -329,32 +333,32 @@ Sintomas: - `channel setup already registered: ()` - `plugin tool name conflict (): ` -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 --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 --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..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..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..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..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 # deep detail -openclaw plugins inspect --json # machine-readable -openclaw plugins inspect --all # fleet-wide table -openclaw plugins info # 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 # detalhes aprofundados +openclaw plugins inspect --json # legível por máquina +openclaw plugins inspect --all # tabela de toda a frota +openclaw plugins info # 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 # install (ClawHub first, then npm) -openclaw plugins install clawhub: # install from ClawHub only -openclaw plugins install npm: # install from npm only -openclaw plugins install --force # overwrite existing install -openclaw plugins install # install from local path -openclaw plugins install -l # link (no copy) for dev +openclaw plugins install # instalar (ClawHub primeiro, depois npm) +openclaw plugins install clawhub: # instalar apenas do ClawHub +openclaw plugins install npm: # instalar apenas do npm +openclaw plugins install --force # sobrescrever instalação existente +openclaw plugins install # instalar de caminho local +openclaw plugins install -l # vincular (sem copiar) para dev openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # record exact resolved npm spec +openclaw plugins install --pin # registrar spec npm resolvida exata openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # update one plugin +openclaw plugins update # atualizar um Plugin openclaw plugins update --dangerously-force-unsafe-install -openclaw plugins update --all # update all -openclaw plugins uninstall # remove config and plugin index records +openclaw plugins update --all # atualizar todos +openclaw plugins uninstall # remover configuração e registros de índice de Plugin openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -412,80 +416,80 @@ openclaw plugins enable openclaw plugins disable ``` -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 `. +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 `. -`--force` sobrescreve um plugin instalado existente ou pacote de hooks no local. Use -`openclaw plugins update ` 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 ` 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 ` 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 ` 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 ` 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 ` 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